Start Keystroke Intercept (50)

Top  Previous  Next

The Start Keystroke Intercept function allows a workstation application to filter any keystrokes sent to a session by a terminal operator. After a call to this function, keystrokes are intercepted and saved until the keystroke queue overflows or until the Stop Keystroke Intercept (53) function or Reset System (21) function is called. The intercepted keystrokes can be:

Received through the Get Key (51) function and sent to the same or another session with the Send Key (3) function
Accepted or rejected through the Post Intercept Status (52) function
Replaced by other keystrokes with the Send Key (3) function
Used to trigger other processes

 

3270

5250

Yes

Yes

 

 

Prerequisite Calls

 

There are no prerequisite calls for this function.

 

 

Call Parameters

 

 

Standard Interface

Enhanced Interface

Function Number

Must be 50

 

Data String

See the following table

 

Length

Keystroke buffer size EHLLAPI allocates 32 bytes minimum for this buffer.

 

PS Position

NA

 

 

The calling data string contains:

 

Byte

 

Definition

Standard

Enhanced

 

1

1

One of the following values:

A specific host presentation space short name (PSID)
A blank or null indicating a request for the host-connected host presentation space

 

2-4

Reserved.

2

5

An option code character:

D for AID keystrokes only.
L for all keystrokes.
M for requesting the asynchronous message mode of the notification (Windows only).  When M is specified, a code character D, or L must be placed in position 13 (7 for 16-bit).

 

6-8

Reserved.

3-4

9-12

When M is specified in position 5 (2 for 16-bit), the window handle of the window that receives the message should be set. The message is a return value of RegisterWindowMessage (PCSHLL) (not equal 0).

7

13

One of the following values if position 5 (2 for 16-bit) is M:

D for AID keystrokes only.
L for all keystrokes.

 

14-16

Reserved.

 

 

Data String

 

If M (asynchronous message mode) is specified in position 5 (2 for standard interface) and the function is completed successfully, the following data string is returned:

 

Byte

 

Definition

Standard

Enhanced

 

1

1

A 1-character presentation space short name (PSID)

 

2-8

Reserved

3-4

9-10

Task ID of asynchronous message mode

 

Note:

If a user sends keystrokes to a session, an application window receives a message. The message is a return value of RegisterWindowMessge (PCSHLL). The wParam parameter contains the Task ID returned by the function call. HIWORD of lParam parameter contains return code 0, which shows that the function was successful, and LOWORD of lParam parameter contains function number 50.

 

 

Return Parameters

 

Return Code

Explanation

0

The Start Keystroke Intercept function was successful.

1

An incorrect presentation space was specified.

2

An incorrect option was specified.

4

The execution of the function was inhibited because the target presentation space was busy.

9

A system error was encountered. Release is being used.

 

 

Remarks

 

1.If a return code of 31 occurs for the Get Key (51) function, either:
Increase the value of the calling length parameter for this function, or
Execute the Get Key (51) function more frequently.

An intercepted keystroke occupies 3 bytes in the buffer. The next intercepted keystroke is placed in the adjacent 3 bytes. When the Get Key (51) function retrieves a keystroke (first-in first-out, or FIFO), the 3 bytes that it occupied are made available for another keystroke. By increasing the size of the buffer or the rate at which keystrokes are retrieved from the buffer, you can eliminate buffer overflow.

In the PC/3270, another way to eliminate return code 31 is to operate the PC/3270 emulator in the resume mode.

2.If option code D is provided, EHLLAPI writes intercepted non-AID keys to the presentation space to which they were originally intended, and returns only AID keys to the application.
3.Call the Stop Keystroke Intercept (53) function before exiting your EHLLAPI application. Otherwise, keystroke interception remains enabled with unpredictable results.