Defining storage for the macro API

The macro API requires the definition of a task storage area.

The task storage area must be known to and addressable by all socket users communicating across a specified connection. A connection runs between the application and TCP⁄IP. The most common way to organize storage is to assign one connection to each MVS™ subtask. If there are multiple modules using sockets within a single task or connection, you must provide the address of the task storage to every user.

The following information describes how to define the address of the task storage:

Code the instruction EZASMI TYPE=TASK with STORAGE=CSECT as part of the program code. This makes the program nonreentrant, but simplifies the code. The expansion of this instruction generates the equate field, TIELENTH, which is equal to the length of the storage area.
Code the instruction EZASMI TYPE=TASK with STORAGE=DSECT as part of the program code. The expansion of this instruction generates the equate field, TIELENTH, which is equal to the length of the storage area. This can be used to issue an MVS GETMAIN to allocate the required storage.

Guideline: Clear the task storage prior to calling EZASMI TYPE=INIT. If the EZASMI TYPE=TASK definition is not named, you can use the EZASMI default storage name of EZASMTIE. Use the TIELENTH field to determine the length of the EZASMTIE storage to clear.

The defining program must make the address of this storage available to all other programs using this connection. Programs running in these tasks must define the storage mapping with an EZASMI TYPE=TASK with STORAGE=DSECT.

Restriction: The task storage area used on an INITAPI call cannot be moved or copied to other storage locations. Attempting to do so will result in an implicit INITAPI being performed with unexpected results.

The EZASMI TYPE=TASK macro generates only one parameter list for a connection. This can lead to overlay problems for programs using APITYPE=3 connections (multiple calls can be issued simultaneously). For more detail on APITYPE=3 connections, see Task management and asynchronous function processing. A program should use the following format to build unique parameter list storage areas if it will be issuing multiple calls simultaneously on one connection:

BINDPRML   EZASMI    MF=L  This will generate the storage used for
                      building the parm list in the following BIND call
           EZASMI    TYPE=BIND,                                        X
                       S=SOCKDESC,                                     X
                       NAME=NAMEID,                                    X
                       ERRNO=ERRNO,                                    X
                       RETCODE=RETCODE,                                X
                       ECB=ECB1,                                       X
                       MF=(E,BINDPRML)

This example of an asynchronous BIND macro would use the MF=L macro to generate the parameter list. The fields that are common across all macro calls, for example, RETCODE and ERRNO, must be unique for each outstanding call.

You can create multiple connections to TCP/IP from a single task. Each of these connections functions independently of the other and is identified by its own task interface element (TIE). The TASK parameter can be used to explicitly reference a TIE. If you do not include the TASK parameter, the macro uses the TIE generated by the EZASMI TYPE=TASK macro.

TIE1    DS XL(TIELENTH)                                         Length of TIE 
 
  EZASMI TYPE=INITAPI,
         MAXSOC=MAX75,                                                  X
          ERRNO=ERRNO,                                                  X
          RETCODE=RETCODE,                                              X
          APITYPE=2,                                                    X
          MAXSNO=MAXS,                                                  X
          TASK=TIE1
 
  EZASMI  TYPE=SOCKET,
           AF='INET',                                                   X
           SOCTYPE='STREAM',                                            X
           ERRNO=ERRNO,                                                 X
           RETCODE=RETCODE,                                             X
           TASK=TIE1

In this example, the TIE TIE1 is used for the connection, not the TIE generated by the EZASMI TYPE=TASK macro.