Integration: Image-Master 6 Direct DDE Control

Overview

Image-Master version 6 incorporated a substantial new functionality in the DDE/Automation control. You can directly control the behavior of the main UI, including sharing and handoff between the user and a control application (henceforth referred to as the "client"). This functionality is incorporated within the main Image-Master program, and is automatically activated and available whenever the main program is running. Either a client or the user can start Image-Master, and the client can terminate control with the user interface left at an appropriate place.

The Image-Master control model is that of a state machine, with the program being in a specific state and able to respond to an appropriate subset of commands. There is a global state variable that a control application (client) can issue a request for that will return the current state. Since the user can also control the program and hence change its state, a third-party control application may want to query the current state to be certain of the environment before issuing commands. For example, a client requests a search on a database, which brings the Image-Master UI forward with the search results displayed. The user then make some selections and then decides to quit the Viewing Module out to Master Control. At this point the database is closed and the client can not assume that the Viewing Module is still active.

In a future Image-Master release, the client will be able to disable certain navigation buttons so that the user can not exit the program or module prematurely.

Image-Master States        State           Control Mode (Topics Allowed)
A. Not Running          n/a             none - must use a ShellEx to invoke IMASTER.EXE
B. Authentication               1               LOGON - must authenticate into Image-Master
C. Master Control               2               CONTROL - database selection, module entry commands
D. Viewing              10              VIEW - Search and document retrieval
                        11              VIEW - At the Search Results List Screen
                        12              VIEW - Performing an API based document export
E. Scanning             20              SCAN - Scanning and filing tasks                        
F. Import/Export                                IMPEXP

There are currently no plans to expose the Database Configuration, Security Access, or Administration functions to clients. If you require access to these areas programmatically, it can be accomplished on an as-needed basis.

Other useful notes about Image-Master states and the corresponding topics which are active:

It is not necessary for a client to transition through all the states. A client can simply request the current state that Image-Master is in and proceed from there. For example, if Image-Master is already in the Scanning Module, either because the user started Image-Master or because another client left it there, then no logon nor control topics need to be established and a conversation can be made directly with the SCAN topic. Of course, if the client ends the conversation which currently forces a state transition, then to return to the desired module will require a conversation be made with the CONTROL topic.

Part 1: Transition from State A to State B

You can click on the appropriate shortcut, the shortcut can be automatically invoked as part of a logon script, startup folder, user profile, or client startup script.
Client can execute an appropriate WinAPI command to load a foreign application. The path to Image-Master can be determined from the EIDMS environment variable which will be present on every legally licensed terminal. The executable program to start is called IMASTER.EXE.

NOTE: It is legal to launch Image-Master with a window type of minimized. Image-Master will recognize this and will bring itself to the foreground and re-minimize itself as required.

Part 2: Determining the Current Image-Master State

Establish a DDE Conversation. Service = IMASTER Topic = SYSTEM
Perform a Link Request on the item named STATE
The request will return a string value (character, not numeric) with the current Image-Master state as specified in the table above.

NOTE: If the request fails, Image-Master is not running and is considered to be in State A (n/a). Start Image-Master as described in Part 1 above. Once Image-Master is running, Part 2 can be retried to confirm that Image-Master can accept API commands.

Part 3: Transition from State B to State C (Logon)

Establish a DDE Conversation. Service = IMASTER Topic = LOGON
Perform an Execute Request as follows:

LOGON=Username,Password

Username is a valid Image-Master user (i.e. Admin by default)

Password is the corresponding password

for example, to login with the default account that ships with Image-Master, use the following command:

LOGON=admin, (Note the trailing comma when there is no password)

The Execute Request will return TRUE if the login was successful and Image-Master has transitioned to State C , or will return FALSE if the logon request failed (Image-Master remains in State B)

Part 4: Operations in State C (Master Control)

Establish another DDE Conversation. Service = IMASTER Topic = CONTROL
Perform an Execute Request as follows:

To select a database: DBF=complete path and filename to a valid IM (CF) database.

I.e. DBF=F:\IMASTER\SAMPLECF.DBF

Function Returns:

TRUE if the database was found and selected.

FALSE if the database can not be located.

No state transition occurs as a result of this request, but many control functions require that a valid database be selected prior to invoking the function.

To open the Viewing Module: VIEW

Note: must have already selected a database using the DBF request

Function Returns:

TRUE if the Viewing Module is active (Transition State C->D)

FALSE if the request was rejected.

To open the Scanning Module: SCAN

Note: must have already selected a database using the DBF request

Function Returns:

TRUE if the Scanning Module is active (Transition State C->E)

FALSE if the request was rejected.

To go back to the logon screen: NEXT

Function Returns:

TRUE if the transition is made (Transition State C->B)

FALSE if the request was rejected.

To quit and close Image-Master: End the conversation with the CONTROL topic.

Part 5: Operations in State D (Viewing Module)

Establish another DDE Conversation. Service = IMASTER Topic = VIEW
Perform an Execute Request as follows:

To Perform an integrated search and viewing request, the following command can be used:

QUERY=SQL search condition string

where, SQL search condition string should be formatted as a standard search expression that will evaluate to the desired document set. Many FoxPro functions and expressions are allowed to be used.

A simple example:

QUERY=name=’John Smith’ .and. dob={12/17/1964}

NOTE: name, and dob are fieldnames for this example. Name is a character type being compared to a literal, dob is a date or datetime type being compared to a specific date. .and. is the logical join, .or. And .not. Could be used as well.

How this function returns results:

If NO documents match the criteria: Function returns FALSE, UI not affected.

If EXACTLY ONE document matches the criteria: Function returns TRUE, UI not affected, matching document called up in the configured viewer which is given the focus.

If MULTIPLE documents match the criteria: Function returns FALSE, (note: this is probably not the most useful return value so it may be changed in a subsequent release), UI is changed to the Search Results list screen. Matching documents are loaded into the grid. and the Image-Master window is brought to the foreground and given the focus. The user may then decide which documents to view/print in the same manner as if a localized search inside the Viewing Module was performed. While Image-Master remains at the Search Results list screen, the STATE request will return ‘11'.

Using the QUERY request with conditions passed along does not alter or affect the Data Entry window nor the fields displayed. Therefore a user can make unrelated ad-hoc queries directly from Image-Master in tandem with client requests made using QUERY. The next set of commands integrate the client document search and retrieval functions more directly with the user interface.

You can also perform a search and retrieval by loading the Data Entry fields with the appropriate values from the client and then either initiating a Standard/Extended search from the client or by letting the user do it (after possibly modifying or adding to the search conditions). In this mode, the client simply loads field values via character literals (no functions are permitted) and Image-Master handles the data type conversion and the SQL query string creation and execution. The user will be able to see and modify the search conditions both before and after they are used, and can perform derivative queries from the Viewing Module from base values provided by the client.

To load a search field with a value:

SET=fieldname=literal value (no delimiters, no quotes necessary)

Function Returns:

TRUE if the field assignment was made successfully

FALSE if the request was rejected.

You need to issue multiple Execute requests, one for each field to be assigned a value. To clear a field that had previously been assigned a value use: SET=fieldname

After the desired fields have been defined, execute a formal search request using either of the two methods that Image-Master supports.

To perform a STANDARD search: SEARCH

Function Returns: behavior identical to the QUERY request defined above

To perform an EXTENDED search: XSEARCH

Function Returns: behavior identical to the QUERY request defined above

NOTE: If the standard search fails to return any documents, the client can then execute an extended search without reloading the field values. If multiple documents are returned, then once the user closes the Search Results list, the search conditions used in the search will be visible in the Data Entry window, and the user can modify or add to the search conditions and perform another search.

To quit the Viewing Module and return to Master Control (Transition State D->C): simply end the conversation with the VIEW topic.

To perform a GENFILE document export request.

GENFILE= {output TIF or PDF path\filename to create},{search expression}~{document order}

{output TIF or PDF path\filename to create} = the path and complete filename of the desired TIF or Adobe Acrobat PDF file that will be created.

{search expression} = a standard DB search expression that match one or more documents. Ex. FILENO='12345' AND GROUP$'SC'

{document order} = an ORDER BY clause that defines the order the documents should be combined. Note that since this is a comma delimited string, the tilde(~) is used as the parameter delimiter instead. Ex. lmdate DESC Ex2. GROUP

GENFILE may take a few moments

Part 6: Operations in State E (Scanning Module)

Establish another DDE Conversation. Service = IMASTER Topic = SCAN
Perform an Execute Request as follows:

SCAN=fieldname1=value1,fieldname2=value2, ...and so on.

SCAN (attended scanning) and SCANB (fully automated scanning) support the loading of index filing fields prior to the scan request being initiated. The format is as follows:

Loading of field(s) during scanning is purely optional. The syntax also supports a DOS batch file compatible form that encloses the index fields in quotes as in:

SCAN="fieldname1=value1..."

In all forms, the case of the commands and fieldnames are irrelevant, but the case of the values are preserved.

NOTE: Fieldname123 is a literal which represents a valid, defined, index field from the currently selected database. If a third-party application tries to pass an undefined fieldname, the user will be advised and that field will be skipped. Any other valid fields will be loaded as expected.

NOTE: Value123 is AN EXPRESSION! (one of FoxPro's greatest features) That means for simple literal assignments, the proper delimiters must be included around the value. For example: Storing a character literal: ADDRESS='123 Any Street' (note the SINGLE quotes around the value) Storing a date literal: TDATE={01/17/1996} (note the curly brackets around the value) and so on...

NOTE: Since the value is an expression, more complex data can be exchanged. For example: Using an internal FoxPro function: TDATE=DATE() (This would store the current system date in the field.) Using a third-party data source: DEALER=EXTNFN()+'extra literal value' quite simply, any expression that evaluates to the correct data type would work.

Another example:

SCAN="COMPANY='Able Fish Industries',TELEPH='(819) 555-1864'"

(This uses the DOS compatible method. The corresponding batch command for a DOS app might be.. ...DISP32.EXE ...\IMASTER.EXE,SCAN=%1 and then the passed parameter would be "COMPANY='Able Fish Industries',TELEPH='(819) 555-1864'")

As mentioned earlier, the value(s) are loaded into the appropriate fields prior to the start of scanning. Therefore, the typical workflow would be for the third-party application to send the request, the scanning operator loads the document set into the scanner as instructed, scans and QC's the document set, fills in any remaining index fields, and then chooses done.

To quit the Scanning Module and return to Master Control (Transition State E->C): end the conversation with the SCAN topic.