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.
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
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
- Register Setting
- 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