Snap the CICS internal trace

Snap takes a low-overhead copy of the CICS internal trace table and writes it to an auxiliary trace data set. Snap can be invoked at any time, even if the C\Prof collection server is not running.

To analyze auxiliary trace data sets created by snap, use menu option 3 Trace on the C\Prof ISPF dialog. Auxiliary trace data sets produced by C\Prof are also compatible with the IBM-supplied trace utility print program (DFHTU700).

Tip: Configure your automation tools to automatically trigger a C\Prof snapshot when problems are detected in CICS. For more information, see Automatic problem capture with event-driven snap.

Requesting snap using the ISPF dialog

Use the C\Prof ISPF dialog to generate snap JCL. Users can select from the following modes when deciding how C\Prof should allocate auxiliary trace data sets:

  • Dynamic data set allocation

    New auxiliary trace data sets are allocated on demand using a naming pattern.

  • Static data sets

    Write to a fixed set of auxiliary trace data sets. With this option, the collector can be configured to stop when the data sets are full or to switch between the data sets in round-robin style.

To take a back-in-time snapshot of the CICS internal trace, decide which data set allocation mode you will use and then complete the following steps:

  1. On the C\Prof primary option menu, select option 4 Batch.

  2. On the Batch menu, select option 1 Snap.

  3. Enter the Job name and LPAR of the CICS region you want to snapshot.

  4. For static data sets only: Specify a static Data set name. If the data set already exists then it will be overwritten. If the data set does not exist then it will be allocated with DISP=NEW in the resultant JCL. The space unit and quantities will be used.

  5. Enter the data set Space units, Primary quantity, and Secondary quantity. These attributes are used for both dynamic and static data set allocation modes.

  6. On the command line, enter 1 to generate JCL for the dynamic recording method, or 2 for the static recording method.

    Capturing recent history in CICS using C\Prof snap to CICS auxiliary trace data set Capturing to statically allocated auxiliary trace data set using the Snap panel

  7. Review the following configuration control statements generated by the dialog.

    • SNAP

      Set the collection mode to SNAP. The SNAP control statement is used to perform an ad hoc snapshot of the CICS internal trace table to an auxiliary trace data set.

    • AUXTRSW=ARCHIVE

      Dynamic mode only: Dynamically allocate the required auxiliary trace data set. For dynamic mode snap, ARCHIVE must be selected. Additional options can be found in AUXTRSW=option.

    • ARCHDSN=<pattern>

      Dynamic mode only: The naming pattern for the dynamically allocated auxiliary trace data set. Rules that govern the naming of data sets can be found in ARCHDSN=pattern.

    • AUXILIARY

      Dynamic mode only: Defines the allocation attributes of the auxiliary trace data set. For more information, see SUMMARY, DETAIL, and AUXILIARY.

    • CICS=<jobname>

      Take a snapshot of the internal trace of the specified CICS jobname. You can add additional regions in the LPAR by inserting your own CICS= control statements. Each region will be captured in sequence to separate auxiliary trace data sets until there are no more regions to process. Examples of multiple region snapshot requests can be found in Snap multiple CICS regions and write to static data sets.

    • OUTDD=<ddname-pattern>

      Static data sets only: Appended to the end of a CICS control statement, the OUTDD control statement directs C\Prof to write trace data collected from that CICS region directly to the auxiliary trace data set (or sets) defined by the named DD statement. You can write to a sequence of data sets by using a naming pattern to match more than one DD name. Names may be specified as a pattern that includes wildcard characters (* for zero or more characters and + for exactly one character). Additional examples using the OUTDD control statement can be found Snap multiple CICS regions and write to static data sets.

    • CHECKPT=<data-set-name> (optional)

      If using dynamic data set allocation, you can optionally register auxiliary trace data sets created during collection in a checkpoint data set. To do this, add the CHECKPT control statement. The checkpoint data set is used by the C\Prof ISPF dialog to locate data sets and by the housekeeping task to manage the removal of old data sets. More information on the CHECKPT control statement can be found in CHECKPT.

  8. Submit the JCL.

    Tip: If you save the job, you can rerun it at any time without having to regenerate the JCL.

  9. Review the collector SYSPRINT output data set to verify that the snapshot was successful.

  10. Select from one of the following options:

    • View trace entries using the C\Prof trace viewer

      Open the resulting auxiliary trace data sets using option 3 Trace on the C\Prof primary option menu. For more information, see Opening personal auxiliary trace data sets for ad hoc analysis.

    • Import trace entries into the C\Prof profiler

      Use C\Prof to import trace entries inside an auxiliary trace data set into C\Prof archive data sets. This process reconstructs transaction information from the trace entries and allows you to view the resulting activity using the C\Prof transaction profiler. For more information, see Import personal auxiliary trace data sets into the profiler.

Note: For deeper snapshot history, increase the size of your CICS internal trace table. For more information, see Step 1: Start and configure the CICS internal trace.

Additional examples of ad hoc snap

Note: A complete set of configuration options for snap can be found in Control statement summary.

Snap multiple CICS regions and write to static data sets

You can snap multiple CICS regions in an LPAR in the same job. To do this with static data sets, list each CICS region and the DD name of the output auxiliary trace data set.

//CPROFCOL JOB ,
/*JOBPARM SYSAFF=SYS1
//*
//S1 EXEC PGM=TXCMAIN
//STEPLIB DD DISP=SHR,DSN=TXC.V1R2M0.STXCAUTH
//SYSPRINT DD SYSOUT=*
//DFHAUXT1 DD DISP=SHR,DSN=USR.SNAPSHOT.TXCAUXT1
//DFHAUXT2 DD DISP=SHR,DSN=USR.SNAPSHOT.TXCAUXT2
//DFHAUXT3 DD DISP=SHR,DSN=USR.SNAPSHOT.TXCAUXT3
//SYSIN DD *
SNAP
CICS=CICSP1 OUTDD=DFHAUXT1
CICS=CICSP2 OUTDD=DFHAUXT2
CICS=CICSP3 OUTDD=DFHAUXT3
/*

Ad hoc snap multiple CICS regions, static data sets

The job is configured as follows:

  • Perform an ad hoc snap of the CICS internal trace (SNAP) on LPAR SYS1 (SYSAFF=SYS1)

  • Snap CICS region CICSP1 to USR.SNAPSHOT.TXCAUXT1 (CICS=CICSP1 OUTDD=DFHAUXT1)

  • Snap CICS region CICSP2 to USR.SNAPSHOT.TXCAUXT2, specified on DD name DFHAUXT2 (CICS=CICSP1 OUTDD=DFHAUXT2)

  • Snap CICS region CICSP1 to USR.SNAPSHOT.TXCAUXT3, specified on DD name DFHAUXT3 (CICS=CICSP1 OUTDD=DFHAUXT3)

Snap multiple CICS regions with dynamic data set allocation

To capture the internal trace for one or more CICS regions where C\Prof will dynamically allocate new auxiliary trace data sets, use the following example JCL:

//JOBCARD JOB (ACCOUNT),'NAME'
/*JOBPARM SYSAFF=SYS1
//*
//S1 EXEC PGM=TXCMAIN,REGION=200M
//STEPLIB  DD DISP=SHR,DSN=TXC.V1R2M0.STXCAUTH
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
SNAP BLKSIZE=24576
AUXTRSW=ARCHIVE               /* Allocate data sets dynamically
CHECKPT=MY.CPROF.CHECKPT      /* Checkpoint new data sets - optional
ARCHDSN=+USERID.CPROF.+CICS   /* New data set naming pattern
AUXILIARY SPACE=(CYL,100,10)  /* New data set attributes
CICS=CICSPA                   /* Snap CICS region CICSPA
CICS=CICSPB                   /* Snap CICS region CICSPB
CICS=CICSPC                   /* Snap CICS region CICSPC
/*

Ad hoc snap - multiple CICS regions, dynamic data set allocation

C\Prof is configured as follows:

  • Perform an ad hoc snap of the CICS internal trace (SNAP)

  • Reduce the amount of I/O for the snap request by using a larger block size for auxiliary trace data sets (BLKSIZE=24576). Auxiliary trace data sets created using this block size will no longer be compatible with the CICS trace utility print program. For more information, see BLKSIZE=value.

  • Allocate auxiliary trace data sets dynamically (AUXTRSW=ARCHIVE)

  • Register newly created auxiliary trace data sets in a checkpoint data set (CHECKPT=MY.CPROF.CHECKPT)

  • Names for new data sets are generated using the specified pattern (ARCHDSN=+USERID.CPROF.+CICS)

  • Define the allocation attributes for new data sets (AUXILIARY SPACE=(CYL,20,10))

  • Capture data from three CICS regions (CICS=CICSPA, etc.)

    Use the housekeeping feature to periodically delete old data sets. For more information, see Cleaning up old collection data via housekeeping.