Programmer Guide

VIP Gateway for Windows allows many 3GL or 4GL host-based applications to communicate with Microsoft Windows workstation products.

VIP Gateway for Windows supports both DDE and non-DDE applications in the PC. However, with DDE applications communications can be two-way, and it is easier to build well-integrated applications.

To be able to take advantage of the DDE capability of workstation applications, developers must become familiar with the DDE commands documented with that application, and then issue or respond to the host commands with their application. VIP Gateway for Windows handles the communication of the host commands to the application, whether the application is in the host or the workstation.

Communications between DDE-aware applications are through messages. These messages are transmitted between the host and workstation environments by the components of VIP Gateway for Windows.

GWWCOM Communication

VIP Gateway for Windows uses a standard host public program to provide all DDE interaction:
GWWCOM. This program can be called from any supported 3GL or 4GL program. The program will be operable assuming the following:

• Gateway for Windows is the active workstation communication program; and there is enough workstation memory available for operation of Gateway for Windows and the source application.
• A call to GWWCOM without meeting all the above criteria met will result in a NO-OP; no activity will occur other than the return of an error code.

GWWCOM Call Format

CALL "GWWCOM", MSG$[ALL]

MSG$[0] Return Status
MSG$[1] Function Code
MSG$[2] Source Name
MSG$[3] Source Topic
MSG$[4] Source Item(s)
MSG$[5] Data (Send and/or Receive)

Detailed Descriptions MSG$

MSG$[0]: Return Status

Return Status	Meaning
. (period)	OK – Operation Successful
ERR(VIP): Description	VIP Error – Unable to Initiate Communication or VIP Not Installed
ERR(GWW): Description	DDE Error in Gateway for Windows
ERR(TSI): Description	Language Error

MSG$[1]: Function Code

Function Code	Meaning
I	Initiate DDE Conversation If application is not active on workstation, start the application.
T	Terminate DDE Conversation Leave application in current state. If you wish to terminate the application, you must do it through the DDE EXECUTE command supported by the source or through Windows keystrokes command.
P	Send (POKE) Data To Source Send a single element of data, or table of data, contained in MSG$[5] to the Item(s) specified in MSG$[$].
R	Request Data From Source Retrieve a single element of data, or table of data, for the items specified in MSG$[4], returning data in MSG$[5].
F	Focus Keystrokes To Application Send the keystrokes contained in MSG$[5] to the source application.
E	Execute the Source Command(s) in MSG$[5].
X	Examine the Windows Environment Indicate if the source application contained in MSG$[2] is active. Return the status in MSG$[5].
IN or FN	Initiate Conversation: If application not operating, start the application in Window Style “N” 1,5,9 Normal, with Focus 2 Minimized, with Focus (Default) 3 Maximized, with Focus 4,8 Normal, without Focus 6,7 Minimized, without Focus The result of any “without focus” option will be to have the operation performed invisibly. You must overtly focus the application before the operator can see it. If the application is currently operating, the focus can only be changed by an overt DDE command to the Windows Program Manager. The requested focus in initiation will be ignored.

MSG$[2]: Source Name

The source name is the Windows application with which communication is desired (“EXCEL.EXE” for Excel). It must end in .exe, .com, .bat, or .pif, other than the reserved source object ME.

Gateway for Windows assumes that the source name is the same as the executable program name minus the extension. For example, EXCEL.EXE translates to source name EXCEL. Where the initiation source name is different from the name used for DDE communications, enclose the source name in parentheses, for example MYPROG.EXE(SUPERC).

MSG$[3]: Source Topic

The source topic is the Windows application topic (SYSTEM or Open Document Name with extension for Excel). This may also be the keyword SERVER when initiating or terminating the host environment as a server process.

MSG$[4]: Source Item

The source items are the functions “P” & “R” or referenced item(s). They are formatted as: c|Item1||Item2|…0 (row/column reference for Excel).

MSG$[5]: Data

Function “P” - The data to send formatted as: c|data1||data2|…0

Function “R” - The data received formatted as: c|data1||data2|…0

Function “E” - The source commands to execute

Function “F” - The keystrokes to send to the source application

Function “X” - The application status, returned as:

|Y| = Yes - The application is active.

|N| = No - The application is not active.

Multiple Item Send and Retrieve

Multiple items can be sent or retrieved by providing a string for the source item (functions “P” & “R”) and source data (function “P”) with each entry enclosed in piping ( | ). Two Excel Cells could be sent by sending the following:

MSG$[1] = "P"
MSG$[2] = "EXCEL.EXE"
MSG$[3] = "SHEET1"
MSG$[4] = "|R1C1||R1C2|"
MSG$[5]= "|A||1|"

Data can be retrieved as follows:

MSG$[1] = "R"
MSG$[2] = "EXCEL.EXE"
MSG$[3] = "SHEET1"MSG$
[4] = "|R1C2||R1C1|"

After CALL:

MSG$[0] = "."
MSG$[5] = "|1||A|"

With multiple item entries, DDE failure will result in no data being returned (function “R”) or an
unknown number of entries being complete (function “P”).

“ME” as Both Destination and Source

For source name you may also use the keyword “ME” for the function code “F” (Focus). This allows you to designate your host application as both the sender of keystrokes and as the receiver of the same keystrokes.

Keystrokes sent with the “ME” source name, would be returned to the host Task approximately 1 second after being sent. This allows you to call Gateway for Windows with an entire series of keystrokes, get a good response (MSG$[0] = “.”), and then branch to your normal application input code. The keystrokes will then be returned to the host program just as if they were entered from the keyboard.

Using function code “F” with the “ME” source name, but with no keystrokes, will result in focusing the Windows Program Manager to the host program Windows terminal task. This ensures that subsequent entries from the keyboard will apply to your UNIX host task.

Sending invalid keystrokes will result in a “no-op” in Gateway for Windows if you are using the “ME” source name. Attempting to send invalid keystrokes to any other source application will result in a normal Gateway for Windows error returned in MSG$[0].

Creating a Keystroke File in the Workstation

Keystrokes (or any data) may also be recorded in a file on the workstation prior to execution by sending a file command using the item variable MSG$[4].

O.FILENAME creates a new file;
I.FILENAME reads the keystrokes from an existing file created using “O.”

Filename may specify any valid path on the workstation.

Re-Sizing the “ME” Window

The “ME” terminal window can be re-sized from the host by sending a suitable Windows command in MSG$[5]. You may choose from:

MSG$[5]="WINDOW RESTORE"
MSG$[5]="WINDOW MINIMIZE"
MSG$[5]="WINDOW MAXIMIZE"
MSG$[5]="WINDOW MOVE(XXX,YYY,CH_WIDTH,LINE_LENGTH"

where xxx and yyy are screen co-ordinates, CH_WIDTH is the required character width and
LINE_LENGTH is the number of lines required to be displayed on the screen.

SendKeys Format

The following describes the format for Visual Basic SendKeys, used by Gateway for Windows to send keystrokes to an application. The instruction format is taken directly from the Microsoft Visual Basic Language Reference.

One or more characters represent each key. To specify a single keyboard character, use the character itself. To represent more than one character, append each to the one preceding it. For example, to represent the letters A, B, C use “ABC” for keytext.

The plus sign (+), caret (^), tilde (~), and parenthesis () have special meanings to Sendkeys. To specify one of these, enclose it inside braces {}. Brackets [] have no special meaning, but must also be enclosed in braces. To send a brace use {{} or {}}.

To send keys combined with any combination of SHIFT, CTRL, and ALT keys, precede the key code with one or more of the following:

SHIFT: + CTRL: ^ ALT: %

To obtain, for example, SHIFT with E and C use parentheses: “+(EC)”.

To specify characters that are not displayed when you press a key (such as ENTER or TAB) use the codes in the following table.

Note

Key	Code	Key	Code	Key	Code
Back	{BACKSPACE}	Break	{BREAK}	Caps	{CAPSLOCK}
Space	or {bs} or			Lock

{bksp}

Clear	{CLEAR}	Del	{DELETE}	Down	{DOWN}
			or {DEL}	Arrow
End	{END}	Enter	{ENTER}	Esc	{ESCAPE}

or ~                 or {ESC}

Help

{HELP} Home {HOME} Ins {INSERT}

Left

{LEFT} Num {NUMLOCK} Page {PGDN}

Note

Arrow		Lock		Down
Page Up	{PGUP}	Print	{PRTSC}	Right	{RIGHT}
		Screen		Arrow
Scroll	{SCROLLLOCK}	Tab	{TAB}	Up	{UP}
Lock				Arrow
F1	{F1}	F2	{F2}	F3	{F3}
F4	{F4}	F5	{F5}	F6	{F6}
F7	{F7}	F8	{F8}	F9	{F9}
F10	{F10}	F11	{F11}	F12	{F12}
F13	{F13}	F14	{F14}	F15	{F15}
F16	{F16}
:::

Note

SendKeys cannot send keystrokes to an application that is not designed to run in Microsoft Windows. Also, SendKeys cannot send the Print Screen key to any application.

Special SendKeys

Gateway for Windows also recognizes two special SendKey formats:

{PAUSE} causes Gateway for Windows to wait four seconds before sending all of the keystrokes preceding the {PAUSE}. This is particularly valuable when using Gateway for Windows to focus keystrokes to an application using ‘CI’ (Host Clear Input Buffer). Keys to be sent after the {PAUSE} will not be affected by the ‘CI’. You can also create a timed running demonstration using this capability. Multiple pauses can be included as {PAUSE}{PAUSE}, creating a total pause time of approximately 8 seconds.

{M:….Message Text….:M} Enclosing a message between message braces {M: and :M} will cause the message to be displayed on the monitor in a Windows Message Box before the key string preceding the message is sent to the host. If a {PAUSE} command does not immediately precede the message, Gateway for Windows will insert one automatically. This allows you to include explanation text along with your self-running demo without modifying your application.

Implementation Guidelines

Adding Gateway for Windows task communication to your application can be accomplished with a minimum of 3GL or 4GL code.

All Applications

For all Windows applications with which you wish to interface, you will need to become familiar and comfortable with the normal operation of the product from the keyboard. You cannot possibly hope to interface properly with an application with which you are not familiar.

Applications Supporting DDE

For applications supporting DDE, you will need to know the format of instructions the application will accept through DDE. Each application is different, and each application supplier documents these instructions in a different manner. Excel, for example, documents each DDE instruction in a separate publication call “Function Reference.” Most of the instructions in this publication can be sent from another application using DDE.

If you are in doubt about the correct DDE instruction to send, you can often turn to the operation of the application itself for examples. Many Windows applications, including Excel, have a Macro Record capability, where anything you accomplish with the mouse or from the keyboard is recorded in a file as a Macro Instruction. Thus, you can: (1) turn on Macro Recording, (2) format your data the way you wish, (3) turn off Macro Recording, (4) examine the Macro File to determine the appropriate formatting instructions, and (5) include the host instructions in your Gateway for Windows communication from your host application.

GWWLOC

VIP Gateway for Windows includes a File Location DDE Server application that can be very useful when communicating with workstation applications. GWWLOC locates a specific filename anywhere on the user’s workstation or attached file system. If GWWLOC can locate the file, the complete directory path is made available to the host destination program.

Most PC-based applications require a complete path to be given when a file is to be manipulated. When the host application programmer is sure of the file name required, but not of the entire directory structure within the PC file system, GWWLOC becomes invaluable.

GWWLOC will search for a file in the following order:

• The current directory
• The WINDOWS directory
• The WINDOWS SYSTEM directory
• The VIP directory
• All directories specified in the PATH environment variable
• All directories mapped into the network

Instructions for using GWWLOC are provided in the Other Applications ReadMe file distributed with the software.

Suggested Implementation Approaches

The following suggestions will help you minimize the amount of coding required for interface with most applications.

Isolate Communication Code into One Public Program

While you can include Gateway for Windows communication code in each application process from which you wish to communicate, that is not really an efficient manner to handle this communication. A better way is to develop a single public program for each application with which you wish to communicate. This program can then be called from any application process, supplying the desired parameters for the function required. In this manner, Windows communication is focused into one program, and the number of lines of code required from the application process can be minimized.

As an example, the sample program GWWXCEL described in the following pages contains all the code necessary to create a fully functional Excel Spreadsheet. This program can be called from any application program with a single statement, only requiring you to supply the data to be charted and the associated titles.

Communication Libraries for popular workstation products, containing the required software plus helpful advice in using Gateway for Windows, are also published as part of the VIP family of products and are available through your usual sales representatives.

Avoid Over Engineering

Most Windows applications allow a great deal of flexibility, particularly in the area of display formatting. As an example, Excel allows the operator to display data using Bar Charts, Pie Charts, 3D, etc., usually with only one or two keystrokes. You should not be concerned with building or allowing selection of all these options from the host; simply choose a single default format, build the chart using the necessary commands for that format, then let the operator override that format, using the standard application capabilities, after the initial display.

From the Gateway for Windows Reference, version 8.9.1. Open this page in the PDF