Record to auxiliary trace data sets

Write the events in the CICS internal trace to one or more auxiliary trace data sets. In this trace capture mode, C\Prof produces output identical to the CICS auxiliary trace, but places a much lower processing burden on CICS. Unlike profiling, this trace capture mode captures only trace events.

To analyze the resulting auxiliary trace data sets, 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).

Recording to auxiliary trace data sets using the ISPF dialog

Use the C\Prof ISPF dialog to generate JCL for recording to auxiliary trace data sets. Users can select from the following data set allocation modes:

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 record from the CICS internal trace, decide which data set allocation mode you will use and then complete the following steps:

On the C\Prof primary option menu, select option 4 Batch.
On the Batch menu, select option 3 AUXTRACE.
Enter the Job name and LPAR of the CICS region you want to record.
Enter the New data set allocation attributes that C\Prof should use when new data sets are required. These attributes are applied when recording in dynamic mode (data sets are allocated on demand) and in static mode if you wish to write to an auxiliary trace data set that has yet to be allocated (catalogued).
For static data sets only: If you are recording to static auxiliary trace data sets, complete the following sub-steps:
1. Specify an option for controlling statically allocated data sets by entering a value in the Autoswitch (AUXTRSW) field. Autoswitch supports the following values:
  - NO
    
    Write to the first data set you specify in the Auxiliary trace data sets list. Once the data set becomes full, recording will stop.
  - NEXT
    
    Write to the data sets you specify in the Auxiliary trace data sets list in order, switching to the next data set when the current data set becomes full. When the last data set becomes full, recording will stop.
  - ALL
    
    Write to the data sets you specify in the Auxiliary trace data sets list in order, switching to the next data set when the current data set becomes full. When the last data set becomes full, recording will recommence with the first listed data set and overwrite it. Data sets will then continue to be overwritten sequentially until the recording limit is reached (using the LIMIT control statement described in LIMIT) or C\Prof is shut down by the user (using operator commands described in Controlling the collector via operator commands).
2. Enter one or more data set names in the Auxiliary trace data sets list. Be sure to surround your data set name with single quotes (') when specifying a fully qualified data set name. You can use line action i to insert new rows and line action d to delete rows. 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.
On the command line, enter 1 to generate JCL for the dynamic recording method, or 2 for the static recording method.

$Recording to CICS auxiliary trace data sets that are compatible with the IBM-supplied trace utility print program (DFHTU700) using C\PRof$ Recording to four static auxiliary trace data sets using the Record to Auxiliary Trace panel
Review the following configuration control statements generated by the dialog.
- RECORD TO AUXTRACE
  
  Set the collection mode to RECORD TO AUXTRACE. This mode is used to perform ad hoc recording of data from the CICS internal trace to auxiliary trace data sets.
- LIMIT=<value>
  
  This optional parameter instructs the collector to stop recording and shut down after the designated time period. This is particularly useful for production systems if you wish to conduct a short burst of analysis. For more information, see LIMIT=value units.
- ACTIVATETRACE=0
  
  Do not change the active CICS trace levels before recording starts. To increase the CICS trace levels to record a minimum set of events for a full transaction profile, use ACTIVATETRACE=1. You can also insert STNTRxx statements for each trace domain you wish to record. For more information, see ACTIVATETRACE=(level [,START [,upsize][,recording-mode]).
- AUXTRSW
  
  Controls the creation and switching method for auxiliary trace data sets. These options are divided into the following modes:
  - dynamic mode option ARCHIVE which instructs C\Prof to dynamically allocate new data sets.
  - static mode options NO, NEXT, and ALL that use pre-defined data sets specified in your JCL.
  For more information, see AUXTRSW=option.
- CHECKPT=<data-set-name>
  
  Register data sets created during collection in a checkpoint data set. 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. If you would like to use a different data set, change the name as required. More information on the CHECKPT control statement can be found in CHECKPT.
- ARCHDSN=<pattern>
  
  Dynamic mode only: When using dynamic data set allocation (AUXTRSW=ARCHIVE), this control statement defines the naming pattern for auxiliary trace data sets. You can also use this control statement if you want to use Generation Data Groups (GDGs). Rules that govern the naming of data sets can be found in ARCHDSN=pattern.
- AUXILIARY
  
  Dynamic mode only: When using dynamic data set allocation (AUXTRSW=ARCHIVE), this control statement defines the allocation attributes of auxiliary trace data sets. For more information, see SUMMARY, DETAIL, and AUXILIARY.
- CICS=<jobname>
  
  Record from the internal trace of the specified CICS jobname. You can record from other CICS regions by inserting additional CICS control statements as required. Examples of recording from multiple regions can be found Record 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 in Record multiple CICS regions and write to static data sets.
Submit the JCL.

Tip: If you save the job, you can rerun it at any time without having to regenerate the JCL.
Review the collector SYSPRINT output data set to verify that recording has started. Activity in CICS will prompt the creation of auxiliary trace data sets in the locations specified in the collector configuration.
Recording will stop if you specified a time limit using the LIMIT control statement, or if the data sets become full and you used the AUXTRSW control statement with the NO or NEXT options. Otherwise, to stop the recording at any time, use the following MVS system commands:
```
MODIFY <collector-jobname>,SHUTDOWN
STOP <collector-jobname>
```
Note: Additional MVS system commands for control of C\Prof are described in Controlling the collector via operator commands.
Review the collector SYSPRINT output data set to verify that recording has stopped.
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.
- 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.

Additional examples of ad hoc recording to auxiliary trace data sets

Note: A complete set of configuration options for recording to auxiliary trace data sets can be found in Control statement summary.

Record multiple CICS regions and write to static data sets

The following example shows static auxiliary trace recording for two CICS regions (CICSP1 and CICSP2). Each region has been assigned three, previously allocated auxiliary trace data sets. C\Prof automatically switches between the three data sets continuously in round-robin fashion until the collector is stopped via operator commands (see Controlling the collector via operator commands).

//JOBCARD JOB (ACCOUNT),'NAME'
//*
//RECORD EXEC PGM=TXCMAIN
//STEPLIB  DD DISP=SHR,DSN=TXC.CPROF.STXCAUTH
//SYSPRINT DD SYSOUT=*
//CICSP1A  DD DISP=SHR,DSN=MY.CPROF.CICSP1.DFHAUXT1
//CICSP1B  DD DISP=SHR,DSN=MY.CPROF.CICSP1.DFHAUXT2
//CICSP1C  DD DISP=SHR,DSN=MY.CPROF.CICSP1.DFHAUXT3
//CICSP2A  DD DISP=SHR,DSN=MY.CPROF.CICSP2.DFHAUXT1
//CICSP2B  DD DISP=SHR,DSN=MY.CPROF.CICSP2.DFHAUXT2
//CICSP2C  DD DISP=SHR,DSN=MY.CPROF.CICSP2.DFHAUXT3
//SYSIN    DD *
RECORD TO AUXTRACE
ACTIVATETRACE=0
AUXTRSW=ALL
CICS=CICSP1 OUTDD=CICSP1* /* Matches CICSP1A, CICSP1B, and CICSP1C
CICS=CICSP2 OUTDD=CICSP2* /* Matches CICSP2A, CICSP2B, and CICSP2C
/*

Ad hoc recording to auxiliary trace data sets - multiple CICS region, static data sets

C\Prof is configured as follows:

Perform an ad hoc recording of the CICS internal trace (RECORD TO AUXTRACE)
Do not change active CICS trace points (ACTIVATETRACE=0)
Switch to the next data set when the previous data set becomes full. When there are no more empty data sets, restart at the first data set and overwrite (AUXTRSW=ALL)
Capture data from CICS region CICSP1 (CICS=CICSP1) and write to the data sets prefixed by DD name CICSP1 (OUTDD=CICSP1*). Similarly, data captured from CICSP2 is output to DD names prefixed with CICSP2.

Record multiple CICS regions with dynamic data set allocation

The following example demonstrates recording of three CICS regions to dynamically allocated auxiliary trace data sets, stopping after an hour.

//JOBCARD JOB (ACCOUNT),'NAME'
/*JOBPARM SYSAFF=SYS1
//*
//RECORD EXEC PGM=TXCMAIN
//STEPLIB  DD DISP=SHR,DSN=TXC.V1R2M0.STXCAUTH
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
RECORD TO AUXTRACE
LIMIT=1 HOURS               /* Record for 1 hour and then stop
ACTIVATETRACE=1             /* Adjust CICS trace points
AUXTRSW=ARCHIVE             /* Allocate data sets dynamically
CHECKPT=MY.CPROF.CHECKPT    /* Register new data sets in checkpoint
ARCHDSN=+USERID.CPROF.+CICS /* Naming pattern for new data sets
AUXILIARY SPACE=(CYL,20,10) /* Allocation attributes
CICS=CICSP1                 /* Collect from CICS region CICSP1
CICS=CICSP2                 /* Collect from CICS region CICSP2
CICS=CICSP3                 /* Collect from CICS region CICSP3
/*

Ad hoc recording to auxiliary trace data sets - multiple CICS region, dynamic data set allocation

C\Prof is configured as follows:

Perform an ad hoc recording of the CICS internal trace (RECORD TO AUXTRACE)
Stop recording after thirty minutes (LIMIT=30 MINUTES)
Change CICS trace points (if necessary) to gather a complete profile of a transaction (ACTIVATETRACE=1)
Allocate auxiliary trace data sets dynamically (AUXTRSW=ARCHIVE)
Register newly created auxiliary trace data sets in a checkpoint data set (CHECKPT=MY.CPROF.CHECKPT). Because the auxiliary trace data sets in this example have been registered in a checkpoint data set, you can use the housekeeping feature to periodically delete data sets that have expired. For more information, see Cleaning up old collection data via housekeeping.
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=CICSP1, etc.)