Retrieve Network Interface Data (QtocRtvNetIfcDta) API

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.
NIFD0200	Detailed information about a TCP/IPv6 network interface. Refer to NIFD0200 Format for details on the format.

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 two formats. The first format is for IPv4 interfaces, and the second is for IPv6 interfaces. The value of the Protocol field determines the format of the rest of the Interface Request. For detailed descriptions of the fields in the table, see Field Descriptions.

IPv4 Interface

IPv6 Interface

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:

Reserved. An ignored field. It should be NULL padded.

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
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.

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:

Associated local interface binary. Binary representation of the associated local interface. The following is a special value:

Automatic start. Whether the interface is started automatically when the TCP/IP stack is activated. Possible values are:

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:

Change status. The status of the most recent change to this interface in the dynamic tables used by the TCP/IP protocol stack.

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:

Configured MTU. The configured maximum transmission unit value specified for this interface. The following is a special value:

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:

Directed broadcast address binary. Binary representation of the directed broadcast address. The following is a special value:

DHCP created. Specifies whether this interface was created using Dynamic Host Configuration Protocol (DHCP) or not. Possible values are:

DHCP dynamic DNS updates. Specifies whether dynamic updates to Domain Name System (DNS) tables are enabled or not. Possible values are:

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.

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:

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:

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:

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:

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:

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.

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.

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.

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.

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:

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.

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
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.

Field Descriptions

Address class. The class of IPv6 address that is assigned to this network interface.

Possible values are:

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:

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:

The following are special values:

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:

The following are special values:

Address type. The type of IPv6 address that is assigned to this network interface.

Possible values are:

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:

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:

The following are special values:

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:

The following are special values:

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:

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:

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:

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:

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:

Interface status. Current status of this logical interface.

Internet IPv6 address. The Internet address, in IPv6 address format, of the interface. The following is a special value:

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:

MTU - configured. The configured maximum transmission unit (MTU) value specified for this interface.

The following is a special value:

MTU - current. Maximum transmission unit (MTU) value currently in effect for this interface.

The following is a special value:

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:

Packet rules. The kind of packet rules data available for the particular line this interface is associated with.

Preferred physical line name. Name of a communications line description in the preferred physical line list.

Reserved. An ignored field.

Error Messages

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