Recovery manager utility program, DFHRMUTL

The recovery manager utility program, DFHRMUTL overrides the type of CICS® startup produced by a START=AUTO, and improving the performance of cold and initial starts.

For detailed information about the type of startup produced by each possible combination of START setting, global catalog and system log contents, and autostart override, see Controlling start and restart.

Overview

DFHRMUTL processes the global catalog data set. It can insert or modify the recovery manager autostart override record. Optionally, it can extract a subset of the catalog records to build a reduced new catalog for a cold start.

You can use the recovery manager utility program to:
  • Set or reset the recovery manager autostart override record on the global catalog.
  • Examine the setting of the autostart override record on the global catalog.
  • Copy that part of the catalog needed for a cold start to a new global catalog.

    If a new catalog is built using DFHRMUTL, CICS is able to perform only a cold start or an initial start with the new catalog. The performance of these starts will, however, be better than that of a cold or initial start with a full catalog.

The following examples illustrate the uses of DFHRMUTL:

DFHRMUTL sets a return code indicating if it has succeeded.

DFHRMUTL writes some or all of the following to the output data set, SYSPRINT:
  • The input record from SYSIN.
  • Error messages.
  • A summary of the autostart override record found on the global catalog, DFHGCD.
  • The next CICS start type found on the global catalog, DFHGCD.
  • Counts of those units of work (UOWs) that were in an indoubt, commit-failed or backout-failed state when CICS was shut down. Note that these counts are provided if the next CICS start type is warm.
  • Whether or not the DFHGCD catalog is a reduced copy from a previous run of DFHRMUTL.
  • The autostart override record that has been set on DFHGCD, or on NEWGCD if a copy is made.

The catalogs DFHGCD and NEWGCD may be updated. If no copy is requested, DFHGCD may have an override record inserted, or updated. If a copy is requested, DFHGCD is unchanged, NEWGCD is cleared, and the copy and new override record written to NEWGCD.

Specifying parameters for DFHRMUTL

You can specify what you want DFHRMUTL to do by supplying parameters in a single optional record in the input data set, SYSIN.

You may need to supply one or two CICS global catalog data sets:
DFHGCD
The catalog from which a copy is extracted or, if no copy is being made, the one in which the autostart override record is placed.
NEWGCD
The catalog which is cleared and receives the copy, if one is requested.

You can use the parameters SET_AUTO_START and COLD_COPY to control the actions that DFHRMUTL takes.

The first record of SYSIN must contain all of the parameters for the utility. If the SYSIN data set is empty, DFHRMUTL outputs a summary of the autostart override record it finds on the DFHGCD catalog. If SYSIN contains more than one record, it is an error.

If specified, the parameters must be separated by commas and contain no embedded blanks. After the parameters, which must be the first non-blank characters of the record, all other characters are ignored.

SET_AUTO_START={AUTOASIS|AUTOCOLD|AUTODIAG|AUTOINIT}
The type of the next startup, if the START=AUTO system initialization parameter is specified. The start-type is placed in the autostart override record of either DFHGCD or (if COLD_COPY is specified) NEWGCD.
AUTOASIS
Perform the default startup, either warm or emergency. If START=AUTO is used on the next startup, the start-type is based on the recovery manager control record. This is the startup you would get if the autostart override record were not present.

This value is not compatible with the COLD_COPY keyword, nor is it allowed if the catalog you are updating is the result of a COLD_COPY and CICS has not used the catalog since then. Either of these combinations would result in CICS performing a warm or emergency restart with insufficient information in the global catalog.

AUTOCOLD
Perform a cold start. If START=AUTO is used on the next startup, CICS performs a cold start, if a cold start is possible at that time.

A CICS system that was shut down warm, and which had no indoubt, commit-failed or backout-failed units of work keypointed at that time, can be restarted cold without loss of data integrity. However, if the system was not shut down in a controlled manner, or indoubt, commit-failed or backout-failed units of work were recorded on the system log, then a cold restart should not be performed, because system data integrity could be compromised.

The DFHRMUTL summary information which is output to SYSPRINT can be used when determining whether AUTOCOLD is suitable or not. DFHRMUTL also issues the information message DFHRM0315I, AUTOCOLD or AUTOINIT should not be used, if it detects that this condition applies.

If the input catalog is empty (or has insufficient information in it) AUTOCOLD is not allowed.

The AUTOCOLD option has no effect on the following system initialization parameters (which are taken from the local catalog), unless they are specified as SIT overrides at CICS startup:
  • DSALIM
  • DUMP
  • EDSALIM
  • STGPROT
  • SUBTSKS
  • TRANISO
AUTODIAG
Perform a diagnostic run. If START=AUTO is used on the next startup, CICS performs a diagnostic run. On a diagnostic run, CICS:
  1. Produces a dump of the CICS system state, retrieved from the CICS system log.
  2. Terminates. Note that, on a diagnostic run, CICS performs no recovery work and no new work.

A diagnostic run is used to diagnose problems on the CICS system log. The output produced by a diagnostic run is usually passed to IBM® Service.

If the system log becomes corrupt, CICS sets the recovery manager autostart override record in the global catalog so that the next automatic start (START=AUTO) is a diagnostic run. However, there may be other occasions (when perhaps the system log is still readable) when you feel it would be useful to perform a diagnostic run. The AUTODIAG option enables you to specify a diagnostic run manually.

For detailed information about diagnostic runs, and the circumstances in which you might need to perform one, see Dealing with a corrupt system log.
Note:
  1. Unlike the other options of SET_AUTO_START, whose effects are limited to the next CICS startup, AUTODIAG has a persistent effect. That is, the autostart override record of DFHGCD is set to produce a diagnostic run on each subsequent AUTO start, and can only be reset by running DFHRMUTL again.
  2. AUTODIAG is not compatible with the COLD_COPY keyword.
AUTOINIT
Perform an initial start. If START=AUTO is used on the next startup, CICS performs an initial start, whatever the other contents of the global catalog.
The AUTOINIT option has no effect on the following system initialization parameters (which are taken from the local catalog), unless they are specified as SIT overrides at CICS startup:
  • DSALIM
  • DUMP
  • EDSALIM
  • STGPROT
  • TRANISO
COLD_COPY
Make a reduced copy of DFHGCD in NEWGCD. Create in NEWGCD a copy of only those records from DFHGCD that CICS needs to perform a cold start, and update NEWGCD with the autostart override record specified by the SET_AUTO_START parameter.
  1. All changes caused by SET_AUTO_START are made to the NEWGCD data set, and DFHGCD is not changed.
  2. COLD_COPY is incompatible with the AUTOASIS and AUTODIAG options of SET_AUTO_START. If you specify COLD_COPY and either of these values of SET_AUTO_START, it is an error.

JCL requirements for DFHRMUTL

DFHRMUTL runs as a standard operating system job. You require a JOB statement, an EXEC statement, and DD statements defining input and output.

The DD statements for the input and output data sets used by DFHRMUTL are:
STEPLIB DD
Defines a partioned data set (DSORG=PO) containing DFHRMUTL. If DFHRMUTL is in the link list, this statement is not required.
SYSPRINT DD
Defines the output data set for results, information and error messages. The DCB parameters for this data set are RECFM=FBA and LRECL=133.

The block size can be provided on the SYSPRINT DD statement and must be a multiple of 133. The default is 133.

SYSIN DD
Defines the input data set. This file must be in 80-byte record format.
DFHGCD DD
Defines the input global catalog data set, which may be empty. This catalog may be updated unless the COLD_COPY parameter is specified, in which case it is only read.
Note: An empty catalog data set, after having an override record inserted by DFHRMUTL, may then be used by a CICS system for startup.
NEWGCD DD
Defines the output global catalog data set. This statement is not required unless the COLD_COPY parameter is specified. If COLD_COPY is specified the NEWGCD data set is first cleared and then has DFHGCD records and an override record added to it. It must have been defined with the VSAM REUSE attribute.

Return codes from DFHRMUTL

DFHRMUTL sets one of the following return codes:
00
The parameters are valid and all reads and writes to the input and output data sets were successful.
16
One or more errors were detected during execution. An error message is output.
Errors that DFHRMUTL may detect are as follows:
  • A read or write error for the SYSIN or SYSPRINT data set
  • A read or write error for one of the catalog data sets
  • A syntax error in the parameters
  • A parameter that is incompatible with the input catalog data set
  • An invalid combination of parameters.

Example: Setting an initial start without operator intervention

Figure 1 shows the statements required to update the global catalog so that CICS performs an initial start if START=AUTO is specified.

You could use this job to modify a newly-defined global catalog. This would mean that could retain START=AUTO for all your CICS start jobs, including the first with a new global catalog.

If you use this step to initialize a newly-defined global catalog, you should use the DFHCCUTL utility to initialize the local catalog too. (If you use it to reinitialize an existing global catalog, it is not necessary to initialize the local catalog.) For information about initializing catalog data sets, see Setting up the catalog data sets.

Figure 1. DFHRMUTL—setting the next auto start to be an initial start.
//RMUTL    EXEC PGM=DFHRMUTL,REGION=1M
//STEPLIB  DD DSNAME=hlq.SDFHLOAD,DISP=SHR
//SYSPRINT DD SYSOUT=A
//DFHGCD   DD DSNAME=catalog.dataset,DISP=OLD
//SYSIN    DD *
  SET_AUTO_START=AUTOINIT
/*

Example: Examining the override record

Figure 2 shows the statements required to examine the autostart override record on a CICS global catalog data set.
Figure 2. DFHRMUTL—examining an autostart override record
//RMUTL    EXEC PGM=DFHRMUTL,REGION=1M
//STEPLIB  DD DSNAME=link.dataset,DISP=SHR 
//SYSPRINT DD SYSOUT=A
//DFHGCD   DD DSNAME=catalog.dataset,DISP=OLD
//SYSIN    DD * 
/*
This JCL also reveals:
  • If this is a catalog data set produced by a COLD_COPY and not yet used by CICS (and so not populated with other records).
  • If it is an “empty” catalog—that is, it does not contain a recovery manager control record.

Example: Resetting a warm or emergency start

Figure 3 shows the statements required to update the global catalog so that CICS performs a warm or emergency start if START=AUTO is specified. This enables you to undo the effects of a previous run of DFHRMUTL that set the autostart override record to AUTOINIT or AUTOCOLD. (The AUTOASIS override record is equivalent to there being no override record in the global catalog.)

If the global catalog data set was produced by a COLD_COPY, or if it is empty, DFHRMUTL rejects the AUTOASIS value.

Figure 3. DFHRMUTL—resetting a warm or emergency start
//RMUTL    EXEC PGM=DFHRMUTL,REGION=1M
//STEPLIB  DD DSNAME=link.dataset,DISP=SHR
//SYSPRINT DD SYSOUT=A
//DFHGCD   DD DSNAME=catalog.dataset,DISP=OLD
//SYSIN    DD *
  SET_AUTO_START=AUTOASIS
/*

Example: Improving the performance of a cold start

Figure 4 shows the statements required to:
  • Create a new global catalog data set consisting only of those records required for a cold start.
  • Set the autostart override record of the new catalog to indicate a cold start.
  • Replace the original catalog with the new one, if the creation step succeeded.

Because the original catalog data set is overwritten by a COLD_COPY, it is not suitable for a warm or emergency start. DFHRMUTL does not allow you to reset the override record to read AUTOASIS.

Figure 4. DFHRMUTL—setting the global catalog for a cold start. COLD_COPY is used to improve performance.
//RMUTL    EXEC PGM=DFHRMUTL,REGION=1M
//STEPLIB  DD DSNAME=link.dataset,DISP=SHR
//SYSPRINT DD SYSOUT=A
//DFHGCD   DD DSNAME=catalog.dataset,DISP=OLD
//NEWGCD   DD DSNAME=newcatalog.dataset,DISP=OLD
//SYSIN    DD *
  SET_AUTO_START=AUTOCOLD,COLD_COPY
/*
//         IF (RMUTL.RC=0) THEN
//* Step to be performed if RMUTL succeeds
//COPY     EXEC PGM=IDCAMS
//DFHGCD   DD DSNAME=catalog.dataset,DISP=OLD
//SYSPRINT DD SYSOUT=A
//NEWGCD   DD DSNAME=newcatalog.dataset,DISP=OLD
//SYSIN    DD *
  REPRO INFILE(NEWGCD) OUTFILE(DFHGCD) REUSE
/*
//* End of step
//         ENDIF