Overview

The Code Debug CICS File Utility Audit Trail uses an MVS subtask to perform the physical I/O to the data set, as well as much of the formatting of the data. Because a subtask is used, the CICS TCB isn’t forced to make the region wait for the I/O to complete. This allows other CICS tasks and Code Debug sessions not using the File Utility to continue normal execution. File Utility users don’t need to wait for the I/O to complete either, because Code Debug  simply queues I/O requests, letting the MVS subtask actually write the data. Requests from multiple users may be interspersed in the data set, because queued data is written on a first-in, first-out basis. Each update, however, is always written in its entirety as a single event.

The Code Debug File Utility Audit Trail is written to a GDG whose generation data sets have a logical record length (LRECL) of 133. The change data is formatted and includes ASA control characters so it can be directly printed. Each entry is given a header line that includes the following information about the change:

• date and time the change occurred
• userID, terminal ID, and netname associated with the person making the change.

This header line has a standard format and can be used as a search key if your site wants to write a program to process the data set for other types of reporting. While the data set is open for output, the data set-in-use flag is enabled, prohibiting any other task, including ISPF browse, from accessing it.

A CICS program furnished with Code Debug  allows you to turn the File Utility Audit Trail on and off or switch the data set to a new generation. Access to this program and its transaction code, XLOG, should be restricted to authorized individuals with your site’s external security manager. For more information, see XLOG-Transaction.

Activation of the File Utility Audit Trail requires few, if any, JCL changes. If your site allows dynamic allocation of data sets, enabling and customizing the File Utility Audit Trail requires no CICS startup JCL changes and only a few global table parameter changes, all of which can be done via the BMC PARMLIB. If your site does not use dynamic allocation, you will need to modify your CICS startup JCL in addition to specifying global parameter changes.

Using dynamic allocation provides another important benefit. When a generation data set fills up, a new one is dynamically allocated so that logging can continue with no loss of information. Without dynamic allocation, if the data set fills up while a entry is being written, the File Utility Audit Trail wraps to the top of the same data set, the remainder of the entry is written, and the previous contents are overlaid. This is not an Code Debug restriction, but an inherent limitation of generation data sets, which are explicitly defined to a jobstream via JCL DD statements.

Task 11.1 Setting Up the File Utility Audit Trail 

This section explains how to enable and configure the Code Debug CICS File Utility Audit Trail. In some steps, global parameter values are set using the BMC PARMLIB. All of the global parameters set in this section are described in Configuration-Parameters. For details on modifying the parameters, see Methods-of-Specifying-and-Updating-Parameters.

Your site’s external security manager—RACF for example—must grant authority to create Code Debug ’s File Utility Audit Trail GDG data set.

Task 11.1.1 Enable the File Utility Audit Trail Facility

Enable the File Utility Audit Trail by adding the following line to your site’s BMC PARMLIB:

Task 11.1.2 Add Program DBUGPLTS to Your CICS Shutdown PLT

Program DBUGPLTS must be added to your CICS shutdown PLT so that the Code Debug File Utility Audit Trail subtask can properly quiesce during CICS shutdown or region cancel.

In your CICS shutdown PLT, before the line reading DFHPLT TYPE=ENTRY,PROGRAM=DFHDELIM, add the following entry:

Task 11.1.3 Define the File Utility Audit Trail GDG 

To use a GDG, you must first define its properties by creating a model data set control block (DSCB) and building a GDG index for it. These properties include the base name of the GDG, the maximum number of data sets in the group, and the action to perform when that maximum is reached. If the File Utility Audit Trail will be used in multiple CICS regions, you must create multiple model DSCBs so that each region has its own GDG.

Member DEFLOGDG contains JCL to create a model DSCB and build a GDG index. The JCL includes an Access Method Services (AMS) DEFINE GENERATIONDATAGROUP statement. BMC recommends using the NOEMPTY and NOSCRATCH parameters shown. With the NOEMPTY parameter, when the maximum number of data sets in the GDG has been reached and a new data set needs to be cataloged, only the oldest data set in the GDG is uncataloged. If the EMPTY parameter were used instead, all the data sets in the GDG would be uncataloged. With the NOSCRATCH parameter, when a generation data set is uncataloged, its DSCB is retained in the volume’s VTOC, allowing it to still be located. See to the topic “DEFINE GENERATIONDATAGROUP” in the IBM documentation site.

Modify the JCL according to the following instructions, then submit it to define your File Utility Audit Trail data set.

1. Add a job card and any necessary OUTPUT specifications to the front of the member.

2. The AMS control statement NAME parameter can be up to 35 positions long. The remaining 9 positions, in the format .GxxxxVxx, will be supplied automatically by MVS when the data set is allocated. Change the NAME parameter in the JCL to the base GDG name you want to use for your generation data sets, then write that base name as follows:
   
   Base GDG name:____________________

   Warning

   Important

   Your site’s external security manager must grant authority to create the GDG data set with the chosen base name.

3. Change the AMS control statement LIMIT parameter to the maximum number of generation data sets you want in your GDG. Valid numbers are 1 to 255. BMC recommends a setting of at least 10.
4. Submit the JCL to create a model DSCB and build the GDG index for your data set.

Task 11.1.4 Enable Allocation of Your File Utility Audit Trail Data set

BMC strongly recommends using dynamic allocation of generation data sets. Use of dynamic allocation ensures continuous logging without overlaying previous information and can be enabled without changing your CICS startup JCL.

If your site allows dynamic allocation of data sets in CICS regions, go to Step 1. If your site does not allow dynamic allocation of data sets in a CICS region, go to Step 2.

1. The first two global parameters in this step establish the use of dynamically allocated generation data sets. Default values are shown for the remaining global parameters which specify various space allocation settings. If you want to use different values, see Configuration-Parameters for more information.
   
   Add the following parameters to your XDGBxxxx member in the BMC PARMLIB:
   
   FILE_UTILITY_AUDIT_TRAIL_DDNAME=DYNAMIC
   FILE_UTILITY_AUDIT_TRAIL_BASE_DSN=base GDG name from Define the File Utility Audit Trail GDG, Step 2
   FILE_UTILITY_AUDIT_TRAIL_ALLOC_TYPE=CYL
   FILE_UTILITY_AUDIT_TRAIL_PRIMARY_ALLOC=10
   FILE_UTILITY_AUDIT_TRAIL_SECONDARY_ALLOC=5
   FILE_UTILITY_AUDIT_TRAIL_BLKSIZE=27930
   FILE_UTILITY_AUDIT_TRAIL_UNIT=SYSDA
   
   No CICS startup JCL changes are needed.
   Go to Specify Format of File Utility Audit Trail Dataset Output.
   
   
2. Modify your XDGBxxxx member in the BMC PARMLIB and CICS startup JCL as follows:
   1. Select a 1- to 8-character ddname for your File Utility Audit Trail data set and write it as follows
      ddname:____________________
   2. Add the following parameter to your XDGBxxxx member in the BMC PARMLIB:
      FILE_UTILITY_AUDIT_TRAIL_DDNAME= ddname written above
   3. Add the following DD statement to your CICS startup JCL:

// ddname written above DD DISP=(NEW,CATLG,CATLG),
// DSN= base GDG name from Define the File Utility Audit Trail GDG,subStep 2 (+1),SPACE=(CYL,(10,5)),
// DCB=(DSORG=PS,RECFM=FBA,LRECL=133,BLKSIZE=27930)

Task 11.1.5 Specify Format of File Utility Audit Trail Data set Output 

Default values are shown for the following global parameters which specify the amount and format of data written to the Code Debug File Utility Audit Trail data set. If you want to use different values, consult Configuration-Parameters for more information.

Add the following parameters to your XDGBxxxx member in the BMC PARMLIB:

Task 11.2 Disabling the File Utility Audit Trail 

If your site chooses not to use the File Utility Audit Trail, you can disable it by adding the following parameter to your XDGBxxxx member in the BMC PARMLIB:

For more information, see Methods-of-Specifying-and-Updating-Parameters.