Start Host Notification (23)

Top  Previous  Next

The Start Host Notification function begins the process by which your EHLLAPI application program determines if the host presentation space or OIA have been updated.

 

After using this function, your application program can use the Query Host Update (24) function to determine when a host event has occurred.

 

3270

5250

Yes

Yes

 

 

Prerequisite Calls

 

There are no prerequisite calls for this function.

 

 

Call Parameters

 

 

Standard Interface

Enhanced Interface

Function Number

Must be 23

 

Data String

Preallocated string; see the following table

 

Length

6 or 7 implied

16

PS Position

NA

 

 

The calling data string contains these elements:

 

Byte

 

Definition

Standard

Enhanced

 

1

1

One of the following values:  A 1-character presentation space short name (PSID)  A blank or null indicating a request for the host-connected host presentation space

 

2-4

Reserved.

2

5

One of the following values:

The character B asking for notification of both host presentation space and OIA updates.
The character O asking for notification of only OIA updates.
The character P asking for notification of only host presentation space updates.  The character A requesting the asynchronous mode of the notification When A is specified, position 9-12 returns the address of an event object. The event selection character B, O, or P must be placed in position 13.

The character M requesting the asynchronous message mode of the notification.  When M is specified, the event selection character B, O, or P must be placed in position 13 (7 for 16-bit).

The character E asking for notification of completion during a printer session.

 

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 A or M:

The character B asking for notification of both host presentation space and OIA updates
The character O asking for notification of only OIA updates
The character P asking for notification of only host presentation update.

 

14-16

Reserved.

 

 

Return Parameters

 

This function returns a data string and a return code.

 

Data String

 

If A (asynchronous mode of notification) is specified in position 5 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.

 

9-12

4-byte value in which the event object address is returned by EHLLAPI. The application can wait for this event object (32-bit only).

 

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 OIA or presentation space is updated, an application window receives a message. The message is a return value of RegisterWindowMessage (PCSHLL). The wParam parameter contains the Task ID returned by the function call. HIWORD of lParam contains Return Code 21 (shows the OIA is updated), 22 (shows the host presentation space is updated), or 23 (shows both the OIA and the host presentation space are updated), and LOWORD of lParam parameter contains function number 23.

 

Return Code

 

The following codes are defined:

 

Return Code

Definition

0

The Start Host Notification function was successful.

1

An incorrect host presentation space was specified.

2

An error was made in designating parameters.

9

A system error was encountered.

 

 

Remarks

 

1.An application program can issue this function for multiple host sessions. The Pause (18) function can notify the application when one or more host sessions (PS, OIA, or both of them) are updated. The Query Host Update (24) function can be used to determine whether a PS, OIA, or both of them have been updated.
2.If the application chooses the asynchronous option, it can wait for the returned event object or semaphore to determine when a host event has occurred.
3.The event object or semaphore is initially in a non-signaled state and is signaled each time an appropriate event occurs. To receive notification for multiple events, the application must put the event object into the non-signaled state each time it has been signaled using either the ResetEvent or the Query Host Update (24) function.
4.An application cannot request Start Host Notification more than once with the same options.
5.This is not an exclusive call. Multiple applications can request this function for the same short session ID.