List Network Routes (QtocLstNetRte) API

  Required Parameter Group:


  Service Program: QTOCNETSTS

  Threadsafe: Yes

The List Network Routes (QtocLstNetRte) API returns a detailed list of all routes. This API returns all IPv4 routes using one output format name, and all IPv6 routes 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 10 characters contain the user space name, and the second 10 characters contain the name of the library where the user space is located.  You can use these special values for the library name:


Format name
INPUT; CHAR(8)

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


Error code
I/O; CHAR(*)

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


Format of Route Lists

To request a list of all routes, use format NRTE0100.

The route description list consists of:

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 routes, request format NRTE0100, and you will get a repeating list of NRTE0100 tables, each one returning information about a single IPv4 route. To retrieve the list of TCP/IPv6 routes, request format NRTE0200, and you will get a repeating list of NRTE0200 tables, each one returning information about a single IPv6 route.


NRTE0100 Format

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



Field Descriptions

Change date.The date of the most recent change to this route in the dynamic tables used by the TCP/IP protocol stack. It is returned as 8 characters in the form YYYYMMDD, where:

Change time.The time of the most recent change to this route in the dynamic tables used by the TCP/IP protocol stack. It is returned as 6 characters in the form HHMMSS, where:

Local binding interface. The IP interface to bind to this route.

Local binding interface binary. Binary representation of the local binding interface.

Local binding interface status. The current status of this logical interface.

The possible values are:

Local binding line description. Each TCP/IP interface is associated with a network. This field displays the name of the communications line description or virtual line (L2TP) that identifies the network associated with an interface. The following are special values:

Local binding line type. Indicates the type of line used by an interface.  The following link protocols are supported:

Local binding network address. The Internet address, in dotted decimal notation, of the IP network or subnetwork that the interface is attached to.

Local binding network address binary. Binary representation of the local binding network address.

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

Local binding subnet mask binary. Binary representation of the local binding subnet mask.

Local binding type. The possible values are:

Start of change Local binding virtual LAN identifier. Indicates the virtual LAN to which this route is bound.

The following are possible returned values:

Next hop. The Internet address of the first system on the path from your system to the route destination in dotted decimal notation. The following are special values:

*DIRECT

This is the next hop value of a route that is automatically created. When an interface is added to this system, a route to the network the interface attaches to is also created.

Next hop binary. The binary represenation of the next hop. For *DIRECT this will be the local binding network address.

Reserved. An ignored field.

Route destination. The Internet Protocol (IP) address, in dotted decimal notation, of the ultimate destination reached by this route. When used in combination with the subnet mask and the type of service values, the route destination identifies a route to a network or system.

Route destination binary. The binary representation of the route destination.

Route MTU. A number representing the maximum transmission unit (MTU) value for this route in bytes. The following are special values:

Route precedence. Identify priority of route, range 1-10. Lowest priority being 1.

Route source. Specifies how this route was added to the IP routing tables.  The possible values are:

Route status. Indicated whether this route is available.

Route type. The route types are:

Subnet mask. The actual value of the subnet mask in dotted decimal notation.

Subnet mask binary. The binary representation of the subnet mask.

Text description. User added text description associated with the route.

Type of service. Defines how the Internet hosts and routers should make trade-offs between throughput, delay, reliability and cost. The following are special values:



NRTE0200 Format

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



Field Descriptions

Actual route MTU. A number representing the maximum transmission unit (MTU) value for this route in bytes.

The following is a special value:

Change date. The date of the most recent change to this route 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 route in the dynamic tables used by the TCP/IPv6 protocol stack. It is returned as 6 characters in the form HHMMSS, where:

Configured route MTU. A number representing the configured maximum transmission unit (MTU) value for this route in bytes.

The following is a special value:

Duplicate indicator. Indicates whether this route is a duplicate of another route in the routing table or not, and also whether there are any routes which are duplicates of this route. Use the Route status field to determine whether the route is in use or not.

Possible values are:

Expiration date. The date when this route will expire or did expire. If the Expiration date and time are in the future, the route has not expired yet. If the Expiration date and time are in the past, then this route has expired and is still being returned for a short period of time to indicate that the route ceased to function because its lifetime expired. The Expiration date is returned as 8 characters in the form YYYYMMDD.

The meaning of the characters is as follows:

The following is a special value:

Expiration time. The time when this route will expire or has expired. If the Expiration date and time are in the future, the route has not expired yet. If the Expiration date and time are in the past, then this route has expired and is still being returned for a short period of time to indicate that the route ceased to function because its lifetime expired. The Expiration time is returned as 6 characters in the form HHMMSS.

The meaning of the characters is as follows:

The following is a special value:

Is on-link. Indicates whether this route is for a directly attached prefix (network) or not.

Possible values are:

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

Local binding line name. The name of the communications line description to which this route is bound. This field is NULL padded.

The following are special values:

Local binding line status. The current operational status of the communications line to which this route is bound.

Possible values are:

Local binding line type. Indicates the type of line to which this route is bound.

Possible values are:

Start of change Local binding virtual LAN identifier. Indicates the virtual LAN to which this route is bound.

The following are possible returned values:

Next hop address family. The address family of the Next Hop address for this route. Use this field to determine whether the IPv4 or IPv6 Next Hop field contains the value of the next hop.

Possible values are:

Note: As of V5R4, AF_INET is no longer supported for next hop address family.

Next hop IPv4. The IPv4 Internet address of the first system on the path from this system to the route destination in dotted-decimal format. The next hop will only be an IPv4 address when the route uses an IPv6 over IPv4 tunnel. This field is only valid when the value of the Next hop address family field is AF_INET. This field is NULL padded

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

Next hop IPv4 binary. The binary representation of the Next hop IPv4 field. This field is only valid when the value of the Next hop address family field is AF_INET.

Note: As of V5R4, AF_INET is no longer supported for a next hop address family. As a result, the value in this field is no longer valid.

Next hop IPv6. The IPv6 Internet address of the first system on the path from your system to the route destination in IPv6 address format. This field is only valid when the value of the Next hop address family field is AF_INET6. This field is NULL padded.

The following special value may be returned:

Next hop IPv6 binary. The binary representation of the Next hop IPv6 field. Even though this field is defined as a character field, a binary IPv6 address is returned in it except when the following special character values are returned. This field is only valid when the value of the Next hop address family field is AF_INET6.

The following special value may be returned:

PPP authentication user id The Point-to-Point Protocol (PPP) authentication user id associated with this route.

PPP configuration profile The name of the Point-to-Point Protocol configuration profile associated with this route.

PPP dial-on-demand profile The name of the Dial-on-demand Remote Peer Enabled Point-to-Point profile associated with this route.

PPP internet IPv6 address The Internet address, in IPv6 address format, to which this Point-to-Point route is bound.

Prefix length. The prefix length defines how many bits of the route destination 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.

Prefix length binary. Binary representation of the prefix length.

Reserved. An ignored field.

Route destination. The Internet Protocol version 6 (IPv6) address, in IPv6 address format, of the ultimate destination reached by this route. When used in combination with the prefix length the route destination identifies a route to a network or system. This field is NULL padded.

Route destination binary. The binary representation of the route destination. Even though this field is defined as a character field, a binary IPv6 address is returned in it.

Route lifetime at creation. The route lifetime value which this route had when it was first created, either automatically or by manual configuration. The route lifetime value is the length of time, in seconds, that a route remains in the route table. Only routes which are discovered on the network will have route lifetimes shorter than infinite. Valid values range from 1 through 4294967295 seconds.

The following is a special value:

Note: As of V5R4, the route lifetime at creation field is always set to infinite.

Route lifetime remaining. The length of time, in seconds, that a route remains in the route table. Only routes which are discovered on the network will have route lifetimes shorter than infinite. Valid values range from -31536000 through 4294967295 seconds. Negative values indicate that the route has expired, but it is being retained for a short period of time to show why the route ceased to function.

The following is a special value:

Note: As of V5R4, the route lifetime remaining field is always set to infinite.

Route preference. Specifies the preference of this route during route selection.

The possible values are:

Route protocol. Specifies the protocol that was used to generate this route.

The possible values are:

Route source. Specifies how this route was added to the IPv6 routing table.

The possible values are:

Route status. The current state of the route.

Possible values are:

Route type. The type of route that this route is.

Possible values are:

Text description. User added text description associated with the route.

Text description CCSID. Coded character set ID for the text description.


Error Messages


API introduced: V5R1