|
- SOC-FUNCTION
- A 16-byte character field containing IOCTL. The field is left-aligned
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. 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 assembly 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 SIOCGHOMEIF6Working-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 returned for an interface only if it has
at least one available IP address. 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 assembly 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:
- Determine the number of interfaces expected to be returned upon
successful completion of this command.
- 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.
- 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 assembly 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:
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 argumentsCOMMAND/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 note1. |
|
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. |
Note: - 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.
|
|