List Network Interfaces (QtocLstNetIfc) API

The List Network Interfaces (QtocLstNetIfc) API returns a list of all logical TCP/IP interfaces with details. This API returns all IPv4 logical interfaces using one output format name, and all IPv6 logical interfaces using a different output format name.

As of V6R1, TCP/IP stack must not necessarily be active for this API to be called, so TCP84C0 will no longer be issued. This API can be used to retrieve the information stored in the TCP/IP configuration files.

Authorities and Locks

User Space Library Authority

*EXECUTE

User Space Authority

*CHANGE

User Space Lock

*SHRNUP

Required Parameter Group

Qualified user space name

INPUT; CHAR(20)

The user space that is to receive the created list. The first ten characters contain the user space name, and the second ten characters contain the name of the library in which the user space is located. You can use these special values for the library name:

*CURLIB	The job's current library
*LIBL	The library list

Format name

INPUT; CHAR(8)

The format of the logical interface information to be returned. The format names supported are:

NIFC0100	Detailed information about each TCP/IPv4 network interface. See NIFC0100 Format for details on the format.
NIFC0200	Detailed information about each TCP/IPv6 network interface. See NIFC0200 Format for details on the format.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

Format of Interface Lists

To request a list of all logical interfaces, use format NIFC0100.

The interface description list consists of:

• A user area
• A generic header
• An input parameter section
• A header section
• A list data section:
  • NIFC100 format, or
  • NIFC0200 format

For details about the user area and generic header, see User spaces. For details about the remaining items, see the following sections.

When you retrieve list entry information from a user space, you must use the entry size returned in the generic header. The size of each entry may be padded at the end. If you do not use the entry size, the result may not be valid. For examples of how to process lists, see Examples: APIs and exit programs.

Input Parameter Section

Header Section

Format of Returned Connection Data

To retrieve the list of TCP/IPv4 network interfaces, request format NIFC0100, and you will get a repeating list of NIFC0100 tables, each one returning information about a single IPv4 network interface. To retrieve the list of TCP/IPv6 network interfaces, request format NIFC0200, and you will get a repeating list of NIFC0200 tables, each one returning information about a single IPv6 network interface.

NIFC0100 Format

The following information about each TCP/IPv4 logical interface is returned for the NIFC0100 format. For detailed descriptions of the fields in the table, see Field Descriptions.

Offset		Type	Field
Dec	Hex
0	0	CHAR(15)	Internet address
15	F	CHAR(1)	Reserved
16	10	BINARY(4)	Internet address binary
20	14	CHAR(15)	Network address
35	23	CHAR(1)	Reserved
36	24	BINARY(4)	Network address binary
40	28	CHAR(10)	Network name
50	32	CHAR(10)	Line description
60	3C	CHAR(10)	Interface name
70	46	CHAR(2)	Reserved
72	48	BINARY(4)	Interface status
76	4C	BINARY(4)	Interface type of service
80	50	BINARY(4)	Interface MTU
84	54	BINARY(4)	Interface line type
88	58	CHAR(15)	Host address
103	67	CHAR(1)	Reserved
104	68	BINARY(4)	Host address binary
108	6C	CHAR(15)	Interface subnet mask
123	7B	CHAR(1)	Reserved
124	7C	BINARY(4)	Interface subnet mask binary
128	80	CHAR(15)	Directed broadcast address
143	8F	CHAR(1)	Reserved
144	90	BINARY(4)	Directed broadcast address binary
148	94	CHAR(8)	Change date
156	9C	CHAR(6)	Change time
162	A2	CHAR(15)	Associated local interface
177	B1	CHAR(3)	Reserved
180	B4	BINARY(4)	Associated local interface binary
184	B8	BINARY(4)	Change status
188	BC	BINARY(4)	Packet rules
192	C0	BINARY(4)	Automatic start
196	C4	BINARY(4)	TRLAN bit sequencing
200	C8	BINARY(4)	Interface type
204	CC	BINARY(4)	Proxy ARP enabled
208	D0	BINARY(4)	Proxy ARP allowed
212	D4	BINARY(4)	Configured MTU
216	D8	CHAR(24)	Network name - full
240	F0	CHAR(24)	Interface name - full
264	108	CHAR(50)	Alias name
314	13A	CHAR(2)	Reserved
316	13C	BINARY(4)	Alias name CCSID
320	140	BINARY(4)	Offset to preferred interface list
324	144	BINARY(4)	Number of entries in preferred interface list
328	148	BINARY(4)	Length of one preferred interface list entry
332	14C	CHAR(50)	Interface description
382	17E	CHAR(2)	Reserved
384	180	BINARY(4)	DHCP created
388	184	BINARY(4)	DHCP dynamic DNS updates
392	188	BINARY(8)	DHCP lease expiration
400	190	CHAR(8)	DHCP lease expiration - date
408	198	CHAR(6)	DHCP lease expiration - time
414	19E	BINARY(8)	DHCP lease obtained
422	1A6	CHAR(8)	DHCP lease obtained - date
430	1AE	CHAR(6)	DHCP lease obtained - time
436	1B4	CHAR(1)	Reserved
This field repeats for each prefered interface list entry		CHAR(*)	Prefered interface list entry (See Format of Prefered 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 NIFC0100 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.

Alias name CCSID. Coded character set ID for the alias name.

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:

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:

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.

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.

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:

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 Vertical 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 user space 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.

NIFC0200 Format

The following information about each TCP/IPv6 logical interface is returned for the NIFC0200 format. For detailed descriptions of the fields in the table, see Field Descriptions.

Offset		Type	Field
Dec	Hex
0	0	CHAR(45)	Internet IPv6 address
45	2D	CHAR(3)	Reserved
48	30	CHAR(16)	Internet IPv6 address binary
64	40	CHAR(3)	Interface prefix length
67	43	CHAR(1)	Reserved
68	44	BINARY(4)	Interface prefix length binary
72	48	BINARY(4)	Address type
76	4C	BINARY(4)	Address state
80	50	BINARY(8)	Address preferred lifetime
88	58	CHAR(8)	Address preferred lifetime expiration date
96	60	CHAR(6)	Address preferred lifetime expiration time
102	66	CHAR(2)	Reserved
104	68	BINARY(8)	Address valid lifetime
112	70	CHAR(8)	Address valid lifetime expiration date
120	78	CHAR(6)	Address valid lifetime expiration time
126	7E	CHAR(10)	Line name
136	88	BINARY(4)	Interface line type
140	8C	CHAR(50)	Interface description
190	BE	CHAR(45)	Network IPv6 address
235	EB	CHAR(1)	Reserved
236	EC	CHAR(16)	Network IPv6 address binary
252	FC	CHAR(45)	Host IPv6 address
297	129	CHAR(3)	Reserved
300	12C	CHAR(16)	Host IPv6 address binary
316	13C	BINARY(4)	Interface status
320	140	BINARY(4)	Automatic start
324	144	BINARY(4)	Packet rules
328	148	BINARY(4)	Interface source
332	14C	BINARY(4)	Duplicate address detection transmits
336	150	BINARY(4)	Multicast - number of references
340	154	CHAR(4)	Reserved
344	158	CHAR(8)	Change date
352	160	CHAR(6)	Change time
358	166	CHAR(2)	Reserved
360	168	BINARY(4)	Interface description CCSID
364	16C	BINARY(4)	MTU - configured
368	170	BINARY(4)	MTU - current
372	174	BINARY(4)	Duplicate address detection maximum transmits
376	178	CHAR(50)	Alias name
426	1AA	CHAR(6)	Reserved
432	1B0	BINARY(4)	Alias Name CCSID
436	1B4	BINARY(4)	On-link
440	1B8	BINARY(4)	Address class
444	1BC	BINARY(4)	Offset to preferred physical interface list
448	1C0	BINARY(4)	Number of entries in preferred physical interface list
452	1C4	BINARY(4)	Length of one preferred physical interface list entry
456	1C8	BINARY(8)	DHCP lease obtained
464	1D0	CHAR(8)	DHCP lease obtained - date
472	1D8	CHAR(6)	DHCP lease obtained - time
478	1DE	CHAR(30)	DHCP server unique identifier
508	1FC	BINARY(4)	DHCP server unique identifier length
512	200	CHAR(10)	Current proxy agent line
522	20A	CHAR (2)	Reserved
This field repeats for each preferred physical interface list entry		CHAR(*)	Preferred physical interface list entry (See Format of Preferred Physical Interface List Entry for more information.)

Format of Preferred Physical Interface List Entry

The preferred physical interface list entry describes the data returned for each entry in the preferred physical interface list of the NIFC0200 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. See the Address State field description for more information. 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 state. The current state of this IPv6 address. This field is no longer available and will always be set to 4.

Possible value is:

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. See the Address State field description for more information. 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.

Alias name CCSID. Coded character set ID for the alias name.

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

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.

Duplicate address detection transmits. Specifies the number of Duplicate Address Detection (DAD) transmissions the stack has sent out on this interface.

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

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 description CCSID. Coded character set ID for the interface description field.

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 interface list entry. The length of a preferred physical interface 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:

Multicast - number of references. The number of Sockets clients that have joined this multicast group.

The following is a special value:

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

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 interface list. The number of entries in the preferred physical interface list.

Offset to preferred physical interface list. The offset from the start of the user space to the beginning of the preferred physical interface 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 interface name. Name of a communications line description in the preferred physical interface list.

Reserved. An ignored field.

Error Messages

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