Retrieve TCP/IP Attributes (QtocRtvTCPA) API

  Required Parameter Group:


  Service Program: QTOCNETSTS

  Threadsafe: Yes

The Retrieve TCP/IP Attributes (QtocRtvTCPA) API retrieves TCP/IPv4 and TCP/IPv6 stack attributes.


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
OUTPUT; 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:


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 TCP/IP Attributes Information

To retrieve the current TCP/IPv4 stack status, use format TCPA0100.

For detailed TCP/IPv4 stack attributes in addition to the TCP/IPv4 stack status, use format TCPA0200.

For Domain Name System (DNS) information in addition to the TCP/IPv4 stack status, use format TCPA0300. As of V6R1, this format is replaced with TCPA1400 and should no longer be used.

To retrieve the current TCP/IPv6 and IPv4 stack statuses, use format TCPA1100.

For detailed TCP/IPv6 stack attributes in addition to the TCP/IPv6 and IPv4 stack statuses, use format TCPA1300.

For detailed information about the TCP/IPv4 and IPv6 domain attributes, in addition to the TCP/IPv6 and IPv4 stack statuses, use format TCPA1400.

For TCP/IPv4 and IPv6 dynamic DNS information, use format TCPA2100.


TCPA0100 Format

This format returns information regarding the status of the TCP/IPv4 stack. For detailed descriptions of the fields in the table, see Field Descriptions.



Field Descriptions

Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.

Bytes returned. The number of bytes of data returned.

How long active. How long, in seconds, the TCP/IP stack has been active if it is active currently, or how long it was active the last time it was up if it is currently inactive.

Length of additional information. The length in bytes of additional information returned that is not part of format TCPA0100.

Limited mode. The current value of the TCP/IP Limited mode flag. TCP/IPv4 can operate while the system is in the restricted state, with limited functionality.

Possible values are:

Offset to additional information. The offset from the beginning of the receiver variable, in bytes, to the start of the next format if a format other than TCPA0100 is requested. This field allows expansion of the basic information. A value of zero is returned if only the TCPA0100 format is requested.

Reserved. An ignored field.

TCP/IPv4 stack status. The current status of the system TCP/IPv4 stack. Possible values are:

When last ended - date. The date when the TCP/IP stack was last ended. The format is YYYYMMDD, where:

When last ended - time. The time when the TCP/IP stack was last ended. The format is HHMMSS, in 24-hour time, where:

When last started - date. The date when the TCP/IP stack was last started. The format is YYYYMMDD, where:

When last started - time. The time when the TCP/IP stack was last started. The format is HHMMSS, in 24-hour time, where:

Who last ended - internal job identifier. A value sent to other APIs to speed the process of locating the job on the system. Only IBM i APIs use this identifier. This field is all NULLs if the TCP/IP stack has not been ended since the last initial program load (IPL), or if the job that ended the TCP/IP stack is no longer active.

Who last ended - job name. The name of the job responsible for ending the TCP/IP stack the last time it was ended. If the TCP/IP stack has not been ended since the last initial program load (IPL), this field is all NULLs.

Who last ended - job number. The job number responsible for ending the TCP/IP stack the last time it was ended. If the TCP/IP stack has not been ended since the last initial program load (IPL), this field is all NULLs.

Who last ended - job user name. The name of the user responsible for ending the TCP/IP stack the last time it was ended. If the TCP/IP stack has not been ended since the last initial program load (IPL), this field is all NULLs.

Who last started - internal job identifier. A value sent to other APIs to speed the process of locating the job on the system. Only IBM i APIs use this identifier. This field is all NULLs if the TCP/IP stack has not been started since the last initial program load (IPL), or if the job that started the TCP/IP stack is no longer active.

Who last started - job name. The name of the job responsible for starting the TCP/IP stack the last time it was started. If the TCP/IP stack has not been started since the last initial program load (IPL), this field will be all NULLs.

Who last started - job number. The job number of the job responsible for starting the TCP/IP stack the last time it was started. If the TCP/IP stack has not been started since the last initial program load (IPL), this field will be all NULLs.

Who last started - job user name. The user name of the job responsible for starting the TCP/IP stack the last time it was started. If the TCP/IP stack has not been started since the last initial program load (IPL), this field will be all NULLs.


TCPA0200 Format

This format returns detailed information about the TCP/IPv4 stack attributes in addition to the TCP/IPv4 stack status (format TCPA0100). For detailed descriptions of the fields in the table, see Field Descriptions.



Field Descriptions

ARP cache timeout. The ARP cache time-out value, in minutes The purpose of the time-out value is to flush out-of-date cache entries from the ARP cache.

The default ARP cache time-out interval is 5 minutes. Valid values range from 1 through 1440 minutes (24 hours).

Dead gateway detection enablement. Whether dead gateway detection is turned on or off. Dead gateway detection is a mechanism that involves polling all attached gateways. If no reply to the polls is received all routes using that gateway are deactivated. Possible values are:

Dead gateway detection interval. The amount of time, in minutes, between dead gateway polls.

The default dead gateway detection interval is 2 minutes. Valid values range from 1 through 60 minutes.

DHCP unique identifier. Specifies the Dynamic Host Configuration Protocol (DHCP) unique user identifier (refer to RFC 3315). This is a globally unique identifier used to identify clients and servers. Possible values are:

Note: Verify the field Length of DHCP unique identifier prior to using this one.

Explicit congestion notification (ECN). If ECN is enabled routers can notify end-nodes of congestion before queues overflow. Without ECN end-nodes can only detect congestion when packets are lost due to queues overflowing.

IP datagram forwarding. Whether the IP layer forwards Internet Protocol (IP) datagrams between different networks. It specifies whether the IP layer is acting as a gateway.

Note: IP does not forward datagrams between interfaces on the same subnet.

The IBM i implementation of TCP/IP does not include full gateway function as defined in RFC1009. Subsets of the gateway functions are supported. One of the gateway functions supported is IP datagram forwarding capabilities. The possible values are:

IP reassembly timeout. The IP datagram reassembly time, in seconds. If this time is exceeded, a partially reassembled datagram is discarded and an ICMP time exceeded message is sent to the source host.

The default IP reassembly timeout is 10 seconds. Valid values range from 5 through 120 seconds.

IP source routing. Whether IP source routing currently is on or off. If IP source routing is on, it means that this system is specifying the route that outgoing IP packets take instead of allowing normal dynamic routing to take place. Some firewalls will not pass datagrams that have IP source routing switched on. The possible values are:

IP time to live. The current TTL value. The IP datagram time-to-live value specifies a relative limit on the number of hops across which an IP datagram remains active. The time-to-live value acts as a hop count that is decremented by each gateway to prevent Internet routing loops.

Note: Even though this parameter is specified as a time-to-live value, it is not used as a time value. It is used as a counter. The standard description is time to live as specified in RFCs.

Note: This IP datagram time-to-live value is not used for datagrams sent to an IP multicast group address. The default IP datagram time-to-live value for datagram sent to an IP multicast group is always 1, as specified by the Internet standards. Individual multicast applications may override this default using the IP_MULTICAST_TTL socket option.

The default time-to-live value is 64. Valid values range from 1 through 255.

Length of DHCP unique identifier. This field should be used in order to determine the number of bytes necessary to display the DHCP unique identifier.

Log protocol errors. Enables a user to log protocol errors that occur during the processing of TCP/IP data. These TCP/IP stack layer functions use this parameter to determine if they log protocol-specific errors: IP, ICMP, ARP, and NAM. TCP and UDP do not log protocol errors.

The 7004 error reference code is logged when the LOGPCLERR(*YES) option is specified and inbound datagrams are silently discarded. Silently discarded means that an ICMP message is not returned to the originating host when a datagram is discarded because of header errors. Examples of such datagrams include those with invalid checksums and invalid destination addresses.

The error reference code is for information only. No action should be taken as a result of this error reference code. It is generated to assist with remote device or TCP/IP network problem analysis.

Note: These error conditions cannot be processed using an APAR.

The log protocol errors parameter should be used when error conditions require the logging of TCP/IP data, such as datagrams, to determine network problems.

The data is logged in the system error log. This error log is available through the Start System Service Tools (STRSST) command. The possible values are:

MTU discovery interval. The amount of time, in minutes, that the TCP/IP protocol stack will cache the results of a path MTU discovery. When the time interval is exceeded, the path MTU is rediscovered.

The default path MTU discovery interval is 10 minutes. Valid values range from 5 through 40320 minutes (28 days). A special value is:

MTU path discovery. Whether the Path Maximum Transmission Unit (MTU) discovery function is enabled on this system.

Network file cache enablement. The current enablement status of the Network File Cache (NFC) function. The Network File Cache is used for the support of FRCA (Fast Response Cache Accelerator). FCRA dramatically improves the performance of serving non-secure static content by Web and other TCP servers.

Possible values are:

Network file cache size. The maximum amount of storage that may be used by the Network File Cache (NFC) for the entire system. This number is the total storage used by all TCP servers for caching files. The storage being allocated is DASD or disk and is not directly allocated from main memory. Valid values range from 10 through 100000 megabytes (100GB).

Network file cache timeout. The maximum amount of time in seconds that a file can be cached in the Network File Cache (NFC). This attribute ensures that a file is refreshed at a regular interval. Valid values range from 30 through 604800 seconds (one week).

Special values are:

Offset to DHCP unique identifier. The offset from the beginning of the receiver variable, in bytes, to the DHCP unique identifier returned with this format.

QoS data path optimization. The type of data path optimization in use by Quality of Service (QoS). This field indicates the extent which QoS will batch datagrams so as to optimize performance at the risk of increasing jitter, or delay. The normal setting maximizes performance by doing more batching of datagram packets. The MinDelay setting minimizes delay by doing less batching of datagram packets and just sending them when they are ready. Possible values are:

QoS enablement. Whether Quality of Service (QoS), IP Type of Service (TOS), or neither of the two are in use. Possible values are:

QoS timer resolution. The Quality of Service (QoS) timer resolution value in milliseconds. This field indicates the amount of control possible over delay variations. A higher timer resolution value contributes to more jitter (delay), and a lower timer resolution uses more CPU time. The timer resolution value that can be tolerated is very dependent on the application. For example, video is highly sensitive to large delay variations. To achieve a smooth rate of flow, timers need to use small timer increments. The smaller the resolution, the smoother the data flow, but at a higher cost in terms of system overhead to manage timers.

The default QoS timer resolution is 100 milliseconds. Valid values range from 5 to 5000 milliseconds.

Reserved. An ignored field.

TCP close connection message. The value of the TCP close connection message attribute. The TCP close connection message attribute specifies whether abnormally closed TCP connections will be logged by messages to the QTCP message queue. TCP connections could be abnormally closed for the following reasons:

Possible values are:

TCP keep alive. The amount of time, in minutes, that TCP waits before sending out a probe to the other side of a connection. The probe is sent when the connection is otherwise idle, even when there is no data to be sent.

The transmission of keep-alive packets is controlled by individual sockets applications through use of the SO_KEEPALIVE socket option. For more information, see the Socket programming topic collection.

The default keep-alive time interval is 120 minutes. Valid values range from 1 through 40320 minutes (28 days).

TCP minimum retransmission timeout. The current value of the configurable TCP minimum retransmission timeout attribute, in milliseconds. This attribute specifies the amount of time that TCP will wait for an acknowledgement (ACK) of a packet. When this amount of time has passed without an acknowledgement, TCP will perform the first retransmission of the packet. The default TCP minimum retransmission timeout is 250 milliseconds. Valid values range from 100 through 1000 milliseconds.

TCP R1 retransmission count. The R1 retransmission count value. The default value is 3. Valid values range from 1 to 15, and R1 must be less than R2.

TCP R2 retransmission count. The R2 retransmission count value. The default value is 16. Valid values range from 2 to 16, and R2 must be greater than R1.

TCP receive buffer. What to allocate for the default receive buffer size. The TCP receive window size is based on this value. Decreasing this value decreases the amount of data that the remote system can send before being read by the local application. Decreasing this value may improve performance in situations where many retransmissions occur due to the overrunning of a network adapter.

Notes:
  1. User Datagram Protocol (UDP) does not have a configurable receive buffer size.
  2. This value is also used as the default receive buffer size by IP over SNA processing.
  3. Setting this parameter does not guarantee the size of the TCP receive buffer. This is the default buffer size that is used for initial TCP connection negotiations. An individual application can override this value by using the SO_RCVBUF socket option. For more information, see Socket programming.

The default TCP receive buffer size is 8192 (8 KB) bytes. Valid values range from 512 through 8388608 (8 MB) bytes.

TCP send buffer. The TCP send buffer size. This parameter informs TCP what to use for the default send buffer size. The TCP send buffer size provides a limit on the number of outgoing bytes that are buffered by TCP. Once this limit is reached, attempts to send additional bytes may result in the application blocking until the number of outgoing bytes buffered drops below this limit. The number of outgoing bytes buffered is decremented when the remote system acknowledges the data sent.

Notes:
  1. This value is used also as the default send buffer size by IP over SNA processing.
  2. UDP does not have a configurable send buffer size.
  3. Setting this parameter does not guarantee the size of the TCP send buffer. This is the default buffer size that is used for initial TCP connection negotiations. An individual application can override this value by using the SO_SNDBUF socket option. For more information, see Socket programming.

The default TCP send buffer size is 8192 (8 KB) bytes. Valid values range from 512 through 8388608 (8 MB) bytes.

TCP time wait timeout. The amount of time, in seconds, for which a socket pair (client IP address and port, server IP address and port) cannot be reused after a connection is closed. The maximum value possible is 2 MSL (maximum segment lifetime). The default value is 120 seconds. Valid values range from 0 (no timer) to 14400 seconds (240 minutes).

TCP urgent pointer. The convention to follow when interpreting which byte the urgent pointer in the TCP header points to. The urgent pointer in the TCP header points to either the byte immediately following the last byte of urgent data (BSD convention) or the last byte of the urgent data (RFC convention).

Note: This value must be consistent between the local and remote ends of a TCP connection. Socket applications that use this value must use it consistently between the client and server applications. This value is set on a system basis. All applications using this system will use this value. The possible values are:

UDP checksum. Whether UDP processing should generate and validate checksums. It is strongly recommended that you use UDP checksum processing. If you are concerned about obtaining the best possible performance and are not concerned with the protection provided by UDP checksum processing, turn UDP checksum processing off. The possible values are:



TCPA0300 Format

This format returns detailed information about the TCP/IPv4 domain attributes, in addition to the TCP/IPv4 stack status (format TCPA0100). For detailed descriptions of the fields in the table, see Field Descriptions. As of V6R1, this format is replaced with TCPA1400 and should no longer be used.



List of Internet Addresses. These fields repeat for each DNS Internet address.



Field Descriptions

DNS listening port. The remote TCP/IP port number used to contact the DNS server or servers listed in the Internet address parameter. 53 is the well-known port used for this purpose.

Note: Use of a TCP/IP port number other than the well-known port 53 for use by the DNS server can result in TCP/IP communication problems. You may inadvertently use a port number that is reserved for use by another TCP/IP application.

The default DNS Listening port is 53. Valid values range from 1 to 65532.

DNS protocol. The TCP/IP protocol used to communicate with the DNS server or servers specified in the Internet address parameter. User Datagram Protocol (UDP) typically is used for this purpose. Use TCP only if your DNS server is specifically configured to use TCP. Possible values are:

Domain name. The name of the TCP/IP domain of which this system is a member.

Domain search list. The TCP/IP domains to be searched whenever a host name is not given as a Fully Qualified Domain Name (FQDN). Up to six domains may be specified, separated by spaces. The list is blank padded.

Entry length for list of Internet addresses. The entry length in bytes of each element in the list of DNS Internet addresses returned with this format. A value of zero is returned if the list is empty.

Host name. The TCP/IP host name of this system. This field returns the value specified by the CHGTCPDMN command, and is the preferred system name if the system has more than one name corresponding to multiple interfaces.

Note: This system's TCP/IP host name must also be defined in the local host table or the DNS server specified in the Internet address parameter. If no DNS server is specified, the local TCP/IP host table is used.

Initial domain name server. How the initial DNS server is chosen when doing a name lookup. The first configured server can always be queried first, or TCP/IP can rotate through the configured servers in a round-robin fashion to provide a form of load balancing on the servers. Possible values are:

Internet address. The IP address of a DNS server to be used by this system. There may be zero, one, two, or three DNS Internet addresses.

If the first DNS server in the list does not respond, the second DNS server in the list will be contacted. If the second DNS server does not respond, the third DNS server will contacted, and so on.

This field is specified in dotted-decimal form.

Internet address binary. The binary representation of a DNS IP address.

Number of Internet addresses. The number of elements in the list of DNS Internet addresses returned with this format. A value of zero is returned if the list is empty.

Offset to list of Internet addresses. The offset from the beginning of the receiver variable, in bytes, to the first element in the list of DNS Internet addresses returned with this format. A value of zero is returned if the list is empty.

Retries. The number of additional attempts made to establish communication with each DNS server, in the event the first attempt fails.

The default number of retries is 2. Valid values range from 0 to 99.

Search order. Whether to search a DNS server first to resolve a TCP/IP host name conflict, or to search the local TCP/IP host table first.

Time interval. The length of time in seconds this system will wait before initiating a retry attempt to connect to a DNS server. The default time interval is 2 seconds. Valid values range from 0 to 99.


TCPA1100 Format

This format returns information regarding the status of the TCP/IPv6 and IPv4 stacks. For detailed descriptions of the fields in the table, see Field Descriptions.



Field Descriptions

Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.

Bytes returned. The number of bytes of data returned.

Length of additional information. The length in bytes of additional information returned that is not part of format TCPA1100.

Offset to additional information. The offset from the beginning of the receiver variable, in bytes, to the start of the next format if format TCPA1200 or format TCPA1300 is requested. This field allows expansion of the basic information. A value of zero is returned if only the TCPA1100 format is requested.

TCP/IPv4 stack status. The current status of the system TCP/IPv4 stack. Possible values are:

TCP/IPv6 stack status. The current status of the system TCP/IPv6 stack. Possible values are:



TCPA1200 Format

This format returns detailed information about the TCP/IPv6 stack attributes in addition to the TCP/IPv6 stack status (format TCPA1100). For detailed descriptions of the fields in the table, see Field Descriptions. As of V5R4, this format is being replaced with TCPA1300 and should no longer be used.



Field Descriptions

ICMP error message send rate time. The current value of the ICMP error message send rate time attribute, in milliseconds. The ICMP error message send rate time attribute controls how often ICMPv6 error messages will be sent out by the system. This control mechanism allows the bandwidth and forwarding costs of sending ICMPv6 error messages to be limited, as in the case of many ICMPv6 error messages being generated in response to another host sending a stream of erroneous packets. The default ICMP error message send rate time is 1000 milliseconds (1 second). Valid values range from 10 through 5000 milliseconds (5 seconds).

Note: As of V5R4, this data is no longer available and is defaulted to 0.

Neighbor advertisement max transmits. The current value of the TCP/IPv6 stack Neighbor advertisement max transmits attribute. The Neighbor advertisement max transmits attribute is specified as a number of transmissions, and is the maximum number of unsolicited Neighbor Advertisements that the system will send at a time. The system might send unsolicited Neighbor Advertisements when one of its link-layer addresses changes (for example, hot-swap of a physical interface card). The default value of the Neighbor advertisement max transmits attribute is 3 transmissions. Valid values range from 1 through 5 transmissions.

Note: As of V5R4, this data is no longer available and is defaulted to 0.

Neighbor solicitation delay first probe time. The current value of the configured Neighbor solicitation delay first probe time attribute. This attribute controls how long a Neighbor Cache entry will stay in the DELAY state before the stack will send another Neighbor Solicitation and move the Neighbor Cache entry's Reachability state to PROBE if reachability still has not been confirmed. The default Neighbor solicitation delay first probe time is 5 seconds. Valid values range from 3 through 10 seconds.

Note: As of V5R4, this data is no longer available and is defaulted to 0.

Neighbor solicitation max multicast solicits. The current value of the configured Neighbor solicitation max multicast solicits stack attribute. This attribute controls the maximum number of multicast Neighbor Solicitations which will be sent out when the system is performing link-layer address resolution for another host (neighbor). If no Neighbor Advertisement is received after the maximum number of Neighbor Solicitations have been sent out, address resolution has failed, and an ICMPv6 error message will be returned to the application. The default value of the Neighbor solicitation max multicast solicits attribute is 3 transmissions. Valid values range from 1 through 5 transmissions.

Note: As of V5R4, this data is no longer available and is defaulted to 0.

Neighbor solicitation max unicast solicits. The current value of the configured Neighbor solicitation max unicast solicits stack attribute. This attribute controls the maximum number of unicast Neighbor Solicitations which will be sent out when the system is performing link-layer address resolution for another host with unicast Neighbor Solicitations. Multicast is the normal way to perform Neighbor Discovery, but unicast Neighbor Solicitations will be used if the local physical interface is not multicast-capable. If no Neighbor Advertisement is received after the maximum number of Neighbor Solicitations have been sent out, address resolution has failed, and an ICMPv6 error message will be returned to the application. The default Neighbor solicitation max unicast solicits value is 3 transmissions. Valid values range from 1 through 5 transmissions.

Note: As of V5R4, this data is no longer available and is defaulted to 0.

Router solicitation interval. The Router solicitation interval is the amount of time, in seconds, to wait between sending Router Solicitations while waiting for a Router Advertisement in reply. The default Router solicitation interval is 4 seconds. Valid values range from 2 through 5 seconds.

Note: As of V5R4, this data is no longer available and is defaulted to 0.

Router solicitation max delay. The Router solicitation max delay attribute is the amount of time, in milliseconds, to wait for a Router Advertisement reply after sending the last Router Solicitation. This attribute is also used to calculate when to send the first Router Solicitation. To avoid congestion on a link when many hosts start up at the same time (such as after a power failure), the system will wait Router solicitation max delay seconds before sending the first Router Solicitation. The default Router solicitation max delay is 1000 milliseconds. Valid values range from 500 through 3000 milliseconds.

Note: As of V5R4, this data is no longer available and is defaulted to 0.

Router solicitation max transmits. The maximum number of Router Solicitations to transmit. If no Router Advertisements are received in response to the transmitted Router Solicitations, the system concludes that there is no IPv6 router on its link. The default Router solicitation max transmits value is 3 transmissions. Valid values range from 1 through 5 transmissions.

Note: As of V5R4, this data is no longer available and is defaulted to 0.

TCP closed timewait timeout. The amount of time, in seconds, for which a socket pair (client IP address and port, server IP address and port) cannot be reused after a connection is closed. The maximum value possible is 2 MSL (maximum segment lifetime). The default value is 120 seconds. Valid values range from 0 (no timer) to 14400 seconds (240 minutes).

Note: As of V5R4, this data is available through format TCPA0200.

TCP keep alive. The amount of time, in minutes, that TCP waits before sending out a probe to the other side of a connection. The probe is sent when the connection is otherwise idle, even when there is no data to be sent.

The transmission of keep-alive packets is controlled by individual sockets applications through use of the SO_KEEPALIVE socket option. For more information, see Socket programming.

The default keep-alive time interval is 120 minutes. Valid values range from 1 through 40320 minutes (28 days).

Note: As of V5R4, this data is available through format TCPA0200.

TCP minimum retransmission timeout. The current value of the configurable TCP minimum retransmission timeout attribute, in milliseconds. This attribute specifies the amount of time that TCP will wait for an acknowledgement (ACK) of a packet. When this amount of time has passed without an acknowledgement, TCP will perform the first retransmission of the packet. The default TCP minimum retransmission timeout is 250 milliseconds. Valid values range from 100 through 1000 milliseconds.

Note: As of V5R4, this data is available through format TCPA0200.

TCP R1 retransmission count. The R1 retransmission count value. The default value is 3. Valid values range from 1 to 15, and R1 must be less than R2.

Note: As of V5R4, this data is available through format TCPA0200.

TCP R2 retransmission count. The R2 retransmission count value. The default value is 16. Valid values range from 2 to 16, and R2 must be greater than R1.

Note: As of V5R4, this data is available through format TCPA0200.

TCP receive buffer size. The TCP receive buffer size in bytes. The TCP receive window size is based on this value. Decreasing this value decreases the amount of data that the remote system can send before being read by the local application. Decreasing this value may improve performance in situations where many retransmissions occur due to the overrunning of a network adapter.

Notes:
  1. User Datagram Protocol (UDP) does not have a configurable receive buffer size.
  2. This value is also used as the default receive buffer size by IP over SNA processing.
  3. Setting this parameter does not guarantee the size of the TCP receive buffer. This is the default buffer size that is used for initial TCP connection negotiations. An individual application can override this value by using the SO_RCVBUF socket option. For more information, see Socket programming.

The default TCP receive buffer size is 8192 (8K) bytes. Valid values range from 512 through 8388608 (8MB) bytes.

As of V5R4, this data is available through format TCPA0200.

TCP send buffer size. The TCP send buffer size in bytes. This parameter informs TCP what to use for the default send buffer size. The TCP send buffer size provides a limit on the number of outgoing bytes that are buffered by TCP. Once this limit is reached, attempts to send additional bytes may result in the application blocking until the number of outgoing bytes buffered drops below this limit. The number of outgoing bytes buffered is decremented when the remote system acknowledges the data sent.

Notes:
  1. This value is used also as the default send buffer size by IP over SNA processing.
  2. UDP does not have a configurable send buffer size.
  3. Setting this parameter does not guarantee the size of the TCP send buffer. This is the default buffer size that is used for initial TCP connection negotiations. An individual application can override this value by using the SO_SNDBUF socket option. For more information, see Socket programming.

The default TCP send buffer size is 8192 (8K) bytes. Valid values range from 512 through 8388608 (8M) bytes.

As of V5R4, this data is available through format TCPA0200.

TCP urgent pointer. The convention to follow when interpreting which byte the urgent pointer in the TCP header points to. The urgent pointer in the TCP header points to either the byte immediately following the last byte of urgent data (BSD convention) or the last byte of the urgent data (RFC convention).

Note: This value must be consistent between the local and remote ends of a TCP connection. Socket applications that use this value must use it consistently between the client and server applications. This value is set on a system basis. All applications using this system will use this value. The possible values are:

As of V5R4, this data is available through format TCPA0200.


TCPA1300 Format

This format returns information regarding the status of the TCP/IPv6 and IPv4 stacks. For detailed descriptions of the fields in the table, see Field Descriptions.

List of temporary prefixes excluded. These fields repeat for each temporary exclusion entry.



Field Descriptions

Address preferred lifetime expiration. The length of time that a "valid" address is preferred, in seconds. This is a temporary address lifetime expiration.

Address valid lifetime expiration. The length of time in seconds, that an address remains in "valid" state. This is a temporary address lifetime expiration.

DHCP unique identifier. Specifies the Dynamic Host Configuration Protocol (DHCP) unique user identifier (refer to RFC 3315). This is a globally unique identifier used to identify clients and servers. Possible values are:

Note: Verify the field Length of DHCP unique identifier prior to using this one.

Entry length for temporary prefix exclusion list. The entry length in bytes of each element in the temporary prefix exclusion list.

Hop limit. The configured IPv6 Hop Limit value specified for all physical interfaces. The Hop limit field is the IPv6 replacement for the IPv4 Time to live (TTL) field. The Hop limit value specifies a relative limit on the number of hops across which an IPv6 datagram remains active. The Hop limit value is hop count that is decremented by each gateway to prevent Internet routing loops. The default Hop limit value is 64. Valid values range from 1 through 255 hops.

ICMP error message burst limit. The maximum number of ICMP error messages sent in a burst. The default value is 10. Valid values range from 1 through 255.

ICMP error message send rate. The average rate limit of sending ICMP error messages in packets/second. The default value is 10. Valid values range from 1 through 255.

Internet IPv6 address. The Internet address, in IPv6 address format, of the interface.

Internet IPv6 address binary. Binary representation of the Internet IPv6 address. Even though this field is defined as a character field, a binary IPv6 address is returned in it.

Length of DHCP unique identifier. This field should be used in order to determine the number of bytes necessary to display the DHCP unique identifier.

Number of temporary prefixes. The number of temporary prefixes to be excluded when creating IPv6 address.

Offset to DHCP unique identifier. The offset from the beginning of the receiver variable, in bytes, to the DHCP unique identifier returned with this format.

Offset to temporary prefix exclusion list. The offset from the beginning of the receiver variable, in bytes, to the first element in the temporary prefix exclusion list. A value of zero is returned if the list is empty.

Prefix length. The prefix length defines how many bits of the interface IPv6 address are in the prefix. It is a zoned decimal number which specifies how many of the left-most bits of the address make up the prefix.

Temporary prefix exclusion list. The prefixes defined that will not be considered when creating IPv6 addresses.

Reserved. An ignored field.

Route load sharing. Whether route load sharing is enabled on the system or not. Possible values are:



TCPA1400 Format

This format returns detailed information about the TCP/IPv4 and IPv6 domain attributes, in addition to the TCP/IPv6 and IPv4 stack statuses (format TCPA1100). For detailed descriptions of the fields in the table, see Field Descriptions.



List of DNS Internet Addresses. These fields repeat for each DNS Internet address (IPv4 or IPv6).



Field Descriptions

DNS Internet address. The Internet address (IPv4 or IPv6) of a DNS to be used by this system. There may be from zero to the number of DNS Internet addresses configured.

If the first DNS server in the list does not respond, the second DNS server in the list will be contacted. If the second DNS server does not respond, the third DNS server will be contacted, and so on.

DNS Internet address binary. The binary representation of a DNS Internet address (IPv4 or IPv6). Even though this field is defined as a character field, a binary IPv4 or IPv6 address is returned in it.

DNS listening port. The remote TCP/IP port number used to contact the DNS server or servers listed in the Internet address parameter. 53 is the well-known port used for this purpose.

Note: Use of a TCP/IP port number other than the well-known port 53 for use by the DNS server can result in TCP/IP communication problems. You may inadvertently use a port number that is reserved for use by another TCP/IP application.

The default DNS Listening port is 53. Valid values range from 1 to 65532.

DNS protocol. The TCP/IP protocol used to communicate with the DNS server or servers specified in the Internet address parameter. User Datagram Protocol (UDP) typically is used for this purpose. Use TCP only if your DNS server is specifically configured to use TCP. Possible values are:

Domain name. The name of the TCP/IP domain of which this system is a member.

Domain search list. The TCP/IP domains to be searched whenever a host name is not given as a Fully Qualified Domain Name (FQDN). Up to six domains may be specified, separated by spaces. The list is blank padded.

Entry length for list of DNS Internet addresses. The entry length in bytes of each element in the list of DNS Internet addresses returned with this format. A value of zero is returned if the list is empty.

Host name. The TCP/IP host name of this system. This field returns the value specified by the CHGTCPDMN command, and is the preferred system name if the system has more than one name corresponding to multiple interfaces.

Note: This system's TCP/IP host name must also be defined in the local host table or the DNS server specified in the Internet address parameter. If no DNS server is specified, the local TCP/IP host table is used.

Initial domain name server. How the initial DNS server is chosen when doing a name lookup. The first configured server can always be queried first, or TCP/IP can rotate through the configured servers in a round-robin fashion to provide a form of load balancing on the servers. Possible values are:

Number of DNS Internet addresses. The number of elements in the list of DNS Internet addresses returned with this format including IPv4 and IPv6 entries. A value of zero is returned if the list is empty.

Offset to list of DNS Internet addresses. The offset from the beginning of the receiver variable, in bytes, to the first element in the list of DNS Internet addresses returned with this format. A value of zero is returned if the list is empty.

Protocol version. The IP version that is used on a specific DNS Internet address. Possible values are:

Request DNSSEC Records. Specifies that the DNSSEC OK bit (DO) is set in DNS queries to indicate that this system is able to accept DNSSEC resource records. This system does not use DNSSEC resource records to validate DNS data. If validation of DNS data is required it must be performed by the domain name servers configured for the system. In addition, the communication channel between this system and the domain name servers should be secured using a method such as TSIG or IPsec. See RFCs 4033, 4044, and 4045 for additional information.

Retries. The number of additional attempts made to establish communication with each DNS server, in the event the first attempt fails.

The default number of retries is 2. Valid values range from 0 to 99.

Search order. Whether to search a DNS server first to resolve a TCP/IP host name conflict, or to search the local TCP/IP host table first.

Time interval. The length of time in seconds this system will wait before initiating a retry attempt to connect to a DNS server. The default time interval is 2 seconds. Valid values range from 0 to 99.



TCPA2100 Format

This format returns detailed information about the TCP/IP (IPv4 and IPv6) dynamic Domain Name Server attributes. For detailed descriptions of the fields in the table, see Field Descriptions.

List of dynamic DNS Internet Addresses. These fields repeat for each dynamic DNS Internet address (IPv4 or IPv6).



Field Descriptions

Dynamic DNS Internet address. The Internet address (IPv4 or IPv6) of a dynamic DNS to be used by this system. There may be from zero to the number of dynamic DNS Internet addresses.
If the first dynamic DNS server in the list does not respond, the second dynamic DNS server in the list will be contacted. If the second dynamic DNS server does not respond, the third dynamic DNS server will be contacted, and so on.

Dynamic DNS Internet address binary. The binary representation of a dynamic DNS Internet address (IPv4 or IPv6). Even though this field is defined as a character field, a binary IPv4 or IPv6 address is returned in it.

Dynamic DNS listening port. The remote TCP/IP port number used to contact the dynamic DNS server or servers listed in the Internet address parameter. 53 is the well-known port used for this purpose.

Note: Use of a TCP/IP port number other than the well-known port 53 for use by the DNS server can result in TCP/IP communication problems. You may inadvertently use a port number that is reserved for use by another TCP/IP application.

The default DNS Listening port is 53. Valid values range from 1 to 65532.

DNS transport protocol. The TCP/IP protocol used to communicate with the dynamic DNS server or servers specified in the Internet address parameter. User Datagram Protocol (UDP) typically is used for this purpose. Use TCP only if your DNS server is specifically configured to use TCP. Possible values are:

List of search domains. The space separated list of domains to be searched whenever a host name is not given as a Fully Qualified Domain Name (FQDN).

Entry length for list of dynamic DNS Internet addresses. The entry length in bytes of each element in the list of dynamic DNS Internet addresses returned with this format. A value of zero is returned if the list is empty.

Entry length for list of search domains. The entry length in bytes of each element in the list of search domains returned with this format. A value of zero is returned if the list is empty.

Number of dynamic DNS Internet addresses. The number of elements in the list of dynamic DNS Internet addresses returned with this format including IPv4 and IPv6 entries. A value of zero is returned if the list is empty.

Number of search domains. The number of elements in the list of search domains returned with this format including IPv4 and IPv6 entries. A value of zero is returned if the list is empty.

Offset to list of dynamic DNS Internet addresses. The offset from the beginning of the receiver variable, in bytes, to the first element in the list of dynamic DNS Internet addresses returned with this format. A value of zero is returned if the list is empty.

Offset to list of search domains. The offset from the beginning of the receiver variable, in bytes, to the first element in the list of search domains returned with this format. A value of zero is returned if the list is empty.

Protocol version. The IP version that is used on a specific dynamic DNS Internet address. Possible values are:

Reserved. An ignored field.

Retries. The number of additional attempts made to establish communication with each DNS server, in the event the first attempt fails.

The default number of retries is 2. Valid values range from 0 to 99.

Time interval. The length of time in seconds this system will wait before initiating a retry attempt to connect to a DNS server. The default time interval is 2 seconds. Valid values range from 0 to 99.


Error Messages


API introduced: V5R1

[ Back to top | >Communications APIs | APIs by category ]