IAM/PLEX Journaling

Overview

IAM/PLEX provides an optional facility to journal before and / or after images of file updates to IAM files being processed by IAM/PLEX. These journals can be used to aid in data recovery due to either hardware or software failures. If IAM/RLS is setup to journal the z/OS System Logger, then the journal records produced will be in the same format written by CICS in the CICS journals to support the use of IBM replication software such as Infosphere CDC. For example, if a media failure occurs and an IAMdata set has to be restored, the IAM/PLEX 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/PLEX 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.

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/PLEX logstreams, called IAMJUTIL. IAMJREST and IAMJUTIL can also be used to process journals created by IAM outside of IAM/PLEX control, as described in IAM-Journal-and-Recovery 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/PLEX logstream records, contact BMC Support.

When implementing IAM/PLEX one must use the z/OS system logger so that all IAM/PLEX members of an RLSGROUP from different LPARS are logging to the same journal data sets. The type of journaling and the logstream files are specified by the IAM/PLEX startup parameters SYSLOGGER, and LOGSTRM, which are described in IAM/PLEX parameters. Journal records are written in IBM replication software format. IAM utilities can process replication format so the journal records serve a dual purpose.

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/PLEX startup procedure, for example: ACCESS DD=&ALLDD,JRNAD=BOTH.
• Specification of the IAM CREATE Override JRNAD when defining the IAM data sets that require journaling.
• Specification of the LOG parameter on the IDCAMS DEFINE for DFSMS managed IAM data sets.

System Logger

IAM/PLEX must 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 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

Perform the following tasks in order to set up the IAM System Logger environment for IAM/PLEX. 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 z/OS 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 Structure in the CFRM policy for the SYSPLEX. This is the structure in the coupling facility that the SYSTEM Logger will initially write the data in before it is moved to logger data sets. This is also done using the IXCMIAPU utility.
5. Define the Structure in the LOGR policy using IXCMIAPU utility.
6. Define the IAM log streams with the DASDONLY(NO) and the
   STRUCTNAME( ) parameters 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.
7. Define the Logger address space (started task) as a TRUSTED facility to avoid RACF problems with the log data sets and structures.

Structure Definition Statements

The following statements need to be added to the CFRM policy.

Example of IAMLOGR Structure, Member IAMSTR01 in ICL

Defining the IAMLOGR Structure

The following example JCL shows how to build the IAMLOGR structure.

JCL to Define IAMLOGR Structure: Member IAMLGSTR in ICL

Define an IAMLog Stream

The following JCL example shows how to create the actual log stream for an IAM/PLEX group.

Example of JCL to Define Log Stream: Member IAMLGDEF in ICL

The LOWOFFLOAD(00) and the HIGHOFFLOAD(50) should not be changed. If you set the HIGHOFFLOAD too high the System Logger could reject logging requests while it is offloading data resulting in a disabling of the journaling facility. The RETPD(10) is the number of days you want the data kept before it can be deleted from the logstream and its offload data sets. The IAMJUTIL utility can also be used to copy data from the logstreams to other data sets for archiving purposes.

Handling Errors

When there is an error, the IAM/PLEX 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 of 00000860 indicating that an offload is needed. All other tasks trying to journal are stacked up behind the one on the buffer queue waiting for the journal buffer lock.

What can be done if there is a catastrophic error with the logstream, or coupling facility is the following:

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

System Logger Use with IBM Replication Software

To use IBM replication software with IAM/PLEX 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/PLEX logstream name. The following is an example of how the pieces of this fit together.