Tracking system activity (CCAJRNL, CCAAUDIT, CCAJLOG)

Overview of the journal data sets

This topic discusses the journal data sets you can create and use in Model 204, how to manage them, and the utilities you can use to report on and analyze the Model 204 information collected. The system manager can set up the following journal data sets, which are not part of Model 204 installation.

The data sets are CCAJRNL, CCAAUDIT, and CCAJLOG. You set each up as:

• A ddname in z/OS
• A FILEDEF in z/VM
• A DLBL in z/VSE

Introducing CCAJRNL

The complete repository of Model 204 system activity and data that would be used in recovery is CCAJRNL. The CCAJRNL file collects all update information used to reconstruct the database during recovery and all other activity history, such as messages and statistics, in an unformatted, therefore unreadable, binary format.

Introducing CCAAUDIT and CCAJLOG

You can also create a CCAAUDIT and/or a CCAJLOG file to track information. CCAAUDIT and CCAJLOG are comprised of the same Model 204 audit trail data, however, differently. The activity history or audit trail is comprised of:

• Important characteristics of a run
• All error messages encountered during a run
• All communications with the operator's console
• Input lines from Online terminals
• HLI calls
• Utilization statistics
• Information specifically directed to the journal/audit trail by users

Watching your system in action: CCAAUDIT

The CCAAUDIT file, also known as the audit trail, logs information about a Model 204 run and prints the information in readable format for the terminal screen while processes are running or to paper.

Improving recovery performance: CCAJLOG

The CCAJLOG file off loads the audit trail information into itself, so that the CCAJRNL contains only the information required for RESTART recovery. Recovery performance is improved, because the audit trail information does not have to be read and rejected for recovery.

Version-specific journals

Journals created by Model 204 prior to V7R1.0 cannot by processed in V7R1.0. The reverse is also true: journals created in V7R1.0 cannot be processed by an earlier version of Model 204.

Using Model 204 journal files

Model 204 system managers and file managers use the journal files in some of the following ways:

Task	Journal used	Utility/command used
Generate an audit trail that can be viewed during processing	CCAAUDIT
Generate an audit trail for printing out later	CCAJRNL, CCAJLOG	Audit204 utility
Regenerate a file to complete media recovery	CCAJRNL (ddname CCAGEN)	REGENERATE command
Recover Model 204 following a system failure	CCAJRNL (ddname CCARF)	RESTART command
Extract a report	CCAJRNL	UTILJ utility
Performance tuning by analyzing statistics	CCAJRNL	Audit204 utility or site written analysis program

The Model 204 system manager is expected to create the CCAJRNL file at their site for recovery purposes. The Model 204 file manager may be responsible for using the CCAJRNL file to regenerate data files.

Creating and generating CCAJRNL

A journal is generated if:

• The SYSOPT parameter includes the 128 specification.

  You must set BLKSIZE for CCAJRNL to not less than 6749 on up to 32K. Buffers are written to CCAJRNL either when a transaction is committed or when the buffer fills. Frequent commits may result in many short blocks/buffers being written to CCAJRNL.

• A CCAJRNL is defined with BLKSIZE set to the minimum, 6749, for:
  • z/OS, a DD statement
  • z/VM, a FILEDEF

Statistics generated in an audit trail line are presented in User statistics entries (Type 9).

The use of CCAJRNL in recovery procedures is explained in Recovery data sets and job control.

How to use CCAJRNL to regenerate a data set is discussed in Media recovery.

CCAJRNL may take multiple extents and may span multiple volumes, since it is read forward-only. Its size cannot be limited in a way similar to the CHKPOINT data set (see Limiting the size of CHKPOINT), because CCAJRNL records all update activity in an Online, which may be required in a subsequent REGENERATE or RESTART process.

CCAJRNL as single data set or stream

You can define CCAJRNL as a single data set or as a stream. Using a DEFINE STREAM command, you incorporate multiple journal data sets.

• For parallel and ring structures, see Example 1: Ring/parallel journal stream.
• For GDG structure, see Perpetual journaling for z/OS.

SWITCH STREAM command

The SWITCH STREAM command switches a stream to the next member of a parallel, ring, concatenated, or Generation Data Group (GDG) stream. You can issue the SWITCH STREAM command for the following streams: CCAJLOG, CCAJRNL, CHKPOINT, or CHKPNTS.

Using the SWITCH STREAM command

When the SWITCH STREAM command is issued, the following messages are produced:

M204.2712: STREAM streamname IS BEING SWITCHED M204.2712: STREAM streamname SWITCHED VIA COMMAND

• When switching a journal stream, CCAJRNL or CCAJLOG, the currently active data set in that stream is closed. The next data set defined to the stream is opened when the next write to that stream is required.
• When switching a checkpoint stream CHKPOINT or CHKPNTS, the currently active data set in that stream is closed after the next record is written to that data set.

If not in an extended quiesce, Rocket Software recommends that you follow a SWITCH STREAM CCAJRNL command with a CHECKPOINT command to ensure that you have a checkpoint in the current journal.

The SWITCH STREAM command is sometimes useful for CCAJLOG and rarely required for CHKPOINT or CHKPNTS.

Journal block header information for SWITCH STREAM

Some journal analysis utilities require additional journal information at sites that embrace GDG streams and the SWITCH STREAM command as a means to keep their Onlines up for long periods. Model 204 includes this additional information in the header for each journal block.

To ensure that the required information is present in the first block of each journal data set created by the SWITCH STREAM command, the header has been expanded. This expansion makes the journal up to 4% larger than in previous releases.

Note: Due to these changes in journal record layouts, CCAJRNL and CHKPOINT/CHKPNT data sets are not compatible with previous releases of Model 204.

For the complete description of the header entry formats in the journal block, see Header entries (Type 0).

In pre-7.4.0 versions of Rocket Model 204, each Online environment might produce a single merged journal daily. If an Online was bounced during the day, then the various journals for the day were merged into a single daily journal. Usually the daily merged journal contained records from only one run. The single merged journal could be used to automate media recovery, rather than manually assemble the recovery job journal concatenation.

Using the SWITCH STREAM command, a site can still prepare a daily merged journal. However, when the SWITCH STREAM command is used, each journal merged does not begin with the initialization of the Online. This means that no Type 12 records or M204.0061 initialization messages are included. Although Model 204 recovery, including media recovery, can successfully process these merged journals, various journal analysis utilities cannot.

Using a SWITCH STREAM CCAJRNL command during extended quiesce

In pre-7.1.0 releases, if you used the checkpoint quiesce feature, a switch to the next journal member at checkpoint quiesce could occur only when CCAJRNL was defined as a ring stream.

However, a switch at checkpoint quiesce may be desirable for all stream configurations of CCAJRNL: ring, parallel, concatenated, and GDG. The switch marks the point where the CCAJRNL data collected thus far is not needed in subsequent REGENERATE processing against files backed up during the quiesce. If file backups or dumps are taken during the checkpoint quiesce, only CCAJRNL data collected after checkpoint quiesce is useful for REGENERATE processing against those files.

A checkpoint is automatically taken if you issue a SWITCH STREAM CCAJRNL command while you are in extended quiesce, as shown in the following table:

SWITCH command within extended quiesce

Step	Command issued	Purpose
1	CHECKPOINT SET EXTENDED QUIESCE	Enables extended quiesce
2	CHECKPOINT or automated checkpoint	The next checkpoint, automated or command initiated, begins the extended quiesce When the checkpoint is successful, the extended quiesce is entered. While in extended quiesce, you cannot issue a CHECKPOINT command. However, you can issue a SWITCH STREAM command, such as the following:
3	SWITCH STREAM CCAJRNL	When the checkpoint is successful, extended quiesce processing can begin for backups, SnapShots, or any activity that does not involve updating.
4	CHECKPOINT END EXTENDED QUIESCE	Concludes extended quiesce. Should recovery be required due to a failure during extended quiesce, journals created prior to the SWITCH STREAM command will not be required, as the last checkpoint resides in the current CCAJRNL member.

This automated checkpoint functionality of SWITCH STREAM CCAJRNL applies only during checkpoint quiesce. The automated checkpoint functionality is not supported for CCAJLOG, CHKPOINT, or CHKPNTS.

SWITCH STREAM limitations

In order for a stream to be switched, there must be a target data set to switch to. If there is no target data set, the following message is issued:

M204.2712: MEMBER membername IS INELIGIBLE FOR SWITCHING

Consider the following example:

DEFINE STREAM CCAJRNL WITH SCOPE=SYSTEM PARALLEL=(JRNL1,JRNL2) MINAVAIL=2 DEFINE DATASET JRNL1 WITH SCOPE=SYSTEM DSN=CCAJRNL.JRNL1 OLD DEFINE STREAM JRNL2 WITH SCOPE=SYSTEM GDG=J2 CONTROL=J2CTL DEFINE DATASET J2 WITH SCOPE=SYSTME DSN=CCAJRNL.GDGBASE.JRNL2 CATALOG - GEN=+1 CYL PRI 500 DEFINE DATASET J2CTL WITH SCOPE=SYSTEM DSN=CCAJRNL.GDGBASE.JRNL2.CTL OLD

Since data set JRNL1 has no target data set for a switch, when the JRNL1 data set is marked full, the number of available parallel stream members (MINAVAIL) drops to one, since only JRNL2 now has space available. Since the number of available members is now less than MINAVAIL, the Online would stop with a "CCAJRNL full" message.

If before JRNL1 fills, a SWITCH STREAM CCAJRNL command were issued, the following messages would be produced:

M204.2712: MEMBER JRNL1 IS INELIGIBLE FOR SWITCHING M204.2712: STREAM JRNL2 IS BEING SWITCHED M204.2712: STREAM CCAJRNL - NOT ALL MEMBERS SWITCHED

Member JRNL1 was not switched. However, if JRNL1 has not filled, the parallel stream will remain open because the number of available members (MINAVAIL) is still 2. Stream JRNL2 always has a target data set to switch to since it is a GDG. Nevertheless, whenever JRNL1 fills, the minimum available members will be less than MINAVAIL, the stream will be closed, and the run will terminate.

Because stream members are not locked before switch processing, and because all members are not switched at exactly the same time, the number of records in individual data sets of a parallel stream may not be identical. This is of no consequence to recovery or REGENERATE, but should be noted. However, the total number of records in each member is identical.

Previously, you had to concatenate all journals into one data set or specify a concatenated CCAGEN DD statement.

SWITCH STREAM command for concatenated streams

The same limitation exists for the last member in a concatenated stream. Since there is no additional member to switch to, the following message is issued:

M204.2712: STREAM streamname IS INELIGIBLE FOR SWITCHING

If all members of a stream are switched, the following message is issued:

M204.2712: STREAM CCAJRNL SWITCHED VIA COMMAND

Handling streams without records

You cannot switch a stream member that contains no records. So in the previous case, if the first G1 stream member has just become full and the newly opened (second) GDG member contains zero records, then a SWITCH STREAM CCAJRNL command is not processed.

Since J1 is ineligible, and G1 (second member) is empty, no switch occurs. The messages issued are:

M204.2712: MEMBER J1 IS INELIGIBLE FOR SWITCHING M204.2712: MEMBER G1 IS EMPTY AND CANNOT BE SWITCHED M204.2712: SWITCH WAS UNSUCCESSFUL

Recovery parameters

Use the following recovery parameters when generating a journal:

Parameter	Set	Specifies...	Comments
FRCVOPT	During file creation or with the RESET command	File recovery options	If the file is included in system or media recovery, do not use FRCVOPT=X'04', which suppresses roll forward logging.
RCVOPT	On the JCL EXEC parameter or on User 0's parameter line	Type of information written to the journal	X'08' writes the roll forward information that is required for system and media recovery to CCAJRNL. X'09' also causes preimages to be written to the CHKPOINT data set for roll back recovery. Use this setting if you want to enable full recovery.

Writing error messages to the journal data set

You can control which error messages or classes of error messages to store in CCAJRNL, CCAAUDIT, or CCAJLOG using MSGCTL command parameters.

ERRMSGL: Setting the length of saved error messages

The ERRMSGL parameter provides the ability to set the number of bytes to use for saved error messages — messages returned by $Errmsg and $Fsterr. You can set ERRMSGL to any value from 80 to 256 — that length includes a count byte. The value is rounded up to an 8-byte multiple. For example, if you set ERRMSGL=99, it will be rounded to 104, that value is reduced by 1 for the count byte, thus allowing up to 103 characters of an error message to be saved.

Server size requirements for saved error messages

Increasing ERRMSGL increases the requirement of the fixed table size of a server. This may necessitate an increase in you SERVSIZE settings. The size requirement for ERRMSGL is:

3 * (ERRMSGL - 80)

For example, increasing ERRMSGL to its maximum of 256 would increase the fixed server requirement by (3 * (256-80) -1), or 527 bytes.

For a full update to the SERVSIZE formula, see Calculating fixed table size.

Using the CCAJRNL data set

During a production Online run, roll forward recovery information is written to the CCAJRNL data set. Additionally, a substantial amount of unformatted audit trail data is also written. When recovery is required and after roll back recovery has completed, that data set (during recovery its ddname is CCARF) is read and the roll forward information is extracted and used to reapply all committed updates up to the time of the system failure.

CCAJRNL collecting all roll forward and audit information

Performance efficiencies using CCAJRNL

Choosing whether to define CCAAUDIT

Model 204 operates more efficiently using CCAJRNL without CCAAUDIT, because it is not also generating a separate audit trail. If you need printed information and your site does not maintain CCAAUDIT, you can extract the audit trail from CCAJRNL in a separate step using AUDIT204.

If you need printed run information immediately upon completion of the job and you also need Roll Forward or Accounting facilities, create both the journal (CCAJRNL) and the audit trail (CCAAUDIT).

You can use CCAJRNL in place of CCAAUDIT when you do not need audit trail data immediately following run termination.

Allocating multiple journal buffers

Setting NJBUFF to a value (NSERVS + NSUBTKS + 1) allocates multiple journal buffers and ensures that a free buffer is always available for the journal. In z/VM, the NJBUFF parameter is stacked in the EXEC that issues all the FILEDEFs.

Using the CCAJLOG data set

If you allocate CCAJLOG, the unformatted audit trail data is written to it and only roll forward recovery data is written to CCAJRNL. Reducing the number of records written to CCAJRNL improves recovery performance and also reduces the likelihood of filling CCAJRNL, which would result in run termination.

• The number of buffers allocated for CCAJLOG is determined by the parameter, NLBUFF, which defaults to five. Only full blocks/buffers are written to CCAJLOG.
• The size of these buffers is determined by the BLKSIZE parameter defined for the CCAJLOG data set which may be as large as 32K.

You can produce a formatted CCAAUDIT report from CCAJLOG using the AUDIT204 utility. In this case, the CCAJLOG is referenced via the ddname CCAJRNL.

CCAJRNL collecting roll forward data;
CCAJLOG collecting audit trail data

Defining the CCAJLOG stream

You can define a CCAJLOG using any of the stream definitions: concatenate, parallel, ring, or GDG; see DEFINE STREAM command.

M204JLOG assembler exit

The assembler exit, M204JLOG, can be invoked if linked in. This exit is initiated when a SWITCH command is issued against a CCAJLOG GDG stream. The exit may be any AMODE and need not be reentrant.

Coding considerations

On entry, the registers contain:

R4 = A(GDG LIOD)

R9 = A(new switch control record) (see CRD dsect)

R13 = A(OSW save area)

R14 = return address

R15 = base address

Model 204 expects no output from the exit. All registers must be restored before return. If any Model 204 data structures are modified by the exit, unpredictable results may occur.

Note: If the user exit abends, Model 204 issues an error and produces a snap. This leaves Model 204 waiting for the switch to complete. At that point the switch will never complete, no further Online activity is possible, and the Online must be cancelled.

In addition, while the M204JLOG user exit is running, Model 204 cannot continue normal processing until a return from the exit is accomplished. For this reason, WAITs and I/Os inside the exit are strongly discouraged.

Sample M204JLOG Assembler exit

M204JLOG CSECT M204JLOG AMODE 31 M204JLOG TITLE 'TEST THE MODEL 204 CCAJLOG USER EXIT' X10 EQU 10 X11 EQU 11 X12 EQU 12 X13 EQU 13 X14 EQU 14 X15 EQU 15 STM X14,X12,12(X13) SAVE CALLERS REGISTERS LR X12,X15 ESTABLISH BASE REGISTER USING M204JLOG,X12 LA X10,SAVEAREA GET A(LOCAL REGISTER SAVEAREA) ST X10,8(,X13) CHAIN OUR SAVEAREA TO CALLERS ST X13,SAVEAREA+4 CHAIN CALLERS SAVEAREA TO OURS LA X13,SAVEAREA SET A(OUR SAVEAREA) WTO 'M204JLOG EXIT INVOKED, DOING SOMETHING' * ******************************************************************* * * * CUSTOMERS MAY PLACE CODE HERE TO DO WHATEVER THEY DESIRE. * * * ******************************************************************* * WTO 'M204JLOG EXIT ENDING' L X13,4(,X13) RESTORE CALLERS SAVEAREA ADDRESS ST X10,16(X13) SET RETURN CODE (R15) LM X14,X12,12(X13) RESTORE CALLERS REGISTERS BR X14 RETURN TO CALLER DS 0D SAVEAREA DS 18F REGISTER SAVE AREA LTORG END

Model 204 roll forward recovery with CCAJLOG

Model 204 operates more efficiently during roll forward recovery, if you have defined CCAJLOG. This is because CCAJRNL now contains only roll forward recovery data; CCAJLOG contains unformatted CCAAUDIT data, which does not have to be read and ignored during the roll forward recovery since it has been removed from CCAJRNL.

Separating transaction (CCAJRNL) and auditing (CCAJLOG) information

Splitting audit trail records — messages and statistics — out from CCAJRNL and writing them to CCAJLOG improves recovery performance by reducing the size of CCAJRNL. This also reduces the likelihood of filling CCAJRNL. However, it does shift the possibility to CCAJLOG and if either CCAJRNL or CCAJLOG fills, the run comes down.

Regenerating files using CCAJRNL and CCAJLOG

Sending audit trail data to CCAJLOG also speeds up the REGENERATE processing, if that is required.

Considerations for CCAJLOG

By specifying CCAJLOG in the JCL or dynamically at the start of CCAIN, all messages and statistics are written to CCAJLOG. All recovery-type records are written to CCAJRNL.

• If you do not specify CCAJLOG, a CCAJRNL is maintained that collects recovery records, messages, and statistics.
• If CCAJLOG is specified but the open fails, the run terminates initialization.
• If CCAJLOG fills during a run, the run is terminated.

Set the NLBUFF parameter to specify the number of buffers to use for CCAJLOG. If you do not specify a value for NLBUFF, a default value of five is allocated.

Using the journals correctly

If you create both a CCAJRNL file and a CCAJLOG file, you must use the CCAJLOG file as input to AUDIT204. And, you must continue to use the CCAJRNL file as input to REGEN and RESTART commands; otherwise, Model 204 issues one of the following messages:

M204:2515: CCAJRNL DATASET IS INVALID FOR AUDIT 204 M204:2515: CCAJLOG DATASET IS INVALID FOR {REGEN | RESTART}

If you create both a CCAJLOG and CCAJRNL and you use the CCAJRNL as input to AUDIT204, AUDIT204 issues the following message and stops processing:

NON-MESSAGE DATASET IS INVALID FOR CCAJRNL

Although UTILJ can handle a CCAJLOG data set, the utility will, of course, find only message and statistics type records in CCAJLOG. So, if you ask for recovery journal entries, type 1-6, the output is empty, since they do not exist on the CCAJLOG.

Because audit trail information is stored in CCAJLOG, if you have written a custom application for statistics reports, use CCAJLOG for input.

CCAJRNL data set record layout

The journal data set is composed of variable length records. Each record consists of a header, one or more journal entries, and a trailer. The format of the journal data set is subject to change with each release of Model 204.

Journal entry format

Journal entries contain audit trail, statistical, and control information, or information used for recovery. Statistics are recorded in the journal as fullword hexadecimal counters. Space is allocated in a given journal statistics entry for all possible statistics, even if they are not being kept. The values for statistics that are not maintained, or do not have relevance to the current configuration of Model 204, are represented as hexadecimal zeros.

Each entry has the same general format:

Bytes	Contents
0-1	Length
2	Entry type
3-n	Data

Offset 0 is a 2-byte hexadecimal field containing the length of the entry. (The only exception to this rule is the header entry, where the length is the length of the entire journal block.)

Offset 2 is a 1-byte field, which identifies the type of the entry: file, system, or user.

Offset 3 is a variable-length data portion. The size and layout depends upon the type of entry.

The following table summarizes the journal entry types, including formatting layouts and statistical information. Use the layout and statistics tables in Using system statistics for developing customized software to extract particular information from the journal data set.

Summary of journal entry types

Type	Journal record
X'00'	Header/Trailer
X'01'	Recovery entry
X'02'	Recovery entry
X'03'	Recovery entry
X'04'	Recovery entry
X'05'	Recovery entry
X'06'	Recovery entry
X'07'	Unused
X'08'	System statistics
X'09'	User statistics
X'0A'	File statistics
X'0B'	Discontinued audit trail text
X'0C'	Initialization entry
X'0D'	Possibly continued audit trail text
X'0E'	Timestamp
X'0F'	Merged journal brackets

Number of lines in the journal data set

The number of lines in the journal are controlled by the CAUDIT, LAUDIT, and SYSOPT parameters.

CAUDIT parameter

The CAUDIT parameter controls physical input lines from a terminal, procedure, some IFAM arguments, or full-screen input. CAUDIT operates at physical line (card) level. It controls the auditing of input lines after line editing has been performed, but before line continuation is interpreted.

CAUDIT is set on any user parameter line at the beginning of CCAIN, and can be reset by a user with system manager privileges who logs in with that user number. (CAUDIT is generally used only by Technical Support staff in special instances.)

LAUDIT parameter

The LAUDIT parameter controls logical input lines from a terminal or procedure, some IFAM arguments, and full screen information. LAUDIT is useful in reconstructing events that lead to a system crash.

Set LAUDIT on any user parameter (IODEV) line or at the beginning of CCAIN. For example:

PAGESZ=6184,NUSERS=1,NSERVS=1,NFILES=20, LENQTBL=15,LAUDIT=5, ...

LAUDIT can be reset by a user with system manager privileges who logs in with that user number.

SYSOPT parameter

The SYSOPT 32 option controls output of information that relates to system initialization or to an IFAM function call.

Sizing the journal buffer

In z/OS and z/VM only, you can specify the NJBUFF parameter on the EXEC statement to make journal entries of one user without interrupting other current users. Valid settings are the default NJBUFF=1 or, to ensure the availability of a free buffer:

NJBUFF = NSERVS + NSUBTKS + 1

In z/OS only, if the setting of the NJBUFF parameter is greater than 1, the setting is automatically recalculated using the previous formula and the initial value of NJBUFF is used to define the number of concurrent I/O operations (NCP) for the journal data set. Sizing NJBUFF to the value calculated in the formula guarantees the optimal number of Network Control Programs (NCP) for the journal data set.

If you use the NJBUFF option, specify BLKSIZE=6749 as the minimum journal buffer size to allow a full page to be written to a single journal buffer. The contents of a buffer are automatically written to CCAJRNL before the buffer is completely full.

Messages giving the number of journal buffers and the number of bytes allocated to the buffers are displayed at the end of the run.

Managing space requirements for all operating systems

The space requirement for CCAJRNL is reduced, if CCAJLOG is enabled. However, CCAJRNL must still be sized to prevent B37, D37, or E37 abends, which will terminate the run and require recovery to get files to a state of logical and physical consistency. The same applies to CCAJLOG: If it fills, the run terminates and recovery is required. Generous secondary extents allocated to these data set also help avoid overflow problems.

Additional managing space requirement on z/OS

At a z/OS site, the most comprehensive way to avoid data set full problems is to define both CCAJRNL and CCAJOG as generation data groups (GDGs). See Perpetual journaling for z/OS.

Introducing Model 204 statistics

A statistic is written to CCAAUDIT only if its value is nonzero. However, all statistics, even those with zero values, are written to CCAJRNL (or CCAJLOG).

Audit trail and journal statistics lines

The statistics generated on audit trail lines are valuable in a study of the performance of an individual user or of the Model 204 system as a whole. The effect of configuration changes within Model 204 and with other jobs in the operating system can be determined by comparing statistics gathered in Model 204 runs.

• Statistics described as percentages are multiplied by 10 (a value printed as 1000 represents 100 percent).
• Statistics described as averages are multiplied by 1000 (1000 represents 1.000).

Output lines

Statistics for each user and file active during a particular run are written to the journal and audit trail files in output lines that begin with ST $$$. The output lines are written in groups of related lines that include:

• User lines, which you can monitor to identify active users and to help determine if individual applications are efficiently implemented
• File lines
• System lines, which you can watch — together with file lines — to signal shifting loads on the CPU, disks, and terminals

The type of line written — user, file, or system — is specified by the value of the first parameter after the journal header.

Identifying subtypes

The subtype — final, partial, performance, or since-last — within each type is specified by the value of the second parameter after the journal header. In the audit trail, the subtype is indicated by USERID=user-id (user statistics), FILE=filename (file statistics), and SYSTEM=Model-204-version (system statistics).

Within each major type of statistics line, subtypes are produced under specified conditions: some are always produced, others are optional. Optional subtypes are produced if the appropriate parameters are set during system initialization. See Setting the NSUBTKS parameter.

Monitoring statistics

The Model 204 statistics that you can monitor are introduced in Using system statistics. The statistics are presented in alphabetical order with their stated purpose, followed by tables that identify their position in various layouts.

You can monitor statistics using one or more of the following methods:

• Print out the audit trail.
• View formatted or unformatted displays of all nonzero cumulative statistics for active users — individual, specified groups, and all users — and system activities.
• Use the AUDIT204 or UTILJ utility program to extract and summarize statistics lines from the journal data set. See Introducing the AUDIT204 utility and Using the UTILJ utility
• Write optional records to the System Management Facilities (SMF) data set; see System Management Facilities.

Setting the NSUBTKS parameter

Gathering partial or performance statistics lines requires a Model 204 pseudo subtask. Model 204 uses pseudo subtasks to perform actions that must be done regularly but that cannot be assigned to a specific user. To accommodate partial and performance statistics lines you might need to increase the NSUBTKS parameter on User 0's parameter line, which controls the maximum number of pseudo subtasks that can be allocated.

Setting parameters to collect certain statistics

You must set various parameters to collect certain statistics. The following table lists the statistics and the corresponding parameter(s):

Parameters to set to collect certain statistics

Statistic	Parameter to set to nonzero
BLKCFRE	CFRJRNL and CFRLOOK
BLKI	RPTCNT and SMPLTIM
BLKO	RPTCNT and SMPLTIM
BLKRLK	CFRJRNL and CFRLOOK
LONGUPDTIME(MS)	MAXUD
LONGUPDTS	MAXUD
PNDGTIME	DKUPDTWT
REDY	RPTCNT and SMPLTIM
RUNG	RPTCNT and SMPLTIM
SMPLS	RPTCNT and SMPLTIM
SWPG	RPTCNT and SMPLTIM
USRS	RPTCNT and SMPLTIM
WTCFR	CFRJRNL and CFRLOOK
WTRLK	CFRJRNL and CFRLOOK
WTSV	RPTCNT and SMPLTIM

Audit trail format

Whether printed to your terminal from CCAAUDIT or CCAJRNL (or CCAJLOG) is processed by AUDIT204, the format of an audit trail line is:

yydddhhmmss nnn sss xxxxx tt (...) audit-trail-text

Where:

• yyddd is the Julian year and day.
• hhmmss is the time of day in hours, minutes, and seconds.
• nnn is a counter to distinguish lines produced in the same second.
• sss is the number of the server currently handling the user. (Leading zeros are suppressed.)
• xxxxx is the 5-digit number of the user associated with the audit trail line. (Leading zeros are suppressed.)
• tt is code for the type of audit trail line. The tt codes are shown in the "Types of audit trail lines" table, below.

Example

05263092241 10 0 1 AD...M204.0763: BEGIN FILE INITIALIZATION:

The following table lists the code and purpose of the audit trail lines:

Types of audit trail lines

Code	Displays...
AD	Special information about the run, job step return code, status of Model 204 files, user or the password table, the SNA Communications Server (formerly VTAM) Interface, or messages sent from an HLI program via the IFERR call. Note that the high-water mark of CCATEMP usage (SCMAX) also reports the total number of pages allocated to CCATEMP.
CI	Physical input line from a user's terminal or some IFAM arguments.
CP	Physical input line from a procedure.
CS	Physical line of full-screen input (see LS below).
ER	Error message sent to the user.
LI	Logical input line from a user's terminal or some HLI arguments.
LP	Logical input line from a procedure.
LR	Read images from a terminal.
LS	Full-screen information. For a screen, each line lists one input value. For a menu, the line provides the menu selection number.
MS	Informational message sent to the user (not an error).
OI	Input line from the operator's console.
OO	Message sent to the operator's console.
RK	Special information that relates to system initialization or to the record of a call to the following types of function: Connect★ HLI MQ/204 PQO SQL UL/DB2
QT	Lines of SQL statement level processing
ST	Utilization statistics (see Using system statistics).
US	Line of special information directed to the audit trail by means of the SOUL Audit statement.
XX	Continuation of the previous line.

Generating an audit trail

Overview of audit trail parameters

An audit trail is generated if:

• The SYSOPT parameter includes the 128 specification
• CCAAUDIT DD statement

The LAUDPROC parameter controls the length of procedure names that appear in since-last statistic lines of the audit trail. You can reset LAUDPROC to a low or high value. A low value conserves memory. A high value captures long procedure names.

z/VSE and the audit trail

In a z/VSE environment, activate the audit trail by incorporating the following specifications into the JCL:

• You must set UPSI to 1xxxxxxx (SYSOPT=128).
• You must write the audit trail file to either a disk device or a print device:
  • Assign a disk device using a DLBL and EXTENT statement for file name CCAUDIT (retention 0 is recommended).
  • Assign a print device using symbolic unit SYS008. (You cannot assign SYS008 to the same physical device as SYSLST.)

    If the DLBL and EXTENT for CCAUDIT are provided in the JCL, the audit trail is written to disk regardless of the assignment of SYS008.

The following example shows a job stream for an ONLINE configuration with the audit trail on disk:

// JOB ONLINE ... // DLBL CCAUDIT,'audit trail file-id',0 // EXTENT SYSnnn,balance of extent information // ASSGN SYSnnn,X'cuu' ... // UPSI 10000000 // EXEC ONLINE, SIZE=AUTO ... /&

After the audit trail has been written to disk, you can print it using the UTLA utility program supplied with the Model 204 DBMS. The UTLA utility is discussed in the Rocket Model 204 Installation Guide for IBM z/VSE.

Use the following JCL:

// JOB UTLA PRINT MODEL 204 AUDIT TRAIL // DLBL M204LIB,'M204.PROD.LIBRARY' // EXTENT SYSnnn,... // LIBDEF PHASE.SEARCH=M204LIB.V411 // DLBL CCAUDIT,'audit trail file-id' // EXTENT SYSnnn,balance of extent information // ASSGN SYSnnn,X'cuu' // ASSGN SYS005,SYSLST // EXEC UTLA,SIZE=AUTO /&

z/VM and the audit trail

In the z/VM/CMS environment, define CCAAUDIT as one of the following:

• CMS file:

  FILEDEF CCAAUDIT DISK ONLN CCAAUDIT A

• Service machine virtual printer:

  FILEDEF CCAAUDIT PRINTER

Introducing the AUDIT204 utility

The AUDIT204 utility program produces the following:

• Complete or partial audit trail from a journal — CCAJRNL or CCAJLOG, as ddname CCAJRNL — produced by a Model 204 run
• Report based on statistics that appear on user logout and partial lines or file closed and partial lines
• Statistical analysis of the evaluation of SOUL requests

The format of AUDIT204 reports is determined by AUDIT204 commands and parameters you enter in:

• z/OS CCAIN data stream
• z/VM (CMS) AUDIT204 CCAIN file
• DOS SYSIPT statement

The basic AUDIT204 input commands are:

AUDIT204 command	For...
ANALYZE	Statistical analysis of the evaluation of User Language requests
FORMAT	Printed audit trail
REPORT	Breakdown of user and file statistics lines containing optional price calculations

Input to AUDIT204

Input to AUDIT204 is free form, located in columns 1-71. The following rules apply:

• Use blanks to separate terms.
• Type each parameter on a separate line.
• You can type parameters for a single command in any order.
• You can add subparameters for some parameters (PRICE and RENAME) by naming the subparameters in the form of character strings:
  • If a name contains a blank or a single quotation mark, you must enclose the name in single quotation marks.
  • Use double quotation marks within the name.
  • Use blanks around the equal signs in the PRICE and RENAME parameters.
  • Use blanks to separate subparameters.
  • If more than one line is required for the subparameters, place a nonblank character in column 72 or repeat the parameter on a new line.
• Any characters appearing in columns 73-80 are ignored.
• You can repeat any parameter.
• Precede each comment by an asterisk (*) in column 1.
• The effect of parameters containing lists of subparameters is cumulative.
• The last value of parameters without subparameter lists is the value used.

ANALYZE command

The ANALYZE command obtains a statistical analysis report on the evaluation of SOUL requests by AUDIT204. The complete report comprises an analysis for each individual account and the system as a whole.

Since-last evaluation lines calculate the mean and standard deviation for each since-last statistic:

Measure	Represents...
Mean	Center of a set of data points (usually referred to as the average value of the set), obtained by summing the values and dividing by the number of values.
Standard deviation	How spread out the data is around the center. In particular, it is useful to know whether the data is tightly clustered around the mean, or more dispersed. A small standard deviation indicates that any given value is likely to be close to the mean, and a large standard deviation implies that a value is more likely to be far away from the mean.

You can obtain more information about the mean and the standard deviation from any standard statistics textbook.

Syntax

Use the following syntax for the ANALYZE command:

ANALYZE [USERID | NOUSERID] [USERIDS userid1...useridn]

or

ANALYZE [ACCOUNT | NOACCOUNT] [ACCOUNTS account1...accountn] [parameters]

Where:

Use the following parameters with the ANALYZE command:

Parameter	Specifies...
ACCOUNT or NOACCOUNT	Whether or not to do an individual account analysis. The ACCT or NOACCT parameters are equivalent to ACCOUNT or NOACCOUNT, respectively.
ACCOUNTS	Login account name(s) to list in the analysis report. Reports are produced only for the specified accounts and only the since-last evaluation lines for those accounts that are included in the systemwide report. Specifying ACCOUNTS sets the ACCOUNT parameter when neither ACCOUNT nor NOACCOUNT was specified.
OMIT name1 name2...	Since-last statistic(s) to list, but omit from the analysis report. The report contains all since-last statistics that are not explicitly omitted.
RENAME name=newname	New names to since-last statistics as column headings for an analysis report.
TIME [yydddhhmmss | yydddhhmmss | cyydddhhmmss | cyyddhhmmss]	Time range from which since-last evaluation lines are taken.
SYS (the default) or NOSYS	Whether or not to do a systemwide analysis using since-last evaluation lines of accounts for which an individual analysis is done.
USERID (the default) or NOUSERID	Performing or suppressing an individual user ID analysis. Totals for a systemwide analysis are still accumulated if NOUSERID is specified.
USERIDS	User(s) for which analysis is requested. The USERIDS keyword is required in addition to the USERID keyword. If neither USERID nor NOUSERID has been specified, specifying USERIDS sets the USERID parameter. Reports are produced only for the specified users and only the since-last evaluation lines for those users who are included in the systemwide report. AUDIT204 uses the values specified in the USERID parameter as a pattern and finds all values that match. For example, USERIDS NANCY KATHY is equivalent to REPORT USERID USERIDS NANCY* KATHY*.

Usage note

The ANALYZE command for AUDIT204 can process only a single journal, CCAJRNL. You cannot use the ANALYZE command against the CCAJLOG file.

FORMAT command

FORMAT prints an audit trail from the journal.

Syntax

FORMAT TIME {yydddhhmmss/yydddhhmmss | cyydddhhmmss/cyydddhhmmss} TYPE type1 USER usernum USERID userid YEARFORM {2 | 4}

Where:

You use the following parameters with the FORMAT command:

Parameter	Specifies...
TIME	Time range to print. The format of the time specification corresponds to the time stamp printed with each audit trail line. You can specify start and end times in either order. If either time is out of the range covered by the journal, it is corrected to match the actual start or end of the journal. If both specified times are before and after the period covered by the journal, nothing is printed. yyddd or cyyddd is the year and Julian date. hhmmss is time based on a 24-hour clock.
TYPE	Type of lines to print, such as AD or MS (see the "Types of audit trail lines" table).
USER	User for whom the printed audit trail lines are generated. Specify user numbers with or without leading zeros.
USERID	One- to ten-character name that identifies the Model 204 user about whom the printed audit trail lines are generated.
YEARFORM	Two- or four-digit year output. The default is 2.

Example

The options specified in the following example restrict the printing of the audit trail to MS (message) lines for USER 01 created on September 22, 1998 between 10:41 A.M. and 10:45 A.M.:

FORMAT TYPE MS, ER TIME 98265104100/98265104500 USER 01

Usage

The FORMAT command can be used against a CCAJRNL file or a CCAJLOG file. Examine the code examples that begin in Samples of a z/OS job stream.

REPORT command

The REPORT command prints user and file statistics in a tabular format and computes costs by account or by file for billing purposes. AUDIT204 reports have a two-line header, as shown in the following example, that reflect the circumstances of your site.

AUDIT204 UTILITY - VERSION 7.10a, DATE/TIME OF RUN: 10/22/208 11:31:38

Syntax

REPORT type [parameters]

Where:

• type is a subcommand that specifies the type of report to print:

  Subcommand	Specifies printing a report from...
  ACCOUNT	User statistics lines for specific accounts
  FILE	File statistics
  USERID	User statistics lines

• parameters is one or more of the following, which can be used with USERID, ACCOUNT, or FILE:

  Parameter	Specifies...
  IND (the default) or NOIND	Printing or not printing individual lines. Totals are still accumulated if NOIND is specified.
  OMIT	Statistic(s) to omit from the report. You must enter the actual name of the statistic, not what appears in a column header in a report. See Description of statistics for an alphabetical listing of statistics.
  PARTIAL or NOPARTIAL	Generation of partial or complete statistics lines. Use: PARTIAL when a report is generated from a journal that did not terminate successfully. NOPARTIAL to avoid processing overhead, when a complete journal is available.
  PRICE	Dollar charge up to five decimal places to any statistic. Decimal point, and leading and trailing zeros are optional. For example: PRICE CPU=0.05 DKRD=.03 DKWR=.035
  RENAME	Column heading names up to nine characters without truncation. The new name completely replaces the old name and must be used if name is specified on other parameters.
  TIME	Time range for statistics line reporting. One of the following formats is required: yydddhhmmss/yydddhhmmss cyydddhhmmss/cyydddhhmmss
  TOTAL (the default) or NOTOTAL	Totalling or suppression of totalling for individual statistics and costs.

Example

Totals are printed after individual statistics lines if both IND and TOTAL are in effect. Each line must contain only one parameter, as in the following examples:

REPORT USERID NOIND PARTIAL TIME yydddhhmmss/yydddhhmmss RENAME name=newname NOTOTAL USERIDS account REPORT FILE FILES filename OMIT statistic PRICE statistic=xx.xx

The subkeywords ACCOUNTS, FILES, and USERIDS can be used with REPORT subcommands ACCOUNT, FILE, and USERID as in the following examples:

REPORT USERID USERIDS JAMES STEVE SANDRA ACCOUNT ACCOUNTS JAMES STEVE SANDRA FILE FILES CLIENTS VEHICLES DAILY

Note: The REPORT command for AUDIT204 can process only a single journal: CCAJRNL. You cannot use against a CCAJOG file.

Using the AUDIT204 utility

CCAJRNL and CCAJLOG data sets as input to utilities

When you need a CCAAUDIT report, use the CCAJLOG data set as input to the AUDIT204 utility, under the ddname of CCAJRNL. You can also use CCAJLOG as input to the UTILJ utility, again under the ddname of CCAJRNL; however, the only useful report produced is a histogram of the number of blocks and block sizes that were written to the CCAJLOG data set.

CCAJRNL is the input data set provided to roll forward recovery (ddname=CCARF), media recovery (ddname= CCAGEN), and UTILJ (ddname=CCAJRNL).

Utilities using CCAJLOG and CCAJRNL data sets as input

Journal stream configurations

AUDIT204 can process only basic journal streams (single data sets). Members of concatenated, parallel, ring, or GDG streams must be processed one at a time.

If there is a wraparound during the output processing of a ring stream, use the offload stream as input to AUDIT204. You can also use regular z/OS concatenation to print the contents of a concatenated stream.

z/OS JCL for AUDIT204

The following considerations apply to z/OS JCL for AUDIT204:

• Use a SORTLIB DD statement to identify the library in which the sort program is stored, if necessary.
• You might need sort work (SORTWKxx) data sets.
• SORTIN, SORTOUT, and SYSOUT statements are necessary only for statistical reports. A sort program must be available:
  • SORTIN contains all the user and file statistics entries extracted from the journal. The size of the data set depends on the number of statistics entries extracted. Each user statistics entry is 198 bytes long. Each file entry is 82 bytes long. Partial statistics entries are not copied to SORTIN.
  • SORTOUT contains the sorted statistics entries from SORTIN. SORTOUT and SORTIN must be the same size.
  • SYSOUT is the SORT message data set.
• STATIN, STATOUT, and SYSOUT statements are necessary only for statistical analysis reports:
  • STATIN contains all the since-last evaluation statistics entries extracted from the journal. The size of the data set depends on the number of since-last evaluation statistics extracted. Each since-last evaluation statistics entry is 188 bytes long.
  • STATOUT contains the sorted statistics entries from STATIN. STATOUT and STATIN must be the same size.
  • Statistics work (STATWKxx) data sets might be needed when using the ANALYZE command, depending on the amount of data generated.
• CCAJRNL describes the data set containing the journal produced by a Model 204 run.
• AUDIT204 does not support streams.
• CCAAUDIT contains the audit trail, statistics report, and statistical analysis report. If you request both the audit trail and statistics, the audit trail appears first.

  The value of the BLKSIZE parameter in the CCAAUDIT DD statement is truncated at 4 more than a multiple of 137. A BLKSIZE value of 141 is the default and minimum value.

  Any LRECL and RECFM specifications are ignored; these parameter values are forced to be 137 and VBA, respectively.

Samples of a z/OS job stream

The following sample job streams run AUDIT204, These examples differ in the use of the journal processed, CCAJRNL or CCAJLOG, and the presence or absence of AUDIT204 commands: ANALYZE, FORMAT, and REPORT.

Where only CCAJRNL is defined, all AUDIT204 commands are valid

//AUDIT EXEC PGM=AUDIT204 //STEPLIB DD DSN=M204.LOADLIB,DISP=SHR //SYSUDUMP DD SYSOUT=A //CCAJRNL DD DSN=M204.CCAJRNL,DISP=SHR //CCAAUDIT DD SYSOUT=A //SORTIN DD DSN=&&SORTIN,UNIT=SYSDA,SPACE=(TRK,nn), // DISP=(NEW,DELETE) //SORTOUT DD DSN=*.SORTIN,VOL=REF=*.SORTIN,DISP=(OLD,PASS) //STATIN DD DSN=&&STATIN,UNIT=SYSDA,SPACE=(TRK,nn), // DISP=(NEW,DELETE) //STATOUT DD DSN=*.STATIN,VOL=REF=*.STATIN,DISP=(OLD,PASS) //SYSOUT DD SYSOUT=A //CCAIN DD * FORMAT ANALYZE REPORT ACCOUNT . . ---- user options . /*

Where CCAJLOG is defined and you want to extract CCAAUDIT

//AUDIT EXEC PGM=AUDIT204 //STEPLIB DD DSN=M204.LOADLIB,DISP=SHR //SYSUDUMP DD SYSOUT=A //CCAJRNL DD DSN=M204.CCAJLOG,DISP=SHR //CCAAUDIT DD SYSOUT=A //SORTIN DD DSN=&&SORTIN,UNIT=SYSDA,SPACE=(TRK,nn), // DISP=(NEW,DELETE) //SORTOUT DD DSN=*.SORTIN,VOL=REF=*.SORTIN,DISP=(OLD,PASS) //STATIN DD DSN=&&STATIN,UNIT=SYSDA,SPACE=(TRK,nn), // DISP=(NEW,DELETE) //STATOUT DD DSN=*.STATIN,VOL=REF=*.STATIN,DISP=(OLD,PASS) //SYSOUT DD SYSOUT=A //CCAIN DD * FORMAT . . ---- user options . /*

Where both CCAJRNL and CCAJLOG are defined and you want a statistical analysis

//AUDIT EXEC PGM=AUDIT204 //STEPLIB DD DSN=M204.LOADLIB,DISP=SHR //SYSUDUMP DD SYSOUT=A //CCAJRNL DD DSN=M204.CCAJRNL,DISP=SHR //CCAAUDIT DD SYSOUT=A //SORTIN DD DSN=&&SORTIN,UNIT=SYSDA,SPACE=(TRK,nn), // DISP=(NEW,DELETE) //SORTOUT DD DSN=*.SORTIN,VOL=REF=*.SORTIN,DISP=(OLD,PASS) //STATIN DD DSN=&&STATIN,UNIT=SYSDA,SPACE=(TRK,nn), // DISP=(NEW,DELETE) //STATOUT DD DSN=*.STATIN,VOL=REF=*.STATIN,DISP=(OLD,PASS) //SYSOUT DD SYSOUT=A //CCAIN DD * ANALYZE REPORT . . ---- user options . /*

z/VSE JCL for AUDIT204

The following considerations apply to z/VSE:

• Under z/VSE, output is sent to SYSLST.
• CCAJRNL can be on tape or disk. If CCAJRNL is on tape, SYS004 must be assigned to a tape drive.
• Running AUDIT204 might require two sorts:
  • REPORT command requires a SORTIN and a SORTOUT data set.
  • ANALYZE command requires a STATIN and a STATOUT data set.
• SORTIN, SORTOUT, STATIN, and STATOUT are work files and must be on disk.
• SORTWK1 data set is required.
• Statistics work (STATWK1) data set might be needed when using the ANALYZE command, depending on the amount of data generated.

Sample z/VSE job stream

The following sample job stream runs AUDIT204:

// JOB AUDIT204 // DLBL M204LIB,'M204.PROD.LIBRARY' // EXTENT SYSnnn,... // LIBDEF PHASE.SEARCH=M204LIB.V210 // DLBL CCAJRNL,'CCAJRNL' Note 1 // EXTENT SYSnnn,... // DLBL SORTIN,'AUDIT204.SORTIN',0 Note 2 // EXTENT SYSnnn,... // DLBL SORTOUT,'AUDIT204.SORTOUT',0 Note 2 // EXTENT SYSnnn,... // DLBL STATIN,'AUDIT204.STATIN',0 Note 3 // EXTENT SYSnnn,... // DLBL STATOUT,'AUDIT204.STATOUT',0 Note 3 // EXTENT SYSnnn,... // DLBL SORTWK1,'SORTWK1',0 Note 4 // EXTENT SYSnnn,... // EXEC AUDIT204,SIZE=(AUTO,xxK) Note 5 INCLUDE IFYLSQRT * Insert AUDIT204 CCAIN commands here FORMAT REPORT ACCOUNT REPORT FILE REPORT ACCOUNT ACCOUNTS MAGGIE MARY DAVE /* /&

Usage notes

• If you use tape instead of the DLBL and EXTENT for CCAJRNL, use the following JCL:

  // TLBL CCAJRNL // ASSGN SYS004,X'cuu'

• DLBL and EXTENT are necessary if you use either the REPORT or the ANALYZE command.
• You must specify a SIZE parameter in the EXEC statement with AUTO and you need some additional storage for the sort program. To determine the amount of additional storage needed for the sort program, refer to IBM's SORT/MERGE Programmer's Guide.

(z/VM) CMS JCL for AUDIT204

The CMS AUDIT204 utility program prints a Model 204 journal file and produces a statistical report from information in a journal file:

• If a statistics report is produced, a SORT utility that can be invoked dynamically must be available for use.
• AUDIT204 output is produced either as a printer spool file or in a CMS disk file.

The following EXEC initiates AUDIT204:

AUDIT204 [datasetname] [filename filetype] filemode

Where:

• datasetname specifies the name of the journal data set on a variable-format disk, with the qualifiers separated by blanks. If no data set name is specified, it is presumed that the name of the journal data set is M204.JOURNAL.
• filename and filetype specify the name and type of the journal file on a CMS-format, or a variable format for z/OS and z/VSE, disk.
• filemode specifies the mode of the disk holding the journal file to be processed. The input to AUDIT204 contains the commands selected from those described earlier and is included in the AUDIT204 CCAIN.

Searching multiple tapes for journal and off load data

When a journal or offload data set is on multiple tapes, you do not need to mount all of them for AUDIT204 processing. You can process a subset of the tapes, as long as you mount them in the order in which they were originally generated.

For example, suppose that your CCAJRNL data set consists of five tapes labeled TAPE01 through TAPE05. You are sure that the information you want to analyze begins on the third tape or later. In this case you can save processing time by specifying only TAPE03, TAPE04, and TAPE05 in the DD statement for the CCAJRNL data set.