For each CICS region you wish to record, C\Prof requires the CICS internal trace be in the STARTED state and the size of the trace table set large enough to reduce the likelihood of wrapping. If operating conditions for a particular CICS region prevent you from permanently applying these settings to the CICS internal trace, you can use the optional C\Prof trace control program, TXCCICS1, to automatically start, stop, and resize the CICS internal trace in that CICS region when recording starts and stops.
You can configure C\Prof to invoke TXCCICS1 by specifying the TRACECONTROL control statement in your C\Prof configuration file. The TRACECONTROL control statement allows you to select from one of the following invocation methods:
-
Invoke TXCCICS1 using a transaction
This method uses a transaction to invoke the C\Prof trace control program. When recording starts or stops, C\Prof will start the transaction by issuing a MODIFY MVS system command against the target CICS region. C\Prof will not start recording from the trace until after the transaction has completed.
-
Invoke TXCCICS1 using the external CICS interface (EXCI)
This method uses the external CICS interface (EXCI) to invoke the C\Prof trace control program. EXCI is an application programming interface that enables a client program running in MVS to call and pass data to a program defined in CICS. The CICS program is invoked as if linked-to by another CICS program and uses a COMMAREA for communication. EXCI has advantages over the transaction-based approach as the collector will not need to wait for the transaction to be queued, dispatched, and the work completed prior to commencing collection.
C\Prof module TXCCICS1 can be found in the STXCLINK library. To use it, you must first install it into CICS. Depending on how you intend to call the program (using EXCI or as a transaction) the method of installation will vary. After you have installed the program, you will need to configure C\Prof to enable trace control for your chosen CICS regions.
Complete the following sections to get started.
Preparing CICS to use TXCCICS1
Before you configure C\Prof for automatic trace control, you must first install the trace control program in each CICS region requiring trace control. The following sections should be completed by your CICS systems administrator.
Security considerations
As TXCCICS1 can modify the CICS internal trace, it is important to secure the program and any associated transactions to prevent unauthorized use in the same way that you might secure any category-2 CICS-supplied transaction. Refer to the CICS Transaction Server topic CICS-supplied transactions in the IBM Knowledge Center for more information.
The following information should be considered when securing the trace control program:
-
CICS application programs can invoke other programs by means of EXEC CICS commands LINK, LOAD, and XCTL. To prevent others from developing and running applications that access TXCCICS1 inappropriately, secure the application program so that it can only be invoked by those authorized to start C\Prof trace collection program TXCMAIN. Refer to the CICS Transaction Server topic Security for application programs in the IBM Knowledge Center for more information.
-
All transactions (including mirror transaction) that access TXCCICS1 must be secured so that only those authorized to start C\Prof trace collection program TXCMAIN can start those transactions. Refer to the CICS Transaction Server topic Transaction security in the IBM Knowledge Center for more information.
-
If you are using the transaction-based invocation method, C\Prof will use a system console to start the transaction by issuing a MODIFY MVS system command against the target CICS region. For the request to be successful, the console USERID must have authority to issue the command and start the transaction. For more information on operating CICS from a console device, see the CICS Transaction Server topic Administering CICS from a console device in the IBM Knowledge Center to learn more.
-
If you are using the EXCI-based invocation method, C\Prof will use the external CICS interface (EXCI) to link to TXCCICS1. Review the information about bind-time security and link security in the CICS Transaction Server topic EXCI security in the IBM Knowledge Center.
Installing TXCCICS1
The following steps describe the process of installing TXCCICS1 into a CICS region so that the program is installed and available on CICS startup. Complete the following steps:
-
Make program TXCCICS1 available to CICS via the DFHRPL concatenation in your CICS startup JCL. You can do this by copying program TXCCICS1 from the C\Prof STXCLINK link library to a data set already listed in the DFHRPL concatenation, or you can add a new DD statement to the concatenation containing the C\Prof link library STXCLINK itself.
-
Create supporting resource definitions for TXCCICS1.
Before you can use TXCCICS1, you will need resource definitions for the program as well as definitions in support of your chosen invocation method. Two sample jobs have been supplied in the pages below that use the CICS system definition file utility program DFHCSDUP to write the required definitions to your CICS system definition (CSD) file. The first job creates only the resource definitions required for a transaction-based invocation (see Sample job for transaction-based invocation). The second job creates resources for both the transaction-based invocation and the EXCI-based invocation (see Sample job for EXCI-based installation with mirror transaction together. Customize and run one of these sample jobs, depending on your choice of invocation method. Be sure to substitute all placeholder values in these jobs as required.
TXCCICS1 requires authority to issue EXEC CICS system programming interface (SPI) commands. If the program does not have authority, the program fails with message TXC3008E Not authorized to issue SPI command. To issue SPI commands, the transaction definition requires the CMDSEC(NO) parameter. For more information, refer to the topic TRANSACTION attributes in the CICS Transaction Server Knowledge Center. For the equivalent system initialization parameter, refer to the topic Parameters for specifying command security in the CICS Transaction Server Knowledge Center.
-
To install the resource definitions, either use the resource management transaction CEDA, or restart your CICS region. If using CEDA, you can install the resource group by entering the following command:
CEDA INSTALL GROUP(CPROF)Note: If CEDA fails to install the CONNECTION definition for an EXCI-based installation, you may need to close IRC temporarily before installing the connection. For more information, see IBM Support technote DFHAM4892 when installing new connection definition in CICS.
Verifying your installation
The following steps assume you have used the name TXC1 (as supplied in the sample jobs in Sample definitions for your trace control transaction definition. If you used a name other than TXC1, simply substitute TXC1 in the steps below for the name of your transaction.
To verify that the installation and setup of TXCCICS1 was successful, complete the following steps:
-
Log onto your CICS region.
-
Display the status and size of the CICS internal trace by typing TXC1. You can use this transaction without parameters at any time to quickly get the status and size of the trace.
-
Modify the attributes of the CICS internal trace using transaction TXC1. To do this in CICS, enter the following command:
TXC1 SIZE=<size> STATUS=<status> MASTER=<value>where
sizeis the desired size of the CICS internal trace in the range 16-104876 KB,statusis eitherSTARTorSTOP, andvalueis eitherONorOFF. For example, to start the trace and set the size to 32768 KB, enterTXC1 SIZE=32768 STATUS=START MASTER=ON. If you wish to suppress the completion message, addNOMSGto the end of the parameter list.Verify that the status and size has changed as requested.
-
If desired, reset the trace attributes to their original values using transaction TXC1 and the parameter format supplied in step 3.
Enabling automatic trace control in C\Prof
If you have successfully installed TXCCICS1 you are ready to modify your C\Prof configuration files and JCL to support automatic trace control. Complete the following steps:
-
For each C\Prof collection server requiring trace control, add the TRACECONTROL control statement to its configuration file. The TRACECONTROL control statement defines how C\Prof will invoke the trace control program when recording starts. Select from one of the following methods:
-
Using the transaction-based method
If you are using the transaction-based method, use the CONSOLE parameter and the name of the transaction as follows:
TRACECONTROL=(CONSOLE,TXC1)By default, the request will time out after 30 seconds. To change the timeout value, specify a new value (in seconds) after the transaction name. For example:
TRACECONTROL=(CONSOLE,TXC1,60) -
Using the EXCI-based method
If you are using the EXCI method, use the EXCI parameter and the name of trace control program, TXCCICS1 as follows:
TRACECONTROL=(EXCI,TXCCICS1)If you wish to use a mirror transaction, specify the name after the program name. For example:
TRACECONTROL=(EXCI,TXCCICS1,TXCM)For more information on the TRACECONTROL control statement, see TRACECONTROL.
-
-
For each configuration file containing a CICS region you wish to control, add the ACTIVATETRACE and RESETTRACE control statements. The ACTIVATETRACE control statement defines the behavior of the trace control program when a collection request is received. The RESETTRACE control statement defines the behavior of the trace control program when collection stops. When applied to a CICS control statement in your configuration file, you can use these statements to temporarily start the trace, set the size, and set trace point levels for a CICS region.
Note: The CICS internal trace is a shared resource. Changing the status and size of the trace will affect all other applications in the CICS region.
The ACTIVATETRACE and RESETTRACE control statements have several options that you can use to control the trace. For first time use, it is recommended that you use the following settings and then modify them as required:
-
ACTIVATETRACE(1,START,32768)When a collection request is received, start the trace, set the table size to 32 MB, and set all trace points needed for transaction profiling.
-
RESETTRACE(1,RESET)When collection ends, stop the trace and reset the trace table size all trace point levels back to their original settings.
To apply these changes to a specific CICS region (overriding any other ACTIVATETRACE and RESETTRACE control statements defined at a global or group level), add the statements immediately after the CICS control statement as follows:
CICS=*jobname* ACTIVATETRACE=(1,START,32767) RESETTRACE=(1,RESET)If you want to apply trace control to a group of CICS regions instead of a single region, add the statements immediately after the GROUP control statement. Similarly, if you wish to apply trace control to all CICS regions in the collector configuration file, you can define it at a global level before the appearance of any GROUP or CICS control statements. More information can be found in ACTIVATETRACE=(level [,START [,upsize][,recording-mode].
Note: Setting the status of the CICS internal trace to STOPPED when collection finishes will reduce the effectiveness of C\Prof snap requests, as only exception events will be collected. If you have set up automated problem capture with event-driven snap (see Automatic problem capture with event-driven snap), consider leaving the trace in the STARTED state. Additional options for RESETTRACE can be found in RESETTRACE.
-
-
If you are using the EXCI-based trace control method: Add the CICS EXCI library, SDFHEXCI, to the STEPLIB concatenation in your C\Prof collection server JCL. In the example below, substitute for the location of the library in your environment. For example:
//CPROFCOL JOB , /*JOBPARM SYSAFF=SYS1 //* //S1 EXEC PGM=TXCMAIN,REGION=200M //STEPLIB DD DISP=SHR,DSN=TXC.V1R2M0.STXCAUTH // DD DISP=SHR,DSN=<CICS.SDFHEXCI//SYSPRINT DD SYSOUT=* //SYSIN DD DISP=SHR,DSN=CPROF.CONFIG(CONFIG1)JCL for TXCMAIN with EXCI-based trace control
-
Restart all C\Prof collection server jobs you have modified in previous steps. If you have modified your JCL, you will need to resubmit it for the changes to take effect. Otherwise, if you have only modified your C\Prof configuration files, you can apply your changes without resubmitting JCL by using an MVS system command as follows, replacing
<collector-name>with the name of your collector:MODIFY <collector-name>,RESTARTNote: Collection will stop for all regions as a result of this process.
Sample definitions
The following sample jobs use the CICS system definition file utility program (DFHCSDUP) to write definitions to the CICS system definition (CSD) file. For more information, see the CICS Transaction Server topic System definition file utility program (DFHCSDUP) in the IBM Knowledge Center. In the following examples, replace the following text with values appropriate to your CICS region:
-
<CICS.SDFHLOAD>The name of your CICS load library.
-
<CICSPROD.DFHCSD>The name of your CICS system definition (CSD) file.
-
<TXC$CPROF>The name of the resource definition group list that will contain the new CPROF resource group.
Sample job for transaction-based definitions (no EXCI support)
Use the following sample job to create a program resource definition for TXCCICS1 and a new transaction named TXC1. Use this job if you do not want to use EXCI to invoke the program.
//CSDJOB JOB ,'CPROF',NOTIFY=&SYSUID,CLASS=A,MSGCLASS=T
//STEP1 EXEC PGM=DFHCSDUP,REGION=30M,
// PARM='CSD(READWRITE),PAGESIZE(60),NOCOMPAT'
//STEPLIB DD DSN=<CICS.SDFHLOAD>,DISP=SHR
//DFHCSD DD DISP=SHR,DSN=<CICSPROD.DFHCSD
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
ADD GROUP(CPROF) LIST(<TXC$CPROF>)
DEFINE PROGRAM(TXCCICS1) GROUP(CPROF)
DESCRIPTION(CPROF supplied Trace Control program)
LANGUAGE(ASSEMBLER)
DATALOCATION(ANY)
EXECKEY(USER)
CONCURRENCY(THREADSAFE)
STATUS(ENABLED)
USAGE(NORMAL)
DEFINE TRANSACTION(TXC1) GROUP(CPROF)
DESCRIPTION(CPROF trace control transaction)
PROGRAM(TXCCICS1)
PROFILE(DFHCICST)
CMDSEC(NO)
DUMP(NO)
STATUS(ENABLED)
TASKDATALOC(ANY)
TRACE(NO)
/*
Sample job to create definitions used to invoke TXCCICS1 with a transaction
Sample job for EXCI-based installation with mirror transaction
The following sample job creates the following definitions:
-
a program definition for TXCCICS1.
-
a transaction definition named TXC1. This is not used by the EXCI connection, however this transaction can be used as a utility to quickly check the status and size of the trace. This transaction is also used to verify the successful installation of the program TXCCICS1 (as described in Verifying your installation).
-
an EXCI connection definition named TXC1.
-
an EXCI session definition named TXCSESS1.
-
a mirror transaction definition named TXCM. If you do not wish to use a mirror transaction, simply remove the final DEFINE TRANSACTION(TXCM) statement from the job.
//CSDJOB JOB ,'CPROF',NOTIFY=&SYSUID,CLASS=A,MSGCLASS=T
//STEP1 EXEC PGM=DFHCSDUP,REGION=30M,
// PARM='CSD(READWRITE),PAGESIZE(60),NOCOMPAT'
//STEPLIB DD DSN=<CICS.SDFHLOAD>,DISP=SHR
//DFHCSD DD DISP=SHR,DSN=<CICSPROD.DFHCSD
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
ADD GROUP(CPROF) LIST(<TXC$CPROF>)
DEFINE PROGRAM(TXCCICS1) GROUP(CPROF)
DESCRIPTION(CPROF supplied Trace Control program)
LANGUAGE(ASSEMBLER)
DATALOCATION(ANY)
EXECKEY(USER)
CONCURRENCY(THREADSAFE)
STATUS(ENABLED)
USAGE(NORMAL)
DEFINE TRANSACTION(TXC1) GROUP(CPROF)
DESCRIPTION(CPROF trace control transaction)
PROGRAM(TXCCICS1)
PROFILE(DFHCICST)
CMDSEC(NO)
DUMP(NO)
STATUS(ENABLED)
TASKDATALOC(ANY)
TRACE(NO)
DEFINE CONNECTION(TXC1) GROUP(CPROF)
DESCRIPTION(EXCI connection for CPROF Trace Control)
ACCESSMETHOD(IRC)
PROTOCOL(EXCI)
CONNTYPE(GENERIC)
ATTACHSEC(LOCAL)
DATASTREAM(USER)
INSERVICE(YES)
MAXQTIME(5)
QUEUELIMIT(5)
DEFINE SESSIONS(TXCSESS1) GROUP(CPROF)
DESCRIPTION(EXCI sessions for CPROF Trace Control)
CONNECTION(TXC1)
AUTOCONNECT(NO)
PROTOCOL(EXCI)
IOAREALEN(0,0)
RECEIVECOUNT(5)
RECEIVEPFX(<)
DEFINE TRANSACTION(TXCM) GROUP(CPROF)
DESCRIPTION(CPROF mirror transaction for EXCI)
PROGRAM(DFHMIRS)
PROFILE(DFHCICSA)
RESTART(NO)
SPURGE(NO)
TPURGE(YES)
CONFDATA(YES)
RESSEC(YES)
CMDSEC(NO)
DUMP(NO)
STATUS(ENABLED)
TASKDATALOC(ANY)
TASKDATAKEY(USER)
TRACE(NO)
/*
Sample job to create definitions used to invoke TXCCICS1 via EXCI
For the C\Prof collection server to establish an EXCI connection to TXCCICS1, CONNECTION and SESSIONS resource definitions must be made available. For more information, refer to the topic CONNECTION resource definition for EXCI and SESSION resource definitions for EXCI in the CICS Transaction Server Knowledge Center.