MODIFY TRACE 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 SCOPE=ALL, code only EVERY or E. Do not code SCOPE=E.

Purpose

The MODIFY TRACE command starts traces or modifies the parameters for currently running traces. VTAM® traces are also started with the TRACE start option, as described in the z/OS Communications Server: SNA Resource Definition Reference.

Activation and use of VTAM traces have dependencies on the options used to start the system trace facility in each operating system environment. See the z/OS Communications Server: SNA Diagnosis Vol 1, Techniques and Procedures for a complete description of the system trace facility requirements, when to use these traces, and how to interpret the results.

General PIU trace (GPT) records are printed by the trace analysis program (ACFTAP) utility. For more information about ACFTAP, see z/OS Communications Server: ACF/TAP Trace Analysis Handbook.

Operands

procname

The procedure name for the command. If procname in the START command was specified as startname.ident, where startname is the VTAM start procedure and ident is the optional identifier, either startname.ident or ident can be specified for procname.

If procname in the START command was startname, startname must be specified for procname.

ALSNAME=adjacent_link_station_name

Applies only when TYPE=GPT and specifies the name of the adjacent link station through which you want tracing to occur. The adjacent link station name must be a PU in an NCP major node or a switched PU connected by an NCP link.

The LU can be traced over multiple connections; however, to do so, you must enter a separate command for each connection.

You do not need to specify the ALSNAME operand if either of the following situations is true:

• The ALS list has only one entry (and it is not ISTAPNPU). That entry is selected.
• The ALS list has two entries, one of which is ISTAPNPU. The entry other than ISTAPNPU is selected.

The command fails if ISTAPNPU is specified, or if ISTAPNPU is used by default because it is the only entry in the ALS list.

If no ALS list exists for the resource, specify the adjacent link station on the ALSNAME operand.

Use the DISPLAY ID=lu_name,SCOPE=ALL command to display all sessions for an independent LU and which adjacent link station list is used for each session.

AMOUNT

Applies only when TYPE=BUF. It determines whether VTAM starts a partial buffer contents trace or a full buffer contents trace for the specified node name.

You can run a partial buffer contents trace and a full buffer contents trace at the same time for different resources. (Issue a separate MODIFY TRACE command for each resource.) For example, you can start a partial buffer contents trace for an application program, with partial buffer contents tracing for some resources in session with the application program and full buffer contents tracing for other resources in session with the application program. When the level of tracing differs between two resources on opposite ends of a session (one is partial and the other is full), full buffer tracing is used.

You can switch between partial and full buffer tracing for the same resource by issuing additional MODIFY TRACE commands, without having to deactivate the trace.

AMOUNT=PARTIAL

Tells VTAM to record the data in trace records with a maximum size of 256 bytes. Each trace record contains a trace record header and data. Data that does not fit in a 256-byte trace record is lost.

AMOUNT=FULL

Tells VTAM to record all of the data transmitted in message buffers. Multiple trace records might be needed to record all of the data.

BFRNUM=number

• When you specify TYPE=VTAM,MODE=EXT this operand specifies the number of 8-K external trace buffers the VTAM internal trace is to allocate and use for generalized trace facility (GTF) processing. Values in the range of 2 - 50, or 0 can be specified. If you omit this option, the default value is 2. To ensure that enough buffers are available, specify a value that is twice as much as the number of processors in the central processing unit (CPU).

  When you specify a value in the range of 2 - 50, VTAM accumulates approximately 8 K of external trace data before sending the data to GTF.

  If 0 is specified or there is no buffer available for the trace record, VTAM sends each trace record to GTF as it is recorded. This can incur a significant system overhead, but might be necessary if you need individually timestamped records.

  If external trace recording is already active, and the new value specified for BFRNUM is less than the existing value, the number of buffers is not changed; if the new value is greater than the existing value, the number of the buffers is increased.

• When you specify TYPE=ROUTE, the BFRNUM operand specifies the maximum number of 40-K buffers to be allocated for the APPN route selection trace table. Values in the range of 1 - 500 can be specified. Storage for the route selection trace is not completely allocated when the trace is activated, but is allocated in 40-K buffers as it is needed. The APPN route selection trace is allocated in extended private storage.

  If you omit the BFRNUM option initially, the default for the maximum number of buffers is 100. After the APPN route selection trace is started, the BFRNUM operand does not have a default value. If successive MODIFY TRACE,TYPE=ROUTE commands are issued, the BFRNUM specification remains the same until you respecify it on a MODIFY command.

  If the BFRNUM value is too small, trace information might be lost as a result of wraparound in the route selection trace table. Also, if the BFRNUM value specified on the MODIFY TRACE,TYPE=ROUTE command is smaller than the previous BFRNUM value, information is lost because the existing trace table is freed. If a MODIFY TRACE,TYPE=ROUTE command is entered with a BFRNUM value larger than the previous BFRNUM value, however, the storage allocated for the trace table will not be freed and additional buffers will be allocated as needed up to the new limit. If an attempt to allocate an additional block of trace table storage fails because of insufficient storage, the route selection trace table size might not reach the maximum size that you requested.

COUNT

Applies only when TYPE=LINE or TYPE=SIT. It specifies the number of bytes that are traced by either the NCP for a line trace (without the TG operand), or the communication scanner processor for the scanner interface trace. The COUNT operand has no effect on NTRI lines before NCP V5R2.1. NTRI always traces the same amount of data.

COUNT=number_of_bytes

Specifies the number of bytes of data to be traced. The value must be a decimal integer 0 - 254. COUNT=0 specifies that only the NCP control characters and none of the data is to be traced.

COUNT=ALL

Specifies that all of the data is to be traced.

DEVICE

Applies only when the ID operand is a TRLE that has the DATAPATH operand coded. Use DEVICE to start input/output trace on OSA-Express devices specified on the DATAPATH operand.

DEVICE=ALL

Specifies to turn on input/output trace on all devices in the DATAPATH list.

DEVICE=hex_device_address

Specifies to turn on input/output trace for a specific DATAPATH device.

FRAMES

Applies only when TYPE=NETCTLR. For a start/stop line, ALL is the only option. If DATA is specified on a start/stop line, it is ignored and the command proceeds as if ALL were specified. For SDLC and BSC lines, either DATA or ALL can be specified, with DATA being the default.

FRAMES=ALL

Specifies that all frames (meaning control and data frames) are to be traced by the cluster control unit.

FRAMES=DATA

Specifies that only data frames are to be traced by the cluster control unit.

ID=name

Specifies the name of the resource for which tracing is to be done. Only active resources can be traced. This operand does not apply when TYPE=MODULE or TYPE=VTAM.

Names of various types of resources can be specified, depending on the value of the TYPE operand. The different resources and the traces that can be specified for them (with the TYPE operand) are shown in Figure 1 and are described in the following information.

For TYPE=BUF, TYPE=IO, TYPE=GPT, or TYPE=STATE, the name can be a network-qualified name. If name is an ACB name, and the ACB name matches the name on the APPL definition statement, then you can use a network-qualified ACB name.

For TYPE=BUF, TYPE=IO, or TYPE=STATE for a CDRM, you can specify a network-qualified name, but this does not remove the restriction that the non-network-qualified CDRM name must be unique across networks.

For TYPE=BUF, TYPE=IO, or TYPE=STATE, the name can be a model resource (APPL or CDRSC). If SCOPE=ALL is specified, the command also applies to the clone resources created from the model. If SCOPE=ONLY is specified, current clone resources are unaffected, but future clone resources will be affected when they are created.

For TYPE=QDIOSYNC, the ID operand specifies the TRLE name of the OSA-Express2 adapter for which diagnostic data synchronization and filtering is to be started. Specify ID=* to start QDIOSYNC for all TRLEs that define OSA-Express2 adapters. When ID=* is specified with SAVE=NO, ID=* indicates that the QDIOSYNC command is to be applied to all currently active TRLEs that define OSA-Express2 adapters. When ID=* is specified with SAVE=YES, ID=* indicates that the QDIOSYNC command is to be applied to all currently active TRLEs that define OSA-Express2 adapters and to those that are activated by this VTAM in the future.

When multiple QDIOSYNC NOTRACE or TRACE commands are specified, the last one that is applicable to a specific trle_name value

takes precedence. For example, TRACE TYPE=QDIOSYNC,ID=TRLE1 requests synchronization for a single OSA-Express2 adapter, but the request is canceled if it is followed by NOTRACE TYPE=QDIOSYNC, ID=*. TRACE TYPE=QDIOSYNC, ID=* requests synchronization of all OSA-Express2 adapters and, if it is followed by NOTRACE TYPE=QDIOSYNC,ID=TRLE1, results in synchronization of all OSA-Express2 adapters except TRLE1.

Figure 1. Resource and trace reference

• For TYPE=BUF or TYPE=IO, any of the following names can be specified along with the SCOPE=ALL operand to trace message activity with the named resource and, if applicable, all of the resource's subordinate nodes:
  • The name of an NCP major node
  • The name of the following major nodes (only TYPE=IO,SCOPE=ALL can be specified):
    • Channel-attachment major node
    • XCA major node
  • The name of a line attached to a communication adapter (only TYPE=IO,SCOPE=ONLY can be specified)
  • The name of a switched line that has a physical unit attached to it
  • The name of a TRLE (only TYPE=IO,SCOPE=ONLY can be specified)
    Restriction: I/O tracing is not supported for a TRLE that represents a 10GbE RoCE Express® feature.
  • The name of one of following types of physical units:
    • Channel-attached SNA physical unit
    • Switched physical unit
  • The name of a logical unit
  • The name of the host CDRM
    Note: If you do a trace for a host CDRM, any subordinate minor nodes also have trace turned on.
  Any of the following names can be specified to trace message activity with the named resource:

  • Host physical unit (for a trace of all PIUs between this host and another PU type 4 or PU type 5)
  • ISTIRN (with TYPE=IO only, for an IO trace of all PIUs passing through this host that are received from a channel-attached PU type 4 or type 5 and are being sent to another channel-attached PU type 4 or type 5)
  • VTAM (for a trace of all SSCP sessions)
  • The name of an NCP
  • The name of a logical unit (including application programs)
  • The name of a local non-SNA minor node
  • The name of a CDRM (only in a multiple-domain or multiple-network environment)
  • The name of a CDRSC
  • The name of the internal or external CMIP application program (for TYPE=BUF only). For the VTAM topology agent, node_name is ISTTOPAG. For notification services, node_name is ISTNOTIF. For external CMIP application programs, node_name is the application name defined as the ACB name of the application program major node. In the following example, APPL1 is the name of the CMIP application program, as defined in the name field of the APPL definition statement.

    APPL1     APPL   PRTCT=ADRAPL01

  The host CP can be traced as an application program minor node, and adjacent CPs can be traced as CDRSC minor nodes.

• For TYPE=CNM, the ID operand specifies one of the following values:
  • PDPIUBUF, to start the problem determination PIU buffer trace
  • SAWBUF, to start the session awareness buffer trace
• For TYPE=EXIT, the ID operand is required and must be specified as ISTEXCAA, ISTEXCCS, or ISTEXCDM.
• For TYPE=GPT, the ID operand specifies the name of the NCP resource for which tracing is to be done:
  • An NCP major node (and all of its resources) that is active or pending active
  • An NCP switched or nonswitched line
    Note: The ID operand of MODIFY TRACE cannot specify an NCP switched line that is a switched subarea connection.
  • An active LU that has been dynamically reconfigured within the NCP
  • An active PU on an NCP switched line
  • An active or inactive PU on an NCP nonswitched line
  • An active PU that is dynamically reconfigured within the NCP
  • An active or inactive LU associated with an active PU on a switched line
  • An active or inactive LU associated with a PU (active or inactive) on a nonswitched line
  • An active or inactive independent LU associated with a PU (ALS) in an NCP major node or a switched PU connected by an NCP link. The state (active or inactive) of the PU with which the independent LU is associated must be as follows:
    • If it has been dynamically reconfigured within the NCP, the PU must be active
    • If it is on an NCP switched line, the PU must be active.
    • If it is on an NCP nonswitched line, the PU can be either active or inactive.

  The SSCP and host CP are not valid resources for a GPT trace, but the adjacent CP can be traced as a CDRSC minor node.

• For TYPE=NETCTLR, the ID operand specifies the name of the physical unit representing the device for which the trace is to be started. (VTAM is not required to own or have knowledge of the 3710.) VTAM sends the name of the PU specified on the ID operand to the 3710 specified on the PU operand.
  If a 3710 is to be simultaneously traced over more than one line, use a separate MODIFY TRACE command to start each trace.

  Note: It is not necessary that the resource specified by the ID operand be another 3710.
• For TYPE=LINE or TYPE=SIT, the ID operand specifies the name of the line for which tracing is to be done.

  ID cannot specify a line attached to a communication adapter or the name of a transmission group through a communication adapter.

• For TYPE=SMS the ID operand is optional. If it is omitted, ID=VTAMBUF will be used for an SMS trace.
• For TYPE=STATE, the ID operand specifies the name of the resource for which state tracing is to be done.
• For TYPE=TG, the ID operand specifies the name of a nonswitched line currently within the transmission group to be traced. All the lines in the transmission group are traced as if they were a single logical line.
• For TYPE=TSO, the ID operand specifies the TSO user ID for which tracing is to be done.

IDTYPE

Specifies the type of resource that the ID operand names. If several types of resources share the same name, IDTYPE identifies which resources the command should act on. IDTYPE applies to TYPE=BUF, TYPE=IO, TYPE=GPT, and TYPE=STATE.

IDTYPE=CP

Starts tracing for the control point (CP) with the name specified on the ID operand. The CP that is traced can be the host CP or a CDRSC representing an adjacent CP.

IDTYPE=SSCP

Starts tracing for the system services control point (SSCP) with the name specified on the ID operand.

IDTYPE=RESOURCE

Starts tracing for a CP, an SSCP, or another resource with the name specified on the ID operand. If both an SSCP and a CP are found, VTAM starts tracing for both of them.

LENGTH

Applies only when the DEVICE operand is specified and the ID operand is a TRLE that has the DATAPATH operand coded. Use LENGTH to specify the number of bytes from each packet to trace. Valid values are 56 - 9016. Values are rounded up to 56 and values above 9016 are rounded down to 9016. All values are rounded up, if necessary, to an even multiple of 28.

Note: The default value is 272 for a TRLE that has the DATAPATH operand coded.

LINE=line_name

Applies only to TYPE=NETCTLR. It specifies the name of a link that is attached to the 3710 that is to be traced. The 3710 performing the trace (named on the PU operand) copies the SDLC, BSC, and S/S data link control frames that are transmitted or received on that link for the physical unit named by the ID operand. VTAM has no knowledge of this link. VTAM sends the name of the link specified on the LINE operand to the 3710 specified on the PU operand.

MODE

Applies only to TYPE=VTAM. It specifies that the VTAM internal trace is to record its data on an internal, wraparound table (MODE=INT) or an external trace file (MODE=EXT).

You can record trace data internally and externally at the same time. If required, you can have different sets of trace options active for internal and external recording. VTAM always runs with MODE=INT and the default trace options, regardless of whether you request tracing.

You must run specific operating system utilities to trap, format, and view external trace output. See z/OS Communications Server: SNA Diagnosis Vol 1, Techniques and Procedures for more information about use of these operating system utilities.

Do not specify MODE=EXT and SIZE on the same command.

MODE=INT

Specifies that the VTAM internal trace is to record its data on an internal, wraparound table.

MODE=EXT

Specifies that the VTAM internal trace is to record its data on an external trace file and on an internal, wraparound table.

OPTION

Applies to TYPE=EXIT, TYPE=MODULE, TYPE=QDIOSYNC, TYPE=STATE and TYPE=VTAM.

For TYPE=EXIT, OPTION specifies the functions of the session management exit (SME), directory services management exit (DSME), or configuration services XID exit for which tracing is to be started.

If more than one option is selected, separate them with commas and enclose the list in parentheses; for example OPTION=(BEGIN,INITAUTH,ACCTING).

For TYPE=MODULE, OPTION specifies the types of processing modules for which tracing is to be started.

If more than one option is selected, separate them with commas and enclose the list in parentheses; for example OPTION=(COMMAND,SESSION).

For TYPE=QDIOSYNC, OPTION specifies the scope and filter to be applied by the OSA-Express2 adapter. OPTION specifies the devices and the direction for which diagnostic data is to be gathered.

For TYPE=STATE, OPTION specifies the types of resources for which resource states are to be recorded. The data is recorded using the mode (internal or external) specified for the SSCP VIT option.

If more than one option is selected, separate them with commas and enclose the list in parentheses; for example OPTION=(APPL,GROUP,NCP).

For TYPE=VTAM, OPTION specifies the VTAM internal functions for which trace data is to be recorded.

The API, CIO, MSG, NRM, PIU, and SSCP VIT options are kept active by VTAM for internal recording (MODE=INT). If you stop them, VTAM immediately restarts them. For external recording (MODE=EXT), there are no default options. You can start or stop any options.

Note: Although the default options are always active, these options do not appear in DISPLAY TRACES output unless you have specified them on the MODIFY TRACE command or the TRACE,TYPE=VTAM start option.

If more than one option is selected, separate them with commas and enclose the list in parentheses; for example OPTION=(API,NRM,SSCP). For information about what is traced for each internal function, see the z/OS Communications Server: SNA Diagnosis Vol 2, FFST Dumps and the VIT.

OPTION=ALL

Applies to TYPE=EXIT, TYPE=MODULE, TYPE=STATE, and TYPE=VTAM.

Note: Turning on all traces slows performance.

For TYPE=EXIT, it starts the tracing of all functions.

For TYPE=MODULE, it starts the tracing of all the modules shown on the OPTION operand for which TYPE=MODULE apply.

For TYPE=STATE, it starts the tracing of resource states for all of the resource types shown on the OPTION operand for which TYPE=STATE apply.

For TYPE=VTAM, it starts the VTAM internal trace for all of the VTAM internal functions for which the VTAM internal trace is available. Exception trace entries continue to be recorded.

For TYPE=EXIT where ID=ISTEXCAA, you can also specify the following options:

OPTION=ALL

Starts the tracing of all functions.

OPTION=ACCTING

Starts tracing the initial and final accounting function of the session management exit (SME).

OPTION=ADJSSCP

Starts tracing the adjacent SSCP selection function of the session management exit (SME).

OPTION=ALIAS

Starts tracing the alias translation function of the session management exit (SME).

OPTION=ALS

Starts tracing the adjacent link station function of the session management exit (SME).

OPTION=BEGIN

Starts tracing the begin function of the session management exit (SME).

OPTION=END

Starts tracing the end function of the session management exit (SME).

OPTION=GWPATH

Starts tracing the gateway path list function of the session management exit (SME).

OPTION=INITAUTH

Starts tracing the initial authorization function of the session management exit (SME).

OPTION=REPL

Starts tracing the exit replacement function of the session management exit (SME).

OPTION=SECAUTH

Starts tracing the secondary authorization function of the session management exit (SME).

OPTION=VRSEL

Starts tracing the virtual route selection function of the session management exit (SME).

OPTION=XRF

Starts tracing the XRF session switch function of the session management exit (SME).

For TYPE=EXIT where ID=ISTEXCCS, you can also specify the following options:

OPTION=ALL

Starts the tracing of all functions.

OPTION=BEGIN

Starts tracing the begin function.

OPTION=CONNSTAT

Starts tracing the connection status.

OPTION=DYNA_XID

Starts tracing the XIDs for dynamic PUs function.

OPTION=END

Starts tracing the end function.

OPTION=PRED_XID

Starts tracing the XIDs for predefined PUs function.

For TYPE=EXIT where ID=ISTEXCDM, you can also specify the following options:

OPTION=ALL

Starts the tracing of all the functions.

OPTION=ADS_SEL

Starts tracing the alternate central directory server selection function.

OPTION=BEGIN

Starts tracing the begin function.

OPTION=BN_SEL

Starts tracing the border node selection function.

OPTION=CDS_SEL

Starts tracing the central directory server selection function.

OPTION=CRR_SEL

Starts tracing the central resource registration selection function.

OPTION=END

Starts tracing the end function.

OPTION=ICN_SEL

Starts tracing the interchange node selection function.

OPTION=INITAUTH

Starts tracing the initial authorization function.

OPTION=REPL

Starts tracing the exit replacement function

For TYPE=MODULE, you can also specify the following options:

OPTION=COMMAND

Starts tracing modules involved in command processing.

OPTION=CONNECTION

Starts tracing modules involved in setting up connections between nodes.

OPTION=DEFINITION

Starts tracing modules involved in resource definition processing.

OPTION=INTERFACES

Starts tracing modules involved in the interface with the host SSCP or the host CP.

OPTION=MANAGEMENT

Starts tracing modules involved in network management.

OPTION=NOEXIT

Specifies that module exits are not traced for modules associated with other OPTION values for TYPE=MODULE. Module exits are not traced for any modules until a subsequent MODIFY NOTRACE,TYPE=MODULE,OPTION=NOEXIT command is issued.

Starting a module trace for any OPTION with TYPE=MODULE starts the tracing of the module exits also, unless you specify OPTION=NOEXIT.

OPTION=PURGE

Causes all information currently held in module tracing buffers to be written to VTAM internal trace (VIT) entries. Upon completion of the command, new information is written to the module tracing buffers.

OPTION=SESSION

Starts tracing modules involved in session establishment.

For TYPE=QDIOSYNC, you can specify the following options:

OPTION=ALLIN

Indicates that the adapter should gather diagnostic data for all devices, including any that might be controlled by other operating systems. This option also indicates that the adapter should collect records pertinent to events and data flowing from the adapter to the host. Code the value OPTION=ALLIN only when advised by IBM® service to do so.

OPTION=ALLINOUT

Indicates that the adapter should gather diagnostic data for all devices, including any that might be controlled by other operating systems. This option also indicates that the adapter should collect both inbound and outbound diagnostic data.

OPTION=ALLOUT

Indicates that the adapter should gather diagnostic data for all devices, including any that might be controlled by other operating systems. This option also indicates that the adapter should collect records pertinent to events and data flowing from the host to the adapter. Code OPTION=ALLOUT only when advised by IBM service to do so.

OPTION=IN

Indicates that the adapter should gather diagnostic data for devices defined to this VTAM only. This option also indicates that the adapter should collect records pertinent to events and data flowing from the adapter to the host. Code OPTION=IN only when advised by IBM service to do so.

OPTION=INOUT

Indicates that the adapter should gather diagnostic data for devices defined to this VTAM only. This option also indicates that the adapter should collect both inbound and outbound diagnostic data. Code OPTION=INOUT only when advised by IBM service to do so.

OPTION=OUT

Indicates that the adapter should gather diagnostic data for devices defined to this VTAM only. This option also indicates that the adapter should collect records pertinent to events and data flowing from the host to the adapter. Code OPTION=OUT only when advised by IBM service to do so.

For TYPE=STATE, you can also specify the following options:

OPTION=ADJCP

Starts tracing the states of all adjacent control points.

OPTION=APPL

Starts tracing the states of all application programs.

OPTION=CDRM

Starts tracing the states of all CDRMs.

OPTION=CDRSC

Starts tracing the states of all CDRSCs.

OPTION=GROUP

Starts tracing the states of all line groups.

OPTION=LINE

Starts tracing the states of all lines.

OPTION=LNKST

Starts tracing of link stations.

OPTION=LU

Starts tracing the states of all logical units.

OPTION=NCP

Starts tracing the states of all NCPs.

OPTION=PU

Starts tracing the states of all physical units.

For TYPE=VTAM, you can also specify the following options:

OPTION=API

Starts tracing the application programming interface.

OPTION=APIOPTS

Starts tracing events related to the application programming interface (API). Specifying this value is equivalent to specifying OPTION=(API,MSG,NRM,PIU,PSS,SMS,SSCP).

OPTION=APPC

Starts tracing LU 6.2 communication.

OPTION=APPCOPTS

Starts tracing events related to LU 6.2 application programs. Specifying this value is equivalent to specifying OPTION=(API,APPC,MSG,NRM,PIU,PSS,SMS,SSCP).

OPTION=CFS

Starts tracing coupling facility services.

OPTION=CIA

This option helps isolate problems related to channel I/O. CIA entries are the remaining trace records from the CIO option.

OPTION=CIO

Starts tracing channel I/O for channel-attached devices and for lines attached to a communication adapter.

OPTION=CMIP

Starts tracing internal events in CMIP services and the VTAM topology agent.

OPTION=CPCPOPTS

Starts tracing events related to CP-CP sessions. Specifying this value is equivalent to specifying OPTION=(API,APPC,MSG,NRM,PIU,PSS,SMS,SSCP).

OPTION=CSM

Starts tracing of the communications storage manager.

OPTION=CSMOPTS

Starts tracing events related to communications storage manager (CSM). Specifying this value is equivalent to specifying OPTION=(API,APPC,CIO,CSM,MSG,NRM,PIU,PSS,SMS,SSCP,XBUF).

OPTION=DLUROPTS

Starts tracing events related to dependent LU requester (DLUR). Specifying this value is equivalent to specifying OPTION=(API,APPC,HPR,MSG,NRM,PIU,PSS,SMS,SSCP).

OPTION=EEOPTS

Starts tracing events related to Enterprise Extender (EE). Specifying this value is equivalent to specifying OPTION=(CIA,CIO,HPR,MSG,NRM,PIU,PSS,SMS,SSCP,TCP).

OPTION=ESC

Starts tracing execution sequence control.

OPTION=HPDTOPTS

Starts tracing events related to high performance data transfer (HPDT). Specifying this value is equivalent to specifying OPTION=(CIA,CIO,HPR,MSG,PIU,PSS,SMS,SSCP).

OPTION=HPR

Starts tracing for HPR.

OPTION=HPROPTS

Starts tracing events related to high performance routing (HPR). Specifying this value is equivalent to specifying OPTION=(API,APPC,CIA,CIO,HPR,MSG,NRM,PIU,PSS,SMS,SSCP).

OPTION=LCS

Starts tracing LAN channel stations.

OPTION=LCSOPTS

Starts tracing events related to LAN channel station (LCS). Specifying this value is equivalent to specifying OPTION=(CIO,LCS,MSG,NRM,PIU,PSS,SMS,SSCP).

OPTION=LOCK

Starts tracing locking.

OPTION=MSG

Starts tracing messages.

OPTION=NRM

Starts tracing network resource management

OPTION=PIU

Starts tracing path information units.

OPTION=PSS

Starts tracing process scheduling services.

OPTION=QDIOOPTS

Starts tracing events related to queued direct I/O (QDIO). Specifying this value is equivalent to specifying OPTION=(CIA,CIO,HPR,MSG,NRM,PIU,PSS,SMS,SSCP).

OPTION=SMS

Starts tracing Storage Management services.

OPTION=SSCP

Starts tracing the system services control point.

OPTION=STDOPTS

Starts tracing events related to the application programming interface, channel I/O, messages, network resource management, path information units, process scheduling services, Storage Management services, and the system services control point. Specifying this value is equivalent to specifying OPTION=(API,CIO,MSG,NRM,PIU,PSS,SMS,SSCP).

OPTION=TCP

Starts tracing the Enterprise Extender events.

OPTION=TCPOPTS

Starts tracing events related to TCP/IP. Specifying this value is equivalent to specifying OPTION=(CIA,CIO,MSG,NRM,PIU,PSS,SMS,SSCP,TCP).

OPTION=VCNS

Starts tracing VTAM common network services.

OPTION=XBUF

Starts tracing of extended buffer list information.

OPTION=XCF

Starts tracing XCF communication.

OPTION=XCFOPTS

Starts tracing events related to the cross-system coupling facility (XCF). Specifying this value is equivalent to specifying OPTION=(CIA,CIO,HPR,MSG,NRM,PIU,PSS,SMS,SSCP,XCF).

PU=3710_pu_name

Applies only when TYPE=NETCTLR. It specifies the name of the IBM 3710 Network Controller that is to perform the trace. VTAM rejects the command if the physical unit is not known to VTAM.

SAVE

Applies to TYPE=BUF, TYPE=IO, TYPE=QDIOSYNC, and TYPE=STATE. It specifies whether the trace command should be saved for the resource named on the ID operand.

SAVE=YES

VTAM saves the trace command for the resource named on the ID operand. If the resource exists when this command is issued, the trace starts immediately. If the resource does not exist when this command is issued, VTAM saves the trace command and starts the trace when the resource is defined.

Note: For TYPE=BUF, TYPE=IO, and TYPE=STATE, if you start a trace with IDTYPE=RESOURCE and a CP or an SSCP (but not both) exists when the command is issued, VTAM starts the trace for the existing resource and saves the trace commands for both resources. If both a CP and an SSCP exist when the command is issued, VTAM starts tracing for them immediately.

You can also issue this command to update a previously saved trace command.

For TYPE=QDIOSYNC:

• If ID=trlename is specified, any saved command from a previous TRACE TYPE=QDIOSYNC command or start option for the TRLE specified by the trle_name value is deleted.
• If ID=* is specified, all saved commands from previous TRACE TYPE=QDIOSYNC commands and start options are deleted.

Use the MODIFY NOTRACE command to delete a saved trace command. VTAM will not delete a saved trace command until you issue a MODIFY NOTRACE command for it, even though the resource might be created and freed or activated and deactivated several times. Saved trace commands are lost when VTAM is halted and restarted.

SAVE=NO

Does not save the MODIFY TRACE command. If the resource does not exist when you issue MODIFY TRACE, the command fails.

SCOPE

Applies when TYPE=BUF, TYPE=IO, or TYPE=GPT. It specifies the scope of the trace.

You can specify the SCOPE operand for TYPE=GPT, but it is meaningful only for the NCP node. SCOPE=ALL is assumed for a GPT trace of all other node types.

SCOPE=ALL

Starts traces for all nodes subordinate to the specified node. If an LU that is subordinate to a node is an independent LU, it is not considered to be subordinate to the node for the purpose of tracing.

SCOPE=ALL is not valid for the host PU trace or for the host intermediate routing node trace (ID=ISTIRN). If SCOPE=ALL is specified, VTAM issues a message and uses SCOPE=ONLY.

For an I/O trace of a channel-attached NCP, SCOPE=ALL provides a trace of all channel I/O, including network message traffic routed through the channel-attached NCP.

If the specified node is a model application, SCOPE=ALL turns on the trace option for the model application and starts traces for all existing dynamic applications created using the model. Traces will be started for future dynamic applications created using the model.

SCOPE=ONLY

Starts a trace only for the specified node.

SCOPE=ONLY on a GPT trace command for the NCP PU limits the trace to RUs that flow on the SSCP-PU session for the NCP.

If the specified node is a model application, SCOPE=ONLY turns on the trace option for the model application. Traces for all existing dynamic applications created using the model are unaffected. Traces will be started for future dynamic applications created using the model.

SIZE=size

Applies only when you specify TYPE=VTAM,MODE=INT. The size operand specifies the number of megabytes to be allocated for the internal trace table. Valid values are in the range 4M - 2048M. The VTAM internal trace table is allocated in 64-bit common (HVCOMMON) storage.

If the VTAM internal trace is not already started and you omit this option, the default size is 4M.

After the VTAM internal trace is started, the SIZE operand does not have a default value. If successive MODIFY commands change other options, the SIZE specification remains the same until you respecify it on a MODIFY command.

If the SIZE value is too small, trace information might be lost as a result of wraparound in the internal trace table. Also, if the SIZE operand specifies a size different from the current table size, information is lost because the trace table is freed when another table with a new size is obtained. When an attempt to increase the SIZE value fails because of insufficient storage, the internal trace table size is set to the minimum size, not the size that you requested.

Restriction: If you specify a SIZE value that is larger than the default value, z/OS® will perform paging on portions of the VIT table. Before you specify a large SIZE value, ensure that you have sufficient real or auxiliary storage to contain the entire VIT. Failure to ensure that sufficient storage might result in an auxiliary storage shortage. If an SVC dump is taken that includes common storage, the size of the dump data set also increases. You must also take the increase in the size of the dump data set into consideration.

SUBTRACE

Specifies that SUBTRACE can be used to turn on a subset of trace entries under a trace option. Of the SUBTRACE types defined, subtrace DIO is defined under the CIA trace option, subtrace TREE, and TGVC are defined under the SSCP trace option, and subtrace ARBP is defined under the HPR trace option.

Note: All of the SUBTRACE options are defaulted to off. They can generate many records in the VTAM trace and can incur a significant overhead, but may be necessary in some cases for diagnostic purposes. It is not recommended to activate them at VTAM start time. If used, the SUBTRACE options should be turned off when the necessary trace output has been obtained.

SUBTRACE=ARBP

Specifies that OPTION is a required keyword when SUBTRACE is specified and HPR must be one of the trace options specified when SUBTRACE=ARBP is coded. After subtrace ARBP is activated, the following trace records will be generated for the ARB algorithm processing: ARBR (Generated when ARB Responsive Mode algorithm is used) and ARBB (Generated when ARB Base Mode algorithm is used).

SUBTRACE=DIO

Specifies that OPTION is a required keyword when SUBTRACE is specified and CIA must be one of the trace options specified when SUBTRACE=DIO is coded. After subtrace DIO is activated, the following trace records may be generated for QDIO and Hipersockets processing: QAPL, QDIP and QSRB.

SUBTRACE=TGVC

Specifies that OPTION is a required keyword when SUBTRACE is specified and SSCP must be one of the trace options specified when SUBTRACE=TGVC is coded. After subtrace TGVC is activated, the following trace records will be generated for various TG Vector requests: TGVC and TGV2. If large amounts of data are being traced, additional TGVC records (plus subsequent TGV2 records) may occur.

SUBTRACE=TREE

Specifies that OPTION is a required keyword when SUBTRACE is specified and SSCP must be one of the trace options specified when SUBTRACE=TREE is coded. After subtrace TREE is activated, the following trace records will be generated for routing trees used by APPN route computation: TRRT, TRR2, TRR3, TRR4, TRR5, HLST, and HLS2.

SYNCID

Valid for TYPE=QDIOSYNC. The OSA-Express2 uses this value as part of an identifier when it captures diagnostic data.

Restriction: If you specify a value for SYNCID, it must conform to the rules for names. See z/OS Communications Server: SNA Resource Definition Reference for more information.

TRACEPT=trace_point_id

Applies to TYPE=SIT and is valid only if you are tracing connectivity subsystem (CSS) resources on an IBM 3745 Communication Controller. This operand specifies the point in the microcode at which tracing should be activated. If you omit this operand, tracing is done for all valid trace points. Using the TRACEPT operand, you can limit the tracing to a single trace point if too much output is being produced.

VTAM accepts any integer in the range 1 - 255; however, only a few values are defined by the NCP. For information about which values are defined and what they mean, see the NCP, SSP, and EP Diagnosis Guide.

TYPE

Specifies the kind of trace that is to be affected. More than one kind of trace can be active at the same time, but you must start or change each trace with a separate MODIFY TRACE command.

TYPE=BUF

Starts the tracing of text that passes through VTAM buffers on the way to or from the node identified by the ID operand. The SCOPE operand can be used to extend the scope of the trace to all nodes subordinate to the specified node. This trace is useful when one of the logical units in the session is an application program in this domain.

TYPE=CNM

Starts a communication network management trace.

Note: When this option is specified, the generalized trace facility (GTF) must be active with the TRACE=USR option specified.

TYPE=EXIT

Starts the tracing of functions of the session management exit (SME).

TYPE=GPT

Starts an NCP generalized PIU trace (GPT) for the resources identified by the ID operand.

Note: The ID operand of MODIFY TRACE cannot specify:

• An NCP switched line that is a switched subarea connection
• A dynamic CDRSC

TYPE=IO

Starts a trace of I/O activity associated with the node identified by the ID operand. The SCOPE operand can be used to extend the scope of the trace to all nodes subordinate to the specified node. In addition, for an NCP major node with an active channel attachment, the SCOPE=ALL operand provides a trace of all I/O going across the channel, including cross-domain session I/O.

Note: The external VIT is now used to record the IO trace entries. PIU, NLPI, NLPO, LSNA, and MPTNFMT entries may be written for a specific IO trace invocation.

TYPE=LINE

Starts an NCP line trace for the line identified by the ID operand.

TYPE=MODULE

Starts module tracing for the options specified on the OPTION operand.

TYPE=NETCTLR

Sends a trace request to the 3710 named on the PU operand.

TYPE=QDIOSYNC

Use TYPE=QDIOSYNC to synchronize and optionally filter OSA-Express2 diagnostic data.

Arming the OSA-Express2 adapter directs it to capture diagnostic data when there is an unexpected loss of host connectivity. Diagnostic data is also captured when the following situations occur:

• The VTAM-supplied message processing facility (MPF) exit IUTLLCMP is driven.
• Either the VTAM or TCP/IP functional recovery routine (FRR) is driven with the ABEND06F abend. ABEND06F is the result of a SLIP PER trap command specifying ACTION=RECOVERY.
  Restriction: The SLIP must be a SLIP PER trap in order to specify ACTION=RECOVERY.
  See z/OS Communications Server: SNA Diagnosis Vol 1, Techniques and Proceduresfor more information about the QDIOSYNC facility.

TYPE=ROUTE

Starts the APPN route selection trace.

TYPE=SIT

Starts a scanner interface trace (SIT) through the communication scanner processor located in the IBM 3720 or 3745 Communication Controller containing the NCP identified by the line specified by the ID operand.

The scanner interface trace and the NCP line trace can be started separately, and can be active at the same time.

TYPE=SMS

Starts a Storage Management services (SMS) trace to record VTAM buffer pool usage data.

TYPE=STATE

Starts a resource state trace to record the changing states of resources.

TYPE=TG

Starts an NCP transmission group trace for the transmission group (TG) containing the NCP line identified by the ID operand. A line is part of a transmission group only when both the line and its subordinate link station are active. A transmission group trace can be started by naming any line within the transmission group. When a transmission group trace is started, another trace of the same transmission group cannot be requested by naming the same or another line within the transmission group in another MODIFY TRACE command.

If the line or its link station subsequently fails or is deactivated (that is, if the line is removed from the transmission group), the transmission group trace is ended, even though the transmission group continues to operate if there are any remaining lines in the transmission group. The trace can be restarted, naming another line in the transmission group.

The NCP line trace and the transmission group trace are mutually exclusive for a particular line. Therefore, when starting a transmission group trace, select a line that is not being used, and is not likely to be used, for a line trace.

TYPE=TSO

Starts a TSO component trace for the user ID identified by the ID operand. GTF must be active when this trace option is specified.

TYPE=VTAM

Starts the VTAM internal trace (VIT) for the components specified by the OPTION operand. If OPTION is omitted, no new component internal traces are initiated; rather, VTAM issues messages identifying the components for which the internal trace is currently active.