| 1 | Qualified user space name | Input | Char(20) |
| 2 | Format name | Input | Char(8) |
| 3 | Connection list qualifier | Input | Char(*) |
| 4 | Connection list qualifier size | Input | Binary(4) |
| 5 | Connection list qualifier format | Input | Char(8) |
| 6 | Error Code | I/O | Char(*) |
The List Network Connections (QtocLstNetCnn) API returns a non-detailed list of all network connections, or a subset of all network connections for a specified network connection type. With each call to this API you can request IPv4 or IPv6 connections, but not both at the same time.
TCP/IP must be active on this system; otherwise, error message TCP84C0 will be issued.
The user space that is to receive the created list. The first 10 characters contain the user space name; the second 10 characters contain the name of the library in which the user space is located. You can use these special values for the library name:
| *CURLIB | The job's current library |
| *LIBL | The library list |
The format of the space information to be returned. The format name supported is:
| NCNN0100 | Non-detailed list of selected TCP/IPv4 local system connections. Refer to NCNN0100 Format for details on the format. |
| NCNN0200 | Non-detailed list of selected TCP/IPv6 local system connections. Refer to NCNN0200 Format for details on the format. |
A restriction on the network connections to be listed.
The size in bytes of the connection list qualifier parameter.
The format of the connection list qualifier parameter. The format name supported is:
| NCLQ0100 | IPv4 connection list qualifier. Refer to NCLQ0100 Format for details on the format. |
| NCLQ0200 | IPv6 connection list qualifier. Refer to NCLQ0200 Format for details on the format. |
The structure in which to return error information. For the format of the structure, see Error code parameter.
To request a non-detailed list of local system connections, use format NCNN0100.
The connection description list consists of:
For details about the user area and generic header, see User spaces. For details about the remaining items, see the following sections.
When you retrieve list entry information from a user space, you must use the entry size returned in the generic header. The size of each entry may be padded at the end. If you do not use the entry size, the result may not be valid. For examples of how to process lists, see Examples: APIs and exit programs.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name specified |
| 10 | A | CHAR(10) | User space library name specified |
| 20 | 14 | CHAR(8) | Format name specified |
| 28 | 1C | CHAR(*) | Connection list qualifier specified |
| BINARY(4) | Connection list qualifier size specified | ||
| CHAR(8) | Connection list qualifier format specified | ||
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name used |
| 10 | A | CHAR(10) | User space library name used |
| 20 | 14 | ||
The following table shows the format of the IPv4 connection list qualifier input parameter, named the NCLQ0100 format. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Net connection type |
| 10 | A | CHAR(10) | List request type |
| 20 | 14 | CHAR(12) | Reserved |
| 32 | 20 | BINARY(4) | Local internet address lower value |
| 36 | 24 | BINARY(4) | Local internet address upper value |
| 40 | 28 | BINARY(4) | Local port lower value |
| 44 | 2C | BINARY(4) | Local port upper value |
| 48 | 30 | BINARY(4) | Remote internet address lower value |
| 52 | 34 | BINARY(4) | Remote internet address upper value |
| 56 | 38 | BINARY(4) | Remote port lower value |
| 60 | 3C | BINARY(4) | Remote port upper value |
| 64 | 40 | ||
List request type. The local internet address range, local port range, remote internet address range, and remote port range for which information is requested. Possible values are:
| *ALL | All objects returned. |
| *SUBSET | Restrict the objects returned in the list to a specified subset. |
Local internet address lower value. The lower value of the local system internet address range, in dotted decimal format, requested for subsetting the list. The following is a special value:
| 0 | Request all local internet addresses. |
Local internet address upper value. The upper value of the local system internet address range, in dotted decimal format, requested for subsetting the list. The following is a special value:
| 0 | Request only one local internet address specified by the local internet address lower value. |
Local port lower value. The lower value of the local system port range requested for subsetting the list. Valid values range from 1 to 65535. The following is a special value:
| 0 | Request all local ports. |
Local port upper value. The upper value of the local system port range requested for subsetting the list. Valid values range from 1 to 65535. The following is a special value:
| 0 | Request only one local port specified in local port lower value. |
Net connection type. The type of connection or socket. Possible values are:
| *ALL | All connection types |
| *TCP | A transmission control protocol (TCP) connection or socket. |
| *UDP | A User Datagram Protocol (UDP) socket. |
| *IPI | An Internet Protocol (IP) over Internetwork
Packet Exchange (IPX) connection or socket.
Note: As of V5R2, IP over IPX is no longer supported. |
| *IPS | An Internet Protocol (IP) over SNA connection or socket. |
Remote internet address lower value. The lower value of the remote system internet address range, in dotted decimal format, requested for subsetting the list. The following is a special value:
| 0 | Request all remote internet addresses. |
Remote internet address upper value. The upper value of the remote system internet address range, in dotted decimal format, requested for subsetting the list. The following is a special value:
| 0 | Request only one remote internet address specified by the remote internet address lower value. |
Remote port lower value. The lower value of the remote system port range requested for subsetting the list. Valid values range from 1 to 65535. The following is a special value:
| 0 | Request all remote ports. |
Remote port upper value. The upper value of the remote system port range requested for subsetting the list. Valid values range from 1 to 65535. The following is a special value:
| 0 | Request only one remote port specified in remote port lower value. |
Reserved. A reserved field. It must be x'00'.
The following table shows the format of the IPv6 connection list qualifier input parameter, named the NCLQ0200 format. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Net connection type |
| 10 | A | CHAR(10) | List request type |
| 20 | 14 | CHAR(12) | Reserved |
| 32 | 20 | CHAR(16) | Local internet IPv6 address lower value |
| 48 | 30 | CHAR(16) | Local internet IPv6 address upper value |
| 64 | 40 | BINARY(4) | Local port lower value |
| 68 | 44 | BINARY(4) | Local port upper value |
| 72 | 48 | CHAR(16) | Remote internet IPv6 address lower value |
| 88 | 58 | CHAR(16) | Remote internet IPv6 address upper value |
| 104 | 68 | BINARY(4) | Remote port lower value |
| 108 | 6C | BINARY(4) | Remote port upper value |
| 112 | 70 | ||
List request type. The local internet address range, local port range, remote internet address range, and remote port range for which information is requested.
Possible values are:
| *ALL | All objects returned. |
| *SUBSET | Restrict the objects returned in the list to a specified subset. |
Local internet IPv6 address lower value. The lower value of the local system internet address range, in IPv6 address format, requested for subsetting the list. 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.
The following is a special value:
| 0 | Request all local internet IPv6 addresses. Specify this value by filling the whole field with binary NULLs (x'000000...'). |
Local internet IPv6 address upper value. The upper value of the local system internet address range, in IPv6 address format, requested for subsetting the list. 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.
The following is a special value:
| 0 | Request only one local internet IPv6 address specified by the local internet IPv6 address lower value. Specify this value by filling the whole field with binary NULLs (x'000000...'). |
Local port lower value. The lower value of the local system port range requested for subsetting the list. Valid values range from 1 to 65535.
The following is a special value:
| 0 | Request all local ports. |
Local port upper value. The upper value of the local system port range requested for subsetting the list. Valid values range from 1 to 65535.
The following is a special value:
| 0 | Request only one local port specified in local port lower value. |
Net connection type. The type of connection or socket.
Possible values are:
| *ALL | All connection types |
| *TCP | A transmission control protocol (TCP) connection or socket. |
| *UDP | A User Datagram Protocol (UDP) socket. |
Remote internet IPv6 address lower value. The lower value of the remote system internet IPv6 address range, in IPv6 address format, requested for subsetting the list. 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.
The following is a special value:
| 0 | Request all remote internet IPv6 addresses. Specify this value by filling the whole field with binary NULLs (x'000000...'). |
Remote internet IPv6 address upper value. The upper value of the remote system internet IPv6 address range, in IPv6 address format, requested for subsetting the list. 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.
The following is a special value:
| 0 | Request only one remote internet IPv6 address specified by the remote internet IPv6 address lower value. Specify this value by filling the whole field with binary NULLs (x'000000...'). |
Remote port lower value. The lower value of the remote system port range requested for subsetting the list. Valid values range from 1 to 65535.
The following is a special value:
| 0 | Request all remote ports. |
Remote port upper value. The upper value of the remote system port range requested for subsetting the list. Valid values range from 1 to 65535.
The following is a special value:
| 0 | Request only one remote port specified in remote port lower value. |
Reserved. A reserved field. It must be x'00'.
To retrieve the list of TCP/IPv4 connections, request format NCNN0100, and you will get a repeating list of NCNN0100 tables, each one returning information about a single IPv4 connection. To retrieve the list of TCP/IPv6 connections, request format NCNN0200, and you will get a repeating list of NCNN0200 tables, each one returning information about a single IPv6 connection.
The following information about a user space is returned for the NCNN0100 format. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(15) | Remote address |
| 15 | F | CHAR(1) | Reserved |
| 16 | 10 | BINARY(4) | Remote address binary |
| 20 | 14 | CHAR(15) | Local address |
| 35 | 23 | CHAR(1) | Reserved |
| 36 | 24 | BINARY(4) | Local address binary |
| 40 | 28 | BINARY(4) | Remote port |
| 44 | 2C | BINARY(4) | Local port |
| 48 | 30 | BINARY(4) | TCP state |
| 52 | 34 | BINARY(4) | Idle time in milliseconds |
| 56 | 38 | BINARY(8) | Bytes in |
| 64 | 40 | BINARY(8) | Bytes out |
| 72 | 48 | BINARY(4) | Connection open type |
| 76 | 4C | CHAR(10) | Net connection type |
| 86 | 56 | CHAR(2) | Reserved |
| 88 | 58 | CHAR(10) | Associated user profile |
| 98 | 62 | CHAR(2) | Reserved |
| 100 | 64 | ||
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 Retrieve Network Connection Data (QtocRtvNetCnnDta) API.
Bytes in. The number of bytes received from the remote host.
Bytes out. The number of bytes sent to the remote host.
Connection open type. The type of open that was done to start this connection. This field only applies to TCP connections.
Possible values are:
| 0 | Passive. A remote host opens the connection. |
| 1 | Active. The local system opens the connection. |
| 2 | Not supported. Connection open type not supported by protocol. |
Idle time in milliseconds. The length of time since the last activity on this connection. The length of time is shown in milliseconds.
Local address. The local system internet address, in dotted decimal format, of the connection.
Local address binary. Binary representation of the local address.
Local port. The local system port number.
Net connection type. The type of connection or socket. Possible values are:
| *TCP | A transmission control protocol (TCP) connection or socket. |
| *UDP | A User Datagram Protocol (UDP) socket. |
| *IPI | An Internet Protocol (IP) over Internetwork
Packet Exchange (IPX) connection or socket.
Note: As of V5R2, IP over IPX is no longer supported. |
| *IPS | An Internet Protocol (IP) over SNA connection or socket. |
Remote address. The internet address, in dotted decimal format, of the remote host.
The following special value may be returned:
| 0 | This connection is a listening or UDP socket so this field does not apply. The "0" is returned as a left adjusted "0" (x'F0404040...'). |
Remote address binary. Binary representation of the remote address.
The following special value may be returned:
| 0 | This connection is a listening or UDP socket so this field does not apply. |
Remote port. The remote host port number. Zero is shown if the list entry is for a UDP socket.
Reserved. An ignored field.
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. |
The following information about a TCP/IPv6 connection is returned for the NCNN0200 format. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(45) | Remote IPv6 address |
| 45 | 2D | CHAR(3) | Reserved |
| 48 | 30 | CHAR(16) | Remote IPv6 address binary |
| 64 | 40 | CHAR(45) | Local IPv6 address |
| 109 | 6D | CHAR(3) | Reserved |
| 112 | 70 | CHAR(16) | Local IPv6 address binary |
| 128 | 80 | BINARY(4) | Remote port |
| 132 | 84 | BINARY(4) | Local port |
| 136 | 88 | BINARY(4) | TCP state |
| 140 | 8C | BINARY(4) | Idle time in milliseconds |
| 144 | 90 | BINARY(8) | Bytes in |
| 152 | 98 | BINARY(8) | Bytes out |
| 160 | A0 | BINARY(4) | Connection open type |
| 164 | A4 | CHAR(10) | Net connection type |
| 174 | AE | CHAR(10) | Associated user profile |
| 184 | B8 | CHAR(10) | Line Description |
| 194 | C2 | ||
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 Retrieve Network Connection Data (QtocRtvNetCnnDta) API.
Bytes in. The number of bytes received from the remote host.
Bytes out. The number of bytes sent to the remote host.
Connection open type. The type of open that was done to start this connection. This field only applies to TCP connections.
Possible values are:
| 0 | Passive. A remote host opens the connection. |
| 1 | Active. The local system opens the connection. |
| 2 | Not supported. Connection open type not supported by protocol. |
Idle time in milliseconds. The length of time since the last activity on this connection. The length of time is shown in milliseconds.
Line Description. The local system line description associated with this connection. This field is only filled for connections bound to link local unicast interfaces.
Local IPv6 address. The local system internet address, in IPv6 address format, of the connection. This field is NULL padded.
Local IPv6 address binary. Binary representation of the local IPv6 address. Even though this field is defined as a character field, a binary IPv6 address is returned in it.
Local port. The port number of the local end of the connection.
Net connection type. The type of connection or socket.
Possible values are:
| *TCP | A transmission control protocol (TCP) connection or socket. |
| *UDP | A User Datagram Protocol (UDP) socket. |
Reserved. An ignored field.
Remote IPv6 address. The internet address, in IPv6 address format, of the remote host. This field is NULL padded.
Special values are:
| :: | This connection is a listening socket so this field does not apply. |
Remote IPv6 address binary. Binary representation of the remote address. Even though this field is defined as a character field, a binary IPv6 address is returned in it.
A special value that may be returned is:
| 0 | This connection is a listening socket so this field does not apply. This value is returned as a binary 0. |
Remote port. The port number of the remote end of the connection.
Special values are:
| 0 | This connection is a listening socket so this field does not apply. |
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. |
| 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. |
| TCP84C7 E | Connections list qualifier parameter not valid. |
| CPF0F03 E | Error in retrieving the user space that was created by the caller. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | API contains a problem. See prior messages to determine why the failure occurred. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9807 E | One or more libraries in library list deleted. |
| CPF9808 E | Cannot allocate one or more libraries on library list. |
| CPF9810 E | Library &1 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9830 E | Cannot assign library &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |