GETIBMOPT

The GETIBMOPT macro returns the number of TCP/IP images installed on a given MVS™ system and the status, version, and name of each image. With this information, the caller can dynamically choose the TCP/IP image with which to connect, using the INITAPI macro. The GETIBMOPT macro is optional. If you do not use this macro, follow the standard method to determine the connecting TCP/IP image:

Connect to the TCP/IP specified by TCPIPJOBNAME in the active TCPIP.DATA file.
Locate TCPIP.DATA using the search order described in the z/OS Communications Server: IP Configuration Reference.

The following requirements apply to this call:

Authorization:

Supervisor state or problem state, any PSW key.

Dispatchable unit mode:

Task.

Cross memory mode:

PASN = HASN.

Amode:

31-bit or 24-bit.

Note: See "Addressability mode (Amode) considerations" under CALL instruction API environmental restrictions and programming requirements.

ASC mode:

Primary address space control (ASC) mode.

Interrupt status:

Enabled for interrupts.

Locks:

Unlocked.

Control parameters:

All parameters must be addressable by the caller and in the primary address space.


>>-EZASMI--TYPE=GETIBMOPT--,COMMAND--=--+-number---+------------>
                                        +-address--+   
                                        +-*indaddr-+   
                                        '-(reg)----'   

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

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

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

Keyword

Description

COMMAND

Input parameter. A value or the address of a fullword binary number specifying the command to be processed. The only valid value is 1.

BUF

Output parameter. A 100-byte buffer into which each active TCP/IP image status, version, and name are placed.

On successful return, these buffer entries contain the status, name and version of up to eight active TCP/IP images. The following layout shows BUF upon completion of the call.

Figure 1. NUM_IMAGES field settings

Table that shows the structure of NUM_IMAGES field, each image is indicated by a 2-byte status, a 2-byte version, and an 8-byte name.

The NUM_IMAGES field indicates how many entries of TCP_IMAGE are included in the total BUF field. If the NUM_IMAGES returned is 0, there are no TCP/IP images present.

The status field can combine the following information:

Status Field: Meaning
X'8xxx': Active
X'4xxx': Terminating
X'2xxx': Down
X'1xxx': Stopped or stopping

Note: In the above status fields, xxx is reserved for IBM® use and can contain any value.

When the status field returns Down and Stopped, TCP/IP abended. Stopped, returned alone, indicates that TCP/IP was stopped. The following table shows the examples that are returned on version field:

Version	Field
TCP/IP z/OS® Communications Server V1R13	X'061D'
TCP/IP z/OS Communications Server V2R1	X'0621'

The name field is the PROC name, left-aligned, and padded with blanks.

ERRNO

Output parameter. A fullword binary field. If RETCODE is negative, ERRNO 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 with the following values:

Value: Description
-1: Call returned error. See ERRNO.
>=0: Successful call.

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.