Quickstart for trace

CICS auxiliary trace

Use CICS auxiliary trace to collect large amounts of trace data or to get a trace of CICS activity in which trace entries are not overwritten.

Start CICS auxiliary trace

If your problem is occurring at CICS startup, set the tracing status at CICS initialization using the following system initialization table (SIT) parameters:

• SYSTR=ON
• AUXTR=ON
• AUXTRSW=NO
• STNTR=1 to turn level 1 tracing on for all CICS components
• STNTRxx=1 where xx is a specific component abbreviation

If your problem is occurring after CICS startup, use CETR to control trace. Enter the following values on the initial CETR screen:

Auxiliary Trace Status ===> Started
Auxiliary Switch Status ==> Next or NO
Main System Trace Flag ==> On

Enter PF4 to display a list of CICS components. In the column entitled Standard, enter 1 or 1-2 to the right of all components depending on the level of tracing required. Press Enter to apply your changes and then PF3 to exit from the components screen.

For more information, see the following topics:

• Setting trace destinations and tracing status
• Component names and abbreviations

Re-create the failure or problem

Re-create the failure or problem by repeating the series of actions you previously took.

Stop CICS auxiliary trace

Use CETR and enter Stopped in the Auxiliary Trace Status.

Auxiliary Trace Status ===> Stopped

Format and interpret CICS auxiliary trace

Format the trace data using the trace utility print program (DFHTUxxx) where xxx is the version of CICS you used to create the trace (for example, DFHTU730 for CICS TS 5.6).

For details, see Formatting and interpreting trace entries.

CICS internal trace

Use CICS internal trace for first failure data capture (FFDC). The CICS internal trace table resides in 64-bit storage. On busy systems, large trace tables can fill up in several seconds. Therefore, a trace table size of 10240K is recommended with an alternative of 4096K.

Start CICS internal trace

If your problem is occurring at CICS startup, set the tracing status at CICS initialization using the following SIT parameters:

• INTTR=ON
• SYSTR=ON
• STNTR=1 to turn level 1 tracing on for all CICS components
• STNTRxx=1 where xx is a specific component abbreviation
• TRTABSZ=10240

If your problem is occurring after CICS startup, use CETR to control trace. Enter the following values on the initial CETR screen:

Internal Trace Status ===> Started
Internal Trace Table Size ===> 10240
Main System Trace Flag ==> On

Enter PF4 to display a list of CICS components. In the column entitled Standard, enter 1 or 1-2 to the right of all components depending on the level of tracing required. Press Enter to apply your changes and then PF3 to exit from the components screen.

For more information, see the following topics:

• Setting trace destinations and tracing status
• Component names and abbreviations

Re-create the failure or problem

Re-create the failure or problem by repeating the series of actions you previously took.

Stop CICS internal trace

Use CETR and enter Stopped in the Internal Trace Status.

Internal Trace Status ===> Stopped

Format and interpret CICS internal trace

Format the internal trace table in one of two ways:

• From a CICS system dump, using IPCS and the CICS print dump exit, DFHPDxxx

  Specify TR=1 to select abbreviated trace and TR=2 to select full trace. Select parts of the CICS internal trace by specifying the TRS parameter.

  For example, you could enter the following when using IPCS:

  1. Enter 0 to display the Defaults panel.
  2. Enter the dump dataset name:

     Source ==> DSNAME('dump.dataset.name')

  3. Enter =6 to display the Command panel.
  4. Enter one of the following commands:
     Note: Update DFHPDxxx depending on your CICS release.
     To select abbreviated trace:

     ==> VERBX DFHPD730 'TR=1'

     To select full trace:

     ==> VERBX DFHPD730 'TR=2,TRS=<TASKID=nnnnn>'

  5. Enter N in response to the following message:

     BLS18160D May summary dump data be used by dump access?

• From a transaction dump, using the CICS dump utility program, DFHDUxxx

  The default action is that the trace will be printed in abbreviated followed by full formats. DFHDUxxx will only format trace entries for the task that the transaction dump was taken for.

  For details, see Formatting transaction dumps and Interpreting transaction dumps.

CICSPlex SM WLM trace

Use CICSPlex® SM Workload Manager (WLM) trace from the routing region to determine why there is a routing failure.

Start WLM trace

Step1. Start auxiliary trace in the CMAS and in the routing region

If your problem is occurring at CICS startup, set the tracing status at CICS initialization using the SIT parameters:

• INTTR=ON
• TRTABSZ=10240
• SYSTR=OFF in the CMAS
• SYSTR=ON in the routing region
• USERTR=ON (CICSPlex SM writes user trace entries)
• AUXTR=ON
• AUXTRSW=NO

If your problem is occurring after CICS startup, use CETR to control trace. Enter the following values on the initial CETR screen:

Internal Trace Status ===> Started
Internal Trace Table Size ===> 4096
Main System Trace Flag ==> Off in the CMAS and On in the routing region
Main User Trace Flag ==> On
Auxiliary Trace Status ===> Started
Auxiliary Switch Status ==> NO

Press Enter to apply your changes and then PF3 to exit from the components screen.

For more information, see Setting trace destinations and tracing status.

Step 2. Turn on WLM trace in the CMAS

1. From the WUI main menu, click CICSPlex SM operations views.
2. From the CICSPlex SM operations views menu, click MASs known to CICSplex.
3. From this view (EYUSTARTMAS.TABULAR), find the active MAS for the routing region to trace.
4. Click the active CMAS name for this region to display the CMAS detail.
5. Scroll to the bottom and click the Trace details link to display the CMAS detail (EYUSTARTCMAS.TRACE) view.
6. Scroll down to the Workload Management trace flags, and enter 30-31.
7. Click Apply changes.

Step 3. Turn on WLM trace in the MAS

1. Go back to the MASs known to CICSplex view (EYUSTARTMAS.TABULAR).
2. From this view (EYUSTARTMAS.TABULAR), find the active MAS for the routing region to trace.
3. Click the MAS name for this region to display the MAS detail (EYUSTARTMAS.DETAILED) view.
4. Scroll to the bottom and click the Trace details link to display the MAS detail (EYUSTARTMAS.TRACE) view.
5. Scroll down to the Workload Management trace flags and enter 18,19,23-27.
6. Click Apply changes.

Re-create the failure or problem

Re-create the failure or problem by repeating the series of actions you previously took.

Take a dump

/DUMP COMM=(your dump title)
/R xx,JOBNAME=(EYUXvrm,cmasname,lmasname
),DSPNAME=('EYUXvrm'.*),CONT
/R yy,SDATA=(ALLNUC,LPA,LSQA,PSA,RGN,SQA,TRT,CSA,GRSQ),END

where EYUXvrm is the ESSS for your release.

Save the unformatted auxiliary trace data sets for review by CICS Support.

Stop WLM trace

Use the instructions above to turn off the WLM flags in the CMAS and MAS by setting them to blank.

Stop auxiliary trace by using CETR. Enter Stopped in the Auxiliary Trace Status.

Format and interpret WLM trace

If you wish to format the trace data from both the CMAS and the MAS routing region, use the CICSPlex SM trace utility program EYU9XZUT program. For details, see Formatting CMAS and MAS trace entries.

See also Using the WUI to control CMAS and MAS tracing.

GTF trace

Use the generalized trace facility (GTF) to simultaneously write trace data to a single dataset from MVS and multiple subsystems like CICS, VTAM®, and Db2®.

Start GTF trace

Step 1. Start GTF trace under MVS

Enter the following MVS commands:

S GTF.identifier
R yy,TRACE=USRP,SYS,DSP,JOBNAMEP
R yy,USR=(F6C,xxx),JOBNAME=cicsjob,END
R yy,U

where yy is the number of the message.

F6C is the user trace ID for CICS trace. SYS and DSP are optional but commonly requested. For a full list of trace options, see GTF trace options in the z/OS MVS Diagnosis: Tools and Service Aids Guide.

Step 2. Start GTF trace in CICS

If your problem is occurring at CICS startup, set the tracing status at CICS initialization using the following SIT parameters:

• SYSTR=ON
• GTFTR=ON
• STNTR=1 to turn level 1 tracing on for all CICS components
• STNTRxx=1 where xx is a specific component abbreviation

If your problem is occurring after CICS startup, use CETR to control trace. Enter the following values on the initial CETR screen:

GTF Trace Status ===> Started
Main System Trace Flag ==> On

Enter PF4 to display a list of CICS components. In the column entitled Standard, enter 1 or 1-2 to the right of all components depending on the level of tracing required. Press Enter to apply your changes and then PF3 to exit from the components screen.

For more information, see the following topics:

• Setting trace destinations and tracing status
• Component names and abbreviations

Re-create the failure or problem

Re-create the failure or problem by repeating the series of actions you previously took.

Stop GTF trace

1. Use CETR to stop trace by entering Stopped in the GTF Trace Status.

   
   GTF Trace Status ===> Stopped

2. Enter MVS command Stop identifier to stop GTF trace. For instructions, see Stopping GTF in the z/OS MVS Diagnosis: Tools and Service Aids Guide.

Format and interpret GTF trace

Use IPCS to format GTF trace with the GTFTRACE subcommand. For instructions, see Using IPCS to print trace records written to GTF.

For example, you can view the trace using TSO, and you could enter the following commands:

1. Enter 0 to display the Defaults panel.
2. Enter the trace dataset name:

   Source ==> DSNAME('trace.dataset.name')

3. Enter =6 to display the Command panel.
4. Enter one of the following commands:

   ==> GTFTRACE USR(ALL)
   ==> GTFTRACE JOBNAME(cicsjob) USR(F6C)
   ==> GTFTRACE USR(F6C) sys dsp

Alternatively, you can format the trace as a batch program.

Read the GTF trace. See Reading GTF output in the z/OS MVS Diagnosis: Tools and Service Aids Guide.

Language Environment feature trace

Use Language Environment® (LE) Feature Trace (FT) to see trace entries for important LE events during the life of a CICS transaction. FT adds trace points inside LE at Event Handle and Set anchor points. It also provides register 13 and parameters before the LE call.

Start LE feature trace

Start trace using the instructions for starting CICS auxiliary trace, CICS internal trace, or GTF trace depending on the destination you choose. Start FT trace by turning on level 2 tracing for the CICS application domain (AP=1-2):

• If your problem is occurring at CICS startup, set the tracing status at CICS initialization using the following SIT parameters:
  • SYSTR=ON
  • STNTRAP=(1,2)
• If your problem is occurring after CICS startup, use CETR to control trace. Enter the following values on the initial CETR screen:

  Main System Trace Flag ==> On

  Enter PF4 to display a list of CICS components. In the column entitled Standard, enter 1-2 to the right of the AP component. Press Enter to apply your changes and then PF3 to exit from the components screen.

Re-create the failure or problem

Re-create the failure or problem by repeating the series of actions you previously took.

Stop LE feature trace

Use CETR:

1. From the initial CETR screen, enter PF4.
2. Enter 1 or OFF to the right of the AP component.
3. Press Enter to apply your changes and then PF3 to exit from the components screen.

Format and interpret LE feature trace

Format FT using the instructions for formatting CICS auxiliary trace, CICS internal trace, or GTF trace depending on the destination you choose. Ensure that CEL4TFMT is in the STEPLIB before formatting the LE trace entries. Otherwise, you will receive message DFHTR5002 stating that the feature formatting program has failed.

Feature trace entries contain a domain identifier of FT. The format of these entries is slightly different from standard trace points. The module identifier contains the short name of the feature and a full module name. Data areas contain the following:

• Event Handler Data Areas:

  Data Area 1 contains register 13 and Event Handler ID in the first two full words. The rest of Data Area 1 consists of 4-byte integers representing each parameter that is passed in the call. This is usually the value passed, but may be the address of the structure passed.

  Data Area 2 (Trace entry 1018) contains EICB.

• Set Anchor Data Areas:

  Data Area 1 contains register 13 (first word), CAA address of this run unit (2nd word), and CEEEDB_CREATOR_RINI which equates to identify creator of an enclave (3rd word).

See also Activating Language Environment feature trace records under CICS in the z/OS Language Environment Debugging Guide.

Language Environment traceback

Use Language Environment (LE) traceback to see a sequential list of all active routines and the routine names, statement numbers, and offsets where the exception occurred.

1. Use LE option TERMTHDACT to determine level of information that LE produces when a failure occurs and the destination of the information.

   For the best performance, specify TERMTHDACT=(MSG) when traceback is not needed. If the traceback is required, specify TERMTHDACT=(TRACE,CICSDDS). The CICSDDS option directs the LE diagnostic output to the CICS dump dataset, rather than to the CESE transient data queue.

   Note: Java™ applications in CICS use MVS LE services rather than CICS LE services. As a result, CICSDDS is not an option and LE writes the traceback information to CEEDUMP.
2. Format LE storage areas and the AP domain for a task by entering IPCS command VERBX DFHPDxxx 'APS=<taskid=nnnnn>' where nnnnn is the task number.
   • CICS routines call the LE verb exit and produce the same output as VERBX CEEERRIP ASID(00nn) CAA(xxxxxxxx) DSA(xxxxxxxx) ALL.
   • This eliminates the need to determine the DSA address (register 13) and the CAA address (register 12).
   • This formats the LE traceback, CAA, PCB, MEML, RCB, EDB, Runtime options, Heap control blocks, Stack storage control blocks (User and Lib), DSA, and Condition Management control blocks.

   For an explanation of the fields in traceback, see item 7 (Traceback) under sections of the Language Environment dump in the z/OS Language Environment Debugging Guide.

Main Trace (MTRACE)

Use Main Trace (MTRACE) to view all recent system messages, including CICS messages that are written to the MVS console. MTRACE is activated automatically at MVS system initialization.

Read the main trace data. See Reading main trace data in the z/OS MVS Diagnosis: Tools and Service Aids Guide.

MVS system trace

Use the MVS System Trace to view an ongoing record of hardware and software events occurring during system initialization and operation.

The system activates system tracing at initialization and the tracing runs continuously, unless your installation has changed the IBM®-supplied system tracing.

Enter MVS command TRACE STATUS to check the size of the internal trace table. Message IEE839I will display. For example, if ST=(ON,0256K,00512K) displays, this indicates that trace is on and has the default size of 256K. You can change the trace table size or add trace branch instructions by using the TRACE command to customize system trace. For detailed instructions, see Customizing system tracing in the z/OS MVS Diagnosis: Tools and Service Aids Guide.

See Reading system trace output for a description of the system trace table entries.