SEND KEY (3)

Purpose

Sends either a keystroke or a string of keystrokes to the currently connected host Presentation Space (PS).

Prerequisite Calls

This function requires a prerequisite call to the CONNECT PRESENTATION SPACE (1) function.

Syntax

hllc (func, apistring, len, ret)
int *func;
char *apistring;
int *len;
int *ret;

Supplied Parameters

Supply the following parameters to invoke the SEND KEY function:

Returned Parameters

Keyboard Mnemonics

Keyboard mnemonics provide ASCII characters that represent the special function keys of the personal computer keyboard. A mnemonic abbreviation code makes these special keys easy to remember. An alphabetic key code is used for the most common keys. For example, the Clear key is C or the Tab key is T. Please note that the uppercase and lowercase alphabetic characters are mnemonic abbreviations for different keys.

ASCII mnemonics are supported in HLLAPI by the 3270 terminal emulator. The following tables list the supported and nonsupported mnemonic keys for 3270 terminal emulation.

Remarks

The SEND KEY function is used to send either a keystroke or a string of keystrokes to the currently connected host PS. You define the string of keystrokes to be sent with the data string parameter. The keystrokes appear to the target session as though they were entered by the user. You can also send all attention identifier (AID) keys such as Enter or PA1. All host fields that are input-protected, or are numeric-only, must be treated accordingly.

The SEND KEY use four sets of parameter options under the SET SESSION PARAMETERS (9) function:

• STRLEN/STREOT
• EOT=c
• AUTORESET/NORESET
• RETRY/NORETRY

Keystrokes cannot be sent to the host session when the keyboard is blocked or in use, but SEND KEY tries to resend the keystrokes until they are sent, or a 4-minute time out occurs. This can be avoided by specifying NORETRY in SET SESSION PARAMETERS (9). The NORETRY option causes the function to return immediately after determining the keyboard is blocked or in use. You can check the keyboard status with the WAIT (4) function.

The length of the data string must, by default, be explicitly defined by using the data string length parameter. Or, the length of the data string can be implicitly defined by using the end of transmission (EOT) delimiter specified with the SET SESSION PARAMETERS (9) function.

When explicitly defining length, the value for the data string length parameter passed by the application must be calculated. For this calculation, allow 2 bytes for compound keystrokes such as @E and allow 4 bytes for compound keystrokes such as @A@C.

To send special function keys, a compound character coding scheme is used. This coding scheme uses ASCII characters to indicate one keystroke and is comprised of the @ sign (default escape character) followed by the key code. For example, to type in the sequence LOGON ABCDE followed by the Enter key, you code the string LOGON ABCDE@E .

This compound coding technique allows an ASCII string representation of all necessary keystroke codes without requiring the use of complex hexadecimal key codes.

If you need higher levels of performance, use the COPY STRING TO FIELD (33) function or the COPY STRING TO PRESENTATION SPACE (15) function rather than send keystrokes with the SEND KEY function. Only the SEND KEY function can send the special function keys.

Keystroke strings with embedded AID keys are sent to the host in multiple passes. Each pass sends a string up to, and including, the first AID key. HLLAPI internally adjusts the length of the string and the starting position for each pass. Depending on the host application, some keystrokes may be lost due to AID key processing. For this reason, sending a list of keystrokes with more than one embedded AID key is not recommended.

While @P (Print) or @A@T (Print Presentation Space) is being processed, any request that updates the PS will be rejected. If a Busy State or Intervention Required occurs during such a print request, the mnemonic @A@R will cancel the request and reset the state.

Related Information

CONNECT PRESENTATION SPACE (1) function, COPY STRING TO FIELD (33) function, COPY STRING TO PRESENTATION SPACE (15) function and SET SESSION PARAMETERS (9) function.