Start Communication Notification (80)

Top  Previous  Next

The Start Communication Notification function begins the process by which your EHLLAPI application can determine whether the specified session is connected to a host.

 

After using this function, the application can use Query Communication Event (81) to determine whether the session is connected or disconnected.

 

3270

5250

Yes

Yes

 

 

Prerequisite Calls

 

There are no prerequisite calls for this function.

 

 

Call Parameters

 

 

Enhanced Interface

Function Number

Must be 80

Data String

Preallocated structure; see the following table

Length

16

PSPosition

NA

 

The calling data structure contains these elements

 

Byte

Definition

1

A 1-character presentation space short name (PSID).

2-4

Reserved

5

One of the following values:  The character C asks for notification when the session either disconnects or connects to the host.  The character A requests the asynchronous mode of notification. When A is specified, position 9-12 returns the address of an event object (Windows). The character C must be placed in position 13.  The character M requests the asynchronous message mode of the notification. When M is specified, the event selection character C must be placed in position 13.

6-8

Reserved

9-12

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

13

This should contain the character C if position 5 is A or M.

14-16

Reserved

 

 

Data String

 

If A (asynchronous mode) is specified in position 5 of the calling data structure and the function is completed successfully, the following data string is returned:

 

Byte

Definition

1

A 1-character presentation space short-name (PSID)

2-8

Reserved

9-12

4-byte binary value in which the event object handle is returned by EHLLAPI. The application can wait for this event object.

 

If M (asynchronous message mode) is specified in position 5 of the calling data structure and the function is completed successfully, the following data string is returned:

 

Byte

Definition

1

A 1-character presentation space short-name (PSID)

2-8

Reserved

9-10

Task ID of asynchronous message mode

 

When the session connects or disconnects an application window receives a message. The message is the return value of RegisterWindow Message (PCSHLL). The wParam contains the Task ID returned by the function call. HIWORD of lParam contains a 21 if the session is connected to the host or a 22 if the session is disconnected. The LOWORD of lParam contains the function number 80.

 

 

Return Parameters

 

Return Code

Definition

0

The function was successful

1

An incorrect PSID 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 Query Communication Event (81) function can be used to determine the session communication status.
2.If the application chooses the asynchronous option, it can use the Windows SDK call WaitForSingleObject to wait until the sessions communication status has changed.
3.The event object is initially in a non-signaled state. It is signaled each time an event occurs. To receive notification for multiple events the application must put the event object into the non-signaled state each time it is signaled, by using the Windows SDK call ResetEvent, or by using function 81 Query Communications Event.
4.Multiple calls to this function with the same options from the same application will be ignored.
5.This is not exclusive to one application. Several applications can request this function for the same Session ID.