GTFTRACE subcommand — format GTF trace records

Use the GTFTRACE subcommand to format generalized trace facility (GTF) records contained in a dump or in a trace data set. The GTF records must be in a single source. If you have multiple GTF trace data sets, use the COPYTRC subcommand to combine the trace records into one data set.

Syntax

      {GTFTRACE } [ ASCB(ascb-address-list) ]
      {GTF      } [ ASID(asidlist) ]
                  [ JOBNAME(joblist) | JOBLIST(joblist) ]
                  [ BEGINFIRST ]
                  [ BEGINOLD   ]
                  [ CICS((text)) ]
                  [ CPU(cpu-address) ]
                  [ DEBUG ]
                  [ EOF ]
                  [ EXIT(pgmname) ]
                  [ START(ddd,hh.mm.ss) ]
                  [ STOP(ddd,hh.mm.ss)  ]
                  [ STARTLOC(ddd,hh.mm.ss) ]
                  [ STOPLOC(ddd,hh.mm.ss)  ]
                  [ SYSNAME(name-list) ]

-------------- Data Selection Parameters -------------------

                  [ CCW[(record-type)] ]
                  [ DSP ]
                  [ EXT ]
                  [ IO[(device-number-list)]            ]
                  [ SSCH[(device-number-list)]          ]
                  [ IOSSCH|SSCHIO[(device-number-list)] ]
                  [ IOX[(device-number-list)] ]  
                  [ PCIE[(pfid-list)] ]
                  [ PI[(codelist)] ]
                  [ RNIO ]
                  [ RR ]
                  [ SLIP ]
                  [ SRM ]
                  [ SVC[(svclist) ] ]
                  [ SYS ]
                  [ USR   {(symbol-list)  } ]
                  [       {(idvalue-list) } ]
                  [       {(idrange-list) } ]
                  [       {(ALL)          } ]

-------- SETDEF-Defined Parameters -------------------------
Note: You can override the following SETDEF parameters.
See SETDEF subcommand — set defaults.

                 [ ACTIVE | MAIN | STORAGE          ]
                 [ DSNAME(dsname) | DATASET(dsname) ]
                 [ FILE(ddname) | DDNAME(ddname)    ]
                 [ PATH(path-name)     ]
                 [ PRINT | NOPRINT ]
                 [ TERMINAL | NOTERMINAL ]
                 [ TEST | NOTEST ]
                 [ FLAG(severity) ]

Note: The PATH keyword is only intended to refer to a dump data set, not an external trace.

Parameters
If you need more than one physical line to enter the GTFTRACE subcommand, continue it with a plus or minus sign as you do with any TSO/E command.
```
Command ===>GTFTRACE DD(SYSTRACE) IO(D34,D0C,ED8,+
           FFF,2A0,2E4)
```
Standard TSO/E continuation techniques apply to all GTFTRACE subcommand parameters.
ASCB(ascb-address-list)

Specifies ASCB addresses corresponding to the trace entries and user records you want to format. Specify the ASCB address list as one or more 1- to 8-digit hexadecimal addresses, separated by commas.

ASID(asidlist)

Specifies a list of ASIDs for the address spaces for which trace entries and user records are to be formatted. The asidlist can be a single ASID or a list of noncontiguous ASIDs. When you specify a list, separate the list members with commas. The ASID can be 1 through 65535.
Note: ASID is ignored when processing data from a trace data set.

JOBNAME(joblist) or JOBLIST(joblist)
Specifies one or more job names for which trace entries and user records are formatted. Each job name can be up to 8 characters long. Job names specified for SYSMDUMP data sets are ignored. SYSMDUMPS do not contain the job name field.
Both generic and specific job names may be used in the joblist. A generic job name may use the following wildcards:
Asterisks to denote any string of valid characters, including no characters. You may use one or more asterisks in any position.

Percent signs to denote one valid character. Use one percent sign for each character position.
For example, given the following job names:
MPA MPPA MPP1A MAP1A M00PA MPP01A MPPABA MPPABCA

MPP*A will match these job names: MPPA, MPP1A, MPPABA, MPPABCA

M*P*A will match all job names in the list.

MPP%%A will match these job names: MPP01A, MPPABA

Note: *MASTER* represents the master address space.
BEGINFIRST

Requests that formatting start with the first block of records in a trace data set, regardless of TAPE/DASD or wrapping. BEGINFIRST is the default for tape data sets; it is ignored for dumps. BEGF may be used as the short form of this parameter.

BEGINOLD
Requests that formatting start with the oldest block of records in a trace data set. The command determines the oldest time stamp record, regardless of where the data set resides (TAPE/DASD). GTFTRACE creates the symbol GTFWRAP to save the number of the oldest block across IPCS sessions.
However, the GTFWRAP symbol will not be created if both of the following are true:
The trace data set has been placed in IPCS fast path access mode (that is, normal initialization of the trace data set has been bypassed).

The trace data set is wrapped (the first trace record in the data set is not the oldest trace record in the data set).
BEGINOLD is the default for DASD data sets; it is ignored for dumps. BEGO may be used as the short form of this parameter.
CICS((text))

Specifies that the entered text be placed in a buffer, preceded by a fullword-length field, and that the address of this text buffer be placed in the work area list entry corresponding to the format identification disk (X'EF') assigned to the Customer Information Control System (CICS®) This processing makes the text string addressable by the CICS formatting appendage, AMDUSREF.

CPU(cpu-address)

Specifies that events occurring on the central processor whose physical identifier is cpu-address be formatted. The cpu-address can be any CPU address supported by the current release. And you can use decimal, hexadecimal (X'xxx...'), or binary (B'bbb...') notations to specify the cpu-address.
CPU filtering is only effective with IO-related trace records. Records which are subject to CPU filtering are SSCH, CSCH, HSCH, MSCH, RSCH, IO, EOS, PCI, and CCW.

DEBUG

Specifies the display of the internal control table after parsing the parameters entered on the GTFTRACE subcommand.

EOF

Specifies that the exit routine identified by the EXIT parameter is to receive control on all GTFTRACE normal and abnormal ending conditions.

EXIT(pgmname)

Specifies the program name of a user-written exit routine that inspects all trace data records. When the EOF parameter is specified, IPCS also passes control to this routine at the logical end of the trace data. If the routine does not exist or if IPCS cannot successfully load it, GTFTRACE processing ends and IPCS processes the next subcommand.

START(ddd,hh.mm.ss) or STARTLOC(ddd,hh.mm.ss)

STOP(ddd,hh.mm.ss) or STOPLOC(ddd,hh.mm.ss)

Specifies that the blocks for processing lie between times. The times for START and STOP are GMT; STARTLOC and STOPLOC indicate local time. IPCS formats only those records that you request with trace data selection parameters. When you do not specify START or STARTLOC, GTFTRACE starts at the beginning of the data set, or at the first block in a dump. When you do not specify STOP or STOPLOC, GTFTRACE completes processing after it reads the end of the data set, or the last block in a dump. The record timestamps are not used, and can have times greater than the block timestamp. ‘ddd’ is Julian day, and ‘hh.mm.ss’ is the hours, minutes and seconds as set in the TOD clock.
Note: You do not need to specify leading zeros.

SYSNAME(name-list)

Filters the GTF data merged from several data sets. When SYSNAME is specified, the GTF data will be formatted only if its system name agrees with one of the values in the name-list. SYSNAME will accept up to 16 names in the name-list.

Data Selection Parameters

Use these parameters to limit the kinds of trace records processed. For these parameters, the phrase “base record” means the first record of the many records that form one logical record. If you omit data selection parameters, the default is SYS.

CCW(record-type)

Requests that channel program trace records be formatted. To format CCW trace records, IPCS formats either SSCH base records or I/O base records, or both. For record-type, you can specify:

I: Requests formatting of all the CCW trace records for I/O events, and, if present, program-controlled interrupt (PCI) events. IPCS formats I/O base records even if you do not specify the IO parameter. When you specify both the IO parameter and CCW(I), IPCS formats only the CCW trace records for events on the devices identified on the IO parameter.
S: Requests formatting of all CCW trace records for start subchannel and resume subchannel operations. IPCS formats SSCH base records even if you do not specify the SSCH parameter. When you specify both the SSCH parameter and CCW(S), IPCS formats only the CCW trace records for events on the devices identified by the SSCH parameter.
SI: Requests formatting of all CCW, I/O, start subchannel, and resume subchannel trace records in the specified data set. IPCS formats SSCH and I/O base records even if you do not specify the SSCH and IO parameters. When you specify the SSCH and IO parameters, with either CCW or CCW(SI), IPCS formats only the CCW trace records for events on the devices identified by the SSCH and IO parameters.

DSP

Requests that IPCS format all dispatching event trace records.

EXT

Requests that IPCS format all trace records for external interruptions.

IO[(device-number-list)]

SSCH[(device-number-list)]

IOSSCH|SSCHIO[(device-number-list)]

Request formatting of I/O trace records, SSCH trace records, or both. Supplied alone, the IO parameter specifies formatting of IO, PCI, HSCH, CSCH, and MSCH trace records. The SSCH parameter tells IPCS to format start and resume subchannel trace records. SSCHIO and IOSSCH are synonymous. Either one requests formatting of both I/O and start and resume subchannel records.

The device-number-list can contain from 1 to 50 device numbers, for which you want either or both types of trace records formatted. IPCS formats trace records only for the specified devices. If you do not specify any device numbers, IPCS formats trace records for all devices.

IOX(device-number-list)

Requests formatting of I/O Summary trace records. The device-number-list can contain from 1 to 50 three-digit device numbers, for which you want records formatted. IPCS formats trace records only for the specified devices. If you do not specify any device numbers, IPCS formats trace records for all devices.

PCIE[(pfid-list)]

Requests formatting of PCIE-related events. The pfid-list specifies the PCIE function identifiers (PFIDs) for which records are to be formatted. PFIDs are 1 to 8 hexadecimal digits. If you do not specify any PFIDs, IPCS formats the trace records for all of the PFIDs found in the trace. End of change

PI[(codelist)]

Specifies formatting of program interruption trace records, for the interruption codes in codelist. codelist can contain 0 to 255 decimal interruption codes of one to three digits each. If you do not specify any codes, IPCS formats trace records for all the program interruption codes found in the dump.

RNIO

Requests formatting of all the records for VTAM® remote network activities.

RR

Requests formatting of all recovery routine event records.

SLIP

Requests formatting of all SLIP trace records.

SRM

Requests formatting of system resources manager (SRM) event records.

SVC[(svclist)]

Requests display of the formatted trace records associated with the numbers specified in svclist. The svclist can contain 0 to 255 decimal SVC numbers of 1 to 3 digits each.

SYS

Requests formatting of all system event trace records. SYS, the default, formats all the GTF trace records that were recorded in a dump or trace data set except for USR records.

USR ({symbol-list | idvalue-list | idrange-list | ALL})

Requests formatting of user/subsystem trace records created by the GTRACE macro. The symbol-list or idvalue-list denote trace records belonging to one component or subsystem. GTRACE data consists of user event trace records or IBM® subsystem event records from these subsystems:

OPEN/CLOSE/EOV
SAM/PAM/DAM
VTAMVSAM

The symbol-list contains 1 through 20 symbols, with multiple symbols separated by commas. When ID values are assigned to a subsystem, the component defines the symbol that is used. The following table shows valid symbols and their corresponding ids and subsystems:

Symbol	ID	Subsystem
AM01	FF5	VSAM
APTH	FE2	TSO/VTAM TGET/TPUT trace
APTR	FE3	VTAM reserved
CL01	FF1	VTAM buffer contents trace (USER)
CL02	FF0	VTAM SMS (buffer use) trace
DB2V	F5F	DB2/VSAM transparency
DMA1	FFF	OPEN/CLOSE/EOV
FSI4	F54	FSI trace
FSI5	F55	FSI trace
FSI6	F56	FSI trace
FSI7	F57	FSI trace
FSI8	F58	FSI trace
FSI9	F59	FSI trace
FSIA	F5A	FSI trace
FSIB	F5B	FSI trace
FSIC	F5C	FSI trace
FSID	F5D	FSI trace
INT1	FE1	VTAM internal table
OSIC	F53	OSI Communication Subsystem
SPD1	FF3	SAM/PAM/DAM
SPD2	FF4	SAM/PAM/DAM
SPD3	FF6	SAM/PAM/DAM
SPD4	FF7	SAM/PAM/DAM
SPD5	FF8	SAM/PAM/DAM
SPD6	FF9	SAM/PAM/DAM
SPD7	FFA	SAM/PAM/DAM
SPD8	FFB	SAM/PAM/DAM
SPD9	FFC	SAM/PAM/DAM
SPDA	FFD	SAM/PAM/DAM
SPDB	FFE	SAM/PAM/DAM
TPIO	FEF	VTAM buffer contents trace

The idvalue-list contains 1 through 20 values, which are 3-digit hexadecimal identifiers assigned to a subsystem. If more than one value is specified, separate them with commas. The following table shows valid identifiers and their corresponding subsystems:

ID	Issued by
000-3FF	GTF user program
400-5F0	Reserved for IBM Use
5F1	PVM
5F2-5F3	Reserved for IBM Use
5F4-5F5	NetView® System Monitor
5F6-F47	Reserved for IBM Use
F48	IOS
F49	BDT
F4F	OSAM
F50-F52	Reserved for IBM Use
F53	OSI Communications Subsystem
F54-F5D	FSI
F5E	Reserved for IBM Use
F5F	DB2®
F60	JES3
F61	VSAM Buffer Manager
F62	Dynamic output SVC installation exit
F63	Converter/Interpreter installation exit
F64	APPC/VM VTAM Support (AVS)
F66-F6A	VTAM
F6C	CICS
FAA	VTAM VM/SNA Console Services (VSCS)
FAB-FAE

The idrange-list contains 1 through 20 ID value ranges, which are the first and last 3-digit values of the id range, separated by a hyphen. If more than one range is specified, separate them with a comma.

ALL requests formatting of all user and subsystem trace records. ALL overrides any idvalue, idrange, or symbol specification.

Return codes
See Standard subcommand return codes for a description of the return codes produced by the GTFTRACE subcommand.
Example: For examples of GTFTRACE output, see the GTF trace in z/OS MVS Diagnosis: Tools and Service Aids.