Retrieve Network Interface Data (QtocRtvNetIfcDta) API
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Interface request | Input | Char(*) |
| 5 | Error Code | I/O | Char(*) |
Service Program: QTOCNETSTS
Threadsafe: Yes
The Retrieve Network Interface Data (QtocRtvNetIfcDta) API retrieves detailed information about a specified IPv4 or IPv6 network interface.
TCP/IP stack must not necessarily be active for this API to be called. This API can be used to retrieve the information stored in the TCP/IP configuration files.
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 logical interface information to be returned. The format names supported are:
NIFD0100 Detailed information about a TCP/IPv4 network interface. Refer to NIFD0100 Format for details on the format. 
NIFD0150Detailed information about a TCP/IPv4 network interface. If NIFD0150 is specified for the format name parameter, the NIFD0100 format is returned Refer to NIFD0100 Format for details on the format. See Usage Notes for details. 
NIFD0200 Detailed information about a TCP/IPv6 network interface. Refer to NIFD0200 Format for details on the format. NIFD0250Detailed information about a TCP/IPv6 network interface. If NIFD0250 is specified for the format name parameter, the NIFD0200 format is returned Refer to NIFD0200 Format for details on the format. See Usage Notes for details.
- Interface request
- INPUT; CHAR(*)
The Internet address and line description that identify the interface for which information is to be retrieved. See Interface Request Format for details about 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.
Interface Request Format
Information passed in the interface request parameter must be in one of the following formats. For detailed descriptions of the fields in the table, see Field Descriptions.
IPv4 Interface
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Protocol |
| 4 | 4 | BINARY(4) | IPv4 address |
| 8 | 8 | ||
Extended IPv4 Interface
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Protocol |
| 4 | 4 | BINARY(4) | IPv4 address |
| 8 | 8 | CHAR(10) | Line name |
| 18 | 12 | CHAR(2) | Reserved |
| 20 | 14 | BINARY(4) | Virtual LAN identifier |
IPv6 Interface
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Protocol |
| 4 | 4 | CHAR(16) | IPv6 address |
| 20 | 14 | CHAR(10) | Line name |
| 30 | 1E | CHAR(2) | Reserved |
| 32 | 20 | ||
Extended IPv6 Interface
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Protocol |
| 4 | 4 | CHAR(16) | IPv6 address |
| 20 | 14 | CHAR(10) | Line name |
| 30 | 1E | CHAR(2) | Reserved |
| 32 | 20 | BINARY(4) | Virtual LAN identifier |
| 36 | 24 | |
|
Field Descriptions
IPv4 address. The IPv4 address of the interface.
IPv6 address. The IPv6 address of the interface. 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.
Line name. Name of the communications line description that identifies the physical network associated with the interface. This field should only be used when trying to retrieve information about an IPv6 link-local interface, otherwise it should be blank-padded.
Protocol. The type and IP version of connection protocol.
Possible values are:
| 1 | TCP/IPv4 - A Transmission Control Protocol (TCP) over IPv4 interface request. |
| 2 | TCP/IPv6 - A Transmission Control Protocol (TCP) over IPv6 interface request. |
Reserved. An ignored field. It should be NULL padded.
Virtual LAN identifier. The virtual LAN to which this interface belongs according to
IEEE standard 802.1Q. This field is only valid for interfaces defined for Ethernet lines.
The following are permissible values:
| 0 | NONE - No virtual LAN identifier is associated with this interface. |
| 1 - 4094 | The virtual LAN identifier associated with this
interface. |
Format of Returned Interface Data
For detailed information about a specific IPv4 interface, use format NIFD0100.
For detailed information about a specific IPv6 interface, use format NIFD0200.
NIFD0100 Format
This format returns detailed information about the TCP/IPv4 interface. 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 | CHAR(15) | Internet address |
| 23 | 17 | CHAR(1) | Reserved |
| 24 | 18 | BINARY(4) | Internet address binary |
| 28 | 1C | CHAR(15) | Network address |
| 43 | 2B | CHAR(1) | Reserved |
| 44 | 2C | BINARY(4) | Network address binary |
| 48 | 30 | CHAR(10) | Line description |
| 58 | 3A | CHAR(2) | Reserved |
| 60 | 3C | BINARY(4) | Interface status |
| 64 | 40 | BINARY(4) | Interface type of service |
| 68 | 44 | BINARY(4) | Interface MTU |
| 72 | 48 | BINARY(4) | Interface line type |
| 76 | 4C | CHAR(15) | Host address |
| 91 | 5B | CHAR(1) | Reserved |
| 92 | 5C | BINARY(4) | Host address binary |
| 96 | 60 | CHAR(15) | Interface subnet mask |
| 111 | 6F | CHAR(1) | Reserved |
| 112 | 70 | BINARY(4) | Interface subnet mask binary |
| 116 | 74 | CHAR(15) | Directed broadcast address |
| 131 | 83 | CHAR(1) | Reserved |
| 132 | 84 | BINARY(4) | Directed broadcast address binary |
| 136 | 88 | CHAR(8) | Change date |
| 144 | 90 | CHAR(6) | Change time |
| 150 | 96 | CHAR(15) | Associated local interface |
| 165 | A5 | CHAR(3) | Reserved |
| 168 | A8 | BINARY(4) | Associated local interface binary |
| 172 | AC | BINARY(4) | Change status |
| 176 | B0 | BINARY(4) | Packet rules |
| 180 | B4 | BINARY(4) | Automatic start |
| 184 | B8 | BINARY(4) | TRLAN bit sequencing |
| 188 | BC | BINARY(4) | Interface type |
| 192 | C0 | BINARY(4) | Proxy ARP allowed |
| 196 | C4 | BINARY(4) | Proxy ARP enabled |
| 200 | C8 | BINARY(4) | Configured MTU |
| 204 | CC | CHAR(24) | Network name |
| 228 | E4 | CHAR(24) | Interface name |
| 252 | FC | CHAR(50) | Alias name |
| 302 | 12E | CHAR(2) | Reserved |
| 304 | 130 | CHAR(50) | Interface description |
| 354 | 162 | CHAR(2) | Reserved |
| 356 | 164 | BINARY(4) | Offset to preferred interface list |
| 360 | 168 | BINARY(4) | Number of entries in preferred interface list |
| 364 | 16C | BINARY(4) | Length of one preferred interface list entry |
| 368 | 170 | BINARY(4) | DHCP created |
| 372 | 174 | BINARY(4) | DHCP dynamic DNS updates |
| 376 | 178 | BINARY(8) | DHCP lease expiration |
| 384 | 180 | CHAR(8) | DHCP lease expiration - date |
| 392 | 188 | CHAR(6) | DHCP lease expiration - time |
| 398 | 18E | BINARY(8) | DHCP lease obtained |
| 406 | 196 | CHAR(8) | DHCP lease obtained - date |
| 414 | 19E | CHAR(6) | DHCP lease obtained - time |
| 420 | 1A4 | BINARY(4) | Use DHCP unique identifier |
| 424 | 1A8 | CHAR(15) | DHCP server IP address |
| 439 | 1B7 | CHAR(1) | Reserved |
| 440 |
1B8 | BINARY(4) | Virtual LAN identifier |
| 444 | 1BC | BINARY(4) | Preferred interface default route |
| This field repeats for each preferred interface list entry | CHAR(*) | Preferred interface list entry (See Format of Preferred Interface List Entry for more information.) | |
Format of Preferred Interface List Entry
The preferred interface list entry describes the data returned for each entry in the preferred interface list of the NIFD0100 format. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(15) | Preferred interface Internet address |
| 15 | F | CHAR(1) | Reserved |
| 16 | 10 | BINARY(4) | Preferred interface Internet address binary |
| 20 | 14 | CHAR(*) | Reserved |
Field Descriptions
Alias name. Name given to the interface to use as an alternate to the IP address.
Associated local interface. The Internet address, in dotted decimal notation, of the local interface that has been associated with this interface. The following is a special value:
| *NONE | No association has been made between this interface and another local interface. |
Associated local interface binary. Binary representation of the associated local interface. The following is a special value:
| 0 | No association has been made between this interface and another local interface. |
Automatic start. Whether the interface is started automatically when the TCP/IP stack is activated. Possible values are:
| 0 | NO. This interface is not started automatically. |
| 1 | YES. This interface is started automatically. |
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.
Change date. The date of the most recent change to this interface in the dynamic tables used by the TCP/IP protocol stack. It is returned as 8 characters in the form YYYYMMDD, where:
| YYYY | Year |
| MM | Month |
| DD | Day |
Change status. The status of the most recent change to this interface in the dynamic tables used by the TCP/IP protocol stack.
| 1 | Add interface request processed |
| 2 | Change interface request processed |
| 3 | Start interface request processed |
| 4 | End interface request processed |
Change time. The time of the most recent change to this interface in the dynamic tables used by the TCP/IP protocol stack. It is returned as 6 characters in the form HHMMSS, where:
| HH | Hour |
| MM | Minute |
| SS | Second |
Configured MTU. The configured maximum transmission unit value specified for this interface. The following is a special value:
| 0 | LIND. The interface is not active currently and the MTU was specified as *LIND. |
Directed broadcast address. The Internet address, in dotted decimal notation, used to broadcast to all systems attached to the same network or subnetwork as this interface. The following is a special value:
| *NONE | The interface is attached to a network that does not support a broadcast operation. |
Directed broadcast address binary. Binary representation of the directed broadcast address. The following is a special value:
| 0 | The interface is attached to a network that does not support a broadcast operation. |
DHCP created. Specifies whether this interface was created using Dynamic Host Configuration Protocol (DHCP) or not. Possible values are:
| 1 | This interface was created using DHCP |
| 0 | This interface was not created using DHCP |
DHCP dynamic DNS updates. Specifies whether dynamic updates to Domain Name System (DNS) tables are enabled or not. Possible values are:
| 1 | DNS updates are enabled. |
| 0 | DNS updates are disabled. |
DHCP lease expiration. This field specifies the date and time when the DHCP lease will expire. This is a system time-stamp.
DHCP lease expiration - date. This field specifies the date when the DHCP lease will expire.
DHCP lease expiration - time. This field specifies the time when the DHCP lease will expire.
DHCP lease obtained. This field specifies the date and time when the DHCP lease was obtained or renewed. This is a system time-stamp.
DHCP lease obtained - date. This field specifies the date when the DHCP lease was obtained or renewed.
DHCP lease obtained - time. This field specifies the time when the DHCP lease was obtained or renewed.
DHCP server IP address. The Internet address, in dotted
decimal notation, of the DHCP server from which the DHCP lease was obtained
or renewed. This field will contain blanks for interfaces that are not
created by DHCP.
Host address. Host portion of the Internet address, in dotted decimal notation, as determined by the subnet mask specified for this interface.
Host address binary. Binary representation of the host address.
Interface line type. Type of line used by an interface. The following link protocols are supported:
| -1 | OTHER - IPS - An Internet Protocol (IP) over SNA interface. |
| -2 | NONE - Line is not defined. This is used for the following interfaces: *LOOPBACK, *VIRTUALIP, *OPC. There is no line type value for these interfaces. |
| -3 | ERROR - This value is displayed if any system errors other than those for *NOTFND are received while trying to determine the link type for an interface. |
| -4 | NOTFND - Not found. This value is displayed if the line description object for this interface cannot be found. |
| 1 | ELAN - Ethernet local area network protocol. |
| 2 | TRLAN - Token-ring local area network protocol. |
| 3 | FR - Frame relay network protocol. |
| 4 | ASYNC - Asynchronous communications protocol. |
| 5 | PPP - Point-to-point Protocol. |
| 6 | WLS - Wireless local area network protocol. |
| 7 | X.25 - X.25 protocol. |
| 8 | DDI - Distributed Data Interface protocol. |
| 9 | TDLC - Twinaxial Datalink Control. Used for TCP/IP over Twinax. |
| 10 | L2TP (Virtual PPP) - Layer Two Tunneling protocol. |
| 12 | VETH - Virtual Ethernet protocol. |
| 13 | PPPoE - Point-to-Point over Ethernet protocol. |
Interface description. Configured free form comment field about this interface.
Interface MTU. Maximum transmission unit value specified for this interface. The following are special values:
| -1 | OTHER. IPS - An Internet Protocol (IP) over SNA interface. |
| 0 | LIND - The interface is not active currently and the MTU was specified as *LIND. |
Interface name. The first 10 characters of the name of this interface.
Interface name - full. The complete 24 character interface name.
Interface status. Current status of this logical interface.
| 0 | Inactive - The interface has not been started. The interface is not active. |
| 1 | Active - The interface has been started and is running. |
| 2 | Starting - The system is processing the request to start this interface. |
| 3 | Ending - The system is processing the request to end this interface. |
| 4 | RCYPND - An error with the physical line associated with this interface was detected by the system. The line description associated with this interface is in the recovery pending (RCYPND) state. |
| 5 | RCYCNL - A hardware failure has occurred and the line description associated with this interface is in the recovery canceled (RCYCNL) state. |
| 6 | Failed - The line description associated with this interface has entered the failed state. |
| 7 | Failed (TCP) - An error was detected in the IBM® TCP/IP Licensed Internal Code. |
| 8 | DOD - Point-to-Point (PPP) Dial-on-Demand. |
| 9 | Acquiring - The interface address is being acquired from the DHCP server. |
Interface subnet mask. The subnet mask for the network, subnet, and host address fields of the Internet address, in dotted decimal notation, that defines the subnetwork for an interface.
Interface subnet mask binary. Binary representation of the interface subnet mask.
Interface type. The interface types are:
| 0 | Broadcast capable |
| 1 | Non-broadcast capable |
| 2 | Unnumbered network |
Interface type of service. The way in which the Internet hosts and routers should make trade-offs between throughput, delay, reliability and cost. The following are special values:
| -1 | OTHER - IPS - An Internet Protocol (IP) over SNA interface. |
| 1 | NORMAL - Used for delivery of datagrams. |
| 2 | MINDELAY - Prompt delivery of datagrams with the minimize delay indication. |
| 3 | MAXTHRPUT - Datagrams with maximize throughput indication. |
| 4 | MAXRLB - Datagrams with maximize reliability indication. |
| 5 | MINCOST - Datagram with minimize monetary cost indication. |
Internet address. The Internet address, in dotted decimal notation, of an interface.
Internet address binary. Binary representation of the Internet address.
Length of one preferred interface list entry. The length of a preferred interface list entry. For virtual interfaces, a length of zero means that a preferred interface list is not being used. For other types of interfaces, this field is set to zero.
Line description Name of the communications line description that identifies the physical network associated with an interface. The following are special values:
| *IPS | This interface is used by Internet Protocol (IP) over SNA. |
| *LOOPBACK | This is a loopback interface. Processing associated with a loopback interface does not extend to a physical line. |
| *VIRTUALIP | The virtual interface is a circuitless interface. It is used in conjunction with the associated local interface (LCLIFC) when adding standard interfaces. |
| *OPC | This interface is attached to the optical bus (OptiConnect). |
Network address. Internet address, in dotted decimal notation, of the IP network or subnetwork to which the interface is attached.
Network address binary. Binary representation of the network address.
Network name. The first 10 characters of the name of the network that this interface is a part of.
Network name - full. The complete 24 character name of the network that this interface is a part of.
Number of entries in preferred interface list. The number of entries in the preferred interface list. For virtual interfaces, zero means that a preferred interface list is not being used. For other types of interfaces, this field is set to zero.
Offset to preferred interface list. The offset from the start of the receiver variable to the beginning of the preferred interface list. For virtual interfaces, zero means that a preferred interface list is not being used. For other types of interfaces, this field is set to zero.
Packet rules. The kind of packet rules data available for a particular line.
| -1 | OTHER - An unknown Packet rules value. |
| 0 | None - No filters and no NAT are loaded for the line specified. |
| 1 | NAT - NAT is enabled for this line. |
| 2 | Filters - Filters are defined for this line. |
| 3 | Filters and NAT - NAT enabled and filters defined. |
| 4 | Filters and IPSec - Filters and IPSec filters are defined for this line. |
| 5 | NAT and Filters and IPSec - NAT enabled and Filters and IPsec filters defined. |
Preferred interface list entry. Specifies information about an interface in the preferred interface list. The order in which the list entries are returned is also the order in which the system uses the interfaces as Proxy Agents.
Preferred interface Internet address. The Internet address, in dotted decimal notation, of an interface in the preferred interface list.
Preferred interface Internet address binary. The binary representation of an interface Internet address in the preferred interface list.
Preferred interface default route. This field describes whether the preferred proxy interfaces are based on the system's default route. Possible values are:
| 0 | The default route is not used to determine the preferred interface. |
| 1 | The default route is used to determine the preferred interface. |
Proxy ARP allowed. This field applies to Opticonnect (*OPC) and Virtual interfaces only. For those types of interfaces, this field indicates whether Proxy ARP has been configured to be allowed or not allowed.
| 0 | NO - Proxy ARP not allowed. |
| 1 | YES - Proxy ARP allowed. |
| 2 | Unsupported - Proxy ARP allowed field is not supported by this interface. |
Proxy ARP enabled. Whether Proxy ARP is currently active for this interface. Proxy ARP allows physically distinct separate networks to appear as if they are a single logical network. It provides connectivity between physically separate network without creating any new logical networks and without updating any route tables.
| 0 | NO - Proxy ARP not enabled. |
| 1 | YES - Proxy ARP enabled. |
Reserved. An ignored field.
TRLAN bit sequencing. The order the Address Resolution Protocol (ARP) puts bits into the hardware address for Token Ring. Possible values are:
| 1 | MSB - The most significant bit is placed first. |
| 2 | LSB - The least significant bit is placed first. |
Use DHCP unique identifier. Whether the DHCP unique identifier (DUID) is used as the client identification for the Dynamic Host Configuration Protocol (DHCP) or not. Possible values are:
| 0 | NO - The hardware (MAC) address is used for the client ID. |
| 1 | YES - The DHCP unique identifier is used for the client ID. |
Virtual LAN identifier. The virtual LAN to which this interface belongs according to
IEEE standard 802.1Q. This field is only valid for interfaces defined for Ethernet lines.
The following are possible returned values:
| 0 | NONE - No virtual LAN identifier is associated with this interface. |
| 1 - 4094 | The virtual LAN identifier associated with this
interface. |
NIFD0200 Format
This format returns detailed information about the TCP/IPv6 interface. 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 | CHAR(45) | Internet IPv6 address |
| 53 | 35 | CHAR(3) | Reserved |
| 56 | 38 | CHAR(16) | Internet IPv6 address binary |
| 72 | 48 | CHAR(3) | Interface prefix length |
| 75 | 4B | CHAR(1) | Reserved |
| 76 | 4C | BINARY(4) | Interface prefix length binary |
| 80 | 50 | BINARY(4) | Address type |
| 84 | 54 | BINARY(8) | Address preferred lifetime |
| 92 | 5C | CHAR(8) | Address preferred lifetime expiration date |
| 100 | 64 | CHAR(6) | Address preferred lifetime expiration time |
| 106 | 6A | CHAR(2) | Reserved |
| 108 | 6C | BINARY(8) | Address valid lifetime |
| 116 | 74 | CHAR(8) | Address valid lifetime expiration date |
| 124 | 7C | CHAR(6) | Address valid lifetime expiration time |
| 130 | 82 | CHAR(10) | Line name |
| 140 | 8C | BINARY(4) | Interface line type |
| 144 | 90 | CHAR(50) | Interface description |
| 194 | C2 | CHAR(45) | Network IPv6 address |
| 239 | EF | CHAR(1) | Reserved |
| 240 | F0 | CHAR(16) | Network IPv6 address binary |
| 256 | 100 | CHAR(45) | Host IPv6 address |
| 301 | 12D | CHAR(3) | Reserved |
| 304 | 130 | CHAR(16) | Host IPv6 address binary |
| 320 | 130 | BINARY(4) | Interface status |
| 324 | 144 | BINARY(4) | Automatic start |
| 328 | 148 | BINARY(4) | Packet rules |
| 332 | 14C | BINARY(4) | Interface source |
| 336 | 150 | CHAR(4) | Reserved |
| 340 | 154 | CHAR(8) | Change date |
| 348 | 15C | CHAR(6) | Change time |
| 354 | 162 | CHAR(2) | Reserved |
| 356 | 164 | BINARY(4) | MTU - configured |
| 360 | 168 | BINARY(4) | MTU - current |
| 364 | 16C | BINARY(4) | Duplicate address detection maximum transmits |
| 368 | 170 | CHAR(50) | Alias name |
| 418 | 1A2 | CHAR(6) | Reserved |
| 424 | 1A8 | BINARY(4) | On-link |
| 428 | 1AC | BINARY(4) | Address class |
| 432 | 1B0 | BINARY(4) | Offset to preferred physical line list |
| 436 | 1B4 | BINARY(4) | Number of entries in preferred physical line list |
| 440 | 1B8 | BINARY(4) | Length of one preferred physical line list entry |
| 444 | 1BC | BINARY(8) | DHCP lease obtained |
| 452 | 1C4 | CHAR(8) | DHCP lease obtained - date |
| 460 | 1CC | CHAR(6) | DHCP lease obtained - time |
| 466 | 1D2 | CHAR(30) | DHCP server unique identifier |
| 496 | 1F0 | BINARY(4) | DHCP server unique identifier length |
| 500 | 1F4 | CHAR(10) | Current proxy agent line |
| 510 | 1FE | CHAR (2) | Reserved |
| 512 |
200 | BINARY(4) | Virtual LAN identifier |
| This field repeats for each preferred physical interface list entry | CHAR(*) | Preferred physical line list entry (See Format of Preferred Physical Line List Entry for more information.) | |
Format of Preferred Physical Line List Entry
The preferred physical line list entry describes the data returned for each entry in the preferred physical line list of the NIFD0200 format. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Preferred physical line name |
| 10 | A | CHAR(2) | Reserved |
| 12 |
C | BINARY(4) | Preferred virtual LAN identifier |
| 16 | 10 | |
|
Field Descriptions
Address class. The class of IPv6 address that is assigned to this network interface.
Possible values are:
| 1 | Public - the interface is a public one. |
| 2 | Temporary - the interface is a temporary one used for privacy extensions. |
Address preferred lifetime. The length of time that a "valid" address is preferred, in seconds. When the preferred lifetime expires, the address becomes Deprecated. Valid values range from 0 through 4294967295 seconds. Negative values indicate that the Address preferred lifetime expired that number of seconds ago.
The following are special values:
| -1000000000 | Infinite - this address has an infinite preferred lifetime. |
| -1000000001 | Not Applicable - this address is not in the Preferred address state, so this field does not apply. |
Address preferred lifetime expiration date. The date when this address will no longer be preferred. If the Address preferred lifetime expiration date and time are in the future, the address is still preferred. If the Address preferred lifetime expiration date and time are in the past, then this address is no longer preferred. The Address preferred lifetime expiration date is returned as 8 characters in the form YYYYMMDD.
The meaning of the characters is as follows:
| YYYY | Year |
| MM | Month |
| DD | Day |
The following are special values:
| 00000000 | Infinite - this address has an infinite preferred lifetime which never expires. |
| 00000001 | Not Applicable - this address is not in the Preferred address state, so this field does not apply. |
Address preferred lifetime expiration time. The time when this address will no longer be in the preferred state. If the Address preferred lifetime expiration date and time are in the future, the address is still preferred. If the Address preferred lifetime expiration date and time are in the past, then this address is no longer preferred. The Address preferred lifetime expiration time is returned as 6 characters in the form HHMMSS.
The meaning of the characters is as follows:
| HH | Hour |
| MM | Minute |
| SS | Second |
The following are special values:
| 000000 | Infinite - this address has an infinite preferred lifetime which never expires. |
| 000001 | Not Applicable - this address is not in the preferred address state, so this field does not apply. |
Address type. The type of IPv6 address that is assigned to this network interface.
Possible values are:
| 1 | Unicast - an identifier for a single interface. A packet sent to a unicast address is delivered to the interface identified by that address. |
| 2 | Multicast - an identifier for a set of interfaces (typically belonging to different nodes). A packet sent to a multicast address is delivered to all interfaces identified by that address. |
| 3 | Anycast - an identifier for a set of interfaces (typically belonging to different nodes). A packet sent to an anycast address is delivered to one of the interfaces identified by that address (the "nearest" one, according to the routing protocols' measure of distance). |
Address valid lifetime. The length of time, in seconds, that an address remains in a "valid" state (Preferred or Deprecated). When the valid lifetime expires, the address becomes Expired. Valid values range from 0 through 4294967295 seconds. Negative values indicate that the Address valid lifetime expired that number of seconds ago.
The following are special values:
| -1000000000 | Infinite - this address has an infinite valid lifetime. |
| -1000000001 | Not Applicable - this address is not in a valid address state, so this field does not apply. |
Address valid lifetime expiration date. The date when this address will expire or did expire. If the Address valid lifetime expiration date and time are in the future, the address has not expired yet. If the Address valid lifetime expiration date and time are in the past, then this address has expired and is still being returned for a short period of time to indicate that the interface ceased to function because its valid lifetime expired. The Address valid lifetime expiration date is returned as 8 characters in the form YYYYMMDD.
The meaning of the characters is as follows:
| YYYY | Year |
| MM | Month |
| DD | Day |
The following are special values:
| 00000000 | Infinite - this address has an infinite valid lifetime which never expires. |
| 00000001 | Not Applicable - this address is not in a valid address state, so this field does not apply. |
Address valid lifetime expiration time. The time when this address will expire or did expire. If the Address valid lifetime expiration date and time are in the future, the address has not expired yet. If the Address valid lifetime expiration date and time are in the past, then this address has expired and is still being returned for a short period of time to indicate that the interface ceased to function because its valid lifetime expired. The Address valid lifetime expiration time is returned as 6 characters in the form HHMMSS.
The meaning of the characters is as follows:
| HH | Hour |
| MM | Minute |
| SS | Second |
The following are special values:
| 000000 | Infinite - this address has an infinite valid lifetime which never expires. |
| 000001 | Not Applicable - this address is not in a valid address state, so this field does not apply. |
Alias name. Name given to interface to use as an alternate to the IP address.
Automatic start. Whether the interface is started automatically when the TCP/IPv6 stack is activated. Possible values are:
| 0 | NO. This interface is not started automatically. |
| 1 | YES. This interface is started automatically. |
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.
Change date. The date of the most recent change to this interface in the dynamic tables used by the TCP/IPv6 protocol stack. It is returned as 8 characters in the form YYYYMMDD, where:
| YYYY | Year |
| MM | Month |
| DD | Day |
Change time. The time of the most recent change to this interface in the dynamic tables used by the TCP/IPv6 protocol stack. It is returned as 6 characters in the form HHMMSS, where:
| HH | Hour |
| MM | Minute |
| SS | Second |
Current proxy agent line. Name of the communication line description that is used with the IPv6 interface for virtual IP address (VIPA) proxy Neighbor Discovery. The following is a special value:
| *NONE | No association has been made between this interface and another physical interface. |
DHCP lease obtained. This field specifies the date and time when the DHCP lease was obtained or renewed. This is a system time-stamp.
DHCP lease obtained - date. This field specifies the date when the DHCP lease was obtained or renewed.
DHCP lease obtained - time. This field specifies the time when the DHCP lease was obtained or renewed.
DHCP server unique identifier. This field specifies the DHCP unique identifier (DUID) of the DHCP server from which the IP address was obtained.
DHCP server unique identifier length. The length of the server's DHCP unique DHCP identifier.
Duplicate address detection maximum transmits. Specifies the maximum number of Duplicate Address Detection (DAD) transmissions the stack will send out on the interface.
Host IPv6 address. Host portion of the Internet address, in IPv6 address format, as determined by the prefix length configured for this interface. This field is NULL padded.
Host IPv6 address binary. Binary representation of the host IPv6 address. Even though this field is defined as a character field, a binary IPv6 address is returned in it.
Interface description Configured free form comment field about this interface.
Interface line type. Type of line used by the interface. The following link protocols are supported:
| -1 | OTHER |
| -2 | NONE - Line is not defined. This value is used for the following interfaces: *LOOPBACK, *VIRTUALIP. There is no line type value for this interface. |
| -3 | ERROR - This value is displayed if any system errors other than those for *NOTFND are received while trying to determine the link type for an interface. |
| -4 | NOTFND - Not found. This value is displayed if the line description object for this interface cannot be found. |
| 1 | ELAN - Ethernet local area network protocol. |
| 5 | PPP - Point-to-point Protocol. |
| 10 | L2TP (Virtual PPP) - Layer Two Tunneling protocol. |
| 12 | VETH - Virtual Ethernet protocol. |
| 13 | PPPoE - Point-to-Point over Ethernet protocol. |
Interface 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. The prefix length is used to generate network and host addresses. This field is NULL padded.
Interface prefix length binary. Binary representation of the interface prefix length.
Interface source Specifies how this interface was added to the TCP/IPv6 stack.
Possible values are:
| 1 | Stateless - the interface was added to the stack by the IPv6 stateless autoconfiguration mechanism. |
| 2 | Stateful - the interface was added to the stack by the IPv6 stateful configuration mechanism (that is, DHCPv6). |
| 3 | Manual - the interface was added to the stack by manual configuration. |
| 4 | Loopback - the interface was added to the stack as the loopback interface. |
Interface status. Current status of this logical interface.
| 0 | Inactive - The interface has not been started. The interface is not active. |
| 1 | Active - The interface has been started and is running. |
| 2 | Starting - The system is processing the request to start this interface. |
| 3 | Ending - The system is processing the request to end this interface. |
| 4 | RCYPND - An error with the physical line associated with this interface was detected by the system. The line description associated with this interface is in the recovery pending (RCYPND) state. |
| 5 | RCYCNL - A hardware failure has occurred and the line description associated with this interface is in the recovery canceled (RCYCNL) state. |
| 6 | Failed - The line description associated with this interface has entered the failed state. |
| 7 | Failed (TCP) - An error was detected in the IBM TCP/IP Licensed Internal Code. |
Internet IPv6 address. The Internet address, in IPv6 address format, of the interface. The following is a special value:
| *IP6SAC | This is an IPv6 SAC created 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 one preferred physical line list entry. The length of a preferred physical line list entry.
Line name. Name of the communications line description that identifies the physical network associated with an interface. This field is blank-padded.
The following are special values:
| *LOOPBACK | This is the IPv6 loopback interface. Processing associated with a loopback interface does not extend to a physical line. |
| *VIRTUALIP | The virtual interface is a circuitless interface. It is used in conjunction with the associated local interface (LCLIFC) when adding standard interfaces. |
MTU - configured. The configured maximum transmission unit (MTU) value specified for this interface.
The following is a special value:
| 0 | LIND - The MTU was configured as *LIND, the MTU size is the maximum frame size found in the line description object associated with this interface. |
MTU - current. Maximum transmission unit (MTU) value currently in effect for this interface.
The following is a special value:
| 0 | LIND - The interface is not active currently and the MTU was configured as *LIND. |
Network IPv6 address. Internet address, in IPv6 address format, of the IPv6 network or subnetwork to which the interface is attached. This field is NULL padded.
Network IPv6 address binary. Binary representation of the network IPv6 address. Even though this field is defined as a character field, a binary IPv6 address is returned in it.
Number of entries in preferred physical line list. The number of entries in the preferred physical line list.
Offset to preferred physical line list. The offset from the start of the receiver variable to the beginning of the preferred physical line list.
On-link. Whether or not this interface and all IPv6 addresses with the same prefix are on the same link. Possible values are:
| 0 | Off-link - Addresses with the same prefix are not assumed to be on the same link. |
| 1 | On-link - Addresses with the same prefix are assumed to be on the same link and directly reachable. |
Packet rules. The kind of packet rules data available for the particular line this interface is associated with.
| -1 | OTHER - An unknown Packet rules value. |
| 0 | None - No filters and no NAT are loaded for the line specified. |
| 1 | NAT - NAT is enabled for this line. |
| 2 | Filters - Filters are defined for this line. |
| 3 | Filters and NAT - NAT enabled and filters defined. |
| 4 | Filters and IPSec - Filters and IPSec filters are defined for this line. |
| 5 | NAT and Filters and IPSec - NAT enabled and Filters and IPsec filters defined. |
Preferred physical line name. Name of a communications line description in the preferred physical line list.
Preferred
virtual LAN identifier. The virtual LAN that is associated with the preferred
physical line name according to
IEEE standard 802.1Q. This field is only valid for Ethernet lines.
The following are possible returned values:
| 0 | NONE - No virtual LAN identifier is associated with the line. |
| 1 - 4094 | The virtual LAN identifier associated with the
line. |
Reserved. An ignored field.
Virtual LAN identifier. The virtual LAN to which this interface belongs according to
IEEE standard 802.1Q. This field is only valid for interfaces defined for Ethernet lines.
The following are possible returned values:
| 0 | NONE - No virtual LAN identifier is associated with this interface. |
| 1 - 4094 | The virtual LAN identifier associated with this
interface. |
Usage Notes
- If NIFD0100 or NIFD0150 is specified as the format parameter; the NIFD0100 format is returned for both. Refer to NIFD0100 Format for details on the returned format.
- If NIFD0200 or NIFD0250 is specified as the format parameter; the NIFD0200 format is returned for both. Refer to NIFD0200 Format for details on the returned format.
- The NIFD0150 format is required to specify a line description name and virtual LAN identifier in order to retrieve details for an *IP4DHCP interface.
- The NIFD0250 format is required to specify a virtual LAN
identifier.
Error Messages
| Message ID | Error Message Text |
|---|---|
| TCP84C5 E | API error listing TCP/IP Network Status list information. |
| TCP84C6 E | Internal operations error - RESULT &1 CC &2 RC &3 ERRNO &4. |
| TCP84CD E | Interface request 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: V6R1
| Top | Communications APIs | APIs by category |