| Where allowed to run: All environments (*ALL) Threadsafe: No |
Parameters Examples Error messages |
The Trace TCP/IP Route (TRCTCPRTE) command, also known as TRACEROUTE, traces the route of IP packets to a user-specified destination system. The route can involve many different systems along the way. Each system along the route is referred to as a hop. You can trace all hops along the route or specify the starting and ending hops to be traced.
The route is traced by sending packets (called probes) to the destination system. Each probe contains an upper limit (called Time To Live or TTL) on the number of hop systems the probe can pass through.
Note: In IP Version 6, Time To Live (TTL) is called the hop limit.
A route is traced by successively incrementing the TTL of the probe packets by one hop. The trace ends when either a probe response is received from the destination system or when the probe Time To Live value equals the maximum allowed.
Responses from the probe packets are sent as messages to the job log or as queue entries to a user-specified data queue.
| Top |
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| RMTSYS | Remote system | Character value | Required, Positional 1 |
| RANGE | Range of hops to probe | Element list | Optional |
| Element 1: Starting probe TTL (hop limit) | 1-255, 1 | ||
| Element 2: Maximum probe TTL (hop limit) | 1-255, 30 | ||
| PROBES | Probes sent per hop | 1-64, 3 | Optional |
| WAITTIME | Response wait time | 1-120, 3 | Optional |
| PKTLEN | Packet length (in bytes) | 40-65535, 40 | Optional |
| OUTPUT | Output | *MSG, *VERBOSE, *DTAQ | Optional |
| DTAQ | Data queue | Qualified object name | Optional |
| Qualifier 1: Data queue | Name | ||
| Qualifier 2: Library | Name, *CURLIB, *LIBL | ||
| ADRVERFMT | Address version format | *CALC, *IP4, *IP6 | Optional |
| LCLINTNETA | Source IP address | Character value, *ANY | Optional |
| RMTPORT | Base remote port | 1-65535, 33434 | Optional |
| NAMELOOKUP | Lookup host names | *YES, *NO | Optional |
| PROBEPCL | Probing protocol | *ICMP, *UDP | Optional |
| FRAGMENT | Allow fragmentation | *TCPA, *NO, *YES | Optional |
| Top |
Specifies the remote system name (255 characters) or IP address of the destination system.
| Top |
Specifies the range of hop systems from which probe responses are expected. Each probe specifies a TTL (Time To Live) integer value. This TTL value is the maximum number of hops the probe can traverse. For example, a probe packet with a TTL of 3 can pass through at most 3 hop systems before the hop system discards the probe and sends information back to the system from which the probe originated.
Element 1 specifies the first TTL value sent in probe packets. Element 2 specifies the last TTL value sent in probe packets. Trace information is generated from each hop system which discards a probe packet because the TTL value in the probe is reached or when the destination system is reached.
Element 1: Starting probe TTL (hop limit)
Element 2: Maximum probe TTL (hop limit)
| Top |
Specifies the number of probe packets sent to each hop system for each probe TTL (hop limit) value in the range specified by the RANGE parameter.
| Top |
Specifies the maximum time, in seconds, to wait for a response from a hop system to each probe.
| Top |
Specifies the total length, in bytes, of the IP packet sent for each probe.
| Top |
Specifies where the results obtained from sending the probe packets is sent. Information is sent for each hop until the destination system is reached, including hop count, average round-trip time, IP address of the hop and host name of the hop.
| Top |
Specifies the data queue on which entries are placed. When a data queue is specified, messages are not sent to the job log unless an error occurs.
Each queue entry contains the response to a probe if one was received or indicates that no probe response was received. The specified data queue must have a queue entry length of at least 32 characters and must exist when this command is issued.
Qualifier 1: Data queue
Qualifier 2: Library
| Top |
Specifies how the host name specified for the Remote system (RMTSYS) parameter is to be resolved.
| Top |
Specifies how the source IP address in the probe packet is chosen.
| Top |
Specifies the base UDP port number used in probes.
| Top |
Specifies whether IP addresses will be resolved to the host name.
| Top |
Specifies the protocol used when sending probe packets.
| Top |
Specifies how the setting of the "Do Not Fragment" option in the IP header of the probe packet is determined.
Note: Use the Change TCP/IP Attributes (CHGTCPA) command to change the value of this attribute.
| Top |
Example 1: Trace Entire Route
TRCTCPRTE RMTSYS('130.14.3.5')
This command traces the entire route between the local system and the destination system whose IP address is '130.14.3.5'. Three probe packets will be sent to each hop system. Each IP probe packet will be 40 bytes long and will contain an ICMP Echo Request packet. Results received are sent as messages to the job log.
Example 2: Trace Partial Route
TRCTCPRTE RMTSYS('AAA.BBBB.COM') RANGE(3 7)
PROBES(5) PROBEPCL(*UDP)
OUTPUT(*DTAQ) DTAQ(MYLIB/MYDATAQ)
This command traces the route between the local system and the destination system whose host name is 'AAA.BBBB.COM'. Five probe packets will be sent for the starting range value of 3. Each probe will be a UDP packet inside an IP packet that is 40 bytes long. Each of these 5 probes will specify a TTL of 3. If system AAA.BBB.COM can be reached by passing through at most 2 hop systems then the trace will terminate at this point.
If system AAA.BBB.COM is futher than 2 hops, another set of 5 probe packets will be sent to the destination AAA.BBB.COM. Each of these 5 probes will specify a TTL of 4. This is repeated until either system AAA.BBB.COM responds to a probe or 5 probes with a TTL of 7, the ending range value, are sent. Any results received are placed as queue entries on data queue MYDATAQ in library MYLIB.
Example 3: Trace Route with an IP Version 6 Address
TRCTCPRTE RMTSYS('1:2:3:4:5:6:7:8')
This command traces the entire route between the local system and the destination system whose IP address is 1:2:3:4:5:6:7:8. Three probe packets will be sent to each hop system. Each IP probe packet will be 40 bytes long and will contain an ICMP6 Echo Request packet. Results received are sent as messages to the job log.
Note: A colon character ( : ) found in the parameter value signifies an IP Version 6 address and will cause an ICMP6 echo request packet to be generated.
Example 4: Trace Route with an IP Version 6 Host Name
TRCTCPRTE RMTSYS('IP6HOST')
This command traces the entire route between the local system and the destination system whose host name is 'IP6HOST'. Three probe packets will be sent to each hop system. Each IP probe packet will be 40 bytes long and will contain an ICMP6 Echo Request packet. Results received are sent as messages to the job log.
The default "Address version format" is *CALC. Host name resolution may return multiple IP addresses for a given host name. But, in the case (*CALC), the first IP address (IP Version 4 or IP Version 6) resolved will be the address used when attempting to trace the route.
Example 5: Trace Route with an IP Version 6 Host Name and Explicitly Use IP Version 6 Host Name Resolution
TRCTCPRTE RMTSYS('IP6HOST') ADRVERFMT(*IP6)
This command traces the entire route between the local system and the destination system whose host name is 'IP6HOST'. Three probe packets will be sent to each hop system. Each IP probe packet will be 40 bytes long and will contain an ICMP6 Echo Request packet. Results received are sent as messages to the job log.
This example differs from example 4 in that only a valid IP version 6 resolved address, for IP6HOST, will be used when attempting to trace the route.
| Top |
*ESCAPE Messages
| Top |