IMS Log Components

The IMS logs comprise a number of components, which are described in the following sections:

• "IMS Log Buffers"

• "Online Log Data Sets (OLDSs)" on page 369

• "Write-Ahead Data Sets (WADSs)" on page 371

• "System Log Data Sets (SLDSs)" on page 372

• "Recovery Log Data Sets (RLDSs)" on page 373

IMS Log Buffers

IMS uses the IMS log buffers to write any information required to be logged, without having to do any real I/O.

Whenever a log buffer is full, IMS schedules the complete log buffer to be written out to the online data set (OLDS) as a background, asynchronous task. In a busy system, IMS generally chains these log buffer write operations together.

Should any application or system function require a log record to be externalized (that is, IMS believes that for recoverability, this log record must be physically written to DASD before proceeding), then IMS uses the write-ahead data set (WADS). See "Write-Ahead Data Sets (WADSs)" on page 371.

The OLDS log buffers are used in such a manner as to keep available as long as possible the log records that might be needed for dynamic backout. If a needed log record is no longer available in storage, one of the OLDS buffers is used for reading the appropriate blocks from the OLDS.

The number of log buffers is specified as an IMS startup parameter. The maximum number of log buffers is 999. The size of each log buffer is dependent on the actual block size of the physical OLDS. The IMS log buffers reside in extended private storage, however; there is a log buffer prefix that exists in extended common service area (ECSA).

Online Log Data Sets (OLDSs)

The OLDSs are the data sets that contain all the log records that are required for restart and recovery. These data sets must be pre-allocated, but need not be pre-formatted, on DASD, and hold the log records until they are archived.

The OLDS is written using BSAM. OSAM is used to read the OLDS for dynamic backout.

The OLDS are made up of multiple data sets that are used in a wrap-around manner. At least 3 data sets must be allocated for the OLDS to allow IMS to start, while an upper limit of 100 is supported.

To enhance performance, only complete log buffers are written to the OLDS. Should any incomplete buffers need to be written out, they are written to the WADS. When the WADS is unavailable, such as at IMS shutdown and when IMS is in degraded logging mode (running with too few OLDSs), then any incomplete buffers are written to the OLDS.

All OLDSs should be dynamically allocated by using the DFSMDA macro, and not hardcoded in the IMS control region JCL.

Dual Logging of OLDS

You can implement dual logging, optionally, with a primary and secondary data set for each defined OLDS.

• A primary and secondary data set are matched and, therefore, the pair should have the same space allocation. Because an OLDS pair contains the same data, extra space allocated to one data set is not used in the other.

• You cannot use secondary extent allocation.

• OLDSs can be allocated on different supported DASDs.

• All OLDSs must have the same block size, and be a multiple of 2 KB (2048 bytes). The maximum allowable block size is 30 KB.

Dynamic Backout

To allow IMS to dynamically back out a failed MPR or BMP program, IMS writes the before images of each database change to the OLDS. These before images show the database record as it was before the program updated it. When the MPR or BMP program issues a synchronization-point call, IMS discards these before images for the program.

Archiving an OLDS

Whenever one of the following situations occurs, the current OLDSs (both primary and secondary) are closed and the next OLDS is used:

• OLDS becomes full.

• I/O error occurs.

• MTO command (such as /SWI OLDS) is issued to force a log switch.

• MTO command (such as /DBR DB without the NOFEOV parameter) is issued to close a database.

When IMS starts using a new OLDS, it automatically notifies DBRC. When this situation occurs, IMS can automatically submit the archive job to the Log Archive utility (DFSUARC0) by using the ARC= IMS startup parameter.

IMS can define whether the log archive process occurs with every log switch or every second log switch. The DBRC skeletal JCL that controls the archiving can be defined to also create one or two system log data sets (SLDSs), and zero, one, or two recovery log data sets (RLDSs). After the last allocated OLDS has been used, the first OLDS is used again in a wrap-around fashion, as long as it has been archived.

The Log Archive utility JCL is in DBRC skeletal JCL, and you can tailor it to create the required SLDS, and optionally dual SLDSs, one or two RLDSs, and any user data sets. Figure 22-1 shows the data sets for the Log Archive utility.

Figure 22-1. Inputs and Outputs of the Log Archive Utility

Related Reading: For the details about the Log Archive utility, see IMS Version 9: Utilities Reference: System.

OLDS I/O Errors

In the case of a write error, IMS puts the subject OLDS (or pair of OLDSs) into a stopped status and it is not used again. This action is equivalent to a user issuing the /STO OLDS command.

If using dual OLDS, then the data set without error is used for IMS archives.

If data set errors result in only a single OLDS that remains, IMS internally schedules a /CHE FREEZE command to shut down the IMS system. If an error occurs on the very last OLDS, IMS abends with a U0618 code.

Information about the OLDS for each IMS system is kept in the RECON data set. The data in the RECON data set indicates whether an OLDS contains active log data that must be archived, or whether the OLDS is available for use.

Too Few Available OLDSs

IMS issues messages when it is running out of OLDSs.

• During the use of the last available OLDS, IMS indicates that no spare OLDS are available.

• When all the OLDSs are full, and the archives have not successfully completed, then IMS stops, and waits until at least one OLDS is archived. IMS repeatedly issues messages to indicate that it is out of OLDSs, and is waiting.

Write-Ahead Data Sets (WADSs)

The WADS is a small, high-performance direct access data set that contains a copy of committed log records that are in OLDS buffers but have not yet been written to the OLDS.

When IMS processing requires writing of a partially filled OLDS buffer, a portion of the buffer is written to the WADS. If IMS or the system fails, the log data in the WADS is used to close (terminate) the OLDS, either as part of an emergency restart or as an option on the Log Recovery utility.

The WADS space is continually reused after the appropriate log data is written to the OLDS. The WADS is required for all IMS systems, and must be pre-allocated and formatted at IMS startup when first used.

All WADSs should be dynamically allocated by using the DFSMDA macro, and not hardcoded in the control region JCL.

All WADSs must be on the same device type and have the same space allocation.

Dual WADS Logging

Dual WADS logging is supported to provide backup in the event of a read error while terminating the OLDS from the WADS. The primary and secondary WADS will contain the same data. Single or dual WADS logging is determined from an IMS startup parameter.

Additional WADS

You can define up to ten WADS to any IMS (for example, WADS0, WADS1,...., WADS9).

WADS0 (and WADS1 if running dual WADS) is active, and the rest remain as spares in case any active WADS has an I/O error. The next spare then replaces the one with the error.

System Log Data Sets (SLDSs)

The SLDS is created by the Log Archive utility, optionally after every OLDS switch. The SLDS is usually written to tape or to a cartridge, but can also reside on DASD. The SLDS can contain the data from one or more OLDS data sets.

The SLDS can also be used as input to all IMS log utilities, and IMS restart.

Information about the SLDS is maintained by DBRC in the RECON data set. Calls to DBRC are made by the Log Archive utility, which identifies the OLDS being archived and the SLDS being created. OLDS that have been archived are then available for reuse by IMS.

Dual Archiving SLDSs

IMS supports dual archiving to two SLDS data sets (primary and secondary).

When archiving to tape or to a cartridge, the user can also force the primary and secondary volumes to contain the same data by specifying the number of log blocks per volume. When this number is reached, a force-end-of-volume (FEOV) occurs on both the primary and secondary SLDSs. In this way, both primary and secondary SLDSs are identical and interchangeable if a subsequent I/O error occurs on one of them.

You can also specify which records are copied from the OLDS to the SLDS. Generally, the SLDS should contain all the log records from the OLDS, but if you want to omit types of log records from the SLDS, you can specify these within the Log Archive utility.

The SLDS must always contain those log records required for database recovery, batch backout processing, or system recovery.

The block size of the SLDS is independent of the block size of the OLDS, and can be specified to maximize space on the SLDS device type.

Recovery Log Data Sets (RLDSs)

When you run the Log Archive utility, you can request that an output data set be created that contains all of the log records needed for database recovery. This output data set is called the recovery log data set (RLDS), and is also known to DBRC.

The RLDS is preferred by many installations. All database recoveries and change accumulation jobs use the RLDS if one exists. Having an RLDS available can considerably speed up any of the recovery processes because the only contents of these data sets are database recovery log records. Other IMS TM, application scheduling, and checkpoint log records are not included on the RLDSs.

The RLDS is optional, and you can also have dual copies of it, as you can with the SLDS.

IMS Log Data Sets and Data Facility Storage Management Subsystem (DFSMS)

Although most IMS data sets can be managed by DFSMS, OLDS data sets should not be managed by DFSMS because if an OLDS is migrated (not very likely in most installations), it might be recalled with different attributes.

OLDS data sets must be allocated in contiguous space. If the OLDS were managed by DFSMS, both the primary and secondary OLDS data sets might be placed on the same volume. If that volume becomes unreadable, this is a major problem. Use management classes to avoid this situation.

Write-ahead data sets (WADS) have a very high write rate and are very sensitive to slow response. These data sets should be placed with some care. DFSMS might not provide a good place to allocate them.

If OLDS, RLDS, SLDS, or image copy data sets are managed by DFSMS, the CATDS parameter must be set for the RECON data set. The CATDS parameter tells DBRC to use the system catalog to find data sets and not be concerned if they are not on the same volumes to which they were originally allocated.

CATDS and cataloging is a good choice even when the data sets are not managed by DFSMS.