Get Key – Function 51

This function allows your Windows HLLAPI application to intercept keystrokes from Host sessions that have keystroke intercept enabled, and to process those keystrokes.

Prerequisite functions

Start Keystroke Intercept (function 50)

Function call

WinHLLAPI(GETKEY,lpbyString,lpwLength,lpwReturnnCode)

Call parameters

Parameter	Description
Data String	An 8-byte string in the following format: Byte 1 Short name session ID of the desired Host session, or space or null for the current Host session. Bytes 2-8 Reserved for return data.
Data Length	NA (length of 2 is implied).
PS Position	NA

Return parameters

Parameter	Description
Data String	An 8-byte string in the following format: Byte 1 Short name session ID of the desired Host session, or space or null for the current Host session. Byte 2 Keystroke code. “A” indicates an ASCII character; “M” indicates a 3270 function key code; “S” indicates a special key modifier (SHIFT, CTRL, or ALT) state. Bytes 3-8 Keystroke(s). Unused bytes are set to null (00h). See “Remarks” section for details.
Data Length	Number of characters in the returned mnemonic.

Parameter

Description

Data String

An 8-byte string in the following format:

Byte 1 Short name session ID of the desired Host session, or space or null for the current Host session.

Byte 2 Keystroke code. “A” indicates an ASCII character; “M” indicates a 3270 function key code; “S” indicates a special key modifier (SHIFT, CTRL, or ALT) state.

Bytes 3-8 Keystroke(s). Unused bytes are set to null (00h). See “Remarks” section for details.

Data Length

Number of characters in the returned mnemonic.

Return code

Code	Description
WHLLOK	Keystroke(s) successfully returned.
WHLLNOTCONNECTED	The Host session presentation space is invalid.
WHLLPARAMETERERROR	One or more of the call parameters are invalid.
WHLLINHIBITED	Start Keystroke Intercept (function 50) was called with the “D” option (intercept AID keys only). Non-AID keys are not returned.
WHLLNOTAVAILABLE	Start Keystroke Intercept (function 50) was not called prior to this function call.
WHLLSYSERROR	The function failed due to a system error.
WHLLUNDEFINEDKEY	The user entered an invalid key combination for this Host session presentation space.
WHLLNOKEYSTROKES	There are no keystrokes available in the keystroke queue.
WHLLKEYOVERFLOW	The keystroke queue has overflowed and keystroke(s) were lost.

Remarks

This function is affected by the session options ESC=c and NWAIT/LWAIT/TWAIT. See Set Session Parameters (function 9) for details. Of particular importance is the ESC=c session option: the escape character may be set to something other than the default of the at sign (@), which is used in the keystroke examples.

Keystrokes entered by the user are queued by WinHLLAPI. Use this function to read the keystrokes from the queue one at a time. You can then use Send Key (function 3) to pass the original keystrokes and/or any other keystrokes you want to send to the Host session presentation space.

The special key modifiers that can be returned indicate which key modifier is active:

@A	ALT key active
@S	SHIFT key active
@	CTRL key active

The 3270 function key codes are defined under Send Key (function 3).

Returned Data String Examples

BAt	“B” is the short name session ID of the Host session. Returned keystroke is ASCII lowercase t (bytes 4-8 are null, 00h).
FM@2	“F” is the short name session ID of the Host session. Returned keystroke is the 3270 function key code for PF@ (bytes 5-8 are null, 00h).
KS@Aa	“K” is the short name session ID of the Host session. Returned keystroke with special key modifier is ALT+A (bytes 6-8 are null, 00h).
MS@rA	“M” is the short name session ID of the Host session. Returned keystroke with special key modifier is CTRL+SHIFT+A (bytes 6-8 are null, 00h). Note that because both the CTRL and SHIFT keys are active, only the CTRL key modifier is indicated but the SHIFT key is implicitly defined by the uppercase A.