Audit trail feature
When using Option 2 of File-AID for IMS/ISPF to edit a database (for example, updating a production database or some other sensitive data), you can specify that an audit trail of your edit session is to be created.
To activate the audit trail feature, enter a Y in the Create Audit Trail field on the Data Base Specification screen. As you use the Formatted, Unformatted, and Character edit sub-options to update your database, all the update activity is captured into an audit trail.
Every time you use the INSERT or REPEAT primary command in the Formatted and Unformatted sub-options or the I (Insert), R (Repeat), and RA (Repeat All) line commands in the Character sub-option, images of the newly created segments are written to the audit trail.
Every time you use the DELETE primary command in the Formatted and Unformatted sub-options and the D (Delete) line command in the Character sub-option, images of the deleted segments are written to the audit trail dataset. Whenever you change the contents of existing segments by typing directly over the segments’ contents, before and after images of the changed segments are written to the audit trail. File-AID for IMS/ISPF also records the number of times you enter the SAVE primary command.
Audit trail dataset usage
File-AID for IMS/ISPF allocates the audit trail dataset at the beginning of your edit session.
If your TSO-PREFIX matches your TSO-ID, the audit trail dataset name is
where... | equals... |
|---|---|
tso-id | Your TSO user ID, up to seven characters. |
yymmdd | The Gregorian date on which the audit trail is created. |
hhmmss | The hour, minute, and second the audit trail is created. |
If your TSO-PREFIX does not match your TSO-ID, the audit trail dataset name is:
where... | equals... |
|---|---|
tso-prefix | Your TSO user PREFIX, up to seven characters. |
System SMF Log File Usage
If an SMF identifier was specified at installation or by the security exit, the audit trail information is written to the system SMF log file.
Audit Trail Disposition
When you enter the END, RETURN, or a jump command to terminate your edit session, the Specify Disposition of Audit Trail screen is displayed as shown in the following figure. This screen is not displayed if the audit trail was written to the SMF log file. This screen is used to decide what to do with the audit trail dataset just created during your edit session.
Specify Disposition of Audit Trail Screen
COMMAND ===>
Audit trail disposition ===> (PK = Print dataset and keep
PD = Print dataset and delete
D = Delete dataset (without printing))
Audit trail dataset ===> 'CW.FIAUDIT.D970315.T130054'
Audit trail ===>
Description ===>
Specify batch JCL information:
Sysout class ===> *
Print format ===> F (F = Formatted; H = Hexadecimal)
Print only changed fields ===> N (Y = Yes; N = No)
JOB statement information:
===> //TSOID01 JOB (XXXXXXX),'FILE-AID AUDIT TRAIL',
===> // MSGCLASS=A,NOTIFY=TSOID01
===> //
===> //
Enter END command to keep audit trail without printin
Enter JCL command to edit generated JCL
Press Enter to submit batch job
Audit Trail Disposition
Indicate whether the audit trail is to be printed and kept by a batch job (PK), printed and deleted (PD), or deleted without printing (D).
Audit Trail Dataset
Displays the data set name of the audit trail just created in a protected field.
Audit Trail Description
Optionally, enter a description of the edit session you just completed. This description is written to the audit trail dataset and appears on the Audit Trail Report if you choose to have it generated. The field is 100 positions long.
Sysout Class
Specify the output class for the report.
Print Format
Specify whether you want the report printed in a formatted mode using segment layouts or in an unformatted, three-line hexadecimal mode.
Print Only Changed Fields
The information in this field affects how File-AID for IMS prints the before and after images of changed segments on the Audit Trail Report. If you enter Y, only the fields that you change are printed. If you enter N, all fields in changed segments are printed. However, the entry you make in this field has no affect on the printing of inserted, repeated, and deleted segment images.
Job Statement Information
Enter the JOB statement JCL for the batch print job submitted when you specify PK or PD for Audit Trail Disposition.
Terminating the Screen
Do one of the following to terminate the Audit Trail Disposition screen:
- Press Enter to generate the JCL, submit the print job for execution, and return to the Data Base Specification screen.
- Enter the JCL command to proceed to an ISPF/PDF Edit screen where you can edit the generated JCL before submitting it. See Editing the Generated JCL.
- Enter the END, RETURN, or a jump command to keep the audit trail dataset for later printing.
If you enter the END, RETURN, or a jump command on the Audit Trail Disposition screen, you can print the audit trail at a later time by using Option 5.5, the Print Audit Trail sub-option. This screen and the Audit Trail Report are described in Print Audit Trail Screen (Online Conversation).
Notes on the Audit Trail Feature
The audit trail dataset that File-AID for IMS/ISPF creates is a sequential, variable blocked file. Its LRECL and BLKSIZE are dependent on the sum of the lengths of the longest segment type and the maximum fully concatenated key contained in the primary database being edited. The sum of these lengths cannot exceed 32,724. For example, if you try to use the audit trail feature while editing a database that contains a segment type 30,000 characters long and the database’s maximum fully concatenated key length is 3,000, an error is generated and you are not able to edit the database.
The amount of space allocated to the audit trail dataset by File-AID for IMS/ISPF is large enough so that you can usually complete your edit session without overflowing the audit trail dataset.
However, if you make a large number of changes during your edit session or if the segments in your database are very large, you could receive error message E345 AUDIT TRAIL DISCONTINUED. This message indicates that File-AID for IMS/ISPF is unable to continue writing to the audit trail dataset. At that point, you have the option to continue your edit session without an audit trail or terminate the session. When you do end your edit session, you still receive the Audit Trail Disposition screen, where you can choose what to do with the audit trail dataset.
When you edit a database that contains nonkeyed and/or nonunique segment types, the capturing of deleted segment images by the audit trail feature can be affected. When you use File-AID for IMS/ISPF to delete a parent segment that has dependent segments under it, File-AID for IMS issues a DL/I DLET call for the parent segment only. IMS automatically deletes all the dependent segments, in addition to the parent. Normally, File-AID for IMS/ISPF retrieves all the dependent segments and writes their images to the audit trail before the deletion of the parent actually occurs. This requires File-AID for IMS/ISPF to reestablish its current segment position in the database to the parent segment before deleting it.
When the parent to be deleted is nonkeyed or nonunique, File-AID for IMS/ISPF is unable to reposition on the parent before deleting it. Therefore, File-AID for IMS/ISPF does not retrieve the dependents and write their images to the audit trail before deleting the parent. The dependent segments are deleted when the parent is deleted, but their images do not appear on the Audit Trail Report. A message appears on the report with the deleted parent’s image to notify you that dependent segments were deleted but are not shown.
Your installation has the capability to force the creation of an audit trail during your edit session through the File-AID for IMS/ISPF security exit routine. Therefore, you can enter N for Create Audit Trail on the Data Base Specification screen, but the security exit routine can override your specification. This means the Audit Trail Disposition screen can appear unexpectedly at the end of your edit session. However, the security exit routine can also force the printing of an audit trail at the end of your edit session. Therefore, you could receive an unexpected batch job submittal message at the end of your edit session without having seen the Audit Trail Disposition screen.
The security exit routine also has the capability to force the use of the system SMF log file to record the audit trail information.
The security exit routine also has the capability to override the default syntax File-AID for IMS/ISPF uses when constructing the audit trail dataset name (the syntax is described on here). Therefore, when the Audit Trail Disposition screen is displayed, you can see an audit trail dataset name that does not coincide with the syntax described.
If you require information on how your installation may be using a security exit routine to force File-AID for IMS/ISPF to create and/or print an audit trail or supplying the audit trail dataset name, contact the person responsible for File-AID for IMS/ISPF at your installation.