This routine lets you add characters to the runtime's keyboard input buffer. This allows a program to simulate user input.
CALL "W$KEYBUF"
USING OP-CODE, parameters
| OP-CODE PIC 9(2) | Vary depending on the op-code chosen |
The first parameter to W$KEYBUF is a number that determines the action of the routine. The following options are supported:
| op-code | Description |
|---|---|
| 1 | Use op-code 1 to add keystrokes to the keyboard input buffer. In this case, the second parameter to W$KEYBUF specifies the key or keys you want to add. Optionally, you may also specify a third parameter that contains the number of characters you want to add. If you omit the third parameter, then all of the second parameter is used (including any trailing spaces). When keystrokes are added to the input buffer, they are placed after any previously added keystrokes, but before any keys typed by the user. This ensures that the user does not interfere with your programmatic control. |
| 2 | This is the same as 1 except that the characters are added at the beginning of the input buffer instead of at the end. |
| 3 | Use op-code 3 to empty the input buffer. This can be useful in some error handling routines. Note that this routine does not empty the operating system's input buffer--any keys queued up by the user are still available. Only keys added with W$KEYBUF are removed. |
| 4 | Op-code 4 turns on the keystroke recording mechanism. You must pass as a second parameter the name of a buffer in which you want to place the recorded keystrokes. The buffer is a field you have defined in the Data Division. The size of this buffer limits the number of keystrokes recorded. You may optionally pass a third parameter that is the size of the buffer. If you omit the third parameter, then the entire buffer is used. The keystroke recorder does not initialize the buffer, and it does not modify any part of the buffer that follows the last recorded keystroke. |
| 5 | Op-code 5 turns off the keystroke recorder. This action sets RETURN-CODE to the number of characters used in the buffer to hold the recorded keystrokes. |
| 6 | Op-code 6 inquires whether or not the keystroke recorder is active. This will set RETURN-CODE to 1 if keystroke recording is currently turned on. If it is turned off, then RETURN-CODE will be set to 0. |
| 7 | Op-code 7 causes keys typed by the user to be recorded in a file. You pass the name of the file as the first parameter after the op-code. If that file exists, it is deleted first. If the file is successfully created, then RETURN-CODE is set to zero. If the file cannot be created, then RETURN-CODE is set to 1. You use op-code 5 to turn off the recording. Only one recording mode can be active at once, so this op-code will cancel any other active keystroke recording. In thin client environments, keys typed by the user are recorded in a temporary local file. That file is automatically uploaded to the server when recording is stopped with op-code 5. |
| 8 | Op-code 8 is identical to op-code 7, except that the file is appended to if it already exists. In thin client environments, the file is downloaded from the server to the client, appended to, and then uploaded to the server with op-code 5. |
| 9 | Op-code
9 causes a previously recorded file to be
played back. The keystrokes recorded in that file are treated as input from the user. The file name is passed as the first parameter
after the op-code. RETURN-CODE is set to zero if the file is opened successfully, otherwise RETURN-CODE is set to
1. Keystrokes inserted into the keyboard buffer using op-codes
1 or
2 of W$KEYBUF are processed before the keystrokes recorded in the file. Once the keystrokes in the file have all been used,
control passes back to the user's keyboard.
In thin client environments, this op-code first tries to open the file on the client machine using the path specified in the CALL statement. If the file is not found, the thin client requests that the file be downloaded from the server. In this case the path specified in the CALL statement refers to the server machine's file system. The specified path can be an absolute path or a path relative to the current working directory, as specified in the alias file. If the file is found, it is downloaded to the client machine and stored in the thin client's temporary cache directory (the directory specified by the TEMP environment variable; often C:\WINDOWS\TEMP. If the TEMP environment variable is not set, the files are stored in the client's current working directory. The file is not downloaded again unless it changes or is deleted from the client. Note: There is a runtime command-line option that causes the immediate playback of a keystroke file. This option,
-k, causes the next command-line argument to be treated as the name of a file that contains recorded keystrokes. The runtime
internally calls W$KEYBUF using op-code
9 and this file name prior to executing the first COBOL program. The effect is that the keystrokes recorded in the file are
treated as the runtime's first user input.
|
| 10 | Op-code
10 allows you to specify how long the system waits after each simulated keystroke is processed. The delay, expressed in hundredths
of a second, is passed as the second parameter. For example, to add a quarter-second delay to each keystroke, use the following:
CALL "W$KEYBUF" USING 10, 25 You can terminate a pause early by pressing any key. |
| 11 | Op-code 11 defines a key that causes the playback to pause for an indefinite time period, allowing you to explain a special feature. The playback resumes when another key is pressed. To designate the pause key, use op-code 11 with the ASCII value of the key. Note that you can only define a pause key that is a simple ASCII key, not a complex key like a function key. |
| 12 | Op-code 12 defines a key that stops the playback and returns the program to interactive mode. Use op-code 12 with the ASCII value of the cancel key. |
You may specify special keystrokes by placing code names in curly braces. Within curly braces, you may use the caret (^) to indicate Control characters or the "at" symbol (@) to indicate ALT characters. For example, "{^M}" indicates Control+M and "{@L}" indicates ALT+L.
You may also use a special key's two-character name as found in Table of Keys in the ACUCOBOL-GT User's Guide. For example, you may refer to function key 2 with "{k2}".
Menu selections are encoded as {m#} where "#" is the numeric ID of the menu item.
You may insert specific pauses in a simulated input stream using the following character sequences:
| {p#} | where # is in hundredths of a second |
| {P#} | where # is in seconds |
| {P} | 1-second pause |
A programmed pause also includes any pause introduced by op-code 10, described above. You can terminate a pause early by pressing any key.
Finally, if you require an opening curly brace on its own, specify it twice. For example: {{.
The following line specifies that the next characters processed should be abc, Tab, def, and function key 1:
CALL "W$KEYBUF" USING 1, "abc{^I}def{k1}".
The keystroke recording mechanism records normal keys as native characters. The keystroke recorder will not record a time out event.
In order to operate correctly with graphical controls on Windows systems, the W$KEYBUF routine converts characters placed into the keyboard buffer into keyboard scan codes. Thus, you can use only those characters that have a corresponding keyboard scan code. As a result, you can play back non-English characters only when you have installed a keyboard that contains those characters.
The behavior of this routine is affected by the FILENAME_SPACES configuration variable. The value of FILENAME_SPACES determines whether spaces are allowed in a file name. See the entry for FILENAME_SPACES in Appendix H for more information.