DISPLAY EEDIAG command

Abbreviations

When using an abbreviation in place of an operand, code the abbreviation exactly as shown in the table. For example, when coding the abbreviation for LIST=DETAIL, code only DETAIL or DET. Do not code LIST=DET.

Purpose

The DISPLAY EEDIAG command can be used to display diagnostic information about one or more EE connections.

The REXMIT format lists Enterprise Extender connections whose retransmission rate, calculated at each port priority, meet, or exceed a specified threshold. The SRQRETRY format lists Enterprise Extender connections that are experiencing LDLC signal retries that meet or exceed a specified threshold. A CLEAR function enables the diagnostic counters used by these commands to be cleared for the next measurement interval. You can specify the CLEAR operand by itself or with either the REXMIT or the SRQRETRY operands. When specified with the REXMIT or SRQRETRY operands, the diagnostic counters are cleared after the display output for the current command is complete.

The Enterprise Extender connectivity test command is useful for debugging various network problems. Use this command to test an existing Enterprise Extender connection, or use it to assist in diagnosing the reason an EE connection cannot be established. Because this is a potentially long-running command, the number of outstanding EE connectivity tests is limited by the value of the MAXEETST start option. See z/OS Communications Server: SNA Resource Definition Reference for details.

An EE connectivity test that specifies LIST=DETAIL verifies that an EE line is available, that address resolution is possible, and that a partner can be reached. To verify that a partner can be reached, LDLC probe commands with varying TTL (time-to-live) or hop count values are sent to the EE partner host. The first LDLC probe request contains the TTL value 1 and is sent to the EE partner node. The command then waits up to 3 seconds for a response to this probe. The expected response is the ICMP message "Time Exceeded" (which indicates that the TTL value has been exceeded), or an LDLC probe response from the partner node. If no response is received, then the LDLC probe request is transmitted up to two additional times, using the same TTL value and wait time. If still no response is received, the TTL value is incremented by 1 and the process is repeated. If no responses to any of the LDLC probe requests are received, then command processing stops when the MAXTIME value is exceeded. When an ICMP "Time Exceeded" message is received in response to the LDLC probe requests, the IP address of the node sending the ICMP message and the round-trip time to that node are recorded. Typically, processing continues until an unexpected ICMP message is received, an LDLC probe response is received from the partner node, or when the MAXTIME value is exceeded. The output generated by this request shows whether the remote EE endpoint can be reached over each of the five UDP ports that are reserved for EE. When multipath support or policy-based routing is being used, all available routes calculated by the local TCP/IP stack to the remote EE endpoint are tested.

An EE connectivity test that specifies LIST=SUMMARY provides the remote partner reachability information quickly. VTAM® sets the TTL count to 255 and sends an LDLC probe to the remote partner, using all five ports. Use this command to quickly determines whether the remote partner is reachable on all five ports. Because VTAM sets the TTL count to 255, the hop count is not determined for LIST=SUMMARY output; however, LIST=DETAIL output includes the hop count. When multipath support or policy-based routing is being used, all available routes calculated by the local TCP/IP stack to the remote EE endpoint are tested.

The TEST=PENDING format lists outstanding Enterprise Extender displays that are pending host name resolution or EE connectivity test results. This might be useful because both host name resolution and the EE connectivity test are potentially long-running functions.

This EEDIAG command format enables you to query the outstanding displays to obtain the status. Each pending display has a unique correlator assigned to it that you can be use to identify each outstanding display request. You can use filters on the DISPLAY EEDIAG command to limit the EE diagnostic scan to a subset of the overall EE connections.

Operands

CLEAR

Specifies which diagnostic counters are to be cleared.

CLEAR=ALL

Clears both REXMIT and SRQRETRY diagnostic counters.

CLEAR=REXMIT

Clears only the REXMIT diagnostic counters.

CLEAR=SRQRETRY

Clears only the SRQRETRY diagnostic counters.

Rule: The REXMIT and SRQRETRY operands limit the scope of the display output, but only the command filters (for example, ID, IPADDR, HOSTNAME) limit the scope of the CLEAR operand. If the command filters are not included on the D EEDIAG command, all EE connections are affected by the scope of this command. Otherwise, the scope of the D EEDIAG command is limited to the EE connections that match the values of the filters. For example, a local IP address (IPADDR) that is used by 500 EE connections can be specified on the command. The CLEAR=ALL option clears both the REXMIT and SRQRETRY counters for all 500 EE connections. However, only one of these EE connections might be experiencing retransmission problems. In this case, message IST2042I lists only one connection.

HOSTNAME

Filter used to limit the scope of the diagnostic scan or connectivity test to Enterprise Extender connections that are specified by the local host name, the remote host name, or both. The local and remote host name filters you specify on this command should be fully qualified TCP/IP domain names, up to 64 characters long.

The Enterprise Extender definitions for your network do not necessarily have to use a HOSTNAME scheme for the DISPLAY EEDIAG command to use host names. VTAM must be able to perform TCP/IP name-to-address resolution, either by connectivity to a DNS name server, or by using a local host file such as HOSTS.SITEINFO or /etc/ipnodes. For more information, see z/OS Communications Server: IP Configuration Guide. If the TCP/IP name-to-address resolution fails for either the local or remote host name, the DISPLAY EEDIAG command will also fail as a result.

The local_hostname value is used to acquire the static VIPA addresses that other Enterprise Extender nodes use in order to communicate with this host using Enterprise Extender. The remote_hostname value is used to acquire the IP address used by the TCP/IP stack on the remote end of the Enterprise Extender connection. Furthermore, if the remote_hostname value represents a z/OS® Communications Server APPN node, the address returned must be a static VIPA address.

Guideline: Ensure that each host name resolves to a unique IP address. When VTAM performs the TCP/IP name-to-address resolution, and the host name resolves to multiple IP address, the first address returned by the resolver is the address used by VTAM.

Restrictions:

• The number of outstanding DISPLAY EE and DISPLAY EEDIAG commands that require host name resolution are limited by the value of the MAXHNRES start option. See z/OS Communications Server: SNA Resource Definition Reference for details. When the MAXHNRES start option value is exceeded, the DISPLAY EE or DISPLAY EEDIAG command fails with message IST2122I.
• VTAM commands that exceed 130 characters in length are subject to being truncated. In particular, the D NET, EEDIAG command allows up to two host name filters as input, each of which can be up to 64 characters in length. However, if the command exceeds 130 characters, the command is truncated and error messages can be issued. To avoid this limitation, perform one of the following actions:
  • Use command abbreviations whenever possible.
  • Define shorter host names to be used as input to the D NET,EEDIAG command.
  • Instead of using host name filters on the D NET, EEDIAG command, use either the ID or IPADDR filters.

Result: When an IP address is passed as input on the HOSTNAME operand, the IP address is simply passed back as output from the resolver. Instead of failing the display command with a host name that is not valid, the IP address is used to process the display command.

Tip: To query outstanding DISPLAY EEDIAG commands that are pending host name resolution, issue the DISPLAY NET,EEDIAG,TEST=PENDING command.

Rule: The remote_hostname value is not always available for use by this command. The remote_hostname value is available for use only by a host when it initiates the connection (dial-out) to the remote EE partner. For a predefined EE connection (non-connection network), which is the dial-in side of the connection, the remote_hostname value is not available for use by this command. For a virtual routing node (VRN) EE connection which is the dial-in side of the connection, the remote_hostname value is available for use after a dial-out is attempted to the remote EE partner. A new session request, initiated from that EE endpoint, must cause the dial to occur to the partner EE endpoint. At that time, the remote_hostname value is resolved, the existing EE connection is found and is used for the session, and the remote host name becomes available for use by this display command.

HOSTNAME=local_hostname

Limits the scope of the diagnostic scan or connectivity test to Enterprise Extender connections that have a local host name that matches the local_hostname parameter value.

Tip: Code either a remote host name (HOSTNAME) or remote IP address (IPADDR) to further refine the scope of the DISPLAY EEDIAG command.

HOSTNAME=(,remote_hostname)

Limits the scope of the diagnostic scan or connectivity test to Enterprise Extender connections that have a remote host name that matches the remote_hostname value.

Tip: Code either a local host name (HOSTNAME) or local IP address (IPADDR) to further refine the scope of the DISPLAY EEDIAG command.

HOSTNAME=(local_hostname,remote_hostname)

Limits the scope of the diagnostic scan or connectivity test to Enterprise Extender connections that have a local host name that matches the local_hostname value and a remote host name that matches the remote_hostname value.

ID=name

Filter used to limit the scope of the diagnostic scan or connectivity test to a single Enterprise Extender connection that is specified by LINE or switched PU name.

Restrictions:

• When issuing a DISPLAY NET,EEDIAG,TEST=YES command on an active EE connection, you can specify the name of the active line or switched PU that is being used for the EE connection.
• If the EE connection is inactive, and you want to use the ID filter to identify the EE connection, you must specify the name of the predefined switched PU name. You must provide a GRPNM value for the predefined switched PU, and either the IPADDR or HOSTNAME operands specified on the associated PATH statement. The GRPNM value must define an active group name within the Enterprise Extender XCA major node. The local IP address or host name used for the connectivity test is obtained from the defined group within the EE XCA major node. The remote IP address or host name used for the connectivity test is taken directly from the PATH definition statement. The ID filter cannot accept a line name when the EE connection is inactive, because it does not uniquely identify the EE endpoints to test.
• Alternatively, you can uniquely identify the EE connection to test by specifying any combination of the IPADDR and HOSTNAME filters that provides both a local and remote input.

IPADDR

Filter used to limit the scope of the diagnostic scan or connectivity test to Enterprise Extender connections specified by the local IP address, remote IP address, or both. The IP address accepts a fully qualified dotted decimal value for IPv4-type addresses, or colon-hexadecimal format for IPv6-type addresses.

IPADDR=local_ipaddr

Limits the scope of the diagnostic scan or connectivity test to Enterprise Extender connections that have a local IP address that matches the local_ipaddr value.

Note: Code either a remote IP address (IPADDR) or remote host name (HOSTNAME) to further refine the scope of the DISPLAY EEDIAG command.

IPADDR=(,remote_ipaddr)

Limits the scope of the diagnostic scan or connectivity test to Enterprise Extender connections which have a remote IP address that matches the remote_ipaddr value.

Tip: Code either a local IP address (IPADDR) or a local host name (HOSTNAME) to further refine the scope of the DISPLAY EEDIAG command.

IPADDR=(local_ipaddr,remote_ipaddr)

Limits the scope of the diagnostic scan or connectivity test to Enterprise Extender connections that have a local IP address that matches the local_ipaddr value and a remote IP address that matches the remote_ipaddr value.

LIST

Specifies the amount of detail the output contains. If you specify the LIST operand without specifying a value, the default of LIST=SUMMARY is assumed.

LIST=DETAIL

When LIST=DETAIL is specified on the DISPLAY NET,EEDIAG,REXMIT command, for connections meeting or exceeding the specified retransmission rate, the output contains Enterprise Extender retransmission rates displayed at the port priority level.

When LIST=DETAIL is specified on the DISPLAY NET,EEDIAG,SRQRETRY command, for connections meeting or exceeding the specified threshold, the output lists each SRQRETRY attempt and the count of LDLC signals that received responses on each attempt to try again. For example, if an LDLC signal requires three retries before receiving a response, the display indicates one occurrence for the third SRQRETRY attempt.

When LIST=DETAIL is specified on the DISPLAY NET,EEDIAG,TEST=YES command, the output lists each hop that was tested during the EE connectivity test.

LIST=SUMMARY

When LIST=SUMMARY is specified on the DISPLAY NET,EEDIAG,REXMIT command, for connections meeting or exceeding the specified retransmission rate, the output contains an Enterprise Extender retransmission rate composed of the average of all port priorities.

When LIST=SUMMARY is specified on the DISPLAY NET,EEDIAG,SRQRETRY command, for connections meeting or exceeding the specified threshold, the output lists only SRQRETRY attempts (and the count of LDLC signals that received responses on this attempt to try again) that meet or exceed the specified threshold. That is, LIST=SUMMARY lists only SRQRETRY attempts that meet or exceed the specified threshold, while LIST=DETAIL lists all SRQRETRY attempts.

Rule: If you specify REXMIT=xx with the LIST=SUMMARY option, the display provides an overall retransmission rate for all port priorities. It is possible that the retransmission rate displayed in message IST2068I, which is associated with all port priorities, is smaller than the rate specified by REXMIT=xx. This means that at least one of the EE port priorities for this EE connection is experiencing a retransmission rate that meets or exceeds the specified rate. In this case, the LIST=SUMMARY option displays the message groups for the specific port priorities that meet or exceed the specified rate, along with the summary of all port priorities.

When LIST=SUMMARY is specified on the DISPLAY NET, EEDIAG,TEST=YES command, the output lists the remote partner reachability information quickly.

MAX

Specifies the maximum number of Enterprise Extender connections that VTAM displays for this command.

The REXMIT and SRQRETRY command can be in one of the following formats:

MAX=*

Specifies that the value of the DSPLYMAX start option is used to limit the display output.

MAX=number_of_EE_connections

Specifies the number of Enterprise Extender connections that VTAM displays for this command. Valid values for this keyword are in the range 1 - DSPLYMAX start option value. The default is 20, or the value specified for the DSPLYDEF start option, whichever is less.

Result: Specifying the MAX operand limits the display output. If fewer Enterprise Extender connections are found than you have specified on the MAX operand, VTAM displays only the Enterprise Extender connections that are found.

Rule: If you specify the CLEAR operand and the display output is truncated as a result of the MAX operand value, processing continues to clear the diagnostic counters for all EE connections affected by the scope of the command.

The TEST=PENDING command can be in the following format:

MAX=number_of_pending_EE_display_commands

Specifies the maximum number of pending Enterprise Extender diagnostic commands that VTAM displays for the TEST=PENDING command. Valid values for this keyword are in the range 1 - DSPLYMAX start option value. The default is 20 or the value specified for the DSPLYDEF start option, whichever is less.

Result: Specifying the MAX operand limits the display output. If fewer pending Enterprise Extender displays are found than you have specified on the MAX operand, VTAM displays only the pending Enterprise Extender displays that are found.

Tip: If the default value of 20 is not optimal for your environment, this value can be modified by altering the IBM-supplied USS table, ISTINCNO. See Unformatted system services command syntax for details.

MAXROUTE

Specifies the maximum number of valid TCP/IP routes that can be tested between two Enterprise Extender (EE) endpoints. Multiple routes might exist when multipath support or policy-based routing is being used in the route calculations between the EE endpoints.

MAXROUTE=*

Specifies that all valid TCP/IP routes between two Enterprise Extender endpoints are to be tested.

MAXROUTE=number_of_EE_routes

Specifies the maximum number of valid TCP/IP routes between two Enterprise Extender endpoints to test. The valid values are in the range 1 - 99. The default is 16 routes.

Result: If the maximum number of routes that are found exceeds this value, then the additional routes are not tested.

Tip: Typically, 16 routes are sufficient to fully test connectivity between two Enterprise Extender endpoints. If message IST2139I indicates that all routes are not being tested, use this operand to increase the number of routes to be tested.

MAXTIME=maxtime

The maxtime value specifies the overall time in seconds that VTAM will spend performing the EE connectivity test. This time does not include the time necessary to resolve host name filters; this is already a timed function within the TCP/IP stack. See z/OS Communications Server: IP Configuration Reference.

Valid range: 30-600. The default is 60 seconds.

Result: If the maximum time is exceeded before the connectivity test is complete, connectivity testing is stopped and the available information is displayed.

Tip: If the default value of 60 seconds is not optimal for your environment, this value can be modified by altering the IBM®-supplied USS table, ISTINCNO. See Unformatted system services command syntax for details.

REXMIT=retransmission_rate_percentage

The retransmission_rate_percentage value specifies that only EE connections that have a retransmission rate equal to or exceeding the specified percentage should be displayed. The REXMIT counters are maintained from the time the EE connection was activated, or since the last DISPLAY EEDIAG command that cleared the REXMIT counters for this EE connection was issued.

The valid range is 0-100. The retransmission_rate_percentage value can be specified up to two decimal points (for example, 0.22, 1.3, 14.5, 2.69).

Result: When a value of 0 is specified for the REXMIT operand, all EE connections associated with the command filters, up to a maximum limited by the MAX operand, are displayed.

Rule: The REXMIT and SRQRETRY operands limit the scope of the display output, but only the command filters (for example ID, IPADDR, and HOSTNAME) limit the scope of the CLEAR operand. If the command filters are not included on the DISPLAY EEDIAG command, all EE connections are affected by the scope of this command. Otherwise, the scope of the DISPLAY EEDIAG command is limited to the EE connections that match the values of the filters. For example, a local IP address (IPADDR) that is used by 500 EE connections can be specified on the command. The CLEAR=REXMIT option clears the REXMIT counters for all 500 EE connections. However, only one of these EE connections might be experiencing retransmission problems. In this case, message IST2042I lists only one connection.

See z/OS Communications Server: SNA Diagnosis Vol 1, Techniques and Procedures for more information related to the DISPLAY EEDIAG command.

SRQRETRY

Specifies that only EE connections that have had an LDLC signal retransmitted a specified number of times or more before receiving a response should be displayed.

SRQRETRY=*

Specifies that the value of the SRQRETRY operand associated with the PORT keyword of the Enterprise Extender XCA major node is to be used. Only EE connections that have had an LDLC signal retransmitted the maximum number of times before receiving a response should be displayed.

SRQRETRY=retries

The retries value specifies that only EE connections with LDLC signal retries equal to or exceeding retries before receiving a response should be displayed.

Entering D NET,EEDIAG,SRQRETRY=retries specifies that only EE connections with LDLC signal retries equal to or exceeding retries before receiving a response should be displayed. The SRQRETRY counters are maintained from the time the EE connection was activated, or since the last DISPLAY EEDIAG command was issued which cleared the SRQRETRY counters for this EE connection.

Valid range: 0-value of the SRQRETRY operand

The upper limit of the range is the value of the SRQRETRY keyword that is associated with the Enterprise Extender XCA major node PORT definition statement. The SRQRETRY operand has a maximum value of 9.

Result: When a value of 0 is specified for the SRQRETRY operand, all EE connections associated with the command filters, up to a maximum limited by the MAX operand, are displayed.

Rule: The REXMIT and SRQRETRY operands limit the scope of the display output, but only the command filters (for example ID, IPADDR, and HOSTNAME) limit the scope of the CLEAR operand. If the command filters are not included on the DISPLAY EEDIAG command, all EE connections are affected by the scope of this command. Otherwise, the scope of the DISPLAY EEDIAG command is limited to the EE connections that match the values of the filters. For example, a local IP address (IPADDR) that is used by 500 EE connections can be specified on the command. The CLEAR=SRQRETRY option clears the SRQRETRY counters for all 500 EE connections. However, only one of these EE connections might be experiencing retransmission problems. In this case, message IST2042I lists only one connection.

See z/OS Communications Server: SNA Diagnosis Vol 1, Techniques and Procedures for more information related to the DISPLAY EEDIAG command.

Rules:

• The REXMIT, SRQRETRY, and TEST operands are mutually exclusive.
• Do not specify values for both remote_hostname and remote_ipaddr.
• Do not specify values for both local_hostname and local_ipaddr.
• You must specify at least one local or one remote input when issuing the D NET,EEDIAG command with the IPADDR operand, the HOSTNAME operand, or both. A local input is either local_ipaddr or local_hostname. A remote input is either remote_ipaddr or remote_hostname. More specifically, when issuing the DISPLAY NET,EEDIAG,TEST=YES command, you must specify command filters that uniquely defines an EE connection. This includes specifying the ID operand, or any combination of the IPADDR and HOSTNAME operands that define both a local and remote input.
• VTAM permits only one EE connectivity test to a specific EE endpoint at a time. If another DISPLAY EEDIAG,TEST=YES command is issued to the same EE endpoint, before the previous Enterprise Extender connectivity test completes, VTAM rejects the most recent display command with the IST2142I message group.

TEST

Specifies whether you want to query the status of outstanding EE display commands, or you want to initiate an EE connectivity test.

TEST=PENDING

Use the DISPLAY NET,EEDIAG,TEST=PENDING command to query the status of the Enterprise Extender display commands that are waiting for host name resolution or EE connectivity test results.

TEST=YES

The DISPLAY NET,EEDIAG,TEST=YES command, or Enterprise Extender (EE) connectivity test, is useful for debugging various network problems. Use this command to test an active Enterprise Extender connection, or to assist in diagnosing the reason an EE connection cannot be activated. This command is similar in operation to the TRACERTE command, except that it uses UDP flows to test connectivity to the EE partner. As with the TRACERTE command, there might be environmental restrictions that limit the information that this command provides.

This command verifies that an EE line is available, that address resolution is possible, and that the partner can be reached. This command verifies the routes from this EE endpoint to a remote EE destination on all defined EE ports. When multipath support or policy-based routing is being used, all available routes calculated by the local TCP/IP stack to the remote EE endpoint are tested.

Restrictions:

• If TCP/IP intrusion detection support (IDS) is enabled and has active policies configured such that ICMP packets are considered to be a restricted protocol, IDS will discard the ICMP messages. This will adversely affect the operation of the EE connectivity test, limiting the diagnostic information.
• Because this is a potentially long-running command, the number of outstanding DISPLAY EEDIAG,TEST=YES commands is limited by the value of the MAXEETST start option. See z/OS Communications Server: SNA Resource Definition Reference for details. When the MAXEETST start option value is exceeded, the DISPLAY EEDIAG,TEST=YES command fails with message IST2144I.
• In order to use the EE connectivity test command, at least one EE line associated with each local static VIPA address (IPADDR) that you want to test must be active and available for use. If an existing EE connection is detected during the connectivity test, the connectivity test requires an available line to test the connection. Having an available line enables the EE connectivity test to run concurrently with the existing EE connection.
• The EEDIAG command filters specified on the EE connectivity test must uniquely identify the EE endpoints you want to test. This can be accomplished by specifying the ID filter, or any combination of the IPADDR and HOSTNAME filters that provides both a local and remote input.
• Enterprise Extender connections that route through firewalls might have limited diagnostic output. The EE connectivity test sends diagnostic probe commands to each hop in the EE route. For the EE connectivity test to function correctly, the ICMP messages that are sent in response must be returned. If firewalls are configured such that ICMP messages are blocked, the output will look as though each hop past the firewall is nonresponsive to the test probe. In some cases, the EE connectivity test will time out because the maximum time allowed for the test to be performed (MAXTIME) has been exceeded. In other cases, if the test probe reaches the EE partner and the partner supports the EE connectivity test, the diagnostic output will validate partner reachability and should provide a count of the number of hops to the partner node. For the EE connectivity test to yield usable results when firewalls are being employed, the firewalls must at least be configured to allow ICMP "Time Exceeded" error messages to be returned. The ICMP "Time Exceeded" error types follow:

  IPv4 protocol: ICMP Message Type 11 - "Time Exceeded"
  IPv6 protocol: ICMPv6 Message Type 3 - "Time Exceeded"

Firewalls permit ICMP message filtering based on the message type. This gives you the flexibility to open the firewalls for specific ICMP messages in order to have the EE connectivity test function at a base level. If you let all ICMP messages pass through your firewalls, the EE connectivity test might be able to provide more diagnostic information. For the EE connectivity test to provide you with more diagnostic information, open your firewalls so the following ICMP messages can be returned:

IPv4 protocol: Type 3 - "Destination Unreachable"
               Type 4 - " Source Quench"
               Type 11 - " Time Exceeded"
               Type 12 - " Parameter Problem"

IPv6 protocol: Type 1 - "Destination Unreachable"
               Type 2 - " Packet too big"
               Type 3 - " Time Exceeded"
               Type 4 - " Parameter Problem"