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

START HOST NOTIFICATION (23)

Purpose

Determines if the designated host Presentation Space (PS) or Operator Information Area (OIA) has been updated. The asynchronous option is also provided using the returned Queue ID mechanism.

Prerequisite Calls

This function requires no prerequisite calls to other functions.

Syntax

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

Supplied Parameters

Supply the following parameters to invoke the START HOST NOTIFICATION function:

func Specifies the number of the function called; must be 23 for the START HOST NOTIFICATION function.
apistring Specifies the attributes of the API string. The calling two-character data string can contain:
Byte Definition
Position 1 One of the following:
  • A specific host PS short session ID
  • A blank or null indicating a request against the currently connected host PS
Position 2 Replace with one of the following characters:
A Requests asynchronous mode of notification. When A is selected, position 5 through 8 returns the address of the notification queue. You may then wait on the queue. The event selection characters P , O , and B must be placed in position 3.
P Asks for notification of PS update only.
O Asks for notification of OIA update only.
B Asks for notification of both PS and OIA updates.
Position 3 Replace with one of the following characters if position 2 is A:
P Asks for notification of PS update only.
O Asks for notification of OIA update only.
B Asks for notification of both PS and OIA updates.
Position 4 Reserved.
len Specifies the length of the host event buffer (256 is recommended).
ret Does not apply for this function.

Returned Parameters

apistring The following codes are valid:
Positions 5-8 Host notify queue.
ret The following codes are valid:
0 Specifies that the START HOST NOTIFICATION function was successful.
1 Specifies that an invalid host PS was specified.
2 Specifies that an error was made in designating parameters.
9 Specifies that a system error occurred.

Remarks

The START HOST NOTIFICATION function begins the process by which your HLLAPI application program determines if the designated host PS or OIA has been updated. The application does not have to connect to the session to issue this call. However, the issuing application has the responsibility to issue the STOP HOST NOTIFICATION (25) function for the same session. Otherwise, other applications will not be notified from this session.

START HOST NOTIFICATION may be issued against multiple sessions simultaneously. If the application chooses the A (asynchronous) option, it may choose to wait on the returned Queue ID to determine when a host event has occurred by issuing a poll command. When the poll returns, the QUERY HOST UPDATE (24) function should then be called to determine the type of update that has occurred.

Attention: Use Queue ID only for waiting on events. Use the PAUSE (18) function to query contents and receive queue events.

After using this function, your application program can use the QUERY HOST UPDATE (24) function to determine when a host event has occurred. The QUERY HOST UPDATE(24) function can be used to determine whether PS, OIA, or both, have changed.

Subsequent START HOST NOTIFICATION functions have no effect as long as the options remain the same as the initial START HOST NOTIFICATION functions.

To receive notification of multiple events, the application must use the QUERY HOST UPDATE (24) function after each event notification.

Related Information

PAUSE (18) function , QUERY HOST UPDATE (24) function and STOP HOST NOTIFICATION function .

[ Previous | Next | Contents | Search ]