&SOCKET TRACEROUTE

Verbs and Built-in Functions › &SOCKET TRACEROUTE

&SOCKET TRACEROUTE

Obtains a list of routers along the route to the host.

&SOCKET TRACEROUTE
      { ADDRESS=ip_address | HOSTNAME=host_name }
      [ PACKETSIZE={ nn | 64 } ]
      [ COUNT={ nn | 3 } ]
      [ HOPS={ nn | 10 } ]
      [ FROMHOP={ nn | 1 } ]
      [ WAIT={ time | 3 } ]
      [ TYPE={ SYNC | ASYNC } ]
      [ GETNAME={ YES | NO } ]
        MDO=mdo_name

TRACEROUTE is used in the diagnosis of connectivity and performance related problems on a TCP/IP network. It is used to find breaks in the route from a host to a remote host, or to verify that a network path to a remote host exists, displaying times for hops along the path.

Operands:

ADDRESS=ip_address

Specifies the IP address of the destination host.

HOSTNAME=host_name

Specifies the name of the destination host.

PACKETSIZE={ nn | 64 }

Specifies the length of the packets to send to the host. This value must be in the range of 40 to 2048 bytes. The default value is 64.

COUNT={ nn | 3 }

Specifies the number of times to execute the trace. This value must be in the range of 1 to 10. The default value is 3.

HOPS={ nn | 10 }

Specifies the maximum number of devices to locate on the route to the host. This value must be in the range of 1 to 256. The default value is 10.

FROMHOP={ nn | 1 }

Specifies the number of hops to the first device for which data is to be returned. This value must be in the range of 1 to 256. The default value is 1.

WAIT={ time | 3 }

Specifies the time in seconds to wait for a response from any one host on the route to the destination host. The default value is 3 seconds.

TYPE={ SYNC | ASYNC }

Indicates whether this is a synchronous (SYNC) or asynchronous (ASYNC) socket request.

If TYPE=ASYNC is specified, WAIT cannot be specified.

If TYPE=ASYNC is specified, the verb returns control immediately, and a notification message is queued to the dependent environment when each hop of the TRACEROUTE completes:

N00101 NOTIFY: TCP/IP EVENT: TRACEROUTE RESOURCE: RC=rc RSN=rsn ERR=errno VERRIN=vendor_info RESULT=**result_type** **addr/name**

where:

**result_type** is PARTIAL (intermediate result) or FINAL (final result).
**addr/name** is set to the destination specified on the TRACEROUTE request (that is, either ADDRESS=ip_address or HOSTNAME=host_name).

The return MDO is available in $INT.USERMDO after &INTREAD receives the message.

GETNAME={ YES | NO }

If the default value YES is used, the names of the hosts on the route to the destination are resolved.

MDO=mdo_name

Specifies the name of the MDO that contains the response from the traceroute. This MDO is mapped by the $NMTCPTC map.

Examples: & SOCKET TRACEROUTE

& SOCKET TRACEROUTE HOSTNAME=TESTMVS1 MDO=MDO1 HOPS=15 WAIT=5

Return Codes:

0: Traceroute successful.
4: HOPS parameter is too low.
8: Traceroute failed; see &ZFDBK for reason code, &ZSOCERRN and &ZSOCVERR for further error information.

Notes:

The information returned is set into the following NCL variables:

&ZSOCHNM contains the host name.
&ZSOCFHNM contains the full name of the host.
&ZSOCHADR contains the IP address of the host.

Some interfaces may not support TRACEROUTE. In this case, &ZFDBK is set to 37 and &ZSOCERRN to 7 (EUNSUPP). The &ZTCPSUPP function is used to test whether TRACEROUTE is supported.