|
The Get Key function lets your EHLLAPI application program retrieve a keystroke from a session specified by the Start Keystroke Intercept (50) function and either process, accept, or reject that keystroke. By placing this function in a loop, you can use it to intercept a string.
Prerequisite Calls
Start Keystroke Intercept (50)
Call Parameters
|
Standard Interface
|
Enhanced Interface
|
Function Number
|
Must be 51
|
|
Data String
|
See the following table
|
|
Length
|
8
|
12
|
PS Position
|
NA
|
|
Data String Contents
Byte
|
|
Definition
|
Standard
|
Enhanced
|
|
1
|
1
|
One of the following values:
| • | A 1-character presentation space short name (PSID) |
| • | A blank or null indicating a function call for the host-connected presentation |
|
|
2-4
|
Reserved
|
2-8
|
5-11
|
Blanks that hold space for the symbolic representation of the requested data
|
|
12
|
Reserved
|
Return Parameters
This function returns a data string and a return code.
Data String
See the following table:
Byte
|
|
Definition
|
Standard
|
Enhanced
|
|
1
|
1
|
One of the following values:
| • | A 1-character presentation space short name (PSID) |
| • | A blank or null indicating a function call for the host-connected presentation |
|
|
2-4
|
Reserved
|
2
|
5
|
An option code character, one of the following characters:
| • | M for keystroke mnemonic |
|
3-8
|
6-11
|
These 6 bytes of the preallocated buffer space are used internally to enqueue and dequeue keystrokes. Possible combinations include:
| • | Byte 3 contains an ASCII character and byte 4 contains X'00' |
| • | Bytes 3 and 4 contain a double-byte character |
| • | Byte 3 contains the escape character (either @ or another character specified using the ESC=c option of function 9) and byte 4 contains a 1-byte abbreviation for a function. |
| • | Bytes 5 through 8 might be similar to bytes 3 and 4 if the returned ASCII mnemonic is longer than 2 bytes (for example, if the ASCII mnemonic represents Attn @A@Q, byte 5 contains @ and byte 6 contains Q). If not used, bytes 5 through 8 are set to zero (X'00'). |
|
Note:
The @ symbol is the default escape character. The value of the escape character can be set to any keystroke represented in ASCII by using the ESC=c option of the Set Session Parameters (9) function. If the escape character has been changed to another character using this option, the @ symbol in the following examples is replaced by the other character.
Return Code
The following codes are valid:
Return Code
|
Explanation
|
0
|
The Get Key function was successful.
|
1
|
An incorrect presentation space was specified.
|
5
|
You specified the AID only option under the Start Keystroke Intercept (50) function, and non-AID keys are inhibited by this session type when EHLLAPI tries to write incorrect keys to the presentation space.
|
8
|
No prior Start Keystroke Intercept (50) function was called for this presentation space.
|
9
|
A system error was encountered.
|
20
|
An undefined key combination was typed.
|
25
|
The requested keystrokes are not available on the input queue.
|
31
|
Keystroke queue overflowed and keystrokes were lost.
|
Remarks
| 1. | If a return code of 31 occurs for the Get Key function, either: |
| • | Execute the Get Key function more frequently. |
An intercepted keystroke occupies 3 bytes in the buffer. The next intercepted keystroke is placed in the adjacent three bytes. When the Get Key function retrieves a keystroke (first in first out, FIFO), the three 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.
For the PC/3270, another way to eliminate return code 31 is to operate the PC/3270 emulator in the resume mode.
| 2. | You can use the Send Key (3) function to pass both original keystrokes and any others that your EHLLAPI application might need to the host-connected presentation space. |
| 3. | Keystrokes arrive asynchronously and are enqueued in the keystroke queue that you have provided in your EHLLAPI application program using the Start Keystroke Intercept (50) function. |
| 4. | The Get Key function behaves like a read. When keystrokes are available, they are read into the data area that you have provided in your application. |
| 5. | In the case of field support for a session, the application might be interested only in AID keys, for example the Enter key. If so, the Start Keystroke Intercept (50) function option code should be set to D (meaning for AID Keys only). |
| 6. | To use this function, preallocate memory to receive the returned data string parameter. The statements required to preallocate this memory vary depending on the language in which your application is written. |
|