This routine lets you add characters to the runtime's keyboard input buffer. This allows a program to simulate user input.
Usage
CALL "W$KEYBUF" USING OP-CODE, parameters
Parameters
OP-CODE PIC 9(1)
OP-CODE parameters
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:
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.
8 Op-code "8" is identical to op-code "7", except that the file is appended to if it already exists.
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.
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.
Special keystrokes
You may specify special keystrokes by placing code names in curly braces. Within curly braces, you may use the caret to indicate control characters. For example, "{^M}" indicates Control-M.
You may also use a special key's two-character name as found in the Table of Keys in the ACUCOBOL-GT User's Guide, section 4.3.4. 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.