Retrieve Network Connection Data (QtocRtvNetCnnDta) API
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Socket connection request | Input | Char(*) |
| 5 | Error Code | I/O | Char(*) |
Service Program: QTOCNETSTS
Threadsafe: Yes
The Retrieve Network Connection Data (QtocRtvNetCnnDta) API retrieves detailed information about a specified IPv4 or IPv6 network connection, including jobs using the connection. It also retrieves information about IPv4 and IPv6 connection totals.
TCP/IP must be active on this system, otherwise, TCP84C0 message will be issued.
The QSYS2.NETSTAT_INFO and QSYS2.NETSTAT_JOB_INFO views can be used as alternatives to this API. See NETSTAT_INFO view and NETSTAT_JOB_INFO view for more information.
Authorities and Locks
None.
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The variable that is to receive the information requested. You can specify the size of this area to be smaller than the format requested if you specify the length of receiver variable parameter correctly. As a result, the API returns only the data that the area can hold.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable. If this value is larger than the actual size of the receiver variable, the result may not be predictable. The minimum length is 8 bytes.
- Format name
- INPUT; CHAR(8)
The format of the space information to be returned. The format names supported are:
NCND0100 TCP/IPv4 connection totals. See NCND0100 Format for details on the format. NCND0200 Detailed TCP or UDP connection status for a specific IPv4 socket connection in addition to TCP/IPv4 connection totals. See NCND0100 Format and NCND0200 Format for details on the format. NCND1100 TCP/IPv6 connection totals. See NCND1100 Format for details on the format. NCND1200 Detailed TCP or UDP connection status for a specific IPv6 socket connection in addition to TCP/IPv6 connection totals. See NCND1100 Format and NCND1200 Format for details on the format.
- Socket connection request
- INPUT; CHAR(*)
The protocol, local address, local port, remote address and remote port identify the connection for which information is to be retrieved. This parameter is ignored when format NCND0100 or format NCND1100 is requested. See Socket Connection Request Format for details on the format.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Socket Connection Request Format
Information passed in the socket connection request parameter must be in one of the following two formats. The first format is for IPv4 connections, and the second is for IPv6 connections. The value of the Protocol field determines the format of the rest of the Socket Connection Request. For detailed descriptions of the fields in the table, see Field Descriptions.
IPv4 connection (Protocol field value is 1 or 2)
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Protocol |
| 4 | 4 | BINARY(4) | Local IPv4 address |
| 8 | 8 | BINARY(4) | Local port number |
| 12 | C | BINARY(4) | Remote IPv4 address |
| 16 | 10 | BINARY(4) | Remote port number |
| 20 | 14 | ||
IPv6 connection (Protocol field value is 3 or 4)
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Protocol |
| 4 | 4 | CHAR(16) | Local IPv6 address |
| 20 | 14 | CHAR(4) | Local port number |
| 24 | 18 | CHAR(16) | Remote IPv6 address |
| 40 | 28 | BINARY(4) | Remote port number |
| 44 | 2C | ||
Field Descriptions
Local IPv4 address. The IPv4 address of the host at the local end of the connection.
Local IPv6 address. The IPv6 address of the host at the local end of the connection. Even though this field is defined as a character field, it must be stored in binary. It is recommended that you use the Sockets in6_addr structure.
Local port number. The port number of the local end of the connection.
Protocol. The type and IP version of connection protocol.
Possible values are:
| 0 | TCP/IP connection totals when using format NCND0100 or format NCND1100. |
| 1 | TCP/IPv4 - A Transmission Control Protocol (TCP) over IPv4 connection or socket request. |
| 2 | UDP/IPv4 - A User Datagram Protocol (UDP) over IPv4 socket request. |
| 3 | TCP/IPv6 - A Transmission Control Protocol (TCP) over IPv6 connection or socket request. |
| 4 | UDP/IPv6 - A User Datagram Protocol (UDP) over IPv6 socket request. |
Remote IPv4 address. The IPv4 address of the host at the remote end of the connection.
Remote IPv6 address. The IPv6 address of the host at the remote end of the connection. Even though this field is defined as a character field, it must be stored in binary. It is recommended that you use the Sockets in6_addr structure.
Remote port number. The port number of the remote end of the connection.
Format of Returned Connection Data
To retrieve the current TCP/IPv4 connection totals, use format NCND0100.
To retrieve the current TCP/IPv6 connection totals, use format NCND1100.
For detailed TCP and UDP connection status for a specific IPv4 socket connection in addition to the TCP/IPv4 connection totals, use format NCND0200.
For detailed TCP and UDP connection status for a specific IPv6 socket connection in addition to the TCP/IPv6 connection totals, use format NCND1200.
NCND0100 Format
Format NCND0100 returns information regarding the TCP/IPv4 connection totals. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | TCP connections currently established |
| 12 | C | BINARY(4) | TCP active opens |
| 16 | 10 | BINARY(4) | TCP passive opens |
| 20 | 14 | BINARY(4) | TCP attempted opens that failed |
| 24 | 18 | BINARY(4) | TCP established and then reset |
| 28 | 1C | BINARY(4) | TCP segments sent |
| 32 | 20 | BINARY(4) | TCP retransmitted segments |
| 36 | 24 | BINARY(4) | TCP reset segments |
| 40 | 28 | BINARY(4) | TCP segments received |
| 44 | 2C | BINARY(4) | TCP segments received in error |
| 48 | 30 | BINARY(4) | UDP datagrams sent |
| 52 | 34 | BINARY(4) | UDP datagrams received |
| 56 | 38 | BINARY(4) | UDP datagrams not delivered - application port not found |
| 60 | 3C | BINARY(4) | UDP datagrams not delivered - other datagrams in error |
| 64 | 40 | BINARY(4) | Offset to additional information |
| 68 | 44 | BINARY(4) | Length of additional information |
| 72 | 48 | ||
Field Descriptions
Bytes available. All of the available bytes for use in your application.
Bytes returned. The number of bytes returned to the user. This may be some but not all the bytes available.
Length of Additional Information.The length in bytes of additional information returned that is not part of format NCND0100.
Offset to Additional Information. The offset in bytes to the rest of the information if a format other than NCND0100 is requested.
TCP active opens. The number of times TCP connections have made a direct transition to the SYN-SENT state from the CLOSED state. This number is an indication of the number of times this local system opened a connection to a remote system.
TCP attempted opens that failed. The total number of times TCP connections have made direct transitions to a CLOSED state from either the SYN-SENT state or the SYN-RECEIVED state and/or to LISTEN from SYN-RECEIVED.
TCP connections currently established. The number of TCP connections for which the current state is either ESTABLISHED or CLOSE-WAIT.
TCP established and then reset. The number of times TCP connections have made a direct transition to the CLOSED state from either the ESTABLISHED state or the CLOSE-WAIT state.
TCP passive opens. The number of times TCP connections have made a direct transition to the SYN-RECEIVED state from the LISTEN state. This number is an indication of the number of times a remote system opened a connection to this system.
TCP reset segments. The number of TCP segments sent containing the RST flag.
TCP retransmitted segments. The number of TCP segments transmitted containing one or more previously transmitted octets.
TCP segments received. The total number of segments received, including those received in error. This count includes segments received on currently established connections.
TCP segments received in error. The total number of segments received in error (for example, bad TCP checksums).
TCP segments sent. The total number of segments sent, including those on current connections but excluding those containing only retransmitted octets.
UDP datagrams not delivered - application port not found. The total number of received UDP datagrams for UDP users for which there was no application at the destination port.
UDP datagrams not delivered - other datagrams in error. The number of received UDP datagrams that could not be delivered for reasons other than the lack of an application at the destination port.
UDP datagrams received. The total number of datagrams received, including those received in error. This count includes datagrams received on currently established connections.
UDP datagrams sent. The total number of UDP datagrams sent from all connections since TCP/IP was started.
NCND0200 Format
This format returns detailed information about the TCP connection status in addition to the TCP/IPv4 connection totals (format NCND0100). For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Returns everything from format NCND0100 | |
| Decimal and hexadecimal offsets are reached by using the offset to additional information field in format NCND0100. This applies to all entries below. | BINARY(4) | Protocol | |
| BINARY(4) | Local IP address | ||
| BINARY(4) | Local port number | ||
| BINARY(4) | Remote IP address | ||
| BINARY(4) | Remote port number | ||
| BINARY(4) | Round-trip time | ||
| BINARY(4) | Round-trip variance | ||
| BINARY(4) | Outgoing bytes buffered | ||
| BINARY(4) | User send next | ||
| BINARY(4) | Send next | ||
| BINARY(4) | Send unacknowledged | ||
| BINARY(4) | Outgoing push number | ||
| BINARY(4) | Outgoing urgency number | ||
| BINARY(4) | Outgoing window number | ||
| BINARY(4) | Incoming bytes buffered | ||
| BINARY(4) | Receive next | ||
| BINARY(4) | User receive next | ||
| BINARY(4) | Incoming push number | ||
| BINARY(4) | Incoming urgency number | ||
| BINARY(4) | Incoming window number | ||
| BINARY(4) | Total retransmissions | ||
| BINARY(4) | Current retransmissions | ||
| BINARY(4) | Maximum window size | ||
| BINARY(4) | Current window size | ||
| BINARY(4) | Last update | ||
| BINARY(4) | Last update acknowledged | ||
| BINARY(4) | Congestion window | ||
| BINARY(4) | Slow start threshold | ||
| BINARY(4) | Maximum segment size | ||
| BINARY(4) | Initial send sequence number | ||
| BINARY(4) | Initial receive sequence number | ||
| BINARY(4) | Connection transport layer | ||
| BINARY(4) | TCP state | ||
| BINARY(4) | Connection open type | ||
| BINARY(4) | Idle time in milliseconds | ||
| CHAR(40) | IP options | ||
| BINARY(4) | Bytes in | ||
| BINARY(4) | Bytes out | ||
| BINARY(4) | Socket state | ||
| BINARY(4) | Offset to list of socket options associated with connection | ||
| BINARY(4) | Number of socket options associated with connection | ||
| BINARY(4) | Entry length for list of socket options associated with connection | ||
| BINARY(4) | Offset to list of jobs associated with connection | ||
| BINARY(4) | Number of jobs associated with connection | ||
| BINARY(4) | Entry length for list of jobs associated with connection | ||
| CHAR(10) | Associated user profile | ||
| CHAR(2) | Reserved | ||
List of Socket Options
These fields repeat for each socket option.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Socket option |
| 4 | 4 | BINARY(4) | Option value |
| 8 | 8 | ||
List of Jobs/Tasks Associated with this Connection
These fields repeat for each job or task.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Format entry |
| 4 | 4 | CHAR(16) | Task name |
| 20 | 14 | CHAR(10) | Job name |
| 30 | 1E | CHAR(10) | Job user name |
| 40 | 28 | CHAR(6) | Job number |
| 46 | 2E | CHAR(16) | Internal job identifier |
| 62 | 3E | CHAR(1) | Job type |
| 63 | 3F | CHAR(7) | Reserved |
| 70 | 46 | CHAR(10) | Current user profile |
| 80 | 50 | ||
Field Descriptions
Associated user profile. The user profile of the job on the local system which first performed a sockets API bind() of the socket.
Note: This field does not reliably indicate the current user of a connection or socket. To see a list of the jobs or tasks currently using a connection or socket, use the List of Jobs/Tasks Associated with this Connection.
Bytes in. The total number of bytes received on the connection, including framing characters.
Bytes out. The total number of bytes transmitted on the connection, including framing characters.
Congestion window. The number of segments that are sent on the next transmission. If an acknowledgment is received, the number is increased. If an acknowledgment is not received, the number is reset to the smallest allowable number. This field is only valid for TCP connections.
Connection open type. A TCP connection can be opened in the following ways:
| 0 | Passive - A remote host opens the connection. |
| 1 | Active - The local system opens the connection. |
| 2 | Unsupported - Connection open type not supported by protocol. |
Connection transport layer. The transport that a connection is using:
| 0 | IPS |
| 1 | IPX
Note: As of V5R2, IPX is no longer supported. |
| 2 | TCP/IP |
Current retransmissions. The number of times the local system retransmitted the current segment without receiving an acknowledgment. This is sometimes referred to as the 'backoff count'. This field is only valid for TCP connections.
Current user profile. The user profile that the thread for which information is being retrieved is currently running under. This name may differ from the user portion of the job name. If this field is requested for a job, the value for the initial thread of the job will be returned.
Current window size. The current send window size in bytes. This field is only valid for TCP connections.
Entry length for list of jobs associated with connection. The entry length in bytes of each element in the list of job connections returned with this format. A value of zero is returned if the list is empty.
Entry length for list of socket options associated with connection. The entry length in bytes of each element in the list of socket options returned with this format. A value of zero is returned if the list is empty.
Format entry. Type of list format for job or task connections.
| 1 | Represents a job format. For this format the task name will be blank. |
| 2 | Represents a task format. For this format the job name, username, number and internal identifier will be blank. |
Idle time. The length of time since the last activity on this connection. The length of time is returned in milliseconds.
Incoming bytes buffered. The current number of bytes that are received and buffered by TCP. These bytes are available to be read by an application.
Incoming push number. The sequence number of the last byte of pushed data in the incoming data stream. This value is zero if no push data is in the incoming data stream. This field is only valid for TCP connections.
Incoming urgency number. The sequence number of the last byte of urgent data in the incoming data stream. This value is zero if no urgent data is in the incoming data stream. This field is only valid for TCP connections.
Incoming window number. The largest sequence number in the incoming window of this connection. Data bytes in the incoming stream having sequence numbers larger than this number are not accepted. This field is only valid for TCP connections.
Initial receive sequence number. The first sequence number received on this connection. This field is only valid for TCP connections.
Initial send sequence number. The first sequence number sent on this connection. This field is only valid for TCP connections.
IP options. Used in displaying the IP datagram options that may have been specified for a connection.
Internal job identifier. A value sent to other APIs to speed the process of locating the job on the system.
Job name. The simple job name as identified to the system.
Job number. System-assigned job or task number.
Job type. The type of the job.
| blank | The job is not a valid job. |
| A | The job is an autostart job. |
| B | The job is a batch job. |
| I | The job is an interactive job. |
| M | The job is a subsystem monitor job. |
| R | The job is a spooled reader job. |
| S | The job is a system job. |
| W | The job is a spooled writer job. |
| X | The job is the SCPF system job. |
Job user name. The user name identifies the user profile under which the job is started. The following special value may be returned:
| *SIGNON | This connection is a telnet connection and the system is performing sign-on processing or is displaying a sign-on prompt on it. In this case the Job name field will contain the network device name, the Job number and Internal job identifier fields will be empty. |
Last update. The sequence number of the incoming segment used for the last window update that occurred on the connection. This field is only valid for TCP connections.
Last update acknowledged. The acknowledgment number of the incoming segment used for the last window update that occurred on the connection. This field is only valid for TCP connections.
Local IP address. The local address of this connection on this system.
Local port number. Your local system port number.
Maximum segment size. The size in bytes of the largest segment that may be transmitted on this connection. This field is only valid for TCP connections.
Maximum window size. The largest size of the send window, in bytes, during the entire time the connection has been active. This field is only valid for TCP connections.
Number of jobs associated with connection. The number of elements in the list of job connections returned with this format. A value of zero is returned if the list is empty.
Number of socket options associated with connection. The number of elements in the list of socket options returned with this format. A value of zero is returned if the list is empty.
Offset to list of jobs associated with connection. The offset in bytes to the first element in the list of job connections returned with this format. A value of zero is returned if the list is empty.
Offset to list of socket options associated with connection. The offset in bytes to the first element in the list of socket options returned with this format. A value of zero is returned if the list is empty.
Option value. The value returned for a particular socket option. Option is set if a nonzero value is returned.
Outgoing bytes buffered. The current number of bytes that an application has requested to send, but TCP has not yet sent. If TCP has sent the bytes to the remote system but has not yet received an acknowledgment, the bytes are considered 'not sent'. They are included in this count.
Outgoing push number. The sequence number of the last byte of push data in the outgoing stream. This value is zero if no push data is in the outgoing data stream. This field is only valid for TCP connections.
Outgoing urgency number. The sequence number of the last byte of urgent data in the outgoing data stream. This value is zero if no urgent data is in the outgoing data stream. This field is only valid for TCP connections.
Outgoing window number. The largest sequence number in the send window of the connection. The local TCP application cannot send data bytes with sequence numbers greater than the outgoing window number.
Protocol. Identifies the type of connection protocol.
| 1 | TCP - A Transmission Control Protocol (TCP) connection or socket. |
| 2 | UDP - A User Datagram Protocol (UDP) socket. |
Receive next. The next sequence number the local TCP is expecting to receive.
Remote IP address. The Internet address of the remote host. Zero is shown, if the list entry is for a UDP socket.
Remote port number. The remote host port number. Zero is shown, if the list entry is for a UDP socket.
Reserved. An ignored field.
Round-trip time. The smoothed round-trip time interval in milliseconds. This is a measure of the time required for a segment on the connection to arrive at its destination, to be processed, and to return an acknowledgment to the client. This field is only valid for TCP connections.
Round-trip variance.The variance in milliseconds from the previous round-trip time. This field is only valid for TCP connections.
Send next. The sequence number of the next byte of data that the local TCP application sends to the remote TCP application.
Send unacknowledged. The sequence number of the last segment sent that was not acknowledged. This is the smallest sequence number of the send window. This field is only valid for TCP connections.
Slow start threshold. The current values for the slow-start threshold and the congestion window are indirect indicators of the flow of data through a TCP connection. These values are used by TCP as part of a congestion control algorithm. This algorithm ensures that this system sends data at a slow rate at first. After the first data has been successfully sent, the rate in which data is sent increases. This change is made in a controlled manner that is dependent on the amount of congestion in the network. Congestion control occurs both at connection start time and when congestion is detected. The values used for the slow-start threshold and the congestion window are determined by TCP and cannot be set by the user.
Socket option. Socket options for this connection.
| 1 | Socket broadcast option Determine if messages can be sent to the broadcast address. This option is only supported for sockets with an address family of AF_INET and type SOCK_DGRAM or SOCK_RAW. Option is set if a nonzero value is returned. | ||||||||
| 2 | Socket bypass route option - Determine if the normal routing mechanism is being bypassed. This option is only supported by sockets with an address family of AF_INET or AF_INET6. Option is set if a nonzero value is returned. | ||||||||
| 3 | Socket debug option - Determine if low-level debugging is active. Option is set if a nonzero value is returned. | ||||||||
| 4 | Socket error - Return any pending errors in the socket. The value returned corresponds to the standard error codes. | ||||||||
| 5 | Socket keep alive option - Determine if the connection is being kept up by periodic transmissions. This option is only supported for sockets with an address family of AF_INET or AF_INET6 and type SOCK_STREAM. Option is set if a nonzero value is returned. | ||||||||
| 6 | Socket linger option - Determine whether the system attempts to deliver any buffered data or if the system discards it when a close() is issued. For sockets that are using a connection-oriented transport service with an address family of AF_INET or AF_INET6, the default is off (which means that the system attempts to send any queued data, with an infinite wait-time). | ||||||||
| 7 | Socket linger time - Determine how much time in seconds the system will wait to send buffered data. | ||||||||
| 8 | Socket out-of-band data option - Determine if out-of-band data is received inline with normal data. This option is only supported for sockets with an address family of AF_INET or AF_INET6. Option is set if a nonzero value is returned. | ||||||||
| 9 | Socket receive buffer size - Determine the size of the receive buffer. | ||||||||
| 10 | Socket receive low-water mark size - Determine the size of the receive low-water mark. The default size is 1. This option is only supported for sockets with type SOCK_STREAM. | ||||||||
| 11 | Socket reuse address option - Determine if the local socket address can be reused. This option is only supported by sockets with an address family of AF_INET or AF_INET6 and with type SOCK_STREAM or SOCK_DGRAM. Option is set if a nonzero value is returned. | ||||||||
| 12 | Socket send buffer size - Determine the size of the send buffer. | ||||||||
| 13 | Socket type value - Determine
the value for the socket type.
|
||||||||
| 14 | Socket use loopback option - Indicates if the loopback feature is being used. Option is set if a nonzero value is returned. | ||||||||
| 15 | Socket receive timeout - Determine the receive timeout value. | ||||||||
| 16 | Socket send lo-water mark size - Determine the size of the send low-water mark. | ||||||||
| 17 | Socket send timeout - Determine the send timeout value. |
Socket state. The current state of the socket.
| 0 | Uninitialized |
| 1 | Unbound |
| 2 | Bound |
| 3 | Listening |
| 4 | Connecting |
| 5 | Connected |
| 6 | Disconnected |
| 7 | Error |
Task name. The task name as identified to the system.
TCP state. A typical connection goes through the states:
| 0 | Listen, waiting for a connection request from any remote host. |
| 1 | SYN-sent, waiting for a matching connection request after having sent connection request. |
| 2 | SYN-received, waiting for a confirming connection request acknowledgement. |
| 3 | Established, the normal state in which data is transferred. |
| 4 | FIN-wait-1, waiting for the remote host to acknowledge the local system request to end the connection. |
| 5 | FIN-wait-2, waiting for the remote host request to end the connection. |
| 6 | Close-wait, waiting for an end connection request from the local user. |
| 7 | Closing, waiting for an end connection request acknowledgement from the remote host. |
| 8 | Last-ACK, waiting for the remote host to acknowledge an end connection request. |
| 9 | Time-wait, waiting to allow the remote host enough time to receive the local system's acknowledgement to end the connection. |
| 10 | Closed, the connection has ended. |
| 11 | State value not supported by protocol. |
Total retransmissions. The total number of times the local system retransmitted a segment because an acknowledgment was not received. This is a cumulative count of all segments resent during the entire time the connection has been active. This field is only valid for TCP connections.
User send next. The sequence number of the next byte of data to be sent by the client application. This field is only valid for TCP connections.
User receive next. The sequence number of the next byte to be passed to the application by TCP.
NCND1100 Format
Format NCND1100 returns information regarding the TCP/IPv6 connection totals. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | TCP connections currently established |
| 12 | C | BINARY(4) | TCP active opens |
| 16 | 10 | BINARY(4) | TCP passive opens |
| 20 | 14 | BINARY(4) | TCP attempted opens that failed |
| 24 | 18 | BINARY(4) | TCP established and then reset |
| 28 | 1C | BINARY(4) | TCP segments sent |
| 32 | 20 | BINARY(4) | TCP retransmitted segments |
| 36 | 24 | BINARY(4) | TCP reset segments |
| 40 | 28 | BINARY(4) | TCP segments received |
| 44 | 2C | BINARY(4) | TCP segments received in error |
| 48 | 30 | BINARY(4) | UDP datagrams sent |
| 52 | 34 | BINARY(4) | UDP datagrams received |
| 56 | 38 | BINARY(4) | UDP datagrams not delivered - application port not found |
| 60 | 3C | BINARY(4) | UDP datagrams not delivered - other datagrams in error |
| 64 | 40 | BINARY(4) | Offset to additional information |
| 68 | 44 | BINARY(4) | Length of additional information |
| 72 | 48 | ||
Field Descriptions
Bytes available. All of the available bytes for use in your application.
Bytes returned. The number of bytes returned to the user. This may be some but not all the bytes available.
Length of Additional Information.The length in bytes of additional information returned that is not part of format NCND0100.
Offset to Additional Information. The offset in bytes to the rest of the information if a format other than NCND0100 is requested.
TCP active opens. The number of times TCP connections have made a direct transition to the SYN-SENT state from the CLOSED state. This number is an indication of the number of times this local system opened a connection to a remote system.
TCP attempted opens that failed. The total number of times TCP connections have made direct transitions to a CLOSED state from either the SYN-SENT state or the SYN-RECEIVED state and/or to LISTEN from SYN-RECEIVED.
TCP connections currently established. The number of TCP connections for which the current state is either ESTABLISHED or CLOSE-WAIT.
TCP established and then reset. The number of times TCP connections have made a direct transition to the CLOSED state from either the ESTABLISHED state or the CLOSE-WAIT state.
TCP passive opens. The number of times TCP connections have made a direct transition to the SYN-RECEIVED state from the LISTEN state. This number is an indication of the number of times a remote system opened a connection to this system.
TCP reset segments. The number of TCP segments sent containing the RST flag.
TCP retransmitted segments. The number of TCP segments transmitted containing one or more previously transmitted octets.
TCP segments received. The total number of segments received, including those received in error. This count includes segments received on currently established connections.
TCP segments received in error. The total number of segments received in error (for example, bad TCP checksums).
TCP segments sent. The total number of segments sent, including those on current connections but excluding those containing only retransmitted octets.
UDP datagrams not delivered - application port not found. The total number of received UDP datagrams for UDP users for which there was no application at the destination port.
UDP datagrams not delivered - other datagrams in error. The number of received UDP datagrams that could not be delivered for reasons other than the lack of an application at the destination port.
UDP datagrams received. The total number of datagrams received, including those received in error. This count includes datagrams received on currently established connections.
UDP datagrams sent. The total number of UDP datagrams sent from all connections since TCP/IP was started.
NCND1200 Format
This format returns detailed information about the TCP connection status in addition to the TCP/IPv6 connection totals (format NCND1100). For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Returns everything from format NCND1100 | |
| Decimal and hexadecimal offsets are reached by using the offset to additional information field in format NCND1100. This applies to all entries below. | BINARY(4) | Protocol | |
| CHAR(16) | Local IPv6 address | ||
| BINARY(4) | Local port number | ||
| CHAR(16) | Remote IPv6 address | ||
| BINARY(4) | Remote port number | ||
| BINARY(4) | Round-trip time | ||
| BINARY(4) | Round-trip variance | ||
| BINARY(4) | Outgoing bytes buffered | ||
| BINARY(4) | User send next | ||
| BINARY(4) | Send next | ||
| BINARY(4) | Send unacknowledged | ||
| BINARY(4) | Outgoing push number | ||
| BINARY(4) | Outgoing urgency number | ||
| BINARY(4) | Outgoing window number | ||
| BINARY(4) | Incoming bytes buffered | ||
| BINARY(4) | Receive next | ||
| BINARY(4) | User receive next | ||
| BINARY(4) | Incoming push number | ||
| BINARY(4) | Incoming urgency number | ||
| BINARY(4) | Incoming window number | ||
| BINARY(4) | Total retransmissions | ||
| BINARY(4) | Current retransmissions | ||
| BINARY(4) | Maximum window size | ||
| BINARY(4) | Current window size | ||
| BINARY(4) | Last update | ||
| BINARY(4) | Last update acknowledged | ||
| BINARY(4) | Congestion window | ||
| BINARY(4) | Slow start threshold | ||
| BINARY(4) | Maximum segment size | ||
| BINARY(4) | Initial send sequence number | ||
| BINARY(4) | Initial receive sequence number | ||
| BINARY(4) | Connection transport layer | ||
| BINARY(4) | TCP state | ||
| BINARY(4) | Connection open type | ||
| BINARY(4) | Idle time | ||
| BINARY(8) | Bytes in | ||
| BINARY(8) | Bytes out | ||
| BINARY(4) | Socket state | ||
| CHAR(10) | Associated user profile | ||
| CHAR(2) | Reserved | ||
| BINARY(4) | Offset to list of socket options associated with connection | ||
| BINARY(4) | Number of socket options associated with connection | ||
| BINARY(4) | Entry length for list of socket options associated with connection | ||
| BINARY(4) | Offset to list of jobs associated with connection | ||
| BINARY(4) | Number of jobs associated with connection | ||
| BINARY(4) | Entry length for list of jobs associated with connection | ||
List of Socket Options
These fields repeat for each socket option.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Socket option |
| 4 | 4 | BINARY(4) | Option value |
| 8 | 8 | ||
List of Jobs/Tasks Associated with this Connection
These fields repeat for each job or task.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Format entry |
| 4 | 4 | CHAR(16) | Task name |
| 20 | 14 | CHAR(10) | Job name |
| 30 | 1E | CHAR(10) | Job user name |
| 40 | 28 | CHAR(6) | Job number |
| 46 | 2E | CHAR(16) | Internal job identifier |
| 62 | 3E | CHAR(1) | Job type |
| 63 | 3F | CHAR(7) | Reserved |
| 70 | 46 | CHAR(10) | Current user profile |
| 80 | 50 | ||
Field Descriptions
Associated user profile. The user profile of the job on the local system which first performed a sockets API bind() of the socket.
Note: This field does not reliably indicate the current user of a connection or socket. To see a list of the jobs or tasks currently using a connection or socket, use the List of Jobs/Tasks Associated with this Connection.
Bytes in. The total number of bytes received on the connection, including framing characters.
Bytes out. The total number of bytes transmitted on the connection, including framing characters.
Congestion window. The number of segments that are sent on the next transmission. If an acknowledgment is received, the number is increased. If an acknowledgment is not received, the number is reset to the smallest allowable number. This field is only valid for TCP connections.
Connection open type. The method in which the TCP connection was opened.
Possible values are:
| 0 | Passive - A remote host opened the connection. |
| 1 | Active - The local system opened the connection. |
| 2 | Unsupported - Connection open type not supported by protocol. |
Connection transport layer. The transport that the connection is using.
Possible values are:
| 0 | IPS |
| 1 | IPX
Note: As of V5R2, IPX is no longer supported. |
| 2 | TCP/IP |
Current retransmissions. The number of times the local system retransmitted the current segment without receiving an acknowledgment. This is sometimes referred to as the 'backoff count'. This field is only valid for TCP connections.
Current user profile. The user profile that the thread for which information is being retrieved is currently running under. This name may differ from the user portion of the job name. If this field is requested for a job, the value for the initial thread of the job will be returned.
Current window size. The current send window size in bytes. This field is only valid for TCP connections.
Entry length for list of jobs associated with connection. The entry length in bytes of each element in the list of job connections returned with this format. A value of zero is returned if the list is empty.
Entry length for list of socket options associated with connection. The entry length in bytes of each element in the list of socket options returned with this format. A value of zero is returned if the list is empty.
Entry type. Specifies whether this entry is a job or a task.
Possible values are:
| 1 | Represents a job format. For this format the task name field is not applicable. |
| 2 | Represents a task format. For this format the job name, username, number and internal job identifier fields are not applicable. |
Idle time. The length of time since the last activity on this connection. The length of time is returned in milliseconds.
Incoming bytes buffered. The current number of bytes that are received and buffered by TCP. These bytes are available to be read by an application.
Incoming push number. The sequence number of the last byte of pushed data in the incoming data stream. This value is zero if no push data is in the incoming data stream. This field is only valid for TCP connections.
Incoming urgency number. The sequence number of the last byte of urgent data in the incoming data stream. This value is zero if no urgent data is in the incoming data stream. This field is only valid for TCP connections.
Incoming window number. The largest sequence number in the incoming window of this connection. Data bytes in the incoming stream having sequence numbers larger than this number are not accepted. This field is only valid for TCP connections.
Initial receive sequence number. The first sequence number received on this connection. This field is only valid for TCP connections.
Initial send sequence number. The first sequence number sent on this connection. This field is only valid for TCP connections.
Internal job identifier. A value sent to other APIs to speed the process of locating the job on the system.
Job name. The simple job name as identified to the system.
Job number. System-assigned job or task number.
Job type. The type of the job.
| blank | The job is not a valid job. |
| A | The job is an autostart job. |
| B | The job is a batch job. |
| I | The job is an interactive job. |
| M | The job is a subsystem monitor job. |
| R | The job is a spooled reader job. |
| S | The job is a system job. |
| W | The job is a spooled writer job. |
| X | The job is the SCPF system job. |
Job user name. The user name identifies the user profile under which the job is started.
The following special value may be returned:
| *SIGNON | This connection is a telnet connection and the system is performing sign-on processing or is displaying a sign-on prompt on it. In this case the Job name field will contain the network device name, and the Job number and Internal job identifier fields will be empty. |
Last update. The sequence number of the incoming segment used for the last window update that occurred on the connection. This field is only valid for TCP connections.
Last update acknowledged. The acknowledgment number of the incoming segment used for the last window update that occurred on the connection. This field is only valid for TCP connections.
Local IPv6 address. The local system Internet address, in IPv6 address format, of the connection. Even though this field is defined as a character field, a binary IPv6 address is returned in it.
Local port number. The port number of the local end of the connection.
Maximum segment size. The size in bytes of the largest segment that may be transmitted on this connection. This field is only valid for TCP connections.
Maximum window size. The largest size of the send window, in bytes, during the entire time the connection has been active. This field is only valid for TCP connections.
Number of jobs associated with connection. The number of elements in the list of job connections returned with this format. A value of zero is returned if the list is empty.
Number of socket options associated with connection. The number of elements in the list of socket options returned with this format. A value of zero is returned if the list is empty.
Offset to list of jobs associated with connection. The offset in bytes to the first element in the list of job connections returned with this format. A value of zero is returned if the list is empty.
Offset to list of socket options associated with connection. The offset in bytes to the first element in the list of socket options returned with this format. A value of zero is returned if the list is empty.
Option value. The value returned for a particular socket option. The socket option is set if a nonzero value is returned.
Outgoing bytes buffered. The current number of bytes that an application has requested to send, but TCP has not yet sent. If TCP has sent the bytes to the remote system but has not yet received an acknowledgment, the bytes are considered 'not sent'. They are included in this count.
Outgoing push number. The sequence number of the last byte of push data in the outgoing stream. This value is zero if no push data is in the outgoing data stream. This field is only valid for TCP connections.
Outgoing urgency number. The sequence number of the last byte of urgent data in the outgoing data stream. This value is zero if no urgent data is in the outgoing data stream. This field is only valid for TCP connections.
Outgoing window number. The largest sequence number in the send window of the connection. The local TCP application cannot send data bytes with sequence numbers greater than the outgoing window number.
Protocol. Identifies the type of connection protocol.
| 1 | TCP - A Transmission Control Protocol (TCP) connection or socket. |
| 2 | UDP - A User Datagram Protocol (UDP) socket. |
Receive next. The next sequence number that TCP is expecting to receive.
Remote IPv6 address. The local system Internet address, in IPv6 address format, of the connection. Even though this field is defined as a character field, a binary IPv6 address is returned in it.
The following special value may be returned:
| 0 | This "connection" is a listening socket, and there is no remote IPv6 address. The zero is returned as a series of binary NULLs (x'000000...') |
Remote port number. The port number of the remote end of the connection.
The following special value may be returned:
| 0 | This "connection" is a listening socket and there is no remote port number. |
Reserved. An ignored field.
Round-trip time. The smoothed round-trip time interval in milliseconds. This is a measure of the time required for a segment on the connection to arrive at its destination, to be processed, and to return an acknowledgment to the client. This field is only valid for TCP connections.
Round-trip variance.The variance in milliseconds from the previous round-trip time. This field is only valid for TCP connections.
Send next. The sequence number of the next byte of data that the local TCP application sends to the remote TCP application.
Send unacknowledged. The sequence number of the last segment sent that was not acknowledged. This is the smallest sequence number of the send window. This field is only valid for TCP connections.
Slow start threshold. The current values for the slow-start threshold and the congestion window are indirect indicators of the flow of data through a TCP connection. These values are used by TCP as part of a congestion control algorithm. This algorithm ensures that this system sends data at a slow rate at first. After the first data has been successfully sent, the rate in which data is sent increases. This change is made in a controlled manner that is dependent on the amount of congestion in the network. Congestion control occurs both at connection start time and when congestion is detected. The values used for the slow-start threshold and the congestion window are determined by TCP and cannot be set by the user.
Socket option. Socket options for this connection.
| 1 | Socket broadcast option Determine if messages can be sent to the broadcast address. This option is only supported for sockets with an address family of AF_INET and type SOCK_DGRAM or SOCK_RAW. Option is set if a nonzero value is returned. | ||||||||
| 2 | Socket bypass route option - Determine if the normal routing mechanism is being bypassed. This option is only supported by sockets with an address family of AF_INET or AF_INET6. Option is set if a nonzero value is returned. | ||||||||
| 3 | Socket debug option - Determine if low-level debugging is active. Option is set if a nonzero value is returned. | ||||||||
| 4 | Socket error - Return any pending errors in the socket. The value returned corresponds to the standard error codes. | ||||||||
| 5 | Socket keep alive option - Determine if the connection is being kept up by periodic transmissions. This option is only supported for sockets with an address family of AF_INET or AF_INET6 and type SOCK_STREAM. Option is set if a nonzero value is returned. | ||||||||
| 6 | Socket linger option - Determine whether the system attempts to deliver any buffered data or if the system discards it when a close() is issued. For sockets that are using a connection-oriented transport service with an address family of AF_INET or AF_INET6, the default is off (which means that the system attempts to send any queued data, with an infinite wait-time). | ||||||||
| 7 | Socket linger time - Determine how much time in seconds the system will wait to send buffered data. | ||||||||
| 8 | Socket out-of-band data option - Determine if out-of-band data is received inline with normal data. This option is only supported for sockets with an address family of AF_INET or AF_INET6. Option is set if a nonzero value is returned. | ||||||||
| 9 | Socket receive buffer size - Determine the size of the receive buffer. | ||||||||
| 10 | Socket receive low-water mark size - Determine the size of the receive low-water mark. The default size is 1. This option is only supported for sockets with type SOCK_STREAM. | ||||||||
| 11 | Socket reuse address option - Determine if the local socket address can be reused. This option is only supported by sockets with an address family of AF_INET or AF_INET6 and with type SOCK_STREAM or SOCK_DGRAM. Option is set if a nonzero value is returned. | ||||||||
| 12 | Socket send buffer size - Determine the size of the send buffer. | ||||||||
| 13 | Socket type value - Determine
the value for the socket type.
|
||||||||
| 14 | Socket use loopback option - Indicates if the loopback feature is being used. Option is set if a nonzero value is returned. | ||||||||
| 15 | Socket receive timeout - Determine the receive timeout value. | ||||||||
| 16 | Socket send lo-water mark size - Determine the size of the send low-water mark. | ||||||||
| 17 | Socket send timeout - Determine the send timeout value. |
Socket state. The current state of the socket.
Possible values are:
| 0 | Uninitialized |
| 1 | Unbound |
| 2 | Bound |
| 3 | Listening |
| 4 | Connecting |
| 5 | Connected |
| 6 | Disconnected |
| 7 | Error |
Task name. The task name as identified to the system.
TCP state. A typical connection goes through the states:
| 0 | Listen, waiting for a connection request from any remote host. |
| 1 | SYN-sent, waiting for a matching connection request after having sent connection request. |
| 2 | SYN-received, waiting for a confirming connection request acknowledgement. |
| 3 | Established, the normal state in which data is transferred. |
| 4 | FIN-wait-1, waiting for the remote host to acknowledge the local system request to end the connection. |
| 5 | FIN-wait-2, waiting for the remote host request to end the connection. |
| 6 | Close-wait, waiting for an end connection request from the local user. |
| 7 | Closing, waiting for an end connection request acknowledgement from the remote host. |
| 8 | Last-ACK, waiting for the remote host to acknowledge an end connection request. |
| 9 | Time-wait, waiting to allow the remote host enough time to receive the local system's acknowledgement to end the connection. |
| 10 | Closed, the connection has ended. |
| 11 | State value not supported by protocol. |
Total retransmissions. The total number of times the local system retransmitted a segment because an acknowledgment was not received. This is a cumulative count of all segments resent during the entire time the connection has been active. This field is only valid for TCP connections.
User send next. The sequence number of the next byte of data to be sent by the client application. This field is only valid for TCP connections.
User receive next. The sequence number of the next byte to be passed to the application by TCP.
Error Messages
| Message ID | Error Message Text |
|---|---|
| TCP84C0 E | TCP/IP stack not active. |
| TCP84C5 E | Error providing TCP/IP Network Status list information. |
| TCP84C6 E | Internal operations error - RESULT &1 CC &2 RC &3 ERRNO &4. |
| TCP84C9 I | Information returned incomplete. |
| TCP84CA E | Connection request parameter not valid. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V5R1
| Top | Communications APIs | APIs by category |