Macro API asynchronous function processing: How it works

The macro API provides for asynchronous function processing in two forms. Both forms cause the system to return control to the application immediately after the function request has been sent to TCP/IP. The difference between the two forms is in how the application is notified when the function is completed:

ECB method: Enables you to pass an MVS™ event control block (ECB) on each socket call. The socket library returns control to the program immediately and posts the ECB when the call has completed.
EXIT method: Enables you to specify the entry point of an exit routine using the INITAPI() call. The individual socket calls immediately return control to the program and the socket library drives the specified exit routine when the socket call is complete.

In either case, the function is completed when the notification is delivered. Note that the notification can be delivered at any time, in some cases even before the application has received control back from the EZASMI macro call. It is therefore important that the application is ready to handle a notification as soon as it issues the EZASMI macro call.

Like nonblocking calls, asynchronous calls return control to your program immediately. But in this case, there is no need to reissue the call. When the requested event has taken place, an ECB is posted or an exit routine is driven.

Using the API macro, you can specify APITYPE=2 or APITYPE=3

APITYPE=2: Allows an asynchronous macro API program to have only one outstanding socket call per socket descriptor. An APITYPE=2 program can use macro API asynchronous calls, but synchronous calls are equally well supported.
APITYPE=3: Allows an asynchronous macro API program to have many outstanding socket calls per socket descriptor. Only the macro API supports APITYPE=3. An APITYPE=3 program must use macro API asynchronous calls with either an ECB or REQAREA parameter.

The REQAREA parameter is used in macros using the EXIT form. This parameter is mutually exclusive with the ECB parameter used with the ECB form.

Figure 1. ECB input parameter

An ECB input parameter contains a 4-byte ECB and a 100-byte storage area.

Like the ECB parameter, the REQAREA parameter points to an area that contains:

A 4-byte token that is presented to your asynchronous exit routine when the response to this function request is complete
A 100-byte storage area that is used by the interface to save the state information

Note: This storage must not be modified or freed until the macro function has completed and the ECB has been posted, or the asynchronous exit has been driven.

Figure 2. User token setting

A user token contains a 4-byte user token and a 100-byte storage area.

Before you issue the macro, you must set the first word of the 104 bytes to a token of any value. The token is used by your asynchronous exit routine to determine the function completion event for which it is being invoked.

Asynchronous functions are processed in the following sequence:

The application must issue the EZASMI TYPE=INITAPI with ASYNC='ECB' or ASYNC=('EXIT', AEEXIT). The ASYNC parameter notifies the API that asynchronous processing is to be used for this connection. The API notes the type of asynchronous processing to be used, ECB or EXIT, and specifies the use of the asynchronous exit routine for this connection.
When a function request is issued by the application, the API takes one of the following actions:
- If the type of asynchronous processing is ECB, and an ECB is supplied in the function request, the API returns control to the application. If Register 15 is 0, the ECB is posted when the function has completed. Note that the ECB might be posted prior to when control is returned to the application.
- If the type of asynchronous processing is EXIT, and a REQAREA parameter is supplied in the function request, the API returns control to the application. If Register 15 is 0, the exit routine is invoked when the function has completed. Note that the exit can be invoked prior to when control is returned to the application.
In either case, Register 15 is used to inform the caller whether or not the ECB is posted or asynchronous exit driven. Therefore, you must not use Register 15 for the RETCODE parameter.

When the asynchronous exit routine is invoked, the following linkage conventions are used:

GPR0

0: Normal return
1: TCP/IP address space has terminated (TCPEND).

GPR1

Points to a doubleword field containing the following information:

WORD1: The token specified by the INITAPI macro
WORD2: The token specified by the functional request macro (First 4 bytes of the REQAREA storage)

GPR13

Points to standard MVS save area in the same key as the application PSW at the time of the INITAPI command.

GPR14

Return address

GPR15

Entry point of the exit routine

The following example shows how to code an asynchronous macro function:

************************************************************************
*   READ A BUFFER OF DATA FROM THE CONNECTION PEER. I MAY NEED TO      *
*   WAIT SO GIVE CONTROL BACK TO ME AND LET ME ISSUE MY OWN WAIT.      *
*   IT COULD BE PART OF A WAIT WHICH WOULD INCLUDE OTHER EVENTS.       *
*   SPECIFY ECB/STORAGE AREA FOR INTERFACE.                            *
************************************************************************

         EZASMI TYPE=READ,                                             X
               S=SOCKNO,                                               X
               NBYTES=COUNT,                                           X
               BUF=DATABUF,                                            X
               ERRNO=ERROR,                                            X
               RETCODE=RCODE,                                          X
               ECB=MYECB,                                              X
               ERROR=ERRORRTN
 
         LTR    R15,R15        Was macro function passed to TCP/IP?
         BNZ    BADRCODE       If no, ECB will not be posted
         WAIT   ECB=MYECB      TELL MVS TO WAIT UNTIL READ IS DONE