GUI ScreenIO for Windows

ScreenIO.com

Simulated Keys

This API lets the program simulate the pressing of keys on the keyboard.  These keys are fed directly into the keyboard driver, and then back to the GUI ScreenIO runtime as if the user had pressed the keys.  ScreenIO will not be able to tell that these keys did not come from the user.

You can submit up to 256 keys on one call to this API. 

You must specify each key press.  And, for certain keys, each key release.  Example: If you need to insert a capital B, you must specify a Shift key (to get in upper case) a B key, and an Shift-Key-release.  This is because shift keys, (Shift, Alt, Ctrl) need to remain down for the duration of all characters that need that shift state, and because of this, we can not know when to release that shift state without explicit directions.

GUI ScreenIO restricts keystrokes to the panel that was active at the time the keys strokes entered the message queue.  This means you really can't use this facility to load keystrokes into the buffer for several subsequent panels.

Client/Server issues

This API will normally simulate key presses on the keyboard of the client.  If you want to feed keys to keyboard on the server, you can select this as follows:

Note:  We do not recommend this because you can never be sure what screen (if any) is available on the server's console to receive these keystrokes.  It is entirely possible to feed keys to what ever window has focus at the time the API call is made. 

Files

Files available to copy to your system:

• SIMKEYS.COB - COBOL copybook with arguments for this function
• WIN32API.COB - COBOL copybook common to all APIs and functions

Usage

Parameters specific to this function

SIMULATE-KEYS-SEQUENCE

This is a 256 byte array of keys that you can send to the keyboard driver.  The keys are set by using the 88s supplied in the copybook.

To send letters and numbers, you may simply move the CAPITOL letter or number to the appropriate slot in the key sequence table.

The first low-value will terminate the key sequence.

The special 88 values in the copybook may be selected by simply setting the key name to true followed by a subscript.  For example, assume you want to tab forward twice based on some situation your program detects.  You would simple load your tabs into the SIMULATE-KEYS-SEQUENCE field as follows:

     SET SK-TAB (1) TO TRUE
     SET SK-TAB (2) TO TRUE

Note that tabbing in this way relieves your program from having to know the field numbers, but is every bit as likely to be messed up by changes in the panel over time, so it is best to copiously document any such usage.

As mentioned above, some shift states need to bracket other keys.  See the sample code in the Usage example above where the tab key is bracketed by a SK-SHIFT and a SK-SHIFT-UP.  Remember to un-shift any shift states you send.

Letters and numbers are moved directly to the Cell in the array where they are desired.  Example:  To cause the machine to type the word "ScreenIO" you would use the following code:

     SET SK-SHIFT (1) TO TRUE
     MOVE 'S' TO SIMULATE-KEYS-SEQUENCE (2)
     SET SK-SHIFT-UP (3) TO TRUE
     MOVE 'C' TO SIMULATE-KEYS-SEQUENCE (4)
     MOVE 'R' TO SIMULATE-KEYS-SEQUENCE (5)
     MOVE 'E' TO SIMULATE-KEYS-SEQUENCE (6
     MOVE 'E' TO SIMULATE-KEYS-SEQUENCE (7)
     MOVE 'N' TO SIMULATE-KEYS-SEQUENCE (8)
     SET SK-SHIFT (9) TO TRUE
     MOVE 'I' TO SIMULATE-KEYS-SEQUENCE (10)
     MOVE 'O' TO SIMULATE-KEYS-SEQUENCE (11)
     SET SK-SHIFT-UP (12) TO TRUE

Clearly there are easier ways.  We don't recommend this a normal text input method.

You can use this API to set Num Lock and if your users are going to be using the numeric pad for data entry.  You can first check to see if the numeric pad is in Number mode by using our KeyState API. Num Lock is a toggle key, and each press changes its state. So turning it on when it is already On will be counter productive.  Caps Lock and Insert mode can also be set this way, but these will not over-ride field definitions for upper case or lower case as designed in the editor. 

IMPORTANT

If some other window gains focus while your code is running this API those keystrokes may get sent to that other window.  This may be desirable in the case where you want to launch another program with our WinExec api and then feed keystrokes to that program.  Because at least half of this transaction is beyond our control we can not guarantee this will work.  Things can go horribly wrong, especially if the users starts clicking other applications into focus because they were surprised to see another window open up.

Finally, you must call GS with a panel after feeding these keys into the keyboard buffer in order for GUI ScreenIO to actually see the keys and act upon them.  COBOL is a single thread language, and while your program is busy stuffing keys in the keyboard buffer, GS32.dll (the GUI ScreenIO runtime) is not getting any opportunity to process those keys.  So be sure to insert calls to a panel periodically.  This is why the buffer is limited to 256 characters.

NOTE:

Not all keys are guaranteed to work on all machines, and some of these keys are sure to be unavailable on any given keyboard. These keys are passed thru your keyboard driver. Therefore, use of keys unknown to your keyboard driver is not recommended and the result remains undefined. 
Pay attention to the notes in the copybook about some of the special cases for specific keys.

WIN32API-PARMS - Used in all GSWINAPI calls

This argument is standard for all Calls to GSWINAPI. It is used to select the desired API or function, and to return the status of the operation.

WIN32API-RC

Used to return the status of a call to GSWINAPI.  A value of zero is a failure, any other value indicates success. 

The value returned, (if greater than zero) is the actual number of characters converted.

Recommended usage is to test the 88-level value WIN32API to see if it worked, then to use the text error message to see why it failed.

WIN32API-ERROR-CODE

Error code that was returned by Windows.  This is not generally useful unless you have the Windows Platform SDK documentation available to you.

WIN32API-ERROR-TEXT

Plain-text error message that describes why the operation failed.

WIN32API-A through WIN32API-F

The number of these present varies depending on how many arguments are used by the desired function.  These are not used, but must be present because this CALL requires seven arguments.