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

GET KEY (51)

Purpose

Intercepts keystrokes from sessions specified by the START KEYSTROKE INTERCEPT (50) function and then process, accept, or reject the keystrokes.

Prerequisite Calls

This function requires a prerequisite call to the START KEYSTROKE INTERCEPT (50) function.

Syntax

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

Supplied Parameters

Supply the following parameters to invoke the GET KEY function:

func Specifies the number of the function called; must be 51 for the GET KEY function.
apistring Specifies the attributes of the API string; the calling data string can contain:
Byte Definition
Position 1 One of the following:
  • A one-character presentation space (PS) short session ID
  • A blank or null character indicating a function call against the currently connected presentation space
Positions 2-8 Space for the symbol representation of the requested data; the previous field, either protected or unprotected
len Does not apply for this function (length of 8 bytes is implied).
ret Does not apply for this function.

Returned Parameters

The GET KEY function returns the following values:

apistring The following are valid:
Position 1 One of the following:
  • A one-character short session ID of the PS
  • A blank or null character indicating a function call against the currently connected PS
Position 2 A code character, which is one of the following:
  • A for ASCII-returned
  • M for keystroke mnemonic
  • S for special shift (Alt or Ctrl) returned with other data
Positions 3-8 The 6 bytes of a previously allocated buffer space to be used internally for enqueuing and dequeuing keystrokes. Possible combinations include the following:
  • Byte 3 contains an ASCII character and byte 4 contains X' 00'.
  • Bytes 3 and 4 contain a keystroke mnemonic (@ or ESC=n character plus an ASCII character).
  • Bytes 5 through 8 may be similar to bytes 3 and 4 if a returned ASCII mnemonic is longer than 2 bytes (for example, in the ASCII mnemonic representing Attn, @A@Q , @ would be in byte 5 and Q in byte 6). If not used, positions 3-6 are set to X' 00'.
    Note: For DBCS, bytes 3 and 4 contain a DBCS character, and bytes 3 through 6 contain a MBCS character.

    For clarification, examples of returned data strings follow:

    EAt E is the presentation space. The keystrokes returned are ASCII. The key being returned is a t (lowercase letter T) (Bytes 4-8 = X' 00' ).
    EM@2 E is the presentation space. The keystrokes returned are represented by an ASCII mnemonic. The key being returned is PF2 (Bytes 5-8 = X' 00' ).
    ES@Aa E is the presentation space. The keystrokes returned are in special shift state. The keys being received are Alt+a.
ret The following codes are valid:
0 Indicates the GET KEY function was successful.
1 Indicates the PS is invalid.
5 Specifies that under the START KEYSTROKE INTERCEPT (50) function, you specified the D option for attention-identifier (AID) keystrokes only. Non-AID keys are inhibited by this session when HLLAPI tries to write invalid keys to the PS.
8 Specifies that no prior START KEYSTROKE INTERCEPT (50) function was called for this PS.
9 Indicates a system error occurred.
20 Specifies that the operator entered an invalid combination of keys for this presentation space session.
25 Specifies that the requested keystrokes are not available on the input queue.
31 Specifies that the keystroke queue overflowed and keystrokes were lost.

Remarks

The GET KEY function behaves as a read command. When keystrokes are available, they are read into the data string you provide with the GET KEY function. User keystrokes are queued by HLLAPI. The GET KEY function dequeues these keystrokes and returns them to the requester one at a time. The GET KEY function is affected by the NWAIT/LWAIT/TWAIT session options. See session option 8 in SET SESSION PARAMETERS (9).

You can use the SEND KEY (3) function to pass both original keystrokes and any other keystrokes that your HLLAPI application wants to send to the target presentation space. Refer to the Keyboard Mnemonics table for a listing of supported keystroke values.

Related Information

SEND KEY (3) function , SET SESSION PARAMETERS (9) function and START KEYSTROKE INTERCEPT (50) function.

[ Previous | Next | Contents | Search ]