[ Previous | Next | Contents | Search ]
3270 Host Connection Program 2.1 and 1.3.3 for AIX: Guide and Reference

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:

func Specifies the number of the function called; must be a 3 for the SEND KEY function.
apistring Specifies the attributes of the data string; must a string of keystrokes, maximum 255 bytes.
len Specifies the length of the source data string. This parameter is overridden if in EOT mode.
ret Does not apply for this function.

Returned Parameters

ret The following codes are valid:
0 Indicates the keystrokes were sent; status was normal.
1 Indicates your program was not connected to the host session.
2 Specifies that an incorrect parameter was passed to HLLAPI.
4 Specifies that the host session was busy; all of the keystrokes could not be sent.
5 Specifies that the input to the target session was inhibited; keystrokes were rejected or invalid keystroke mnemonics were sent. All of the keystrokes could not be sent.
9 Indicates a system error occurred.
Notes:
  1. See session option 7 (NORESET option) in SET SESSION PARAMETERS (9) function to increase the performance of this function.
  2. If NORESET is not requested, a reset mnemonic is always prefixed to the keystroke string. This will reset all states that can be reset except input-inhibited states.
  3. The NORESET option is not the same as the RESET SYSTEM (21) function.

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.

Mnemonics with Uppercase Alphabetic Characters
ASCII Mnemonic Meaning
@B Left Tab
@C Clear
@D Delete
@E Enter
@F Erase EOF
@I Insert
@L Cursor Left
@N New Line
@P Print
@R Reset
@T Right Tab
@U Cursor Up
@V Cursor Down
@X Alternate Character Set (DBCS)
@Z Cursor Right
Mnemonics with Lowercase Numbers or Letters
ASCII Mnemonic Meaning
@0 Home
@1 PF1/F1
@2 PF2/F2
@3 PF3/F3
@4 PF4/F4
@5 PF5/F5
@6 PF6/F6
@7 PF7/F7
@8 PF8/F8
@9 PF9/F9
@a PF10/F10
@b PF11/F11
@c PF12/F12
@d PF13
@e PF14
@f PF15
@g PF16
@h PF17
@i PF18
@j PF19
@k PF20
@l PF21
@m PF22
@n PF23
@o PF24
@x PA1
@y PA2
@z PA3
Mnemonics with @A and @ Uppercase Alphabetic Characters
ASCII Mnemonic Meaning
@A@D Word Delete
@A@F Erase Input
@A@H System Request
@A@I Insert Toggle
@A@J Cursor Select
@A@Q Attention
@A@T Print Presentation Space
ASCII Mnemonics Using Data Keys and Combinations of "Shift" (@S) and "@" Uppercase Alpha Keys
ASCII Mnemonic Meaning
@S@P POR
@S@x Dup
@S@y Field Mark
Note: @S@P for sending only
Mnemonics with @X and @ Numeric Keys
ASCII Mnemonic Meaning
@X@l SI/SO toggle key (DBCS only)
Mnemonics with Special Character Keys
ASCII Mnemonic Meaning
@@ @
@< Backspace
Alphabetic Keys
ASCII Mnemonic Meaning
a - z a - z
A - Z A - Z
0 - 9 0 - 9
~ ~
# #
! !
$ $
% %
& &
' '
( (
) )
* *
+ +
- -
. .
/ /
: :
; ;
< <
> >
= =
? ?
{ {
} }
[ [
] ]

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:

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.


[ Previous | Next | Contents | Search ]