Using IPCS to print trace records written to GTF

When GTF trace is on, and the CICS® master trace flag is also on, CICS writes trace entries to a GTF data set. CICS writes these records by issuing the GTRACE macro with the following parameters specified:

FID=X‘EF’
The format identifier (FID) of the CICS GTF trace entry
ID=X‘F6C’
The subsystem event trace identifier for CICS GTF trace entries.

You can print CICS trace entries written to GTF by invoking IPCS with the GTFTRACE subcommand, and specifying the USR parameter with the event trace identifier of the records you want IPCS to select for formatting. You can also specify most of the DFHTU640 selective trace control statements on the CICS(text) parameter. The CICS-supplied formatting routines are called DFHTG640 and DFHTR640, supplied in CICSTS31.CICS.SDFHLINK. DFHTG640 has the alias of AMDUSREF. The last two characters of the AMDUSREF alias ("EF") correspond to the format identifier (FID), and enable IPCS to invoke the CICS formatting routine automatically when you use the GTFTRACE subcommand.

Several CICS regions, at different CICS releases, can write to the same GTF data set. You can print GTF trace entries written to GTF using the same GTFTRACE command. To do so, you must make available the formatting routine for each CICS release. For example, for CICS Transaction Server for z/OS®, Version 3 Release 1, you would need to specify DFHTG640, its alias AMDUSREF, and DFHTR640.

The GTFTRACE subcommand of IPCS and associated parameters

To use IPCS to format and print CICS trace entries, you must specify the GTFTRACE subcommand. The following are the main IPCS GTFTRACE parameters that you need to process CICS trace entries:

GTFTRACE
Use this IPCS subcommand to format CICS trace records contained in a GTF trace data set.
JOBNAME({name1[,name2,.,namen]})
Code this to specify one or more jobnames for which you want DFHTR640 to format trace entries.
CICS(CICS trace selection parameters)
Code this parameter to specify any selection and formatting control statements required by the CICS formatting routine, DFHTR640. You can code any of the DFHTU640 parameters except EXCEPTION, PAGESIZE and TIMERG, which are not allowed. You can change the default pagesize by using the IPCS subcommand PROFILE PAGESIZE(value); for an example, see Figure 26. For further information about the PROFILE PAGESIZE subcommand, see the z/OS MVS IPCS Commands. (You can use the GTFTRACE START and STOP parameters in place of TIMERG; see below.)
Note:
The whole string of CICS trace selection parameters must be enclosed in parentheses. If your CICS trace selection parameter is more than can be contained on one line, terminate the line with a right parenthesis followed by a comma, and specify the remainder on the next line. You must repeat the CICS keyword on the continuation line(s).
START(ddd,hh.mm.ss) and STOP(ddd.hh.mm.ss)
Code the START and STOP parameters to specify trace entries for a particular time range. If you omit the STOP parameter, IPCS continues processing until it reaches the end of the data set.
USR(event-id-value-list|ALL)
Code this parameter to specify formatting of subsystem event trace records created by the GTRACE macro. The trace ID for CICS GTF trace entries is ‘CICS’, which translates to X'F6C'. For information about the IDs of other subsystem trace records (for example, VSAM, VTAM®), see the z/OS MVS IPCS Commands . (You can code X'F6C' directly for the CICS trace event ID; USR(CICS) is an alias for USR(F6C).)

Specify ALL to request formatting of all subsystem trace entries.

There are many other parameters that you can specify on the GTFTRACE subcommand of IPCS. For information about the GTFTRACE command, see the z/OS MVS IPCS Commands .

Sample batch job to print CICS GTF trace entries

You can specify the GTFTRACE subcommand of IPCS in TSO, or in a batch job as shown in Figure 26.

Figure 26. Sample IPCS job to print CICS trace entries from a GTF data set
Start of change//IPCSGTF  JOB ( accounting info),
//             CLASS=A,MSGCLASS=H,MSGLEVEL=(1,1),NOTIFY=userid
//PRINTTR  EXEC PGM=IKJEFT01,REGION=4096K
//STEPLIB  DD DSN=CICSTS31.CICS.SDFHLINK,DISP=SHR             1 
//         DD DSN=CICSTS23.CICS.SDFHLINK,DISP=SHR
//DFHTRACE DD DSN=GTF.TRACEnn,DISP=SHR
//IPCSDDIR DD DSN=ipcs.dump.directory,DISP=SHR           2 
//SYSABEND DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//IPCSPRNT DD SYSOUT=*
//SYSTSIN  DD *
IPCS NOPARM
SETDEF DD(DFHTRACE) NOPROBLEM PRINT NOCONFIRM NOTERMINAL LIST
PROFILE PAGESIZE(60)
GTFTRACE +
CICS((ABBREV,TERMID=LP1,TRANID=<ABRW,AORD>,)) +
CICS((TYPETR=(SM01FF-03BC),TASKID=(J01,J03-J05,TCP))) +
USR(F6C)
END
/*
//End of change

Notes:  1  The batch job in Figure 26 includes a STEPLIB statement for the load libraries that contain the modules (DFHTG640, its alias AMDUSREF, DFHTR640, DFHTG640, its alias AMDUSREF and DFHTR640) to be used to format the GTF trace entries. Depending on which releases of CICS have GTF trace entries to be printed, you should include the following libraries in the STEPLIB concatenation:

Start of change
STEPLIB CICS releases to be formatted
CICSTS31.CICS.SDFHLINK CICS Transaction Server for z/OS, Version 3 Release 1 only.
CICSTS31.CICS.SDFHLINK
CICSTS23.CICS.SDFHLINK

CICS Transaction Server for z/OS, Version 3 Release 1, and CICS Transaction Server for z/OS, Version 2 Release 3
CICSTS31.CICS.SDFHLINK
CICSTS22.CICS.SDFHLINK

CICS Transaction Server for z/OS, Version 3 Release 1, and CICS Transaction Server for z/OS, Version 2 Release 2
CICSTS31.CICS.SDFHLINK
CICSTS13.CICS.SDFHLINK

CICS Transaction Server for z/OS, Version 3 Release 1, and CICS Transaction Server for OS/390®, Version 1 Release 3
End of change

 2  The IPCSDDIR statement specifies a directory data set needed by IPCS. A sample job to create an IPCS directory data set is given in Figure 32.

Invoking the CICS formatting routine from TSO

To enable the CICS formatting routines to be invoked from TSO, copy the modules DFHTG640, AMDUSREF, DFHTR640, and DFHTRVR3 to a suitable library in the MVS™ linklist, or ensure that the CICS libraries listed above are included in the MVS linklist.

Ensure that you have sufficient TSO storage (specified for your TSO userid when you logon) for GTF trace formatting, because otherwise storage fragmentation causes formatting problems. When using one job to format trace entries for several CICS releases, the loading of the multiple release formatters needed uses more storage.

Related reference
Trace utility print program (DFHTU640)
The CICS trace utility program, DFHTU640
The trace selection parameters for DFHTU640
[[ Contents Previous Page | Next Page Index ]]