Online Change Copy utility (DFSUOCU0)

The Online Change Copy utility copies a source library with your new definitions to a target library. Issuing the Online Change command sequence to prepare and commit an online change causes the inactive library to become the active library. Using a z/OS® serialization service, this utility prevents other utilities from updating the staging (source) or inactive (target) libraries while the copy is in progress. The Online Change Copy Utility clears the target library and then invokes IEBCOPY to move the source library contents.

The Online Change Copy utility can copy the contents of the staging libraries to the active libraries during the installation of IMS, prior to the first cold start. To do this, the parameter for the output ddname must be specified when invoking the utility, because the initial contents of IMS.MODSTAT (or OLCSTAT data set, if global online change is enabled) will specify the active libraries.

The Online Change Copy utility (DFSUOCU0) can be used to create a backup copy of the active ACB library, which can be used for fallback purposes. This backup copy is created by specifying all of the following elements:

• The copy type parameter, TYPE=ACTVACB, which specifies that the Online Change Copy utility copies the members from the active ACB library
  Attention: The OLCSTAT library must be initiated before running the Online Change Copy utility with TYPE=ACTVACB specified.
• The target library parameter, OUT=O, which specifies that the Online Change Copy utility copies the content of an active ACB library to a library other than the inactive ACB library
• The IMSACBO DD statement, which specifies where the backup copy is created

In an IMSplex where IMS subsystems are not cloned and the libraries not shared, the Online Change Copy utility might need to be executed on every IMS in the IMSplex. In an IMSplex where IMS subsystems are cloned and the libraries are shared, the Online Change Copy utility might need to be executed only once on one IMS.SDFSRESL at the highest IMS level.

Subsections:

• Restrictions
• Prerequisites
• Requirements
• Recommendations
• JCL specifications

Restrictions

The following restrictions apply to the Online Change Copy utility:

• If any of the ACBLIB, FORMAT, or MODBLKS libraries are shared among IMS systems, all systems must use the same libraries during execution of this utility.
• In an XRF environment ACBLIBs, FORMATs, and MODBLKs data sets must be on shared non-duplexed DASD for error protection. Make the same additions or changes to separate but duplicate copies of IMS data sets.
• You cannot use the Online Change Copy utility to make additions or changes that require new IMS modules to be added to the IMS.SDFSRESL data set.
• You cannot add, modify, or delete MSDBs using this utility. However, PSB related changes for MSDBs can be made to the ACBLIBs, as long as no DBD changes are included.
• You cannot add, modify, or delete partitions of a HALDB database using this utility; only by using the Partition Definition utility. However, PSB related changes for HALDB database can be made to the ACBLIBs, as long as no DBD changes are included.
• In an RSR environment, this utility has no effect on the copies of the ACBLIBx, FORMATx, MODBLKSx, and MODSTAT data sets that are used on the tracking subsystem to track an active subsystem.
• If dynamic resource definition (DRD) is enabled (MODBLKS=DYN is specified in the DFSCGxxx IMS.PROCLIB member or in the COMMON_SERVICE_LAYER section of the DFSDFxxx IMS.PROCLIB member), the Online Change Copy utility might not be needed. Because the online change function is disabled, you do not need to copy stored resource definitions to prepare for an online change. You can use the Online Change Copy utility to copy stored resource definitions to a MODBLKS data set that will be loaded by an IMS cold start.

If the Online Change Copy utility is canceled prior to completion, the status of the ACBLIB, FMTLIB, or MODBLKS data set is unpredictable. The data set that is being changed by the utility is cleared as soon as the utility has exclusive control of the data set, and then new information is written to the data set. If the utility is canceled prior to its successful completion the information in the data set is not usable.

Prerequisites

Currently, no prerequisites are documented for the DFSUOCU0 utility.

Requirements

Three copies of the following libraries are required for online change:

ACBLIB

Database and program descriptors such as DMBs and PSBs

FORMAT

Control blocks produced by the MFS Language utility and service utility

MODBLKS

A subset of the control blocks for the resources to be modified

One copy of each library is used exclusively for offline functions. This library has no suffix and is called the staging library.

The other two copies of each library have a suffix of A or B. Only one of these libraries is used by the IMS online system at any one time. The one in use is referred to as the active library. The other is called the inactive library.

The Online Change Copy utility can copy the contents of the staging library to the inactive library based on the information in the MODSTAT data set (local online change) or the OLCSTAT data set (global online change).

The same method of serialization prevents this utility from updating the active libraries while they are being used by an IMS online system.

Recommendations

Create a backup copy of all the active ACB library members before you perform an ACB library member online change operation.

JCL specifications

Procedure statement

The procedure statement must be in the following form to invoke the utility and to include optional IEBCOPY parameters:

OLCUTL PROC TYPE=,IN=,OUT=,SOUT=A,SYS=,SYS2=,OLCGLBL='DUMMY,',OLCLOCL=

OLCGLBL=

OLCLOCL=

These parameters produce the OLCSTAT DD card or the MODSTAT/MODSTAT2 DD cards.

OLCGLBL='DUMMY,',OLCLOCL=

Produced by Stage 2 system definition. This parameter results in the OLCUTL procedure being set up for local online change as the default with the following DD statements:

//MODSTAT  DD &OLCLOCL.DSN=IMS.&SYS.MODSTAT,DISP=SHR
//MODSTAT2 DD &OLCLOCL.DSN=IMS.&SYS.MODSTAT2,DISP=SHR 
//OLCSTAT  DD &OLCGLBL.DSN=IMSPLEX.OLCSTAT,DISP=OLD

For global online change, set the OLCGLBL= and OLCLOCL= parameters as follows:

OLCGLBL=,OLCLOCL='DUMMY,'

These parameters generate the following DD statements to be used for global online change:

//MODSTAT DD DUMMY,DSN=IMS.&SYS..MODSTAT,DISP=SHR
//MODSTAT2 DD DUMMY,DSN=IMS.&SYS..MODSTAT2,DISP=SHR
//OLCSTAT DD DSN=IMSPLEX.OLCSTAT,DISP=OLD

SOUT=

Specifies the class assigned to SYSOUT DD statements.

SYS=

Specifies an optional second level dsname qualifier for those data sets which are designated as Mandatory Shared in an XRF complex. When specified, the parameter must be enclosed in quotes and must include a trailing period; for example, SYS='IMSA.'

SYS2=

Specifies an optional second level dsname qualifier for those data sets which are designated as Optional Replicate in an XRF complex. When specified, the parameter must be enclosed in quotes and must include a trailing period; for example, SYS2='IMSA.'

EXEC statement

The EXEC statement determines which copy is made and which data sets are used for input and output. The format of this statement can include optional IEBCOPY parameters specified in the order of WORK, SIZE, LIST after the target library.

When you omit a parameter, include a comma in its place. For example, when you specify only the LIST parameter without specifying WORK or SIZE, use the following syntax: ,,&LIST

The IEBCOPY options list, which contains the IEBCOPY keywords, equal signs, parameter values, and commas, cannot exceed 64 bytes. The IEBCOPY parameters are passed to the IEBCOPY utility when the utility is called.

PGM=DFSUOCU0,PARM=(&TYPE,&IN,&OUT,&WORK,&SIZE,&LIST)

DD statements

IMSACB DD

IMSACBA DD

IMSACBB DD

Defines the staging, active, or inactive ACBLIB.

IMSACBI DD

User-defined input ACBLIB.

IMSACBO DD

User-defined output ACBLIB.

FORMAT DD

FORMATA DD

FORMATB DD

Defines the staging, active, or inactive MFS format library.

FORMATI DD

User-defined input FORMAT library.

FORMATO DD

User-defined output FORMAT library.

OLCSTAT DD

Defines the global online change status data set name for an IMS enabled for global online change. The OLCSTAT data set is similar to the MODSTAT data set used for local online change. The OLCSTAT DD should not be defined if local online change is enabled, or if global online change is enabled and the OLCSTAT data set is to be dynamically allocated.

The SYSIN DD statement may be specified for &OUT option G, in order to dynamically allocate the OLCSTAT data set, rather than define it with the OLCSTAT DD statement. The OLCSTAT data set must be defined as data after the SYSIN DD statement, starting in column 1.

If the OLCSTAT data set is defined with the OLCSTAT DD statement and the SYSIN DD statement, the SYSIN DD statement is ignored.

If a multi-step batch job invokes the DFSUOCU0 utility in a step after a CSLUSPOC step that issues INITIATE OLC commands, the DFSUOCU0 utility must allocate the OLCSTAT data set dynamically.

MODBLKS DD

MODBLKSA DD

MODBLKSB DD

Defines the staging, active, or inactive system definition library.

MODBLKSI DD

User-defined input MODBLKS library.

MODBLKSO DD

User-defined output MODBLKS library.

MODSTAT DD

MODSTAT2 DD

Defines the local online change modify status data set names. This is the active data set (and inactive data set, if XRF is used) that online IMS should use at initialization.

SYSUDUMP DD

Defines the dump data set for this program. The data set can reside on a printer, tape, or direct-access device, or be routed through the output stream.

SYSPRINT DD

Defines the message output data set. The data set can reside on a printer, tape, or direct-access device, or be routed through the output stream. This DD statement must always be included.

SYSUT3 DD

Defines a work data set that is required.

SYSUT4 DD

Same function as SYSUT3.

COPYCTL DD

Defines a copy control data set to be built prior to calling IEBCOPY.