IAM Record Level Sharing

IAM/RLS is easy to use. The setup checklist for preparing for IAM/RLS includes the following:

1. Allocating an IAM/RLS parameter library, and choosing the startup parameters.
2. Allocating the IAM/RLS journal data sets, if journaling is going to be used, and setting up backup and empty procedures for the journal data sets.
3. Allocate a Record Lock Journal for each IAM/RLS address space for the persistent record lock capability.
4. Deciding on eligibility criteria for IAM/RLS usage and building the data set name table if it is going to be used. Set the desired option for RLS processing in the IAM Global Options Table.
5. Setting up the IAM/RLS proc from the example provided in the IAMSAMP and placing it in a system procedure library.
6. Start the IAM/RLS procedure. This can even replace the existing IAMSTART procedure, because starting IAM/RLS will automatically start the IAM VSAM Interface if not active already.

Once IAM/RLS is active, data sets will be automatically selected for processing by IAM/RLS, based on installation criteria. Most application programs and jobs will not require any changes to code or JCL to make use of IAM/RLS. Data sets will have to be defined as IAM data sets. The circumstances where changes are required include the following:

1. For batch applications that update a large number of records on recoverable files, it is necessary to utilize the IAM batch syncpoint process. This can be done through the use of IAM Override AUTOSYNCPOINT or by revising the application program. The maximum number of updated / inserted / deleted records to IAM/RLS recoverable files will be limited to the value specified as MAXLOCKS. This limitation is to prevent potential storage shortages and failures in the IAM/RLS address space. This will also aid in preventing a large number of records from being locked out for update by other jobs and CICS transactions.
2. Install and activate the IAM CICS exits that are needed for communicating transaction events to IAM/RLS.

The IAM/RLS address space is designed and intended to provide its services in the background, with little if any operator intervention. However, should the need arise, there are a variety of commands that can be given to the IAM/RLS address space through the Z/OS MODIFY (F) command. These include display as well as action commands. IAM/RLS activity can also be viewed from a TSO/ISPF session, using the provided IAMBMON program. This program can be invoked either as a TSO command from any ISPF panel, or from the IAM ISPF utility menu.

IAM/RLS processing overview

The IAM Record Level Sharing within a single system is achieved by IAM internally passing all the I/O requests for the files being shared to the IAM/RLS address space. This is done automatically for files that meet the installation’s selection criteria, which can be determined from a combination of share options and data set names as set by the IAM Global Option of RLS. If the IAM/RLS address space has not been activated, and the RLS Global Option has not been changed, then processing for those files will be performed as it is currently within the job’s address space. The use of IAM/RLS can also be controlled by use of the IAM ACCESS overrides of RLS and NORLS.

IAM utilizes z/OS cross memory services to provide the record level sharing services. All of the OPEN, CLOSE, and I/O requests for shared files will be passed to the IAM/RLS address space for processing, and the appropriate status, key and record will be passed back to the user’s address space when the request has completed within the IAM/RLS address space. Record level locking is achieved within the IAM/RLS address space, with a lock manager that will handle the locking requests, and provides for deadlock analysis and detection within the resources managed within the IAM/RLS address space.

IAM also utilizes the z/OS dynamic resource manager facilities so that IAM will get control whenever a job step or an address space that is using IAM files through IAM/RLS terminates. This function will make sure that the IAM file(s) are properly closed within the IAM/RLS address space will release any record locks for jobs that are normally ending, and will retain record locks of recoverable files for jobs that are abending.

Multiple IAM/RLS address spaces

Multiple IAM/RLS address spaces can be executed on a particular LPAR or Z/OS system image. Each IAM/RLS address space must have its own unique 4-character identifier, referred to as the RLSID, a separate PROC with a name that differs from the other IAM/RLS address spaces, its own journal data sets and its own RLS parameters. The RLSID can be specified via the RLS parameters, or from the IAM Global Options Table, which can be copied into another load library having a different RLSID value. Use of the additional IAM/RLS address spaces can be selected by IAM CREATE or ACCESS Override specifications of RLSID values, through the specification of an RLSID within the eligible data set name table, or by using a different IAM Global Options Table.

The restrictions with using multiple IAM/RLS address spaces are primarily that a job or CICS region can establish a connection with only one IAM/RLS address space, and an IAM data set can only be opened under one IAM/RLS address space at any point in time.

For more information, read Multiple-IAM-RLS-Address-Spaces

Journaling

In addition to handling the I/O and locking services, the IAM/RLS address space can also journal before and / or after images of updated records. The journaling can be performed either to standard DASD sequential data sets, or to the z/OS System Logger. The IAM journaling services are primarily provided to allow for the back out of updates performed by failing batch job(s), or to perform a forward recovery of updates, if a file has encountered media damage. CICS will handle its own transaction back out and other recovery as it does today, using its own logging mechanisms that is independent of the journaling provided by IAM.

IAM/RLS journaling facilities can be used for IAM data sets that are not being processed by IAM/RLS. This will provide improved usability for customers using journaling by eliminating a one to one correspondence between a journal data set and the actual IAM data set. The journal data sets can be managed at the system level, and only one execution of the IAM journal backout recovery program, IAMJREST, is needed even if multiple IAM data sets are processed by a job. This capability is activated by specification of the IAMGlobal Option ENABLE=RLSJRNL.

Security

The IAM/RLS address space will have to be given the appropriate security authority to update those files that are going to be processed by IAM record level sharing. This will include CREATE authority for files that can be extended to additional volumes. IAM does issue the RACROUTE macro within the individual job’s address space to validate that the requesting user does have authority to read or update, as appropriate, the IAM data set being opened prior to requesting that IAM/RLS open the data set. If the RACROUTE indicates that the user / job do not have authority to access the data set, then the OPEN request is failed. The failing job will receive an IAMW18 error message. Additional security will be performed by z/OS services when IAM attempts to take an extent.

Reliability

IAM/RLS utilizes the various z/OS error handling and recovery facilities to recover from errors and abend conditions that may occur. The two goals in providing error recovery routines are to provide continuous availability of the services being provided by the IAM/RLS address space, and secondly to automatically collect enough information about any failures, such that problem determination and correction can be performed from the single failure. The job that had submitted an I/O request to IAM/RLS that causes a failure will in most circumstances, receive a failure code. It will be up to the program to decide whether to continue processing.

The error data collection will include various messages to the job log, system log, and when applicable the RLS log indicating the abend code, general registers, access registers if applicable, and the failing module. The error routines do attempt to not duplicate diagnostic information that is produced by z/OS, but rather provide additional diagnostic information to be combined with the information provided by z/OS. The error information contained in these messages may be sufficient for problem determination and resolution, particularly if a problem had been previously reported to BMC. If the error occurred within the IAM/RLS address space, an error trace table will be kept in storage, particularly in situations where multiple errors have occurred. Most error situations will also result in a request for a dump to be taken to a system dump data set, which may include both the IAM/RLS address space and possibly the address space of the job that submitted the failing request. The IAM index space associated with the IAM/RLS address space may also be dumped.

Serviceability

To aid in serviceability, a mechanism is being provided for system support personnel to apply critical fixes to the IAM modules within the IAM/RLS address space, without the need to shut down the address space. This facility will also be able to back out fixes should they cause other problems.

Record Locking

For the single system record level sharing, IAM utilizes its own record level lock manager. The IAM lock manager utilizes a hashing algorithm to provide for fast lock acquisition and release. The trigger to release a record lock will depend on the environment in which the lock was requested. The IAM lock manager will check for potential deadlocks within the scope of the IAM data sets that it is managing. If a deadlock condition would occur the request will be failed with a logical error.

For CICS transactions, records are locked by transaction identification. IAM determines from CICS whether or not the IAM files accessed are recoverable, and if they are, it will hold the record lock(s) until either a SYNCPOINT is executed, or the transaction ends. If an IAM file is detected as being not recoverable under CICS, then the record lock is only held from the time of the GET for UPDATE until the record is actually updated or erased, or for records being added, only for the duration of the actual add processing. IAM /RLS also provides support for the CICS VSAM RLS parameters UNCOMMITTED, CONSISTENT, REPEATABLE, and NOSUSPEND. IAM/PLEX provides equivalent functionality for these parameters.

For other than CICS processing, that is batch jobs or TSO users, IAM will generally only hold the record lock(s) from the time of the GET for UPDATE until the record is actually updated or erased, or for records being added, only for the duration of the actual add processing. The exception to this is if IAM is journaling before images of records, implying that a back out could be performed if there is a failure, then the record lock(s) will be held until the program either calls the IAM batch syncpoint, or the job step terminates.

If a job step abends while processing a recoverable file, any record locks obtained for that job step will be held until a recovery takes place. If there were any other jobs or CICS transactions waiting for the record locks that are being retained until recovery, those requests will fail when the abend is detected. The recovery can be performed by IAM’s Dynamic Job Back Out function, by IAMJREST, or by other procedures or recovery software that may be available. Information about any retained locks can be found by using the DISPLAY, RETAINEDLOCKS modify command to IAM/RLS. Such retained locks can also be released by the RELEASELOCKS command.

Dynamic job back out

IAM/RLS provides a Dynamic Job Back Out function for IAM files opened through IAM/RLS. Whenever a job step abends, all updates done by that job step will be automatically removed. If the failing job step has taken IAM batch syncpoints, then the back out will be performed to the most recent syncpoint taken by the job step prior to abending. Control of Dynamic Job Back Out will be provided as an IAM/RLS parameter, and as an IAM Override.