TRACE for MODULE, STATE (with OPTION), or VTAM internal trace


                                 (1)                            
   .-NOTRACE--,--TYPE--=--MODULE----------------------------.   
>>-+--------------------------------------------------------+--->
   |                                                    (2) |   
   '-TRACE--,--TYPE--=--MODULE--,--| MODULE operands  |-----'   

   .-NOTRACE--,--TYPE--=--STATE (¹)-------------------------.   
>--+--------------------------------------------------------+--->
   '-TRACE--,--TYPE--=--STATE--| STATE trace operands (²) |-'   

   .-TRACE--,--TYPE--=--VTAM--,--| VIT   operands (²) |-.   
>--+----------------------------------------------------+------><
   |                           (3)                      |   
   '-NOTRACE--,--TYPE--=--VTAM--------------------------'   

MODULE operands

|--,--OPTION--=--+-ALL-------------------+----------------------|
                 +-option----------------+   
                 +-(--option--)----------+   
                 '-(--+-COMMAND-----+--)-'   
                      +-CONNECTIONS-+        
                      +-DEFINITION--+        
                      +-INTERFACES--+        
                      +-MANAGEMENT--+        
                      +-NOEXIT------+        
                      '-SESSION-----'        

STATE trace operands

|--,--OPTION--=--+-ALL-------------+----------------------------|
                 +-option----------+   
                 +-(--option--)----+   
                 '-(--+-ADJCP-+--)-'   
                      +-APPL--+        
                      +-CDRM--+        
                      +-CDRSC-+        
                      +-GROUP-+        
                      +-LINE--+        
                      +-LU----+        
                      +-NCP---+        
                      '-PU----'        

VIT operands

   .-,--MODE--=--INT--,--SIZE--=--4M---------------.   
|--+-----------------------------------------------+------------>
   |                    .-,--BFRNUM--=--2------.   |   
   '-,--MODE--=--+-EXT--+----------------------+-+-'   
                 |      '-,--BFRNUM--=--number-' |     
                 '-INT--+------------------+-----'     
                        '-,--SIZE--=--size-'           

                                                                                      (4) (5)     
   .-,--OPTION--=--(--API--,--CIO--,--MSG--,--NRM--,--PIU--,--PSS--,--SMS--,--SSCP--)---------.   
>--+------------------------------------------------------------------------------------------+--|
   |                                   (6)                                                    |   
   +-,--SUBTRACE=ARBP,OPTION--=--+-HPR----------------+---------------------------------------+   
   |                             +-ALL----------------+                                       |   
   |                             +-hprgrpopt----------+                                       |   
   |                             |             (7)    |                                       |   
   |                             +-(..,HPR,..)--------+                                       |   
   |                             '-(..,hprgrpopt ,..)-'                                       |   
   |                                  (8)                                                     |   
   +-,--SUBTRACE=DIO,OPTION--=--+-CIA----------------+----------------------------------------+   
   |                            +-ALL----------------+                                        |   
   |                            +-ciagrpopt----------+                                        |   
   |                            |             (9)    |                                        |   
   |                            +-(..,CIA,..)--------+                                        |   
   |                            '-(..,ciagrpopt ,..)-'                                        |   
   |                                                (10)                                      |   
   +-,--SUBTRACE--=--+-TGVC-+--,--OPTION--=--+-SSCP---------------+---------------------------+   
   |                 '-TREE-'                +-ALL----------------+                           |   
   |                                         +-groupopt-----------+                           |   
   |                                         |              (11)  |                           |   
   |                                         +-(..,SSCP,..)-------+                           |   
   |                                         '-(...,groupopt ,..)-'                           |   
   '-,--OPTION--=--+-ALL----------------+-----------------------------------------------------'   
                   +-NONE---------------+                                                         
                   +-option-------------+                                                         
                   +-(--option--)-------+                                                         
                   '-(--+-API------+--)-'                                                         
                        +-APIOPTS--+                                                              
                        +-APPC-----+                                                              
                        +-APPCOPTS-+                                                              
                        +-CFS------+                                                              
                        +-CIA------+                                                              
                        +-CIO------+                                                              
                        +-CMIP-----+                                                              
                        +-CPCPOPTS-+                                                              
                        +-CSM------+                                                              
                        +-CSMOPTS--+                                                              
                        +-DLUROPTS-+                                                              
                        +-EEOPTS---+                                                              
                        +-ESC------+                                                              
                        +-HPDTOPTS-+                                                              
                        +-HPR------+                                                              
                        +-HPROPTS--+                                                              
                        +-LCS------+                                                              
                        +-LCSOPTS--+                                                              
                        +-LOCK-----+                                                              
                        +-MSG------+                                                              
                        +-NRM------+                                                              
                        +-PIU------+                                                              
                        +-PSS------+                                                              
                        +-QDIOOPTS-+                                                              
                        +-SMS------+                                                              
                        +-SSCP-----+                                                              
                        +-STDOPTS--+                                                              
                        +-TCP------+                                                              
                        +-TCPOPTS--+                                                              
                        +-VCNS-----+                                                              
                        +-XBUF-----+                                                              
                        +-XCF------+                                                              
                        '-XCFOPTS--'

Notes:

Do not use NOTRACE when starting VTAM®, except to override a TRACE start option coded in a predefined list.
You can code TRACE and its qualifiers through position 71, even if you are in the middle of the start option. Continue the remainder of the item in the next record. Code the TYPE qualifier immediately after you code the TRACE start option.
NOTRACE,TYPE=VTAM is accepted but ignored. Tracing is started with the default trace table size and the default options.
The default options apply only to MODE=INT.
PSS and SMS can be turned off.
When SUBTRACE=ARBP is specified, if a single OPTION value is coded, it must be HPR, ALL, or one of the group options (hprgrpopt) that include HPR as an individual option equivalent. The applicable group options are DLUROPTS, EEOPTS, HPDTOPTS, HPROPTS, QDIOOPTS, and XCFOPTS.
If multiple trace options are coded in parentheses, either HPR or one of the group options (hprgrpopt) that include HPR as an individual option equivalent must be coded inside the parentheses when SUBTRACE=ARBP is coded.
When you specify SUBTRACE=DIO and you code a single OPTION value, the OPTION value must be CIA, ALL, or one of the group options (ciagrpopt) that include CIA as an individual option equivalent. The applicable group options are EEOPTS, HPDTOPTS, HPROPTS, QDIOOPTS, TCPOPTS and XCFOPTS.
When SUBTRACE=DIO is coded and you code multiple trace options in parentheses, you must code either CIA or one of the group options (ciagrpopt) that include CIA as an individual option equivalent inside the parentheses.
When SUBTRACE=TGVC or SUBTRACE=TREE is coded, if a single OPTION value is coded, it must be SSCP, ALL, or one of the group options (groupopt), all of which include SSCP as an individual option equivalent. The group options are APIOPTS, APPCOPTS, CPCPOPTS, CSMOPTS, DLUROPTS, EEOPTS, HPDTOPTS, HPROPTS, LCSOPTS, QDIOOPTS, STDOPTS, TCPOPTS, and XCFOPTS.
If multiple trace options are coded in parentheses, either SSCP or one of the group options (groupopt) must be coded inside the parentheses when SUBTRACE=TGVC or SUBTRACE=TREE is coded.

Specifies whether VTAM starts or cancels a specific type of trace.

If you code the TRACE option, code the TYPE qualifier immediately after TRACE.

You can change the value of TRACE with the MODIFY TRACE command while VTAM is running.

BFRNUM=number

Specifies the number of 8K external trace buffers the VTAM internal trace is to allocate and use for generalized trace facility (GTF) processing. Integers 0 or 2–50 can be specified. The default is 2. Two times the number of processors in the central processing unit (CPU) should ensure that enough buffers are available.

When an integer of 2–50 is specified, VTAM accumulates approximately 8K of external trace data prior to sending the data to GTF.

If zero is specified or there is no buffer available for the trace record, VTAM sends each trace record to GTF as it is recorded. This incurs a significant system overhead, and should be avoided.

MODE

Specifies that the VTAM internal trace is to record its data on an internal, wraparound table (MODE=INT) and optionally, on an external trace file (MODE=EXT).

MODE applies only to TYPE=VTAM.

You can record trace data internally and externally simultaneously. If you want, 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, whether you request tracing or not.

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 as well as on an internal, wraparound table. You can record external trace data using the generalized trace facility (GTF). GTF must be active when you initiate traces. You can format output using IPCS.
See z/OS Communications Server: SNA Diagnosis Vol 1, Techniques and Procedures for a more detailed description of formatting and printing trace output.

NOTRACE

Specifies that VTAM cancels the trace requested by the TYPE operand. Code this start option only when it is necessary to override a predefined TRACE start option. Code a separate NOTRACE start option to stop each trace.

NOTRACE,TYPE=VTAM

Accepted but ignored. Tracing is started with the default trace table size and the default options.

OPTION=(option,option,…option)

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

You can abbreviate this operand as OPT.

You can code one or more of the options listed for each TYPE operand.

Note: Each trace option can affect the performance of your host and the VTAM network. Be sure to understand the effect this function can have on performance in your environment before specifying OPTION=ALL.

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

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.

For TYPE=VTAM, OPTION is a listing of the VTAM functions that you want to trace.

When VTAM encounters an exception condition involving an API, NRM, PIU, SSCP, or SMS function, it generates a trace record whether or not you have activated that option.

Note: Although the default options are always active for internal recording, 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.

ALL

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

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

For TYPE=STATE, OPTION=ALL 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, OPTION=ALL specifies that the VTAM internal trace (VIT) is to be started for all of the VTAM internal functions for which the VIT is available, including VCNS trace functions. It is equivalent to specifying all of the internal trace types. Exception trace entries continue to be recorded.

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

OPTION=COMMAND: Starts tracing modules involved in command processing.
OPTION=CONNECTIONS: 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=SESSION: Starts tracing modules involved in session establishment.

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=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:

API

Helps you determine whether an application program is causing a problem. API entries are written for RPL macros, RPL exit routines, user exit routines, and user posts.

APIOPTS

A grouping of multiple VIT options that includes all of the individual VIT options usually required to diagnose potential non-LU 6.2 application program problems. Specifying APIOPTS is equivalent to specifying all of the following VIT options: API, MSG, NRM, PIU, PSS, SMS, and SSCP.

APPC

Helps you determine whether an LU 6.2 application is causing a problem. LU 6.2 entries are written for the following items:

APPCCMD macro invocations
User posts and exit scheduling by LU 6.2 code
Calls to a security manager for security processing
Message unit transmissions between LU 6.2 components

APPCOPTS

A grouping of multiple VIT options that includes all of the individual VIT options usually required to diagnose potential LU 6.2 application program problems. Specifying APPCOPTS is equivalent to specifying all of the following VIT options: API, APPC, MSG, NRM, PIU, PSS, SMS, and SSCP.

CFS

Helps you assess and manage your coupling facility structure.

CIA

Helps isolate problems indirectly related to channel IO by tracing additional data near the time of channel IO activity.

CIO

Helps isolate problems related directly to channel I/O (CIO). CIO entries are written for attentions, error recovery, interruptions, HALT I/O SVC, and START I/O SVC.

CMIP

Indicates whether a CMIP problem is in VTAM or in a CMIP application program.

This option traces:

Calls from CMIP application programs to the management information base (MIB) application programming interface
Calls to the read-queue exit of the CMIP application program
Topology updates from VTAM resources

CPCPOPTS

A grouping of multiple VIT options that includes all of the individual VIT options usually required to diagnose potential CP-CP session problems. Specifying CPCPOPTS is equivalent to specifying all of the following VIT options: API, APPC, MSG, NRM, PIU, PSS, SMS, and SSCP.

CSM

Traces the parameter list information that flows across the communications storage manager (CSM) interface for the following events:

Requests to obtain a buffer
Requests to free a buffer
Requests to assign additional tokens to the buffer
Requests to change the ownership of a buffer
Requests to change the pageable state of a buffer
Requests to copy data to or from a CSM buffer or a user data area
Buffer pool expansion
Buffer pool contraction

Note: For installations using high performance data transfer (HPDT), the use of the CSM trace should be restricted to times when diagnostic information is needed. Using this option on a regular basis minimizes the performance benefits provided by HPDT services.

CSMOPTS

A grouping of multiple VIT options that includes all of the individual VIT options usually required to diagnose potential communications storage manager (CSM) problems. Specifying CSMOPTS is equivalent to specifying all of the following VIT options: API, APPC, CIO, CSM, MSG, NRM, PIU, PSS, SMS, SSCP, and XBUF.

DLUROPTS

A grouping of multiple VIT options that includes all of the individual VIT options usually required to diagnose dependent LU requester (DLUR) problems. Specifying DLUROPTS is eqivalent to specifying all of the following VIT options: API, APPC, HPR, MSG, NRM, PIU, PSS, SMS, and SSCP.

EEOPTS

A grouping of multiple VIT options that includes all of the individual VIT options usually required to diagnose Enterprise Extender (EE) problems. Specifying EEOPTS is equivalent to specifying all of the following VIT options: CIA, CIO, HPR, MSG, NRM, PIU, PSS, SMS, SSCP, and TCP.

ESC

Helps you track, in detail, the flow of requests for a given process.

HPDTOPTS

A grouping of multiple VIT options that includes all of the individual VIT options usually required to diagnose high performance data transfer (HPDT) problems. Specifying HPDTOPTS is equivalent to specifying all of the following VIT options: CIA, CIO, HPR, MSG, PIU, PSS, SMS, and SSCP.

HPR

Helps you isolate problems related to High-Performance Routing (HPR). Events include invocation of the HPRCTL macroinstruction, invocation of the HPR timer control macroinstruction, any LU-LU session data sent across a rapid transport protocol (RTP) connection, a network layer packet (NLP) sent or received, a dispatch of the RTP context manager (RCM) PAB, a dispatch of a RTP PAB, an error detected by RTP, and a route setup sent or received.

HPROPTS

A grouping of multiple VIT options that includes all of the individual VIT options usually required to diagnose High-Performance Routing (HPR) problems. Specifying HPROPTS is equivalent to specifying all of the following VIT options: API, APPC, CIA, CIO, HPR, MSG, NRM, PIU, PSS, SMS, and SSCP.

LCS

Helps you isolate problems occurring during data transfers from an IBM® 3172 Interconnect Controller to VTAM. The LCS option enables tracing of data that VTAM receives from an IBM 3172 Interconnect Controller at four levels: LCSX (cross-channel), LCSP (port or adapter), LCSS (service access point of the adapter) and LCSL (line).

LCSOPTS

A grouping of multiple VIT options that includes all of the individual VIT options usually required to diagnose LAN channel station (LCS) problems. Specifying LCSOPTS is equivalent to specifying all of the following VIT options: CIO, LCS, MSG, NRM, PIU, PSS, SMS, and SSCP.

LOCK

Helps you determine when VTAM modules get and release locks.

MSG

Helps you correlate other VIT internal entries with the console messages even if the console sheet is lost. MSG entries are written for all messages to the VTAM operator.

NONE

Specifies that no traces are active.

NRM

Helps you follow the services of the network resource management component. These include the assignment of, references to, and the deletion of certain VTAM resources such as node names, network addresses, and control blocks. NRM entries are written for all I/O and buffer contents traces.

PIU

Helps you isolate problems to hardware, to the NCP, or to VTAM. PIU entries are written for all I/O to and from VTAM, which can be an advantage over I/O and buffer content traces.

PSS

Helps you track the flow of requests through VTAM. PSS entries are written for the VTAM macros that invoke and control PSS, and for scheduling and dispatching VTAM routines.

QDIOOPTS

A grouping of multiple VIT options that includes all of the individual VIT options usually required to diagnose queued direct I/O (QDIO) problems. Specifying QDIOOPTS is equivalent to specifying all of the following VIT options: CIA, CIO, HPR, MSG, NRM, PIU, PSS, SMS, and SSCP.

SMS

Helps you isolate problems caused by storage shortages. When used with the SSCP or PSS trace options, it can also help you isolate internal VTAM problems. SMS entries are written when SMS macros are used to request or release fixed-length or variable-length buffers. SMS entries are also written when VTAM expands or attempts to expand a buffer pool.

SSCP

Helps you isolate problems to a specific VTAM component or module. SSCP entries are written for the request or response units (RUs) sent between VTAM components.

STDOPTS

A grouping of multiple VIT options that includes all of the individual VIT options usually required to diagnose problems related to high CPU, session services, storage, Open/Close ACB, and DLCs such as MPC and CTC. Specifying STDOPTS is equivalent to specifying all of the following VIT options: API, CIO, MSG, NRM, PIU, PSS, SMS and SSCP.

TCP

Helps you trace Enterprise Extender events.

TCPOPTS

A grouping of multiple VIT options that includes all of the individual VIT options usually required to diagnose problems related to TCP/IP. Specifying TCPOPTS is equivalent to specifying all of the following VIT options: CIA, CIO, MSG, NRM, PIU, PSS, SMS, SSCP, and TCP.

VCNS

Helps you determine whether a VCNS application is causing a problem. VCNS entries are written for VCNSCMD macro invocations, user posts, and exit scheduling by VCNS code, and work element transmissions between VCNS components.

XBUF

Records information contained within the extended buffer list, particularly in regard to information on CSM usage by VTAM. This option traces the contents from the application supplied extended buffer list as well as the internal buffer list that VTAM uses to carry the extended buffer list information.

Note: For installations using high performance data transfer (HPDT), the use of the XBUF trace should be restricted to times when diagnostic information is needed. Using this option on a regular basis minimizes the performance benefits provided by HPDT services.

XCF

Helps you trace XCF communication.

XCFOPTS

A grouping of multiple VIT options that includes all of the individual VIT options usually required to diagnose cross-system coupling facility (XCF) problems. Specifying XCFOPTS is equivalent to specifying all of the following VIT options: CIA, CIO, HPR, MSG, NRM, PIU, PSS, SMS, SSCP, and XCF.

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.

Restriction: If you specify a SIZE value that is larger than the default value, z/OS® performs 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 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 TREE and TGVC are defined under the SSCP trace option, subtrace ARBP is defined under the HPR trace option, and subtrace DIO is defined under the CIA trace option.

Recommendation: All of the SUBTRACE options are defaulted to off. They can generate a large number of 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 the ARB (Adaptive Rate Based) algorithm performance trace records that are to be generated. The OPTION operand is required 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 Direct IO related trace records are to be generated. The OPTION operand is required 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 APPN transmission group vector (TGVC) trace records are to be generated. The OPTION operand 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, TGV2. If large amounts of data are being traced, additional TGVC records (plus subsequent TGV2 records) may occur.
SUBTRACE=TREE: Specifies the APPN routing tree trace records that are to be generated. The OPTION operand is required 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.

TYPE=MODULE

Specifies whether a module trace is started or stopped for the types of modules listed on the OPTION operand.

TYPE=STATE

Specifies whether a resource state trace is started or stopped to monitor changes in the state of the type of resources listed on the OPTION operand.

TYPE=VTAM

Specifies the VTAM internal trace (VIT).

Use IBM Health Checker for z/OS to check whether various VTAM internal trace parameters have been set to values that reflect best practices. For more details about IBM Health Checker for z/OS, see z/OS Communications Server: IP Diagnosis Guide.