INITAPI

The INITAPI macro connects an application to the TCP⁄IP interface. Almost all sockets programs that are written in COBOL, PL/I, or assembler language must issue the INITAPI macro before they issue other sockets macros.
Note: Because the default INITAPI still requires the TERMAPI to be issued, you always code the INITAPI command.
The exceptions to this rule are the following calls, which, when issued first, will generate a default INITAPI call:
  • GETCLIENTID
  • GETHOSTID
  • GETHOSTNAME
  • GETIBMOPT
  • SELECT
  • SELECTEX
  • SOCKET
  • TAKESOCKET
Note: Only the first INITAPI triggers a read of the TCPIP.DATA and all other INITAPIs under that address space will use the values read by the first INITAPI.
The following requirements apply to this call: 
Read syntax diagramSkip visual syntax diagram
>>-EZASMI--TYPE=INITAPI--+--------------------------+----------->
                         '-,MAXSOC--=--+-number---+-'   
                                       +-address--+     
                                       +-*indaddr-+     
                                       '-(reg)----'     

>--+---------------------------+--+-------------------------+--->
   '-,SUBTASK--=--+-address--+-'  '-,IDENT--=--+-address--+-'   
                  +-*indaddr-+                 +-*indaddr-+     
                  '-(reg)----'                 '-(reg)----'     

>--,MAXSNO--=--+-address--+--,ERRNO--=--+-address--+------------>
               +-*indaddr-+             +-*indaddr-+   
               '-(reg)----'             '-(reg)----'   

>--,RETCODE--=--+-address--+--+---------------------------+----->
                +-*indaddr-+  '-,APITYPE--=--+-'2'------+-'   
                '-(reg)----'                 +-'3'------+     
                                             +-address--+     
                                             +-*indaddr-+     
                                             '-(reg)----'     

>--+--------------------------+--------------------------------->
   '-,UEEXIT--=--+-address--+-'   
                 +-*indaddr-+     
                 '-(reg)----'     

>--+----------------------------------------+------------------->
   '-,ASYNC--=--+-'NO'--------------------+-'   
                +-'ECB'-------------------+     
                '-('EXIT',--+-address)--+-'     
                            +-*indaddr)-+       
                            '-(reg))----'       

>--+------------------------+--+------------------------+------><
   '-,ERROR--=--+-indaddr-+-'  '-,TASK--=--+-address--+-'   
                '-(reg)---'                +-*indaddr-+     
                                           '-(reg)----'     
Keyword
Descriptions
MAXSOC
Optional input parameter. A halfword binary field specifying the maximum number of sockets supported by this application. The maximum number is 65535 and the minimum number is 50. The default value for MAXSOC is 50. If less than 50 are requested, MAXSOC defaults to 50.
SUBTASK
Optional input parameter. An 8-byte field that is used to identify a subtask in an address space that can contain multiple subtasks. It is suggested that you use your own job name as part of your subtask name. This will ensure that, if you issue more than one INITAPI command from the same address space, each SUBTASK parameter will be unique.
IDENT
Optional input parameter. A structure containing the identities of the TCP/IP address space and your address space. Specify IDENT on the INITAPI macro from an address space. The structure is as follows:
Field
Description
TCPNAME
Input parameter. An 8-byte character field set to the name of the TCP/IP address space that you want to connect to. If this is not specified, the system derives a value from the configuration file, as described in the z/OS Communications Server: IP Configuration Reference.
ADSNAME
Input parameter. An 8-byte character field set to the name of the calling program's address space. If this is not specified, the system will derive a value from the MVS™ control block structure.
MAXSNO
Output parameter. A fullword binary field containing the greatest descriptor number assigned to this application. The lowest socket number is 0. If you have 50 sockets, they are numbered in the range 0 – 49. If MAXNO is not specified, the value for MAXNO is 49.
ERRNO
Output parameter. A fullword binary field. If RETCODE is negative, ERRNO field contains a valid error number. Otherwise, ignore ERRNO.

See Socket call error return codes for information about ERRNO return codes.

RETCODE
Output parameter. A fullword binary field that returns one of the following values:
Value
Description
0
Successful call.
-1
Check ERRNO for an error code.
APITYPE
Optional input parameter. A halfword binary field specifying the APITYPE. For details on usage, see Task management and asynchronous function processing.
Value
Meaning
2
APITYPE 2. This is the default.
3
APITYPE 3
For an APITYPE value of 3, the ASYNC parameter must be either 'ECB' or 'EXIT'.
UEEXIT
Optional input parameter. A doubleword value as follows:
  • A fullword specifying the entry point address of the user unsolicited event exit.
  • A fullword specifying the token that will be presented to the unsolicited event exit at invocation.
ASYNC
Optional input parameter. One of the following:
  • The literal 'NO' indicating no asynchronous support.
  • The literal 'ECB' indicating the asynchronous support using ECBs is to be used.
  • The combination of the literal 'EXIT' and the address of a doubleword value as follows:
    • A fullword specifying the entry point address of the user's asynchronous event exit.
    • A fullword specifying the token which will be presented to the asynchronous event exit at invocation.
ERROR
Input parameter. The location in your program to receive control when the application programming interface (API) processing module cannot be loaded.
TASK
Input parameter. The location of the task storage area in your program.
Parent topic: Macros for assembler programs