Reference: Log data archiving: Configure the Command and Audit Log Archive (ATYARCH0) utility

IMS Administration Tool provides the Command and Audit Log Archive (ATYARCH0) utility that copies old log data to a DSORG=PS data set, and simultaneously marks it eligible for deletion. The ATYARCH0 utility supports both command log data and audit log data. You can select the log records to archive; command log records, audit log records, or both.

The ATYARCH0 utility provides several options for determining what log records are considered old, and therefore subject to archiving/deletion. Most of the archiving options archive only log records that were written prior to the current date. Use the MAX control card if you must archive log records from the current date.

If the log data needs to be kept for historical purposes, the retention period must be high enough so that the z/OS® System Logger will not delete the log data before it is off-loaded by the ATYARCH0 utility.

The output log data is displayed in the same format as the log of View Audit Log. To check the format, use either the IMS Administration Tool web interface or the ISPF interface: Setup and Administration > View Audit Log.

If you are migrating IMS Command Control Facility resources to IMS Administration Tool, the following considerations apply:
  • The ATYARCH0 utility supports command log records written by IMS Command Control Facility.
  • A CCF log record (log record generated by IMS Command Control Facility) is identified by its first character "c" in the archived data set. A command log record of IMS Administration Tool is identified by its first character "C".
  • The View Audit Log function and the View IMS Command Log function of IMS Administration Tool do not support CCF log records. You can view CCF log records only in the archived data set.
  • The IMS Command Control Facility archive utility does not support log records that are written by IMS Administration Tool. If log records of both products are stored in the same log stream, use the ATYARCH0 utility.
Subsections:

ATYARCH0 JCL

Sample JCL for archiving log data can be found in the SATYSAMP sample library, member ATYARCH0.

Figure 1. Sample JCL to archive log data (ATYARCH0)
//ATYARCH0  JOB  (TECH),ATYARCH0,CLASS=A,MSGCLASS=H,                   
//      REGION=4M,NOTIFY=&SYSUID,COND=(0,NE)                           
//*                                                                    
//*------------------------------------------------------------------* 
//* IBM*                                                               
//* ROCKET**                                                           
//* LICENSED MATERIALS - PROPERTY OF IBM                               
//* 5655-CAT                                                           
//* COPYRIGHT IBM CORPORATION 2019  ALL RIGHTS RESERVED.               
//* COPYRIGHT ROCKET SOFTWARE, INC. 2019 ALL RIGHTS RESERVED.          
//* *TRADEMARK OF INTERNATIONAL BUSINESS MACHINES                      
//* **TRADEMARK OF ROCKET SOFTWARE, INC.                               
//*------------------------------------------------------------------* 
//*-------------------------------------------------------------------*
//* CHANGES:                                                           
//*                                                                    
//* YY-MM-DD REL APAR    DESCRIPTION                                   
//* -------- --- ------- --------------------------------------------- 
//* 19-06-06 110 PH12977 ARCHIVE AUDIT LOG SUPPORT                     
//*                                                                    
//*------------------------------------------------------------------* 
//*                                                                    
//*      THIS SAMPLE JCL IS FOR ARCHIVING THE ATY COMBINED             
//*   MESSAGE LOG.                                                     
//*                                                                    
//*      THE FOLLOWING CHARACTER STRINGS MUST BE TAILORED:             
//*   ##SATYLOAD -  MUST BE THE NAME OF THE ATY LOAD DATASET.          
//*   ##LOGOUT   -  MUST PROVIDE ALL DATA SET INFORMATION.             
//*                 THE DATA SET MUST BE LRECL=1024 AND RECFM=VB.      
//*                 ALL OTHER PARAMETERS ARE INSTALLATION SPECIFIC.    
//*   ##LOGGER   -  MUST BE THE 1-26 BYTE Z/OS LOGSTREAM NAME.         
//*                                                                    
//*   -  ADDITIONAL SYSIN CONTROL CARDS CAN BE FOUND IN                
//*      THE ATY USERS GUIDE.  (SYSIN CONTROL CARDS MUST               
//*      START IN COLUMN 1 OR 2).                                      
//*                                                                    
//STEP01   EXEC PGM=ATYARCH0                                           
//STEPLIB   DD  DISP=SHR,DSN=##SATYLOAD                                
//LOGOUT    DD  ##LOGOUT                                               
//SYSABEND  DD  SYSOUT=*                                               
//SYSPRINT  DD  SYSOUT=*                                               
//SYSIN     DD  *                                                      
 LSN=##LOGGER

EXEC statement

Specify PGM=ATYARCH0 for the EXEC statement.

DD statements

The following DD statements define the data sets that are required by the ATYARCH0 utility.
STEPLIB DD
Specify the IMS Administration Tool product load library.
LOGOUT DD
Describes the output data set where the command and log data is written.

The data set is defined as LRECL=1024 and RECFM=VB.

The size of the data set is determined by the amount of data that is being archived.

SYSPRINT DD
An output data set that provides informational messages about the utility.

SYSPRINT is defined as LRECL=80 and RECFM=FB.

The output can be written to SYSOUT or a data set.

SYSIN DD
An input data set that contains control statements that specify archiving parameters.

SYSIN is defined as LRECL=80 and RECFM=FB.

SYSIN control statements

The SYSIN data set contains your description of the processing to be done by the ATYARCH0 utility.

Follow these coding conventions when you write control statements in the SYSIN data set:
  • Keywords and keyword values must be coded within column 1 and column 71. Keywords must start on column 1 or 2.
  • The column 72 must be blank.
  • A keyword and its value must be joined with an equal sign (=) and they must be coded on the same line.
  • More than one keyword can be coded on one line. Keywords must be separated by blank space.
  • Keywords are not positional parameters; they can be specified in any order.
  • A comment line must begin with an asterisk (*) in column 1.
  • Blank lines are ignored.
The following tables list the control statements.
  • Table 1 summarizes required control statements.
  • Table 2 summarizes control statements for narrowing down the records by time range and the number of records. Records identified by these control statements will be marked as eligible for deletion.
  • Table 3 summarizes control statements for selecting the type of log records to copy to the archive data set. Among the log records that are marked as eligible for deletion, only the type of log records selected by these control statement are copied to the archive data set.
Table 1. ATYARCH0 SYSIN control statements - required control statements
Definition Value

LSN=name

Required. Specify the 1- to 26-byte log stream name.
Table 2. ATYARCH0 SYSIN control statements to narrow the time range
Definition Value

DATE

Default. The utility starts processing from the oldest record and continues until it encounters a log record with a different date.

HOURS=nn

The utility starts processing from the oldest record and continues until nn number of hours of log records has been archived, or a log record with the current date is encountered.

Valid values for nn are 1-24.

When the HOURS definition is specified in conjunction with DATE, the processing continues until nn hours of records have been processed, or a log record with a date change has been encountered.

RECS=nnnnnn

The utility starts processing from the oldest record and continues until nnnnnn records have been processed.

Valid values for nnnnnn are 1-999999.

This control statement is not valid with any other control statements listed in this table.

ALL

The utility starts processing from the oldest record and continues until a log record with the current date minus one day has been encountered.

For example, if the utility is run at 2022/10/20 15:32, any log record created on and before 2022/10/19 are processed.

This control statement is not valid with any other control statements listed in this table.

MAX

The utility starts processing from the oldest record and continues until a log record with the current hour minus one hour has been encountered.

For example, if the utility is run at 2022/10/20 15:32, any log record created at and before 2022/10/20 14:59 are processed.

If using this option, it is recommended that the archive job (ATYARCH0) be scheduled at 15 minutes past the hour. This ensures at least 15 minutes of log data is always present in the log stream.

This control statement is not valid with any other control statements listed in this table.

Table 3. ATYARCH0 SYSIN control statements to filter the type of log
Definition Value

FILTER=[A | C | X]

Optional. Specify the type of log records to copy to the archive data set.

A
Audit log records.
C
Command log records.
X
Both command log records and audit log records. This is the default value.

CCFLOG=[Y | N]

Optional. Specify whether to copy CCF log records to the archive data set.

Y
Copies CCF log records to the archive data set. This is the default value. If FILTER=A is specified, CCFLOG=Y is ignored.
N
Does not copy CCF log records to the archive data set.

SYSIN control statement examples

The following SYSIN control statement example is for archiving both command log records and audit log records. Because ALL is specified, the utility starts archiving with the oldest record and continues until it encounters a log record with the current date.
//SYSIN DD *
LSN=Logger data set name
FILTER=X
ALL
/*
The following SYSIN control statement example is for archiving command log records.
  • The first line is a comment line because the first column has an asterisk.
  • The second line has keyword LSN starting from the second column. This is valid because keywords must start in column 1 or 2.
  • The third line is a blank line. The utility skips this line.
  • The forth line has multiple keywords in one line.
//SYSIN DD *
*  Comment line
 LSN=Logger data set name
 
 FILTER=C MAX
/*