z/OS Communications Server: IP Programmer's Guide and Reference
Previous topic | Next topic | Contents | Contact z/OS | Library | PDF


TCP⁄IP NMI response format

z/OS Communications Server: IP Programmer's Guide and Reference
SC27-3659-02

The following list describes the general format of the response:
  • The response header, which is defined by the NWMHeader structure, the request section descriptors (triplets), and the response section descriptors (quadruplets). Processing is slightly different for the request types (poll-type and action-type) as described in the following topics.
  • The request sections.
  • The response output. See the following topics about the poll-type and action-type response output for a description.
    Guideline: Some of the data in the response output uses data structures in a variable size. Do not rely on the documented size of the data structure for accessing data. You must use the length field of the response output section descriptors (triplets) to determine the correct size of each response.
    Tip: Connection elements for TN3270E Telnet server connection performance data are returned only if the connection is being monitored by a MonitorGroup that is mapped to the connection. See Connection monitoring mapping statement in z/OS Communications Server: IP Configuration Guide for details.

Processing poll-type request responses

The format of the response output depends on the specific request.
  • The following requests return one or more response section elements of the same type.
    Table 1. Poll-type request responses
    Request Response
    GetConnectionDetail NWMTCPConnEntry (assembler), NWMConnEntry (C/C++)
    GetDVIPAConnRTab NWMDvConnRTabEntry
    GetDVIPAList NWMDvListEntry
    GetDVIPAPortDist NWMDvPortDistEntry
    GetDVIPARoute NWMDvRouteEntry
    GetIfStats NWMIfStatsEntry
    GetStorageStatistics NWMStgStatEntry
    GetSysplexXCF NWMSyXcfEntry
    GetTCPListeners NWMTCPListenEntry
    GetTnConnectionData NWMTnConnEntry
    GetTnMonitorGroups NWMTnMonGrpEntry
    GetUDPTable NWMUDPConnEntry
  • The following requests return one or more records. Each record begins with an NWMRecHeader structure that describes the record. See the specific request topics for a detailed description of the response output of each request.
    • GetFTPDaemonConfig
    • GetGlobalStats
    • GetIfs
    • GetIfStatsExtended
    • GetProfile
    • GetRnics
    • GetSmcLinks
    • GetTNProfile
The response output is described by the response section quadruplet in the NWMHeader structure. The quadruplet consists of the following fields:
  • The offset, in bytes, of the first response section element or record. This offset is relative to the beginning of the response buffer.
  • The number of elements in the response section or the number of records that are returned.
  • The length of a response section element for requests that return one or more response section elements of the same type. For requests that return one or more records, the value of this field is 0. The NWMRecHeader structure for each returned record contains the actual length of each record.
  • The total number of elements that passed the requested filter checks.

The response header contains the number of bytes required to contain all the requested data. When the return code is ENOBUFS, use this value to allocate a larger request/response buffer and reissue the request.

GetFTPDaemonConfig response format

For the GetFTPDaemonConfig request, the output is returned as one record. The response section quadruplet contains the following values:
  • The offset, which is in the response buffer, of the output record.
  • The length of each element. It is always 0.
  • The number of elements that are returned is always 1, which indicates that only one record was returned.
  • The number of elements that matched the filters is always 1, which indicates that one record was matched.
The output record consists of the following fields:
Record header
The record header is mapped by the NWMRecHdr structure and consists of the following fields:
  • An EBCDIC identifier.
  • The total length of the record.
  • The number, which is always 3, of section descriptors that are included in this record. The section descriptors are mapped by the NWMTriple structure.
Section descriptor triplets
The following three section descriptors that describe the returned information for each section type are always included. For each section type, only one section is included.
  • FTP daemon identification section
  • FTP daemon general configuration section
  • FTP daemon configuration data section
The sections of data that this request provides are identical to the corresponding sections in the SMF 119 subtype 71 record. See FTP daemon configuration record (subtype 71) for the layout of these sections:
FTP daemon identification section - SMF119FT_FD
This section provides information that identifies which FTP daemon this record is collected for.
FTP daemon general configuration section - SMF119FT_FDCF
This section provides configuration information for the statements whose value has a fixed length.
FTP daemon configuration data section - SMF119FT_FDCD
This section provides configuration information for the statements whose value has a variable length. This section is a set of entries with a variable length for each statement. Each entry contains the following fields:
  • Total length of the entry.
  • Key of the entry. This value identifies the statement that the entry represents.
  • Value that is specified for the statement.

In this section, only statements that are explicitly specified or have default values are provided. You can use the SMF119FT_FDCD_Key value of each configuration data entry in this section to determine which statements are contained.

GetGlobalStats response format

For the GetGlobalStats request, the output is returned as one record. The response section quadruplet contains the following values:
  • The offset, which is in the response buffer, of the output record.
  • The length of each element. It is always 0.
  • The number of elements in the response section. It is set to 1 to indicate that only one record was returned.
  • The total number of matching elements. It is set to 1 because filters are not supported.
The output record consists of the following fields:
  • Record header. The record header is mapped by the NWMRecHdr structure and consists of the following fields:
    • An EBCDIC identifier
    • The total length of the record
    • The number of section descriptors (mapped by the NWMTriple structure) that are present in this record
  • Section descriptor triplets for each set of statistic counters. The returned statistic counters are similar to the counters in the output of the Netstat STATS/-S report. See Netstat STATS/-S report in z/OS Communications Server: IP System Administrator's Commands for a description of each field. The following section descriptors that describe the returned information for each section type are always included:
    • IP counters section - A section for IPv4 counters is always returned. If the TCP/IP stack is IPv6-enabled, a section for IPv6 counters is also returned.
    • IP general counters section - Only one section of this type is included.
    • TCP counters section - Only one section of this type is included. If Shared Memory Communications over Remote Direct Memory Access (SMC-R) was ever configured, this section includes SMC-R statistics.
    • UDP counters section - Only one section of this type is included.
    • ICMP global counters section - A section for IPv4 counters is always returned. If the TCP/IP stack is IPv6-enabled, a section for IPv6 counters is also returned.
    • ICMP type counters section - One section is returned for each ICMP and ICMPv6 type. For more information about these types, see http://www.iana.org/assignments/icmp-parameters and http://www.iana.org/assignments/icmpv6-parameters.
  • IP counters sections (NWMIpStatsEntry) - Sections for IPv4 and IPv6 counters.
  • IP general counters section (NWMIpGenStatsEntry)
  • TCP and SMC-R counters section (NWMTcpStatsEntry)
  • UDP counters section (NWMUdpStatsEntry)
  • ICMP global counters sections (NWMIcmpStatsEntry)
  • ICMP type counters sections (NWMIcmpTypeStatsEntry)

GetIfs response format

For the GetIfs request, the output is returned as one record per interface. The response section quadruplet contains the following values:
  • The offset, which is in the response buffer, of the first output record.
  • The length of each element. It is always 0.
  • The number of elements in the response section. It is set to the total number of records that are returned.
  • The total number of matching elements. It is set to the number of records that are returned because filters are not supported.
All fields that contain EBCDIC values are padded with EBCDIC blanks (x'40') and are set to EBCDIC blanks if the field does not contain a value.
Each output record consists of the following fields:
  • Record header. The record header is mapped by the NWMRecHdr structure and consists of the following fields:
    • An EBCDIC identifier
    • The total length of the record
    • The number of section descriptors (mapped by the NWMTriple structure) that are present in this record
  • Section descriptor triplets. Two section descriptors that describe the returned information for each section type are always included:
    • Base section - Only one section of this type is included per interface.
    • IP address section - Only one section of this type is included for every IP address for the interface. If an interface does not have an IP address, the section descriptor triplet fields are all set to 0.
  • Base section (NWMIfEntry). This section provides the interface name, status, and attributes.
  • One or more IP address sections (NWMIpadEntry)

GetIfStatsExtended response format

For the GetIfStatsExtended request, the data link control (DLC) tuning statistics output is returned as one record per data subchannel address that is used by an OSA-Express QDIO ethernet or HiperSockets™ interface. The response section quadruplet contains the following values:
  • The offset, which is in the response buffer, of the first output record.
  • The length of each element. It is always 0.
  • The number of elements in the response section. It is set to the total number of records that are returned.
  • The total number of matching elements. It is set to the number of records that are returned because filters are not supported.
All fields that contain EBCDIC values are padded with EBCDIC blanks (x'40').
Each output record consists of the following fields:
  • Record header. The record header is mapped by the NWMRecHdr structure and consists of the following fields:
    • An EBCDIC identifier
    • The total length of the record
    • The number of section descriptors (mapped by the NWMTriple structure) that are present in this record
  • Section descriptor triplets. Four section descriptors that describe the information that is returned for each section type are always included:
    • Base section - Only one section of this type is included per data subchannel address.
    • Interface section - One section of this type is included for each interface that shares the data subchannel address.
    • Read queue counters section - There is one of these sections for the Primary read queue.per read queue supported for the data subchannel address. For more information about the OSA-Express read queues, see QDIO inbound workload queueing in z/OS Communications Server: IP Configuration Guide. HiperSockets interfaces support only one read queue.
    • Write queue counters section - One section of this type is included for each of one to four possible write priority queues that are supported for the data subchannel address.
  • Base section (NWMIFStExtBaseEntry). This section provides information about the data, read control, write control subchannel addresses, the TRLE name, and OSA-Express ports. This section also includes a time stamp of when the counters were last reset.
  • Interface section (NWMIFStExtIntfEntry)
  • Read queue sections (NWMIfStExtReadEntry)
  • Write queue sections (NWMIfStExtWriteEntry)

GetProfile response format

For the GetProfile request, the output is returned as one record. The response section quadruplet contains the following values:
  • Offset is the offset, into the response buffer, of a GetProfile record header.
  • The length of each element is always 0.
  • The number of elements in the response section is always 1 to indicate that only one record was returned.
  • The total number of matching elements is always 1, because filters are not supported.
The record header is mapped by the NWMRecHdr structure. The header consists of the following fields:
  • An EBCDIC identifier
  • The total length of the record
  • The number of section descriptors (triplets) that are present in this record. Twenty-one section descriptors are always returned. The section descriptor triplets are mapped by the NWMTriple structure.
The section descriptors (triplets) immediately follow the record header, and the sections immediately follow the section descriptors. If there is no profile information for a section, the section descriptor triplet fields for that section all contain 0.

The section structures in the GetProfile response are identical to the section structures in the TCP/IP profile SMF 119 subtype 4 event records. If you already have an application that processes the SMF record section structures, you can also use it for processing the GetProfile response section structures. See TCP/IP profile event record (subtype 4) for a layout of this SMF record.

In the GetProfile response, the Profile Information Common and Data Set Name sections primarily contain information about the initial profile, not about the last change to the profile; however, the following fields contain the date and time of the last change to the profile:
  • NMTP_PICOChangeTime
  • NMTP_PICOChangeDate

GetRnics response format

For the GetRnics request, the output is returned as one record per interface. The response section quadruplet contains the following values:
  • The offset, which is in the response buffer, of the output record.
  • The length of each element. It is always 0.
  • The number of elements in the response section. It is set to the number of records that are returned.
  • The total number of matching elements. It is set to the number of records that are returned because filters are not supported on the GetRnics request.

All fields that contain EBCDIC values are padded with EBCDIC blanks (X'40').

Each output record consists of the following fields:
  • Record header. The record header is mapped by the NWMRecHdr structure and consists of the following fields:
    • An EBCDIC identifier
    • The total length of the record
    • The number of section descriptors (mapped by the NWMTriple structure) that are present in this record
  • Section descriptor triplets. Two section descriptors that describe the returned information for each section type are always included:
    • Base 10GbE RoCE Express® interface section; only one section of this type is included per interface.
    • VTAM® tuning statistics section; only one section of this type is included per interface.
  • Base 10GbE RoCE Express interface section (NWMRnicBaseEntry). This section provides the interface name, status, and attributes.
  • VTAM tuning statistics section (NWMRnicTuningEntry). This section provides the VTAM tuning statistics information.

GetSmcLinks response format

For the GetSmcLinks request, the output is returned as one record per SMC-R link group. The response section quadruplet contains the following values:

  • The offset, which is in the response buffer, of the output record.
  • The length of each element. It is always 0.
  • The number of elements in the response section. It is set to the number of records that are returned.
  • The total number of matching elements. It is set to the number of records that are returned because filters are not supported on the GetSmcLinks request.

All fields that contain EBCDIC values are padded with EBCDIC blanks (X'40').

Each output record consists of the following fields:

  • Record header. The record header is mapped by the NWMRecHdr structure and consists of the following fields:
    • An EBCDIC identifier
    • The total length of the record
    • The number of section descriptors (mapped by the NWMTriple structure) that are present in this record
  • Section descriptor triplets. Two section descriptors that describe the returned information for each section type are always included:
    • SMC-R link group section; only one section of this type is included per SMC-R link group.
    • SMC-R link section; one section of this type is included for every SMC-R link that is a member of an SMC-R link group.
  • SMC-R link group section (NWMSmcGrpEntry). This section provides the SMC-R link group identifier and statistics related to the SMC-R link group.
  • SMC-R link section (NWMSmcLnkEntry). This section provides the SMC-R link local and remote identifiers and additional statistics related to the individual link.

GetTnProfile response format

For the GetTnProfile request, the output is returned as one record. The response section quadruplet contains the following values:

  • Offset is the offset, into the response buffer, of a GetTnProfile record header.
  • The length of each element is always 0.
  • The number of elements in the response section is always 1 to indicate that only one record was returned.
  • The total number of matching elements is always 1 because filters are not supported.
The NWMRecHdr structure maps the record header. The header consists of the following fields:
  • An EBCDIC identifier.
  • The total length of the record.
  • The number of section descriptors (triplets) that are present in this record. Management section descriptors are always returned. The NWMTriple structure maps the section descriptors.

The section descriptors immediately follow the record header, and the sections immediately follow the section descriptors. If no profile information for a section is available, the section descriptor fields for that section are all 0.

The section structures in the GetTnProfile response are identical to the section structures in the TN3270E Telnet server profile SMF 119 subtype 24 event records. If you have an application that processes the SMF record section structures, you can use it to process the GetTnProfile response section structures. See TN3270E Telnet server profile event record (subtype 24) for a layout of this SMF record.

In the GetTnProfile response, the Profile Information and Data Set Name sections contain information about the last profile. The following fields contain the date and time when the last profile was activated:
  • SMF119TN_PIProfStck
  • SMF119TN_PIProfTime
  • SMF119TN_PIProfDate

If the NWMTnGrpDtl flag is set, multiple entries for a group are generated. If the flag is not set, only the first entry of each group is available.

Processing action-type request responses

Processing the response for the DropConnection action-type request is described in this section.

For this type of request, the quadruplet contains the offset and number of elements, which is the same as the offset and number of elements in the triplet (output is the same as the input). If the call to EZBNMIFR returns a nonnegative return value, and the value for NWMQMatch returned in the quadruplet section is equal to the number of entries input, NWMQNumber, then all of the connections or endpoints were dropped successfully. If the call to EZBNMIFR returns a nonnegative return value, and if NWMQMatch is less than NWMQNumber, then not all of the connections or endpoints were successfully dropped. In this case, the program should examine the return code that is set in each NWMDropConnEntry field. If the value of the return code is nonzero, then this connection was not dropped; if the value of the return code is 0, then the connection was dropped.

The following describes the codes:
Table 2. Return code values
NWMDropConnRC NWMDropConnRSN Description
ENOENT JRGetConnErr The connection was not in the correct state for retrieving or the connection was not found.
EMVSERR JRPATDELErr Deletion of a restricted port entry failed.
EACCES JRPORTACCESSAUTH User does not have authority to access this port.
EMVSERR JRPATFNDErr Search for a restricted port failed or the connection was not found.
ENOENT JRPATFNDErr Search for a restricted port failed or the connection was not found.
ENOENT JRGETCONNERR The connection was not in the correct state for retrieving.
EAGAIN JRUDPNOTUP TCP⁄IP was not initialized
EAGAIN JRTCPNOTUP The request was not successful. The target TCP⁄IP stack was not active.
EINVAL JRINVALIDVALUE The request was not successful. A value that is not valid was specified in the request/response header.
Guideline: Input to the DropConnection request will most likely be from the output result of a GetUDPTable or GetConnectionDetail request where the filtered connection information might return connections that are not intended for termination. Applications that support the DropConnection request should be coded to ensure that the connections input for termination have been examined carefully by programming logic that selects connections that meet a specific criteria, such as state.

Example

One NWMDropConnEntry is submitted:

Resource ID =003A, Local IP Address=9.0.0.1, Local Port=5003, 
Remote IP Address=9.0.0.5, Remote Port=3000, Protocol=TCP
The following TCP connections exist:
  • Resource Name = FTP1, Resource ID = 001A, Local IP Address = 9.0.0.2, Local Port = 5000,Remote IP Address = 9.0.0.5, Remote Port = 3001
  • Resource Name = FTP2, Resource ID = 002A, Local IP Address = 9.0.0.1, Local Port = 5001,Remote IP Address = 9.0.0.5, Remote Port = 3002
  • Resource Name = USR1, Resource ID = 004F, Local IP Address = 9.0.0.1, Local Port = 5002,Remote IP Address = 9.0.0.5, Remote Port = 3003
  • Resource Name = USR7, Resource ID = 003A, Local IP Address = 9.0.0.1, Local Port = 5003, Remote IP Address = 9.0.0.5, Remote Port = 3000

When a DropConnection request is made, connection 4 is dropped because it matches the five required items.

Parent topic: TCP/IP callable NMI (EZBNMIFR)

Go to the previous page Go to the next page

Notices | Terms of use | Support | Contact z/OS | zFavorites



Copyright IBM Corporation 1990, 2014