Global Online Change utility (DFSUOLC0)

Use the Global Online Change utility to initialize, recreate, or unlock the OLCSTAT data set.

To use the Global Online Change utility to initialize OLCSTAT data sets, you must first define either MDBS=A or MDBS=B, even for an IMS that does not define the MODBLKS data sets. For an IMSplex to be enabled for global online change, the Global Online Change utility must be used to initialize the OLCSTAT before the first IMS in the IMSplex cold starts the first time. The Global Online Change utility can be used to recreate the OLCSTAT data set after an error that renders the OLCSTAT data set unusable.

The Global Online Change commands, INITIATE OLC PHASE(PREPARE), followed by INITIATE OLC PHASE(COMMIT), cause the inactive library to become the active library.

The OLCSTAT data set contains the global online change status, which includes the modify id, the active online change libraries, a lock field, the last online change, and a list of IMS systems that are current with the online change libraries. When an IFP region is running, OLC commit stops because of existing active route code. Therefore, all IFP regions must be terminated before commit.

The Online Change Copy utility supports an OLCSTAT DD statement, to identify the global online change status data set name. The OLCSTAT data set is comparable to the MODSTAT data set used by local Online Change.

Attention: Use the recreate and unlock functions with extreme caution. Use the unlock function only if a series of errors has left the OLCSTAT data set locked and no online change is in progress. If you inadvertently destroy valid OLCSTAT data set contents, global online change and initialization of additional IMS systems fail until the OLCSTAT data set is re-initialized.

Establish an OLCSTAT data set recovery procedure to deal with the loss of the OLCSTAT data set. After every successful global online change, record the following data:

The modify id
The active online change library suffixes
The list of IMS systems that are current with the online change libraries

If the OLCSTAT data set is destroyed, run the initialize function of the Global Online Change utility with the recorded data to re-initialize the OLCSTAT data set.

The DFS3499 message, which identifies the current values of the online change libraries in the OLCSTAT data set, follows the DFS994 checkpoint message. The DFS3410 message at initialization also identifies the current online change libraries from the OLCSTAT data set.

DFSUOLC0 can also be used to update the IMS version in the OLCSTAT data set header. When you upgrade to a new version of IMS that is higher than the previous level, the IMS version in the OLCSTAT header will be automatically updated during IMS cold start. However, this automatic update will not be completed if you fall back to a lower IMS level. In this case, the Global Online Change utility must be run to update the IMS version in the OLCSTAT header to the lower IMS level.

Start of change If you use the UNL function to unlock the OLCSTAT data set, and all of the IMSs failed during a global online change, you will need to start IMS. IMS will start because the OLCSTAT data set is no longer locked. End of change

If you use the UNL function to unlock the OLCSTAT data set after the global online change command master failed during online change while holding the OLCSTAT data set lock, the next global online change command to issue depends upon the state of the online change.

If the global online change passed the commit 1 phase where the OLCSTAT data set has been updated, the online change is committed and the only command that can be issued is another INIT OLC PHASE(COMMIT) command to complete the commit by cleaning up.
If the global online change failed before commit phase 1 where the OLCSTAT data set is updated, the global online change is not committed. Commit can be attempted again with an INIT OLC PHASE(COMMIT) command, or the global online change can be aborted with a TERMINATE OLC command.

To see the state of the global online change, issue the QUERY MEMBER TYPE(IMS) SHOW(STATUS) command to see the state of all the IMSs participating in the global online change. For more information, see Handling errors for global online change commands. End of change

Subsections:

Restrictions
Prerequisites
Requirements
Recommendations
JCL specifications

Restrictions

Currently, no restrictions are documented for the DFSUOLC0 utility.

Prerequisites

Currently, no prerequisites are documented for the DFSUOLC0 utility.

Requirements

Currently, no requirements are documented for the DFSUOLC0 utility.

Recommendations

Currently, no recommendations are documented for the DFSUOLC0 utility.

JCL specifications

The following JCL will run with the DFSUOLC procedure and invoke the utility with VERS=2, which is the default.

//DFSUOLC0 JOB
//STEP1 EXEC DFSUOLC,FUNC=,ACBS=,MDBS=,FMTS=,MDID=,PLEX=
//SYSIN DD *
//

The following JCL will run with the DFSUOLC procedure and invoke the utility with VERS=1.

//DFSUOLC0 JOB
//STEP1 EXEC DFSUOLC,FUNC=,ACBS=,MDBS=,FMTS=,MDID=,PLEX=,VERS=1
//SYSIN DD *
//

Procedure statement

The JCL shown in the following figure shows the statements used to invoke the DFSUOLC procedure. This procedure is generated by stage 2 of system definition and placed in the IMS.PROCLIB.

//PROC FUNC=,ACBS=,MDBS=,FMTS=,MDID=,PLEX=,VERS=,SOUT=A 
//STEP1  EXEC PGM=DFSUOLC0,
//              PARM=(&FUNC,&ACBS,&MDBS,&FMTS,&MDID,&PLEX,&VERS)
//OLCSTAT DD DSN-IMSPLEX.OLCSTAT,DISP=OLD
//SYSPRINT DD SYSOUT=&SOUT
//SYSIN DD DUMMY

EXEC statement

The format of the EXEC statement is:

PGM=DFSUOLC0,PARM=(&FUNC,&ACBS,&MDBS,&FMTS,&MDID,&PLEX,&VERS)

The Global Online Change utility (DFSUOLC0) supports the following parameters.

ACBS

Specifies the IMS JCL IMSACB DD statement suffix for the active ACB library. The suffix can be A or B. A means IMSACBA is the DD statement of the active library. B means IMSACBB is DD statement of the active library.

FMTS

Specifies the IMS JCL FORMAT DD statement suffix for the active MFS FORMAT library. The suffix can be A or B. A means FORMATA is the DD statement of the active library. B means FORMATB is the DD statement of the active library. FORMAT contains online MFS definitions to be used as the format library by the online system. MFS-supported terminals and the MFS Language utility program require their use. This parameter is required, even if no IMS in the IMSplex uses the MFS format library.

FUNC

Specifies the Global Online Change utility function to perform.

ADD

Add one or more IMS members to the list of IMS systems that are current with the online change libraries. Add an IMS when the OLCSTAT data set suffered an error that made it unusable and you are trying to recreate the OLCSTAT data set contents. The IMS systems to add must be specified with the SYSIN DD card.

Add IMS systems that are current with the online change libraries; for example, IMS systems that are currently up.

Attention: If you add an IMS that is not current with the online change libraries, and warm start that IMS, the warm start might fail.

DEL

Delete one or more IMS systems from the list of IMS systems that are current with the online change libraries.

Delete an IMS when you never intend to bring the IMS up again, so that the INITIATE OLC command does not need to be specified with the FRCABND or FRCNRML keyword. The IMS systems to delete must be specified with the SYSIN DD card.

INI

Function to initialize the OLCSTAT data set. ACBS, MDBS, FMTS, and MDID must also be specified. An optional list of one or more IMS systems can be specified with the SYSIN DD statement. If no IMS systems are specified with the SYSIN DD statement, the list of IMS systems is deleted from the OLCSTAT data set.

The INI function is required before the first IMS in the IMSplex cold starts the first time to initialize the OLCSTAT data set.

If the OLCSTAT record contents are lost and must be reconstructed, you must run the Global Online Change utility INI function to construct its contents with the correct values for the online change identifier and online change library ddnames. You might also want to add IMS systems that are current with the online change libraries using the SYSIN DD statement. Keep track of the current online change libraries and modify id so that you can reconstruct the OLCSTAT data set contents in case of failure.

UNL

Function to reset the OLCSTAT data set lock after all IMS systems failed during online change.

The UNL function of the Global Online Change utility is required to reset the OLCSTAT data set lock, in the case where all IMS systems in the IMSplex failed during an online change. Online change sets a lock field in the OLCSTAT data set to prevent other IMS systems from initializing during the online change. IMS initialization fails if a global online change is in progress (between the prepare and commit phases), because the OLCSTAT data set lock is set. When an IMS tries to initialize after all IMS systems failed during online change, IMS initialization is rejected because the OLCSTAT data set lock is set. In this case, you must run the Global Online Change utility with the UNL function to reset the OLCSTAT data set lock. No IMS can initialize until the OLCSTAT data set lock is reset. The UNL function should rarely need to be used. It is needed only if all the IMS systems fail during an online change.

MDBS

Specifies the IMS JCL MODBLKS DD statement suffix for the active MODBLKS data set. The suffix can be A or B. A means MODBLKSA is the DD statement of the active library. B means MODBLKSB is the DD statement of the active libraries.

If DRD is enabled, you can start IMS without defining MODBLKS DD cards. However, to use the Global Online Change utility to initialize OLCSTAT data sets, you must first define either MDBS=A or MDBS=B, even for an IMS that does not define the MODBLKS data sets. If the MODBLKS data sets are not defined to IMS, the MODBLKS value in the OLCSTAT data set is ignored.

MDID

Specifies the modifyid (online change status identifier) for the INI function. This should be initialized to zero to indicate that the number of global online changes performed is zero. The modifyid is used to determine whether an IMS was down for one or more online changes and to determine the kind of restart IMS can perform. The modifyid is used by IMS internal processing:

To determine whether IMS must cold start.
If an IMS participated in the last global online change, its modifyid matches the modifyid in the OLCSTAT data set. This IMS is allowed to warm start. If an IMS did not participate in the last global online change, its modifyid does not match the modifyid in the OLCSTAT data set. It is permitted to warm start if its restart type does not conflict with the last online change that was performed. If the IMS was down for two or more global online changes, it must cold start.
To recover security status during emergency restart processing.

PLEX

Specifies a 1-5 character identifier that specifies the z/OS® cross-system coupling facility CSL IMSplex group name for the UNL function. PLEX is required for the UNL function. All OM, RM, SCI, IMS, and ODBM IMSplex members that are in the same IMSplex sharing group, sharing either databases or message queues, must specify the same identifier. The same identifier must also be used for the IMSPLEX= parameter in the CSLSIxxx, CSLOIxxx, CSLRIxxx and DFSCGxxx PROCLIB members.

SOUT

Specifies the class assigned to SYSOUT DD statements.

The STEPLIB DD statement identifies the IMS.SDFSRESL. The IMS.SDFSRESL contains the IMS required modules. This IMS.SDFSRESL must be the highest level available in the IMSplex.

The SYSUDUMP DD statement defines the dump data set for this program.

The SYSPRINT DD statement defines the message output data set.

The OLCSTAT DD statement identifies the OLCSTAT (global online change status) data set name. The OLCSTAT DD statement is required.

The SYSIN DD statement contains the list of IMS systems to define, add, or delete. Specify one IMS ID per line.

The SYSIN DD statement specified with the ADD function adds one or more IMS systems to the existing list of IMS systems in the OLCSTAT data set.

The SYSIN DD statement specified with the DEL function deletes one or more IMS systems from the existing list of IMS systems in the OLCSTAT data set.

The SYSIN DD statement specified with the INI function defines a new list of IMS systems. If IMS records already existed, they are wiped out.

VERS

Specifies the OLCSTAT version that is used to initialize the OLCSTAT. The valid values are 1 and 2. The default value is 2.

1: Indicates that the OLCSTAT is to be initialized to Version 1 format for the header.
Use VERS=1 if there are one or more IMS Version 9 or IMS Version 10 systems in the OLCSTAT along with IMS 14 systems.
2: Indicates that the OLCSTAT is to be initialized to Version 2 format for the header.
Use VERS=2 if all IMS systems in the OLCSTAT are IMS 14. VERS=2 is required to utilize the TYPE(ACBMBR) member online change.