|
The Start Keystroke Intercept function allows a workstation application to filter any keystrokes sent to a session by a terminal operator. After a call to this function, keystrokes are intercepted and saved until the keystroke queue overflows or until the Stop Keystroke Intercept (53) function or Reset System (21) function is called. The intercepted keystrokes can be:
| • | Replaced by other keystrokes with the Send Key (3) function |
| • | Used to trigger other processes |
Prerequisite Calls
There are no prerequisite calls for this function.
Call Parameters
|
Standard Interface
|
Enhanced Interface
|
Function Number
|
Must be 50
|
|
Data String
|
See the following table
|
|
Length
|
Keystroke buffer size EHLLAPI allocates 32 bytes minimum for this buffer.
|
|
PS Position
|
NA
|
|
The calling data string contains:
Byte
|
|
Definition
|
Standard
|
Enhanced
|
|
1
|
1
|
One of the following values:
| • | A specific host presentation space short name (PSID) |
| • | A blank or null indicating a request for the host-connected host presentation space |
|
|
2-4
|
Reserved.
|
2
|
5
|
An option code character:
| • | D for AID keystrokes only. |
| • | M for requesting the asynchronous message mode of the notification (Windows only). When M is specified, a code character D, or L must be placed in position 13 (7 for 16-bit). |
|
|
6-8
|
Reserved.
|
3-4
|
9-12
|
When M is specified in position 5 (2 for 16-bit), the window handle of the window that receives the message should be set. The message is a return value of RegisterWindowMessage (PCSHLL) (not equal 0).
|
7
|
13
|
One of the following values if position 5 (2 for 16-bit) is M:
| • | D for AID keystrokes only. |
|
|
14-16
|
Reserved.
|
Data String
If M (asynchronous message mode) is specified in position 5 (2 for standard interface) and the function is completed successfully, the following data string is returned:
Byte
|
|
Definition
|
Standard
|
Enhanced
|
|
1
|
1
|
A 1-character presentation space short name (PSID)
|
|
2-8
|
Reserved
|
3-4
|
9-10
|
Task ID of asynchronous message mode
|
Note:
If a user sends keystrokes to a session, an application window receives a message. The message is a return value of RegisterWindowMessge (PCSHLL). The wParam parameter contains the Task ID returned by the function call. HIWORD of lParam parameter contains return code 0, which shows that the function was successful, and LOWORD of lParam parameter contains function number 50.
Return Parameters
Return Code
|
Explanation
|
0
|
The Start Keystroke Intercept function was successful.
|
1
|
An incorrect presentation space was specified.
|
2
|
An incorrect option was specified.
|
4
|
The execution of the function was inhibited because the target presentation space was busy.
|
9
|
A system error was encountered. Release is being used.
|
Remarks
| 1. | If a return code of 31 occurs for the Get Key (51) function, either: |
| • | Increase the value of the calling length parameter for this function, or |
An intercepted keystroke occupies 3 bytes in the buffer. The next intercepted keystroke is placed in the adjacent 3 bytes. When the Get Key (51) function retrieves a keystroke (first-in first-out, or FIFO), the 3 bytes that it occupied are made available for another keystroke. By increasing the size of the buffer or the rate at which keystrokes are retrieved from the buffer, you can eliminate buffer overflow.
In the PC/3270, another way to eliminate return code 31 is to operate the PC/3270 emulator in the resume mode.
| 2. | If option code D is provided, EHLLAPI writes intercepted non-AID keys to the presentation space to which they were originally intended, and returns only AID keys to the application. |
| 3. | Call the Stop Keystroke Intercept (53) function before exiting your EHLLAPI application. Otherwise, keystroke interception remains enabled with unpredictable results. |
|