Parameter values set by the application

SOC-FUNCTION

A 16-byte character field containing IOCTL. The field is left-justified and padded to the right with blanks.

S

A halfword binary number set to the descriptor of the socket to be controlled.

COMMAND

To control an operating characteristic, set this field to one of the following symbolic names. A value in a bit mask is associated with each symbolic name. By specifying one of these names, you are turning on a bit in a mask which communicates the requested operating characteristic to TCP/IP.

FIONBIO

Sets or clears blocking status.

FIONREAD

Returns the number of immediately readable bytes for the socket.

SIOCATMARK

Determines whether the current location in the data input is pointing to out-of-band data.

SIOCGHOMEIF6

Requests all IPv6 home interfaces.

Note: To request OSM interfaces, the application must have READ authorization to the EZB.OSM.sysname.tcpname resource.

When the SIOCGHOMEIF6 IOCTL is issued, the REGARQ must contain a Network Configuration Header. The NETCONFHDR is defined in the SYS1.MACLIB(BPXYIOC6) for assembler language. The following fields are input fields and must be filled out:

NchEyeCatcher

Contains eye catcher '6NCH'

NchIoctl

Contains the command code

NchBufferLength

Buffer length large enough to contain all the IPv6 interface records. Each interface record is length of HOME-IF-ADDRESS. If buffer is not large enough, then errno will be set to ERANGE and the NchNumEntryRet will be set to number of interfaces. Based on NchNumEntryRet and size of HOME-IF-ADDRESS, calculate the necessary storage to contain the entire list.

NchBufferPtr

This is a pointer to an array of HOME-IF structures returned on a successful call. The size will depend on the number of qualifying interfaces returned.

NchNumEntryRet

If return code is 0 this will be set to number of HOME-IF-ADDRESS returned. If errno is ERANGE, then will be set to number of qualifying interfaces. No interfaces are returned. Recalculate The NchBufferLength based on this value times the size of HOME-IF-ADDRESS.

REQARG and RETARG

Point to the arguments that are passed between the calling program and IOCTL. The length of the argument is determined by the COMMAND request. REQARG is an input parameter and is used to pass arguments to IOCTL. RETARG is an output parameter and is used for arguments returned by IOCTL. For the lengths and meanings of REQARG and RETARG for each COMMAND type, see Table 1.

Figure 1. COBOL language example for SIOCGHOMEIF6

Working-Storage Section.
       01  SIOCGHOMEIF6-VAL       pic s9(10) binary value 3222599176.
       01  SIOCGHOMEIF6-REDEF REDEFINES SIOCGHOMEIF6-VAL.
           05 FILLER              PIC 9(6) COMP.
           05 SIOCGHOMEIF6        PIC 9(8) COMP.
       01  IOCTL-RETARG           USAGE IS POINTER.
       01  NET-CONF-HDR.
           05 NCH-EYE-CATCHER     PIC X(4) VALUE '6NCH'.
           05 NCH-IOCTL           PIC 9(8) BINARY.
           05 NCH-BUFFER-LENTH    PIC 9(8) BINARY.
           05 NCH-BUFFER-PTR      USAGE IS POINTER.
           05 NCH-NUM-ENTRY-RET   PIC 9(8) BINARY.
      01  HOME-IF.
           03 HOME-IF-ADDRESS.
              05 FILLER           PIC 9(16) BINARY.

Linkage Section.

       01 L1.
          03 NetConfHdr.
             05 NchEyeCatcher     pic x(4).
             05 NchIoctl          pic 9(8) binary.
             05 NchBufferLength   pic 9(8) binary.
             05 NchBufferPtr      usage is pointer.
             05 NchNumEntryRet    pic 9(8) binary.
      * Allocate storage based on your need.
          03 Allocated-Storage    pic x(nn).

       Procedure Division using L1.
           move '6NCH' to NchEyeCatcher.
           set NchBufferPtr to address of Allocated-Storage.
      * Set NchBufferLength to the length of your allocated storage.
           move nn to NchBufferLength.
           move SIOCGHOMEIF6 to NchIoctl.
           Call 'EZASOKET' using soket-ioctl socket-descriptor
                                 SIOCGHOMEIF6
                                 NETCONFHDR NETCONFHDR
                                 errno retcode.

SIOCGIFADDR

Requests the IPv4 network interface address for a given interface name. For assembler, see the IOCN_IFNAME field in the SYS1.MACLIB(BPXYIOCC) API. For COBOL, see the IFR-NAME field in the SEZAINST(EZACOBOL) API. For PL/I, see the IFR_NAME field in the SEZAINST(CBLOCK) API.

SIOCGIFBRDADDR

Requests the IPv4 network interface broadcast address for a given interface name. For assembler, see the IOCN_IFNAME field in the SYS1.MACLIB(BPXYIOCC) API. For COBOL, see the IFR-NAME field in the SEZAINST(EZACOBOL) API. For PL/I, see the IFR_NAME field in the SEZAINST(CBLOCK) API.

SIOCGIFCONF

Requests the IPv4 network interface configuration. The configuration is a variable number of 32-byte structures. For assembler, see the IOCN_IFREQ field in the SYS1.MACLIB(BPXYIOCC) API for the structure format. For COBOL, see the IFREQ field in the SEZAINST(EZACOBOL) API for the structure format. For PL/I, see the IFREQ field in the SEZAINST(CBLOCK) API for the structure format.

When IOCTL is issued, REQARG must contain the length of the array to be returned. To determine the length of REQARG, multiply the structure length (array element) by the number of interfaces requested. The maximum number of array elements that TCP⁄IP can return is 100.
When IOCTL is issued, RETARG must be set to the beginning of the storage area that you have defined in your program for the array to be returned.

SIOCGIFDSTADDR

Requests the network interface destination address for a given interface name. For assembler, see the IOCN_IFNAME field in the SYS1.MACLIB(BPXYIOCC) API. For COBOL, see the IFR-NAME field in the SEZAINST(EZACOBOL) API. For PL/I, see the IFR_NAME field in the SEZAINST(CBLOCK) API.

SIOCGIFMTU

Requests the IPv4 network interface MTU (maximum transmission unit) for a given interface name. For assembler, see the IOCN_IFNAME field in the SYS1.MACLIB(BPXYIOCC) API. For COBOL, see the IFR-NAME field in the SEZAINST(EZACOBOL) API. For PL/I, see the IFR_NAME field in the SEZAINST(CBLOCK) API.

SIOCGIFNAMEINDEX

Requests all interface names and interface indexes including local loopback but excluding VIPAs. Information is returned for both IPv4 and IPv6 interfaces whether they are active or inactive. For IPv6 interfaces, information is only returned for an interface if it has at least one available IP address.

Note: To request OSM interfaces, the application must have READ authorization to the EZB.OSM.sysname.tcpname resource.

The configuration consists of IF_NAMEINDEX structure, which is defined in SYS1.MACLIB(BPX1IOCC) for the assembler language.

When the SIOCGIFNAMEINDEX IOCTL is issued, the first word in REQARG must contain the length (in bytes) to contain an IF-NAME-INDEX structure to return the interfaces. The formula to compute this length is as follows:
1. Determine the number of interfaces expected to be returned upon successful completion of this command.
2. Multiply the number of interfaces by the array element (size of IF-NIINDEX, IF-NINAME, and IF-NIEXT) to get the size of the array element.
3. Add the size of the IF-NITOTALIF and IF-NIENTRIES to the size of the array to get the total number of bytes needed to accommodate the name and index information returned.
When IOCTL is issued, RETARG must be set to the address of the beginning of the area in your program's storage that is reserved for the IF-NAMEINDEX structure that is to be returned by IOCTL.
The command 'SIOCGIFNAMEINDEX' returns a variable number of all the qualifying network interfaces.

Figure 2. COBOL language example for SIOCGIFNAMEINDEX

 WORKING-STORAGE SECTION.
       01 SIOCGIFNAMEINDEX-VAL pic 9(10) binary value 1073804803.
       01 SIOCGIFNAMEINDEX-REDEF REDEFINES SIOCGIFNAMEINDEX-VAL.
          05 FILLER            PIC 9(6) COMP.
          05 SIOCGIFNAMEINDEX  PIC 9(8) COMP.
       01 reqarg               pic 9(8) binary.
       01 reqarg-header-only   pic 9(8) binary.
       01 IF-NIHEADER.
          05 IF-NITOTALIF      PIC 9(8) BINARY.
          05 IF-NIENTRIES      PIC 9(8) BINARY.
          01 IF-NAME-INDEX-ENTRY.
             05 IF-NIINDEX     PIC 9(8) BINARY.
             05 IF-NINAME      PIC X(16).
             05 IF-NINAMETERM  PIC X(1).
             05 IF-NIRESV1     PIC X(3).
          01 OUTPUT-STORAGE    PIC X(500).
       Procedure Division.
           move 8 to reqarg-header-only.
           Call 'EZASOKET' using soket-ioctl socket-descriptor
                                 SIOCGIFNAMEINDEX
                                 REQARG-HEADER-ONLY IF-NIHEADER
                                 errno retcode.
           move 500 to reqarg.
           Call 'EZASOKET' using soket-ioctl socket-descriptor
                                 SIOCGIFNAMEINDEX
                                 REQARG OUTPUT-STORAGE
                                 errno retcode.

SIOCGIPMSFILTER

Requests a list of the IPv4 source addresses that comprise the source filter, with the current mode on a given interface and a multicast group for a socket. The source filter can include or exclude the set of source address, depending on the filter mode (MCAST_INCLUDE or MCAST_EXCLUDE). When the SIOCGIPMSFILTER IOCTL is issued, the REQARG parameter must contain a IP_MSFILTER structure, which is defined in SYS1.MACLIB(BPXYIOCC) for assembler language, in SEZAINST(CBLOCK) for PL/I, and in SEZAINST(EZACOBOL) for COBOL. The IP_MSFILTER must include an interface address (input), a multicast address (input), filter mode (output), the number of source addresses in the following array (input and output), and an array of source addresses (output). On input, the number of source addresses is the number of source addresses that will fit in the input array. On output, the number of source addresses contains the total number of source filters in the output array. If the application does not know the size of the source list prior to processing, it can make a reasonable guess (for example, 0), and if when the call completes the number of source addresses is a greater value, the IOCTL can be repeated with a buffer that is large enough. That is, on output, the number of source addresses is always updated to be the total number of sources in the filter, but the array holds as many source addresses as will fit, up to the minimum of the array size passed in as the input number.

Calculate the size of IF_MSFILTER value as follows:

Determine the number of expected source addresses.
Multiply the number of source addresses by the array element (size of the IMSF_SrcEntry value) to determine the size of all array elements.
Add the size of all array elements to the size of the IMSF_Header value to determine the total number of bytes needed to accommodate the source addresses information that is returned.

SIOCGMSFILTER

Requests a list of the IPv4 or IPv6 source addresses that comprise the source filter, with the current mode on a given interface index and a multicast group for a socket. The source filter can include or exclude the set of source address, depending on the filter mode (MCAST_INCLUDE or MCAST_EXCLUDE). When the SIOCGMSFILTER IOCTL is issued, the REQARG parameter must contain a GROUP_FILTER structure, which is defined in SYS1.MACLIB(BPXYIOCC) for assembler , in SEZAINST(CBLOCK) for PL/I, and in SEZAINST(EZACOBOL) for COBOL. The GROUP_FILTER option must include an interface index (input), a socket address structure of the multicast address (input), filter mode (output), the number of source addresses in the following array (output), and an array of the socket address structure of source addresses (input and output). On input, the number of source addresses is the number of source addresses that will fit in the input array. On output, the number of source addresses contains the total number of source filters in the output array. If the application does not know the size of the source list prior to processing, it can make a reasonable guess (for example, 0), and if when the call completes the number of source addresses is a greater value, the IOCTL can be repeated with a buffer that is large enough. That is, on output, the number of source addresses is always updated to be the total number of sources in the filter, but the array holds as many source addresses as will fit, up to the minimum of the array size passed in as the input number.

Calculate the size of the GROUP_FILTER value as follows:

Determine the number of source addresses expected.
Multiply the number of source addresses by the array element (size of the GF_SrcEntry value) to determine the size of all array elements.
Add the size of all array elements to the size of the GF_Header value to determine the total number of bytes needed to accommodate the source addresses information returned.

SIOCGPARTNERINFO

Provides an interface for an application to retrieve security information about its partner. When you issue the SIOCGPARTNERINFO IOCTL, the REQARG parameter must contain a PartnerInfo structure. The PartnerInfo structure is defined in members within SEZANMAC; EZBPINF1 defines the PL/I layout, EZBPINFA defines the assembler layout, and EZBPINFB defines the COBOL layout. For more information about using the SIOCGPARTNERINFO IOCTL, see z/OS Communications Server: IP Programmer's Guide and Reference.

SIOCSAPPLDATA

The SIOCSAPPLDATA IOCTL enables an application to set 40 bytes of user-specified application data against a socket endpoint. You can also use this application data to identify socket endpoints in interfaces such as Netstat, SMF, or network management applications. When the SIOCSAPPLDATA IOCTL is issued, the REQARG parameter must contain a SetApplData structure as defined by the EZBYAPPL macro. See the CBLOCK and the EZACOBOL samples for the equivalent SetApplData and SetADcontainer structure definitions for PL/I and COBOL programming environments. See z/OS Communications Server: IP Programmer's Guide and Reference for more information about programming the SIOCSAPPLDATA IOCTL.

SetAD_buffer: The user-defined application data is 40 bytes of data that identifies the endpoint with the application. You can obtain this application data from the following sources:

Netstat reports. The information is displayed in the ALL/-A report. If you use the APPLDATA modifier, then the information also is displayed on the ALLConn/-a and COnn/-c reports.
The SMF 119 TCP connection termination record. See TCP connection termination record (subtype 2) in z/OS Communications Server: IP Programmer's Guide and Reference for more information.
Network management interfaces. See Network management interfaces in z/OS Communications Server: IP Programmer's Guide and Reference for more information.

Consider the following guidelines:

The application must document the content, format and meaning of the ApplData strings that it associates with the sockets that it owns.
The application should uniquely identify itself with printable EBCDIC characters at the beginning of the string. Strings beginning with 3-character IBM® product identifiers, such as TCP/IP's EZA or EZB, are reserved for IBM use. IBM product identifiers begin with a letter in the range A-I.
Use printable EBCDIC characters for the entire string to enable searching with Netstat filters.

Tip: Separate application data elements with a blank for easier reading.

SIOCSIPMSFILTER

Sets a list of the IPv4 source addresses that comprise the source filter, with the current mode on a given interface and a multicast group for a socket. The source filter can include or exclude the set of source address, depending on the filter mode (MCAST_INCLUDE or MCAST_EXCLUDE). When the SIOCSIPMSFILTER IOCTL is issued, the REQARG parameter must contain a IP_MSFILTER structure, which is defined in SYS1.MACLIB(BPXYIOCC) for assembler, in SEZAINST(CBLOCK) for PL/I and in SEZAINST(EZACOBOL) for COBOL. The IP_MSFILTER option must include an interface address, a multicast address, filter mode, the number of source addresses in the following array, and an array of source addresses.

Calculate the size of the IF_MSFILTER value as follows:

Determine the number of expected source addresses.
Multiply the number of source addresses by the array element (size of the IMSF_SrcEntry value) to determine the size of all array elements.
Add the size of all array elements to the size of the IMSF_Header value to determine the total number of bytes needed to accommodate the source addresses information that is returned.

SIOCSMSFILTER

Sets a list of the IPv4 or IPv6 source addresses that comprise the source filter, along with the current mode on a given interface index and a multicast group for a socket. The source filter can include or exclude the set of source address, depending on the filter mode (INCLUDE or EXCLUDE). When the SIOCSMSFILTER IOCTL is issued, the REQARG parameter must contain a GROUP_FILTER structure which is defined in SYS1.MACLIB(BPXYIOCC) for assembler, in SEZAINST(CBLOCK) for PL/I, and in SEZAINST(EZACOBOL) for COBOL. The GROUP_FILTER option must include an interface index, a socket address structure of the multicast address, filter mode, the number of source addresses in the following array, and an array of the socket address structure of source addresses.

Calculate the size of GROUP_FILTER as follows:

Determine the number of source addresses expected.
Multiply the number of source addresses by the array element (size of the GF_SrcEntry value) to get the size of all array elements.
Add the size of all array elements to the size of the GF_Header value to get the total number of bytes needed to accommodate the source addresses information returned.

SIOCSPARTNERINFO

The SIOCSPARTNERINFO IOCTL sets an indicator to retrieve the partner security credentials during connection setup and saves the information, enabling an application to issue a SIOCGPARTNERINFO IOCTL without suspending the application, or at least minimizing the time it takes to retrieve the information. The SIOCSPARTNERINFO IOCTL must be issued prior to the SIOCGPARTNERINFO IOCTL. When you issue the SIOCSPARTNERINFO IOCTL, the REQARG parameter must contain a constant value, PI_REQTYPE_SET_PARTNERDATA. This constant is defined in members within SEZANMAC; EZBPINF1 defines the PL/I layout, EZBPINFA defines the assembler layout, and EZBPINFB defines the COBOL layout. For more information about using the SIOCSPARTNERINFO IOCTL, see z/OS Communications Server: IP Programmer's Guide and Reference.

SIOCTTLSCTL

Controls Application Transparent Transport Layer Security (AT-TLS) for the connection. REQARG and RETARG must contain a TTLS_IOCTL structure. If a partner certificate is requested, the TTLS_IOCTL must include a pointer to additional buffer space and the length of that buffer. Information is returned in the TTLS_IOCTL structure. If a partner certificate is requested and one is available, it is returned in the additional buffer space. The TTLS_IOCTL structure is defined in members within SEZANMAC. EZBZTLS1 defines the PL/I layout, EZBZTLSP defines the assembler layout, and EZBZTLSB defines the COBOL layout. For more usage details, see the Application Transparent TLS (AT-TLS) information in z/OS Communications Server: IP Programmer's Guide and Reference.

Restriction: Use of this ioctl for functions other than query requires that the AT-TLS policy mapped to the connection be defined with the ApplicationControlled parameter set to On.

REQARG and RETARG

Points to arguments that are passed between the calling program and IOCTL. The length of the argument is determined by the COMMAND request. REQARG is an input parameter or an output parameter and is used to pass and receive arguments to and from IOCTL. RETARG is an output parameter and receives arguments from IOCTL. The REQARG and RETARG parameters are described in Table 1.

Table 1. IOCTL call arguments
COMMAND/CODE	SIZE	REQARG	SIZE	RETARG
FIONBIO X'8004A77E'	4	Set socket mode to: X'00'=blocking, X'01'=nonblocking.	0	Not used.
FIONREAD X'4004A77F'	0	Not used.	4	Number of characters available for read.
SIOCATMARK X'4004A707'	0	Not used.	4	X'00'= not at OOB data X'01'= at OOB data.
SIOCGHOMEIF6 X'C014F608'	20	NetConfHdr		See Figure 1 NetConfHdr.
SIOCGIFADDR X'C020A70D'	32	First 16 bytes - interface name. Last 16 bytes - not used.	32	Network interface address. For assembler, see the IOCN_SADDRIF field in the SYS1.MACLIB(BPXYIOCC) API. For COBOL, see the IFR-ADDR field in the SEZAINST(EZACOBOL) API. For PL/I, see the IFR_ADDR field in the SEZAINST(CBLOCK) API.
SIOCGIFBRDADDR X'C020A712'	32	First 16 bytes - interface name. Last 16 bytes - not used.	32	Network interface address. For assembler, see the IOCN_SADDRIFBROADCAST field in the SYS1.MACLIB(BPXYIOCC) API. For COBOL, see the IFR-BROADADDR field in the SEZAINST(EZACOBOL) API. For PL/I, see the IFR_BROADADDR field in the SEZAINST(CBLOCK) API.
SIOCGIFCONF X'C008A714'	8	Size of RETARG.	See note¹.
SIOCGIFDSTADDR X'C020A70F'	32	First 16 bytes - interface name. Last 16 bytes - not used.	32	Destination interface address. For assembler, see the IOCN_SADDRIFDEST field in the SYS1.MACLIB(BPXYIOCC) API. For COBOL, see the IFR-DSTADDR field in the SEZAINST(EZACOBOL) API. For PL/I, see the IFR_DSTADDR field in the SEZAINST(CBLOCK) API.
SIOCGIFMTU X'C020A726'	32	First 16 bytes - interface name. Last 16 bytes - not used.	32	IPv4 interface MTU (maximum transmission unit). For assembler, see the IOCN_MTUSIZE field in the SYS1.MACLIB(BPXYIOCC) API. For COBOL, see the IFR-MTU field in the SEZAINST(EZACOBOL) API. For PL/I, see the IFR_MTU field in the SEZAINST(CBLOCK) API.
SIOCGIFNAMEINDEX X'4000F603'	4	First 4 bytes size of return buffer.		See Figure 2 IF-NAMEINDEX .
SIOCGIPMSFILTER X'C000A724'	–	See IP_MSFILTER structure in macro BPXYIOCC. See note 2.	0	Not used
SIOCGMSFILTER X'C000F610'	–	See GROUP_FILTER structure in macro BPXYIOCC. See note 3	0	Not used
SIOCGPARTNERINFO X'C000F612'	–	For the PartnerInfo structure layout, see SEZANMAC(EZBPINFA) for assembler, SEZANMAC(EZBPINF1) for PL/I, and SEZANMAC(EZBPINFB) for COBOL. See note 4.	0	Not used
SIOCSAPPLDATA X'8018D90C'	–	See SETAPPLDATA structure in macro EZBYAPPL	0	Not used
SIOCSIPMSFILTER X'8000A725'	–	See IP_MSFILTER structure in macro BPXYIOCC. See note 2.	0	Not used
SIOCSMSFILTER X'8000F611'	–	See GROUP_FILTER structure in macro BPXYIOCC. See note 3	0	Not used
SIOCSPARTNERINFO X'8004F613'	4	See PI_REQTYPE_SET_PARTNERDATA in SEZANMAC(EZBPINFA) for assembler, SEZANMAC(EZBPINF1) for PL/I, and SEZANMAC(EZBPINFB) for COBOL.	0	Not used
SIOCTTLSCTL X'C038D90B'	56	For IOCTL structure layout, see SEZANMAC(EZBZTLS1) for PL/I, SEZANMAC(EZBZTLSP) for assembler, and SEZANMAC(EZBZTLSB) for COBOL.	56	For IOCTL structure layout, see SEZANMAC(EZBZTLS1) for PL/I, SEZANMAC(EZBZTLSP) for assembler, and SEZANMAC(EZBZTLSB) for COBOL.
Notes: When you call IOCTL with the SIOCGIFCONF command set, REQARG should contain the length in bytes of RETARG. Each interface is assigned a 32-byte array element and REQARG should be set to the number of interfaces times 32. TCP/IP Services can return up to 100 array elements. The size of the IP_MSFILTER structure must be equal to or greater than the size of the IMSF_Header value. The size of the GROUP_FILTER structure must be equal to or greater than the size of GF_Header value. The size of the PartnerInfo structure must be equal to or greater than the PI_FIXED_SIZE value.