IAM/RLS Journaling

Overview

IAM/RLS provides an optional facility to journal before and / or after images of file updates to IAM files being processed by IAM/RLS. These journals can be used to aid in data recovery due to either hardware or software failures, or for participation with IBM Data Replication products (GDPS Active-Active or Infosphere CDC). For example, if a media failure occurs and an IAM data set has to be restored, the IAM/RLS journals can be used to reapply the updates that had been made to the file since it was backed up to bring the file status up to the point of failure. If before images are captured then IAM can backout updates performed by failing job steps. The IAM journaling is not a replacement for CICS journaling and CICS dynamic transaction backout, but rather an additional facility that provides for increased recovery capabilities. IAM/RLS as a default, will not journal the before images for updates being done by CICS transactions, because CICS will handle the transaction back outs. However, this can be changed if an installation needs to have those records included in the IAM journals. Many users have found the journal records useful for activity review and auditing purposes.

IAM provides programs to perform recoveries, IAMJREST and IAMBREST. IAMJREST runs as a batch job that can perform forward or backout recoveries. IAMBREST provides for dynamic job step backout of updates performed by a batch job step that abends. IAM also provides a program to perform utility functions on the IAM/RLS journals, called IAMJUTIL. IAMJREST and IAMJUTIL can also be used to process journals created by IAM outside of IAM/RLS control, as described in IAM-Journal-and-Recovery . Customers can provide their own utility program to process the data contained in the journals, and to even perform recoveries if so desired. For information on the format of the data contained in the IAM/RLS journal records, contact BMC.

Journaling can be done to either sequential data sets, or using the z/OS system logger. When IAM/RLS is setup to use the z/OS system logger, journal records are written in IBM replication software format. IAM utilities can process replication format so the journal records serve a dual purpose. We recommend that customers use the sequential data sets for journaling, unless they have experience in using the z/OS System Logger facilities. The type of journaling and the journal files are specified by the IAM/RLS startup parameters LOGDSNn, SYSLOGGER, and LOGSTRM, which are described inIAM/RLS parameters

Customers select the IAM data sets that they want to have IAM journal, by one of the following methods:

• Specification of the IAM ACCESS Override JRNAD on the IAM/RLS startup procedure, for example: ACCESS DD=&ALLDD,JRNAD=BOTH.
• Specification of the IAM CREATE Override JRNAD when defining the IAM data sets that are to have journaling.
• Specification of the LOG parameter on the IDCAMS DEFINE for DFSMS managed IAM data sets.

BEFORE (BACKOUT) Images

As of IAM Version 9.3/02 Spin Level 10, when batch jobs are using IAM data sets that are utilizing IAMRLS and it’s journal functions for backout records, it will only journal the backout image when the record is actually being updated. IAMRLS will save a copy of the non-updated record, and when the update actually is issued, it will then write out the before image to the journal prior to updating the record. This will eliminate from the journal, all of the records that are read in update mode but are not being updated, and also reduce the number of record locks that are being held for the records that were read for update but not updated.

This change does not affect read for updates done by CICS.

Sequential Log Data Sets

The sequential log data sets must have space allocated prior to starting IAM/RLS, and are identified by the LOGDSNn= parameter, where n is a numerical digit from 1 to 6. It is recommended that you allocate at least 2 log data sets, preferably 3 or more. Having several large journal data sets will provide for fast access to journal data for job backout recoveries, and help to make sure that there will always be an available journal data set for IAM/RLS, in case some of the journal offloads take longer than anticipated. The amount of DASD space required depends on the update activity and the journaling options specified. Each journal record has a header of 112 bytes that is followed by an image of the data record and is written out in a standard blocked variable length record format. The log data sets may be allocated with secondary space specified, however, it is recommended that each log data set resides on a single volume.

JCL to ALLOCATE JOURNALS

Shown below is an example of allocating 6 journal data sets for IAM/RLS use.

Example of JCL to allocate IAM/RLS Journals (EX2030A)

IAM/RLS Startup Parameters for Sequential Journals

When IAM/RLS is started, the journal subtask will look at all specified journal data sets. It will select the one with the most recent data (as determined by timestamps within the journal records). If all of the journal data sets are empty, it will start with LOGDSN1. As each journal data set is filled, or manually switched with the JSWITCH command, IAM/RLS will use the next higher LOGDSNn data set. When the highest one has been used, then IAM/RLS will switch back to the first one, LOGDSN1.

Example of IAM/RLS Startup parameters for Sequential Journals (See EX2010A)

When IAM/RLS performs a journal switch, it will start the procedure identified by JRNPROC to offload the journal and either empty the data set or flag it for reuse. If JRNPROC has not been specified, the customer must make sure that the journal data set is offloaded and emptied prior to IAM/RLS requiring the data set again. Users that have automated operations software can trigger a job or procedure by watching for the IAML0510 message, indicating that a journal data set has been closed. If a journal switch occurs, and the next journal data set is not ready to be written to, then IAM/RLS will issue a WTOR for operator interaction on how to proceed, which will delay IAM/RLS processing.

Data from an IAM/RLS journal can be offloaded by using the IAMJUTIL program, by IEBGENER, or with their own utility program. We recommend the use of IAMJUTIL because it offers selection criteria on which journal records are copied, and it can indicate that the journal data set can be reused, while retaining the data in the journal data set until it is reused. The advantage of reuse is that it simplifies job backout recoveries, because a lot more of the journal data will be readily available than if the journal had been emptied. If you are planning on using the Dynamic Job Backout function of IAM/RLS, then you definitely should use IAMJUTIL to offload the journal data sets.

One scenario for managing the journals is when a journal is full, to use IAMJUTIL to copy only the after images to a tape, which can be used for subsequent forward recovery if needed. The before images, used for backout recovery will be discarded upon reuse of a journal data set. By providing a large enough set of journals, such that the immediate backout needs can be met, this will reduce the amount of journal data that has to be saved.

Sequential Journal Offload PROC

An example of a “proc” that can be started by IAM/RLS, which will copy the after images to a GDG is:

Example of PROC to Offload Journal After Image Records (EX2030B)

If you will not be making use of the IAM Dynamic Job Backout capability, then other alternative procedures could be used. For example, once a journal data set is filled, it could be renamed, and space allocated then for the original data set name. Or, you could have a secondary set of journals, and use the IAM/RLS CHANGEPARM command to switch the journaling to the alternate set.

System Logger

As an alternative to the traditional sequential log data sets, customers can optionally use the z/OS System Logger DASD-only logging instead. IAM/RLS can use the z/OS system logger for journaling file updates to allow for back out and forward recovery of IAM files. The z/OS system logger is a component of z/OS that must be activated and configured. For more information on the z/OS system logger see the following publications:

• z/OS MVS Setting Up A Sysplex
• z/OS MVS Initialization and Tuning Reference

You must perform the following tasks in order to set up the IAM System Logger environment. Your z/OS systems programmer must do some of these tasks.

1. Make sure you have authorization to the z/OS system logger address space and that the z/OS system logger (IXGLOGR) is running before you define and use IAM log streams. The section "Define Authorization to System Logger address space" in the z/OS MVS Setting Up a Sysplex space provides more information about this.
2. You must also have authorization to the MVS IXCMIAPU utility. This utility is used to define, update, and delete entries in the LOGR couple data set. IXCMIAPU is documented in the z/OS MVS Setting Up a Sysplex space in appendix B.
3. Use the IXCL1DSU utility to define and format the LOGR couple data set. Your installation may have already done this if they are using the z/OS system logger for other products. This utility is documented in the Z/OS MVS Setting Up a Sysplex space.
4. Define the IAM log streams in the LOGR couple data set using the z/OS utility IXCMIAPU. See the section "Add Information about Log Streams and Coupling Facility Structures to the LOGR Policy" in the z/OS MVS Setting Up a Sysplex space. The following JCL can be used to set the values required for the IAM log stream using the IXCMIAPU utility.

JCL to Define IAM Log Stream

Shown below is an example of the JCL to define the log stream.

Example of Defining a log stream (EX2030C)

Handling Errors

When there is an error, the IAM/RLS JRNAD exit will end up waiting on the buffer queue until buffers are emptied and the request on top of the queue gets posted when the error is resolved. At this time the only error automatically handled is for reason code 00000860, indicating that an offload is needed. All other tasks trying to journal are stacked behind the one on the buffer queue waiting for the journal buffer lock.

If there is a catastrophic error with the logstream, or coupling facility, do the following:

1. Disconnect from the current logstream: F iamrls1,LOGGER,DISCON
2. Define a new logstream
3. Change the IAM/RLS parameter library LOGSTREAM value.
4. Issue the IAM/RLS CHANGEPARM command: F iamsls1,CHANGEPARM
5. Reconnect to the new logstream: F iamrls1,LOGGER,RECON
6. At that point the waiting request should be posted. If not, then issue the IAM/RLS LOGGER POST command: F iamrls1,LOGGER,POST

System Logger Use with IBM Replication Software

To use IBM replication software with IAM/RLS journaling you need to journal After images. Therefore, when you request journaling for a particular IAM data set, you will need to use the JRNAD=BOTH or JRNAD=AFTER on an IAM CREATE Override statement when the data set is defined or on an IAM/RLS JCL ACCESS override statement. You must also define the cluster with the IBM IDCAMS LOGREPLICATE and LOGSTREAMID keywords. The LOGSTREAMID coded logstream name must match the IAM/RLS logstream name. Below is an example of how the pieces fit together-