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.

TCP/IP must be active; otherwise error message TCP84C0 will be issued.

Authorities and Locks

User Space Library Authority

*EXECUTE

User Space Authority

*CHANGE

User Space Lock

*SHRNUP

Required Parameter Group

Qualified user space name

INPUT; CHAR(20)

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

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

Format name

INPUT; CHAR(8)

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

NIFC0100	Detailed information about each TCP/IPv4 network interface. Refer to NIFC0100 Format for details on the format.
NIFC0200	Detailed information about each TCP/IPv6 network interface. Refer to 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:
  • NIFC0100 format, or
  • NIFC0200 format

For details about the user area and generic header, see User Space Format for List APIs. 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 API Examples.

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

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:

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:

-1	OTHER - IPI - An Internet Protocol (IP) over Internetwork Pack Exchange (IPX) interface. IPS - An Internet Protocol (IP) over SNA interface. PPPoE - Point-to-Point over Ethernet protocol. Note: As of V5R2, IP over IPX is no longer supported.
-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 errrors 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.

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.

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

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.

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:

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

Field Descriptions

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. IPv6 addresses are in different states at different times, due to Duplicate Address Detection (DAD) and address lifetimes. Unicast and Multicast addresses have different possible states and the only state that applies to either type is Failed.

When a unicast address is one of the two "valid" states, Preferred and Deprecated, it may be used as the source or destination address of a packet. When a unicast address is in one of the five "invalid" states it may not be used as the source or destination address of a packet. The five "invalid" states are: Tentative, Expired, Inactive, Duplicate and Failed.

When a multicast address is one of the two "valid" states, Idle Listener and Delaying Listener, it may be used as the source or destination address of a packet. When a multicast address is in one of the two "invalid" states, Non-listener and Failed, it may not be used as the source or destination address of a packet.

Possible values are:

Note: As of V5R4, this field is no longer available and will always be set to 4.

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:

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:

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.

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.

Line name. Name of the communications line description that identifies the physical network associated with an interface. This field is NULL 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:

0	LIND - The interface is not active currently and the MTU was configured as *LIND.

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.

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

Reserved. An ignored field.

Error Messages