List Network Connections (QtocLstNetCnn) API
| 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(*) |
Service Program: QTOCNETSTS
Threadsafe: Yes
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 QSYS2.NETSTAT_INFO view can be used as an alternative to this API. See NETSTAT_INFO view for more information.
Authorities and Locks
- User Space Library Authority
- *EXECUTE
- User Space Authority
- *CHANGE
- User Space Lock
- *SHRNUP
Required Parameter Group
- Qualified user space name
- INPUT; CHAR(20)
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
- Format name
- INPUT; CHAR(8)
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.
- Connection list qualifier
- INPUT; CHAR(*)
A restriction on the network connections to be listed.
- Connection list qualifier size
- INPUT; BINARY(4)
The size in bytes of the connection list qualifier parameter.
- Connection list qualifier format
- INPUT; CHAR(8)
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.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format of Connection Status Lists
To request a non-detailed list of local system connections, use format NCNN0100.
The connection description list consists of:
- A user area
- A generic header
- An input parameter section
- A header section
- A list data section:
- NCNN0100 format, or
- NCNN0200 format
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.
Input Parameter Section
| 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 | ||
Header Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name used |
| 10 | A | CHAR(10) | User space library name used |
| 20 | 14 | ||
NCLQ0100 Format
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 | ||
Field Descriptions
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'.
NCLQ0200 Format
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 | ||
Field Descriptions
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'.
Format of Returned Connection Data
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.
NCNN0100 Format
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 | ||
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 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. |
NCNN0200 Format
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 | CHAR(2) | Reserved |
| 196 | C4 | BINARY(4) | Virtual LAN identifier |
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 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 set 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. |
Virtual LAN identifier. The virtual LAN identifier associated with this connection. This field is only set for connections bound to link
local unicast interfaces.
Possible values are:
| 0 | NONE - No virtual LAN identifier is associated with this connection. |
| 1 - 4094 | The virtual LAN identifier associated with this
connection. |
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. |
| 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 | Error(s) occurred during running of &1 API. |
| 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. |
API introduced: V5R1
| Top | Communications APIs | APIs by category |