Send Key (3)

Top  Previous  Next

The Send Key function is used to send either a keystroke or a string of keystrokes to the host presentation space.


You define the string of keystrokes to be sent with the calling data string parameter. The keystrokes appear to the target session as though they were entered by the terminal operator. You can also send all attention identifier (AID) keys such as Enter and so on. All host fields that are input protected or are numeric only must be treated accordingly.








Prerequisite Calls


Connect Presentation Space (1)



Call Parameters



Standard Interface

Enhanced Interface

Function Number

Must be 3.


Data String

A string of keystrokes, maximum 255. Uppercase and lowercase ASCII characters are represented literally. Function keys and shifted function keys are represented by mnemonics. See Keyboard Mnemonics.



Length of the source data string. Overridden if in EOT mode.


PS Position





Return Parameters


Return Code



The keystrokes were sent; status is normal.


Your program is not connected to a host session.


An incorrect parameter was passed to EHLLAPI.


The host session was busy; all of the keystrokes could not be sent.


Input to the target session was inhibited or rejected; all of the keystrokes could not be sent.


A system error was encountered.





1.The parameters under the Set Session Parameters (9) function are related to this function. They are the AUTORESET/NORESET, STRLEN/STREOT, EOT=c, ESC=c, and RETRY/NORETRY session options.
2.Keystrokes cannot be sent to the host session when the keyboard is locked or busy. You can check this condition with the Wait (4) function.
3.If the host is busy, input might be rejected.
4.The length of the data string must be explicitly defined by the default length parameter, but it can be defined implicitly by the EOT=c option of the Set Session Parameters (9) function.

When explicitly defining length, the value for the 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.

5.To send special control keys, a compound character coding scheme is used. In this coding scheme, one keystroke is represented by a sequence of two to four ASCII characters. The first and third character are always the escape character. The second and fourth character are always a keycode.

To send the sequence LOGON ABCDE followed by the Enter key, you would code the string LOGON ABCDE@E. A complete list of these keycodes is represented in Keyboard Mnemonics.

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

The default escape character is @. The value of the escape character can be changed to any other character with the ESC=c option of the Set Session Parameters (9) function.

6.Users needing higher levels of performance should use the Copy String to Field (33) or Copy String to Presentation Space (15) function rather than send keystrokes with the Send Key (3) function. But remember, only the Send Key (3) function can send the special control keys.
7.Refer to Set Session Parameters (9) session option 10 (NORESET option) to improve the performance of this function.

Unless NORESET is required, the reset mnemonic is added to the keystroke strings as a prefix. Therefore, all resettable status except input inhibit are reset.

The NORESET option is not the same as the Reset System (21) function.

8.The keystroke strings, including the AID key, are sent to the host via multiple paths. Each path sends the strings before the first AID key (or including the AID key). EHLLAPI adjusts the string length and the start position of each path. For a host application program, any keystroke might be lost by the AID key process. Therefore, you should not send a keystroke list that includes plural AID keys.
9.During the @P (Print) or @A@T (Print Presentation Space) process, all requests that update the presentation space are rejected. If the presentation space is busy or the interruption request occurs during the print request, the mnemonic @A@R (Device Reset - Cancel to print the Presentation Space) cancels the request and resets the status.