Defining BTS data sets

You need to define two types of BTS data set:

Use the IDCAMS program to define your BTS data sets to MVS™.

Repository data sets

When a process is not executing under the control of the CICS® business transaction services domain, its state and the states of its constituent activities are preserved by being written to a VSAM data set known as a repository.

The states of all processes of a particular process-type (and of their activity instances) are stored on the same repository data set. Records for multiple process-types can be written to the same repository. You specify the repository on which processes of a particular process-type are stored when you define the process-type--see CEDA DEFINE PROCESSTYPE.

You must define at least one BTS repository data set to MVS. You may decide to define more than one, assigning a different set of process-types to each. One reason for doing this might be storage efficiency--maybe some of your process-types tend to produce longer records than others.

Note:
To enable you to distinguish between process-types during a browse, you don’t need to assign each process-type to a separate repository.

If you operate BTS in a sysplex, several CICS regions may share access to one or more repository data sets. This enables requests for the processes and activities stored on the data sets to be routed across the participating regions--see Using BTS in a sysplex.

Start of changeYou must define the repository file as recoverable.End of change

Specify the following parameters to IDCAMS:

INDEXED
BTS repository data sets must be in KSDS format.
KEYS(50 0)
The file key. The file key is 50 bytes in length and is located at offset X'0' in the record.
LOG(UNDO|ALL)
The recovery options for the data set:
UNDO
The data set is recoverable.
ALL
Forward recovery is required. If you specify LOG(ALL), you must also specify a log stream on the LOGSTREAMID parameter.
LOGSTREAMID(log_stream_ID)
The identifier of the log stream to which forward recovery records are to be written. This parameter is required only if you specify LOG(ALL).
RECORDSIZE(average  maximum)
The average and maximum size of records on the data set, in bytes.

Specify maximum as 16384 bytes. (CICS automatically splits any records that are larger than 16KB.)

It is difficult to predict the average size of repository records. (A notional record of 20000 bytes, for example, will be split into one record of 16384 bytes and one of 3616 bytes.) Initially, specify average as 8KB. If you find in practice that the average size of records is markedly different from this, you can specify a different value.

SPANNED
A single record may span control intervals. Specify this parameter if the record size is larger than the CI.

Figure 34 shows example JCL for defining a BTS repository data set. Note that the JCL is for illustration only.

Figure 34. Example JCL for defining a BTS repository data set. The numbers are for illustration only.
//SMITHGOT JOB (WINVMC,SMITH),CLASS=E,USER=username
//IJMRBTS EXEC PGM=IDCAMS,REGION=6144K
//SYSPRINT DD SYSOUT=A
//AMSDUMP  DD SYSOUT=A
//SYSIN    DD *
  DELETE ('CICSTS31.CICS.BTS') PURGE CLUSTER
  DEFINE CLUSTER (                         -
                NAME( CICSTS31.CICS.BTS )  -
                LOG(UNDO)                  -
                CYL(2,1)                   -
                CISZ(4096)                 -
                SPANNED                    -
                VOLUMES (P2DA62)           -
                KEYS( 50 0 )               -
                INDEXED                    -
                RECORDSIZE(8192  16384 )   -
                FREESPACE( 5 5 )           -
                SHAREOPTIONS( 2 3 )        -
                )                          -
  INDEX         (                          -
                NAME( CICSTS31.CICS.BTS.INDEX )   -
                )                          -
  DATA          (                          -
                NAME( CICSTS31.CICS.BTS.DATA )    -
                )
/*
//

To ensure that your repositories are continuously available, you are recommended to define them to use the backup while open (BWO) facility provided by DFSMSdss and DFSMShsm. For details of BWO, and how to define VSAM data sets to use it, see the CICS System Definition Guide.

Local request queue data set

The local request queue data set is used to store pending BTS requests--for example, timer requests, or requests to run activities. It is recoverable, and is used to ensure that, if CICS fails, no pending requests are lost.

Requests that CICS can execute immediately--for example, requests to run activities--are stored on the data set only briefly. Requests that CICS cannot execute immediately--for example, timer or unserviceable requests--may be stored for longer periods. When CICS has processed a request, the request is deleted from the data set.

The local request queue data set differs from repository data sets, in that:

Specify the following parameters to IDCAMS:

INDEXED
BTS local request queue data sets must be in KSDS format.
KEYS(40 0)
The file key. The file key is 40 bytes in length and is located at offset X'0' in the record.
LOG(UNDO|ALL)
The recovery options for the data set:
UNDO
The data set is recoverable.
ALL
Forward recovery is required. If you specify LOG(ALL), you must also specify a log stream on the LOGSTREAMID parameter.
LOGSTREAMID(log_stream_ID)
The identifier of the log stream to which forward recovery records are to be written. This parameter is required only if you specify LOG(ALL).
RECORDSIZE(average  maximum)
The average and maximum size of records on the data set, in bytes.

Start of changeSpecify average as 2232 bytes and maximum as 2400 bytes.End of change

Figure 35 shows example JCL for defining a BTS local request queue data set.

Figure 35. Example JCL for defining a BTS local request queue data set. The numbers are for illustration only.
Start of change//SMITHGOT JOB (WINVMC,SMITH),CLASS=E,USER=username
//IJMRLRQ  EXEC PGM=IDCAMS,REGION=6144K
//SYSPRINT DD SYSOUT=A
//AMSDUMP  DD SYSOUT=A
//SYSIN    DD *
  DEFINE CLUSTER (                         -
                NAME( CICSTS31.CICS.LRQ )  -
                LOG(UNDO)                  -
                CYL(2,1)                   -
                VOLUME (SYSDAV)            -
                KEYS( 40 0 )               -
                INDEXED                    -
                RECORDSIZE( 2232 2400 )    -
                FREESPACE( 0 10 )          -
                SHAREOPTIONS( 2 3 )        -
                )                          -
  DATA          (                          -
                NAME( CICSTS31.CICS.LRQ.DATA )    -
                CISZ(2560) -
                )
  INDEX         (                          -
                NAME( CICSTS31.CICS.LRQ.INDEX )   -
                )                          -
/*
//End of change

The LRQ data set is critical to the operation of BTS. Because its loss could severely impact the progression of BTS activities, you should consider defining it to use backup while open (BWO) and forward recovery.

Note:
For information about how to define the LRQ file to the CICS CSD, see Defining the LRQ file to the CSD.

Sizing and maintaining the LRQ data set

Sizing

The space you allocate for the LRQ data set depends on how often you plan to trim the file (see Maintenance) and the amount of BTS work likely to be undertaken in the periods between maintenance. Each RUN ASYNCHRONOUS or DEFINE TIMER request causes a record to be written to the LRQ file, each record being 2KB in length.

You are recommended to allow plenty of space for contingencies. Remember that records representing timers that are defined to expire far in the future will remain on the data set until their timers expire. And even after records have expired, VSAM still maintains control interval key ranges for their key values, even though the records for these keys have been deleted by CICS. These key ranges will never be reused because they represent time in the past, and their control interval space can only be recovered by periodic maintenance of the data set (see below).

Maintenance

The key of the LRQ data set includes a time stamp. This means that BTS generally adds requests to the end of the file. Although BTS deletes requests when they have completed, VSAM does not physically delete the records; so the space is not reused. Therefore, unless the LRQ data set is regularly maintained, it may become very large.

You can use an AMS command such as REPRO to shrink the data set--that is, to remove the records that have been logically-deleted by VSAM. Before doing this, you must quiesce CICS. (Disabling the LRQ file definition is not sufficient--if you do only this, activations may fail with ASP7 abends.)

Before undertaking maintenance, quiesce the CICS region. If you use CICSPlex® SM for routing BTS activities, you could route work away from the region by altering a CICSPlex SM workload definition (WLMDEF). If you use a CICS distributed routing program, you could alter your routing program. Although the region has been temporarily quiesced, BTS operations within the sysplex will be uninterrupted.

When reorganizing the data set, consider the percentage of control areas specified on the FREESPACE parameter on the cluster definition. If there are a large number of records representing timers far in the future, and new timers are to be added for events that will expire earlier than these existing records, a large FREESPACE percentage will decrease the number of likely control area splits that may occur. If the majority of new timer events are added for times later than existing events, the freespace percentage for control areas may be set to 0.

Related concepts
What are CICS business transaction services?
Related tasks
Defining the LRQ file to the CSD
Naming the routing program
Related reference
How to define VSAM data sets to use BWO
How to use DFHDEFDS
[[ Contents Previous Page | Next Page Index ]]