The ACTIVATETRACE option specifies the settings to apply to the internal trace of a CICS region when recording starts. The recording-mode parameter allows you to refine the statement further by limiting application of the settings to a particular recording mode.
Parameters
The following parameters may be specified.
level parameter
C\Prof requires a minimum set of CICS trace points to provide a complete application view of a transaction when recording for profiling. The level parameter allows you to control how C\Prof will modify those trace points in active CICS regions to achieve a complete profile of a transaction. The recommended minimum set of trace points can be found in Trace levels required for profiling.
The level specified in the ACTIVATETRACE control statement can be one of the following values: C\Prof level values for the ACTIVATETRACE control statement
| Level | Description |
|---|---|
| 0 | Do not allow C\Prof to change the CICS trace levels. Use this setting if you want to manually adjust the trace levels yourself or you do not wish to change the trace points. If you are recording for profiling, you may not capture a complete application view of the trace if the recommended minimum set of trace points have not been set. |
| 1 | Allow C\Prof to set all trace levels required for profiling - all other trace levels that are set in your CICS region remain unchanged and retain their values. This setting allows C\Prof to obtain a complete application view of your transactions. This is the recommended setting when recording for profiling. |
| 2 | Allow C\Prof to set all trace levels required for profiling - all other trace levels that are not required by C\Prof will be turned off. This is the most efficient method of running the CICS internal trace for profiling purposes. This option ensures that the CICS trace contains only those trace levels required for profiling and that no unnecessary additional overhead is incurred by activating trace levels that are not needed. |
The default value of level changes depending on the specified mode of operation of the C\Prof collector. For more information on C\Prof operating modes, see Collection modes (mode of operation). If ACTIVATETRACE is not specified, the following default values are applied:
-
When the mode of operation is SERVER or RECORD FOR PROFILING, the default value for level is 1.
-
When the mode of operation is RECORD TO AUXTRACE, the default value for level is 0.
The level is only applied to the recording mode specified (or determined by default) in the recording-mode parameter (see below).
A recording to an auxiliary trace data set does not require a minimum set of trace points unless you wish to import the resulting data sets into the C\Prof profiler. For more information on importing auxiliary trace data sets, see Import an auxiliary trace data set into the profiler.
START parameter
Optional parameter. When recording starts, use the method defined on the TRACECONTROL control statement to start the CICS internal trace and to set Master System Trace Flag to ON. If START is not specified, you must start the CICS internal trace using one of the other methods described in Step 1: Start and configure the CICS internal trace.
"Note: If the CICS internal trace is not in the STARTED state, only exception events are collected."
The START parameter is only applied to the recording mode specified (or determined by default) in the recording-mode parameter (see below).
upsize parameter
Optional parameter. When recording starts, use the method defined on the TRACECONTROL control statement to increase the size of the CICS internal trace table to the number of kilobytes specified in the upsize parameter.
For C\Prof to function, the internal trace table must be large enough to ensure that C\Prof can collect the trace before the oldest entries are overwritten by new entries, a condition known as wrapping . To reduce the risk of wrapping, it is recommended that you set an initial value for the trace table size to 32MB and increase it as required.
The minimum permitted value of upsize is 16 (kilobytes). The maximum permitted value of upsize is 1048576 (kilobytes). The upsize parameter cannot be used to reduce the size of the CICS internal trace table. If the upsize parameter is not specified, the size of the CICS internal trace table remains unchanged.
The upsize parameter is only applied to the recording mode specified (or determined by default) in the recording-mode parameter (see below).
recording-mode parameter
Optional parameter. Apply these settings only for the specified recording mode. The following values may be specified:
C\Prof recording-mode values for the ACTIVATETRACE control statement
| Mode | Description |
|---|---|
| PROFILING | Applies only when recording for profiling. |
| AUXTRACE | Applies only when recording to auxiliary trace data sets. |
| BOTH | Applies to both types of recording (record for profiling and record to auxiliary trace data sets. |
The default value of recording-mode changes depending on the specified mode of operation of the C\Prof collector. For more information on C\Prof operating modes, see Collection modes (mode of operation). If recording-mode is not specified, the following default values are applied:
-
When the mode of operation is SERVER or RECORD FOR PROFILING, the default value for recording-mode is PROFILING.
-
When the mode of operation is RECORD TO AUXTRACE, the default value for recording-mode is AUXTRACE.
"Note: If the recording-mode is specified (or determined by default) as PROFILING or AUXTRACE, users can still request recording for the alternate, unspecified mode, however only the default trace configuration values will be applied. For example, if recording-mode is set to PROFILING, users may still record to auxiliary trace data sets but the ACTIVATETRACE settings will not be applied (i.e. the CICS internal trace will remain unchanged)."
Examples
Example 1: Set profiling trace points with 64 MB trace table
To start the CICS internal trace, set the trace table size to 64 MB (65536 KB), and set all trace levels required for profiling but leaving other trace levels unchanged when recording for profiling begins, use the following control statement:
ACTIVATETRACE=(1,START,65536,PROFILING)
Example 2: Minimum settings required for transaction profiling
To start the CICS internal trace, set the trace table size to 32 MB (32768 KB), set all trace levels required for profiling and unset all those that are not required for all record for profiling requests, use the following control statement:
ACTIVATETRACE=(2,START,32768,PROFILING)
Example 3: Start the CICS internal trace, but make no other changes
To start the CICS internal trace, but leave the trace point levels and trace table size unchanged for both record for profiling and record to auxiliary trace data set requests, use the following control statement:
ACTIVATETRACE=(0,START,BOTH)
Trace levels required for profiling
When using ACTIVATETRACE=1 or ACTIVATETRACE=2, C\Prof will set the trace point levels described in the table below. These settings allow C\Prof to obtain a complete application view of your transactions. More information about CICS trace point domains can be found in the CICS reference manual topic STNTRxx system initialization parameter in the IBM Knowledge Center. CICS trace points set by the ACTIVATETRACE=1 and ACTIVATETRACE=2* control statements
| Component (domain) | Level | What does it provide? |
|---|---|---|
| AP | 1 | Application domain:
|
| EI | 2 | EXEC interface:
|
| LD | 1 | Loader domain:
|
| PG | 1 | Program manager domain:
|
| RA | 1 | Resource manager adapters domain:
|
| RI | 1 | Resource manager interface (RMI):
|
| RM | 1 | Recovery manager domain:
|
| XM | 1 | Transaction manager domain:
|
| XS | 1 | Security manager domain:
|
More granular control of trace levels is also available via the STNTRxx control statement. More information can be found in STNTRxx.
Considerations when using ACTIVATETRACE
Consider the following information when using ACTIVATETRACE control statement.
Performance
"Warning: C\Prof uses only a small set of trace points to profile transactions. However, changing trace levels in CICS can adversely affect transaction CPU and response time."
To minimize the impact, use the RESETTRACE control statement to restore your CICS trace points after collection stops. The advantage of this approach is that C\Prof can be used in production to collect a short burst of transaction data with low impact and without the need to manually reset your trace options.
More information on the RESETTRACE control statement can be found in RESETTRACE.
Activating additional trace domains
If you are using ACTIVATETRACE=1 or ACTIVATETRACE=2, you can add STNTRxx control statements to your configuration file to either:
-
Activate additional CICS trace component levels.
-
Override the component trace levels described in Trace levels required for profiling.
More information on the STNTRxx control statement can be found in STNTRxx.
When using ACTIVATETRACE=1, C\Prof will apply the trace point levels described in Trace levels required for profiling whilst retaining trace levels. For example, if trace point domain EI is already set to level 1 before the collector is started:
-
ACTIVATETRACE=1 will set it to EI=1-2.
-
ACTIVATETRACE=2 will set it to EI=2 (along with changes to other trace points).
-
ACTIVATETRACE=1 and STRTREI=2 will set it to EI=2.
-
ACTIVATETRACE=0 will leave it unchanged at EI=1.
Setting trace points manually
When using ACTIVATETRACE=0, you must set the trace points manually before the collector is started. Use CICS transaction CETR to view and edit your current levels (press PF4 after running CETR), or modify your SIT parameters accordingly.
At a minimum, C\Prof requires trace point domain XM level 1 and AP level 1 to capture the start and end of a transaction. Message TXC0301W may be issued if the minimum trace level has not been achieved. This may result in an incomplete view of your transactions.