In these days of highly accountable environments, it’s important for CICS customers to know where and when CICS transactions have been executed. CICS Transaction Server (TS) exploits the z/OS System Management Facility (SMF) to a considerable degree, but part of the data interrogation process must occur offline. Occasionally, it’s useful for a user to know what happened to transaction “WXYZ,” which ran in the past minute or so, without waiting for the transactional SMF data to be cut and extracted.
With that reporting time latency in mind, the CICS Transaction History record was implemented several years ago—and fitted as far back as CICS TS version 2.2. It was originally exposed as part of the CICS Performance Monitor (PM) tool. However, when CICS PM was withdrawn, the task history views were integrated directly into the standard CICS TS Web User Interface (WUI). This article demystifies the Transaction History Recorder set-up process and highlights some of its pitfalls.
How the History Recorder Operation Works
Although the raw task data is provided by CICS, the recording and reporting functions of the History Recorder are subcomponents of CICSPlex SM. If you want to view the statistics data for recently completed tasks, you must implement CICSPlex SM. If you understand CICS, the task history recording process won’t be rocket science, and a little black magic will help you be a power user!
Users who currently record task SMF data will know that CICS regions cut CICS task performance records to SMF as they complete. The History Recorder function simply grabs a copy of these records and stores them in a reportable data set that’s cyclically reused. This means that data recorded in the CICS history data set must be considered transient and isn’t permanent. Each region that’s required to report task history must have at least two recorder data sets allocated; their Data Definition (DD) names will be EYUHISTA and EYUHISTB. Additional data sets may be allocated, and their DD names must follow in alphabetic sequence from EYUHISTC all the way to EYUHISTZ.
CICS will fill each data set with completed task data. As each data set fills up, CICS will flip to the next available data set in alphabetic sequence and then flip back to data set A when the last available data set is filled. Clearly, there’s a trade-off here between maximizing History Recorder performance and keeping the history records viewable for as long as possible before a data set switch occurs.
Where disk space is at a premium for history data recording, you can section an area into more than two data sets:
- When only two data sets are available, 50 percent of your recorded data will be erased each time a switch occurs; however, system performance won’t be denigrated by repeated data set switching.
- When 10 data sets are defined, 10 percent of your recorded data will be erased with each data set switch, but you may notice slower performance with the more regular suspensions for switching.
- If data retention is a priority, you could allocate 25 history data sets. In that instance, only 4 percent of your history data will be overwritten with each switch, but clearly, data set switching will be occurring much more often than in the two previous instances.
It isn’t necessary to allocate history data sets with the same size. In terms of usability of the function, it makes more sense to have them identically allocated. However, the recorder function won’t restrict you from varying file size allocation.
History files must be allocated as a VSAM Relative Record Data Set (RRDS) file—not the usual key sequenced format required for most other CICS uses. When a CICS task completes, CICSPlex SM intercepts the task performance monitor record for it and writes it to the current, or next available, History Recorder data set. The size of the data set allocation and number of data sets allocated controls the volume of data retained. The more data sets allocated, the longer the history data will be reportable until it’s cyclically overwritten with fresher history data.
History Recorder JCL Configuration
The starting point to implementing the History Recorder is to allocate at least two recorder data sets in each region where recording is required. The sample Job Control Language (JCL) to allocate these files is in the EYUJHIST member of the CICS-supplied DFHINST data set.
Always allocate the files using the member pertaining to the CICS release you’re setting up. Generally, the record size of these data sets enlarges with each successive CICS version, so don’t simply re-specify the data sets for an earlier CICS version to the new configuration. You can migrate the history records from an earlier CICS release to a new CICS version, but given the transient nature of the history records, it seems hardly worth the effort.
After allocating the data sets, identify them in your CICS JCL with the EYUHISTx DD statements, ensuring that you specify DISP=OLD. This is necessary to allow recycling. The other JCL change is to ensure the appropriate CICS System Initialization (SIT) parameters are set so CICS generates the required performance monitoring data. This is achieved with these overrides: