SNAP-IX Administration Command Reference

2.3 add_dlc_trace

The add_dlc_trace command controls tracing on SNA messages sent on a DLC. It can be used to activate tracing on a particular DLC, port, LS, or HPR RTP connection. It can also be used to activate tracing on a particular session on a specified LS or to specify which types of messages are to be traced. The command can also be used to activate tracing on all DLCs, ports, link stations, and HPR RTP connections. For more information about how to use SNAP-IX tracing, refer to the SNAP-IX Diagnostics Guide.

If multiple add_dlc_trace commands relating to the same resource are issued, a message will be traced if it matches any of the commands currently active. For example:

If you issue a command to trace all messages for a port and its link stations and then issue a second command to trace only messages with a specified LFSID for one of the link stations owned by the port, all messages for the LS will continue to be traced (because they match the first command). If you then use remove_dlc_trace to remove tracing for the port, messages on the LS with the specified LFSID will continue to be traced (because they match the second command which is still active), but other messages on this LS will not be traced.
If you issue a command to trace XID messages on all resources and then issue a second command to trace SC and DFC messages on a particular LS, all three message types will be traced for this LS.

If you are tracing an SDLC line and would like more detailed trace information, you can get this by using internal tracing on SDLC as well as line tracing. The additional detail is formatted as part of the output for line tracing, so that you will see all of the SDLC tracing in one file. For more information, see set_trace_type.

2.3.1 Supplied Parameters

Parameter name                    Type           Length     Default
[add_dlc_trace]
resource_type                     constant                  ALL_RESOURCES
resource_name                     character      8          (null string)
sidh                              hex byte                  0
sidl                              hex byte                  0
odai                              constant                  NO
message_type                      constant                  TRACE_ALL

Supplied parameters are:

resource_type

Specifies the resource to be traced and optionally the specific message types to be traced for this resource. Possible values are:

ALL_RESOURCES: Specify tracing options for all DLCs, ports, link stations, and RTP connections.
DLC: Specify tracing options for the DLC named in resource_name and for all ports and link stations that use this DLC.
PORT: Specify tracing options for the port named in resource_name and for all link stations that use this port.
LS: Specify tracing options for the LS named in resource_name .
RTP: Specify tracing options for the RTP connection named in resource_name.
PORT_DEFINED_LS: Specify tracing options for the port named in resource_name and for all defined link stations (but not implicit link stations) that use this port.
PORT_IMPLICIT_LS: Specify tracing options for the port named in resource_name and for all implicit link stations (but not defined link stations) that use this port.

resource_name

The name of the DLC, port, LS, or RTP connection for which tracing is to be activated. Do not specify this parameter if resource_type is set to ALL_RESOURCES.

If resource_type is set to RTP, you can specify the name of a particular RTP connection (this name begins with the @ character), or you can omit this parameter to indicate that all RTP traffic is to be traced.

The following three parameters identify the Local Form Session Identifier (LFSID) for a session on the specified LS. These parameters are valid only if resource_type is set to LS, and they indicate that only messages on this session are to be traced. The LFSID consists of the following parameters:

sidh

Session ID high byte

sidl

Session ID low byte

odai

Origin Destination Assignor Indicator. Possible values are:

YES: The BIND sender is the node containing the secondary link station.
NO: The BIND sender is the node containing the primary link station.

message_type

The type of messages to trace for the specified resource or session. To trace all messages, set this parameter to TRACE_ALL. To trace specific messages, specify one or more of the following values (combined using a + character):

TRACE_XID: Trace XID messages
TRACE_SC: Trace Session Control Request/Response Units (RUs)
TRACE_DFC: Trace Data Flow Control RUs
TRACE_FMD: Trace Function Management Data messages
TRACE_SEGS: Trace Non-BBIU segments that do not contain an RH
TRACE_CTL: Trace Messages other than MUs and XIDs
TRACE_NLP: Trace Network-Layer Protocol messages
TRACE_NC: Trace Network Control messages

For tracing on an RTP connection, the values TRACE_XID, TRACE_NLP , and TRACE_CTL are ignored. At least one of the other values listed must be specified for RTP tracing.

2.3.2 Returned Parameters

No parameters are returned by SNAP-IX when this command executes successfully.

2.3.3 Error Return Codes

If the command cannot be executed, SNAP-IX returns a primary return code to indicate the type of error and a secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

If the command does not execute because of a parameter error, SNAP-IX returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

Possible values are:

INVALID_RESOURCE_TYPE: The value specified in the resource_type parameter was not valid.
INVALID_MESSAGE_TYPE: The value specified in the message_type parameter was not valid.
INVALID_RTP_CONNECTION: The resource_name parameter does not match any RTP connection.

State Check

No specific state errors, other than those listed in Common Return Codes from snaadmin Commands, occur for this command.

Other Conditions

Common Return Codes from snaadmin Commands, lists combinations of primary and secondary return codes that are common to all commands.