Partial Database Reorganization utility (DFSPRCT1 and DFSPRCT2)

Use the Partial Database Reorganization utility to reorganize user-specified ranges of an HDAM or HIDAM database.

A range is either a group of HIDAM records with continuous key values or a group of HDAM records with continuous relative block numbers. A range is specified using a low and high pair of key or block number values.

Up to 49 related databases can be processed and as many as 500 segment types can participate in a reorganization. Up to 500 scan and reload actions are allowed for pointer resolution. Up to 10 KEYRANGEs or FROMAREAs are allowed and up to 10 TOAREAs are allowed after each FROMAREA or KEYRANGE.

You can use the Database Surveyor utility (DFSPRSUR) to produce a report that describes the physical organization of the database. This information can help you determine a range for the reorganization.

The Partial Database Reorganization utility, in one execution, performs operations that are similar to several other reorganization utilities, such as:
  • Unloading, in hierarchic sequence, all root segments within a specified range and all segments dependent on those roots
  • Reloading, in hierarchic order, those root and dependent segments into specified contiguous free space
  • Resolving all pointers relating to the reloaded segments, including:
    • Logically related segments in the same database
    • Logically related segments in other databases
    • Physical twin pointers of roots at boundaries of selected ranges
To accomplish the reorganization, two steps are executed:
  1. The DFSPRCT1 utility performs preorganization functions to check for user errors without requiring use of the database.
  2. The DFSPRCT2 utility performs the unload/reload/pointer resolution functions with the database offline.

The Partial Database Reorganization utility has restart capabilities. Utility checkpoints are taken before the unload/reload phase, at the end of each sort phase, and at the beginning of the prefix update phases. A restart can be performed from any checkpoint. Before restarting, you must use the Batch Backout utility (DFSBBO00) to undo any changes made after the checkpoint was taken.

Subsections:

Restrictions

The following restrictions apply when using the Partial Database Reorganization utility:
  • Structural changes to the database are not allowed.
  • HISAM logically related databases cannot have a direct pointer in a logical child or logical parent segment.
  • The DFSPRCT1 and DFSPRCT2 utilities will work on full-function non-HALDB databases only.
  • Utilities that alter databases cannot be run while the database is quiesced.

Prerequisites

Currently, no prerequisites are documented for the Partial Database Reorganization utility.

Requirements

Currently, no requirements are documented for the Partial Database Reorganization utility.

Recommendations

Currently, no recommendations are documented for the Partial Database Reorganization utility.

Input and output

Two steps are used in the Partial Database Reorganization utility. The input for each step is described in the following topics.

Several reports are produced by the utility.

Step 1: prereorganization

The first step of partial database reorganization performs initialization functions consisting of:
  • Reading control statements that specify the range of records
  • Creating control tables for use during Step 2
  • Determining logically related databases that might require pointer resolution
  • Preparing a report

Step 1 requires, as input, the DBD of the database to be reorganized and utility control statements defining the record ranges and sort options.

The primary output is the set of control tables to be used by Step 2 to perform the partial reorganization. Optionally, PSB source statements can be produced to create a PSB for use in Step 2. (This PSB must contain PCBs for four required GSAM work data sets and must be assembled and bound before Step 2.) After the PSB generation is done for the databases to be reorganized, that process does not have to be repeated for subsequent reorganizations of the same databases. Step 1 also produces two scan reports. The REQUIRED-SEGMENT-SCAN report lists any logically related segments of logically related databases that are automatically scanned during Step 2 processing. The OPTIONAL-SEGMENT-SCAN report lists any logically related segments of logically related databases for which a scan is optional. (To select an optional segment for scanning, provide a SCANSEG control statement as Step 2 input.)

The scan examines every occurrence of all segment types being scanned and builds a work record for each occurrence. Step 2 uses these work records to speed its location of the segment occurrences that need pointer updating. If a scan is not performed for the optional scan segments, the prefix update phase of Step 2 must follow pointer chains to locate segments to be updated.

Scanning the optional segments has advantages when:
  • Other segments in the same database require the scan
  • A large proportion of the optional scan segments contains pointers to required scan segments being moved in a logically related database

Additional Step 1 outputs include reports, possibly error messages, and a return code.

Step 2: unload, reload, and pointer resolution

The second step reads the control tables produced by Step 1 and the user-supplied control statements. According to the specified record ranges, all segments (roots and their dependents) are unloaded in hierarchic order to an intermediate data set. The space within the database that these records occupied is freed. Again according to your specification, the records are reloaded into ranges of free space within the database and the new record locations saved in work records. Then, all logically related databases are scanned for pointers to the records that have been moved: work records are created to designate where pointer resolution is required. All work records are then sorted (by z/OS® SORT) according to database name and segment name. Finally, all pointers to the records having new locations are changed to point to the new locations.

Output from Step 2 includes the partially reorganized database, as well as a report of what was done and a return code. In the case of an unsuccessful execution, an error message is issued.

JCL specifications

The Partial Database Reorganization utility is executed as two standard z/OS jobs in an IMS batch processing region. The following JCL statements are required:
  • A JOB statement that you define to meet the specifications of your installation.
  • An EXEC statement
  • DD statements that define inputs and outputs

JCL statements for step 1: DFSPRCT1

This topic explains the EXEC statement and DD statements for Step 1.

EXEC statement for step 1

The EXEC statement describes the program to be run. The format of the statement is: 

PGM=DFSPRCT1,PARM=()
To run the DFSPRCT1 utility in an IMS-managed application control blocks (ACBs) environment, modify the IMS Catalog Definition exit routine (DFS3CDX0). For more information, see IMS Catalog Definition exit routine (DFS3CDX0).
Note: When the IMS management of ACBs is enabled, the DFSPRCT1 utility obtains the database descriptors (DBD) from the IMS catalog instead of the DBD library that is specified in the IMS DD statement.

DD statements for step 1

The following DD statements define the required and optional input and output data sets for Step 1.
STEPLIB DD
Points to the IMS.SDFSRESL, which contains the IMS nucleus and required action modules.
IMS DD
Defines the library containing the DBDs that describe the database to be reorganized and all logically related databases.
If the IMS management of ACBs is enabled, the IMS DD statement is optional and ignored by IMS.
SYSPRINT DD
Defines the message and report output data set. The data set can reside on a tape, a direct-access device, or a printer, or be routed through the output stream.

DCB parameters for this data set are RECFM=FBA and LRECL=121. BLKSIZE must be provided on the DD statement and must be a multiple of 121.

This DD statement is required.

SYSIN DD
Defines the input control data set for this job. The data set can reside on a tape, or direct-access device, or be routed through the output stream. The LRECL must be specified as 80.
SYSABEND DD or SYSUDUMP DD
Define a dump data set. If both statements are present, the last occurrence is used for the dump.
SYSPUNCH DD
Defines the data set that contains the PSB source statements if the user elected to have them produced.

DCB parameters for this data set are RECFM=FBS and LRECL=80. BLKSIZE must be provided on this DD statement and must be a multiple of 80.

DFSPRCOM DD
Defines the data set that contains the control tables that are to be used by Step 2.

JCL statements for step 2: DFSPRCT2

This topic explains the EXEC statement and DD statements for Step 2.

EXEC statement for step 2

The EXEC statement describes the program to be run. The format is: 
PGM=DFSRRC00,PARM=(DLI,DFSPRCT2,psbname)

DLI describes the region, DFSPRCT2 names the Step 2 program, and psbname is the name of the PSB that includes the database to be reorganized. The normal IMS positional parameters can follow the psbname in the PARM field.

To run the DFSPRCT2 utility in an IMS-managed application control blocks (ACBs) environment for batch application programs, update the JCL or modify the IMS Catalog Definition exit routine (DFS3CDX0), which is an alternative to referencing the DFSDFxxx member of the IMS.PROCLIB data set in the JCL of batch application programs. For more information, see IMS Catalog Definition exit routine (DFS3CDX0).
Note: When the IMS management of ACBs is enabled, the DFSPRCT2 utility obtains the program specification block (PSB) from the IMS catalog, instead of from the PSB library that is specified in the IMS DD statement.

An additional EXEC parameter, DFSDF, must be specified to use this utility with an IMS catalog database that is not registered in the RECON data set. DFSDF= specifies the member name or names of the unregistered catalog PSB. For example:

//PGM=DFSRRC00,
//   PARM=(DLI,DFSPRCT2,psbname,,,,,,,,,,,N,N,,,,,,,,,,,,,,,,
,,,,,,,,,,
//       'DFSDF=CAT')

Replace the 3-character suffix CAT with the suffix of the DFSDFxxx member that specifies the unregistered IMS catalog database names.

DD statements for step 2

The following DD statements define the required and optional input and output data sets for Step 2.
STEPLIB DD
Points to IMS.SDFSRESL, which contains the IMS nucleus and required action modules. If STEPLIB is unauthorized by having unauthorized libraries concatenated to IMS.SDFSRESL, a DFSRESLB DD statement must be included.
DFSRESLB DD
Points to an authorized library which contains the IMS SVC modules.
IMS DD
Defines the libraries containing the DBDs that describe the database to be reorganized and all logically related databases. This library must also contain the PSB named in the EXEC statement and the required GSAM DBDs.
If the IMS management of ACBs is enabled, the IMS DD statement is optional and ignored by IMS.
DFSPRWF1 DD
Defines an intermediate work data set. Specify DISP=NEW for this data set.
DFSPRWF2 DD
Defines an intermediate work data set. This is a GSAM data set. DCB parameters must include LRECL=18 and RECFM=FB. Specify DISP=NEW for this data set, except when executing a restart from a checkpoint with a number greater than DFSPR001. In this case, specify DISP=OLD. A GSAM DBD must be generated for this data set.
DFSPRWF3 DD
Defines an intermediate work data set. This is a GSAM data set. DCB parameters must include LRECL=18 and RECFM=FB. Specify DISP=NEW for this data set, except when executing a restart from a checkpoint with a number greater than DFSPR001. In this case, specify DISP=OLD. A GSAM DBD must be generated for this data set.
DFSPRWF4 DD
Defines an intermediate work data set. This is a GSAM data set. DCB parameters must include LRECL=1000 and RECFM=VB. Specify DISP=NEW for this data set, except when executing a restart from a checkpoint with a number greater than DFSPR001. In this case, specify DISP=OLD. A GSAM DBD must be generated for this data set.
DFSPRWF5 DD
Defines an intermediate work data set. This is a GSAM data set. DCB parameters must include LRECL=1000 and RECFM=VB. Specify DISP=NEW for this data set, except when executing a restart from a checkpoint with a number greater than DFSPR001. In this case, specify DISP=OLD. A GSAM DBD must be generated for this data set.
DFSPRWF6 DD
Defines an intermediate work data set. Specify DISP=NEW for this data set, except when executing a restart from a checkpoint with a number greater than DFSPR001. In this case, specify DISP=OLD.
DFSPRWF7 DD
Defines an intermediate work data set. Specify DISP=NEW for this data set, except when executing a restart from a checkpoint with a number greater than DFSPR002. In this case, specify DISP=OLD.
DFSPRWF8 DD
Defines an intermediate work data set. Specify DISP=NEW for this data set, except when executing a restart from a checkpoint with a number greater than DFSPR003. In this case, specify DISP=OLD.
DFSPRWF9 DD
Defines an intermediate work data set. Specify DISP=NEW for this data set, except when executing a restart from a checkpoint with a number greater than DFSPR004. In this case, specify DISP=OLD.
DFSPRWFA DD
Defines an intermediate work data set. Specify DISP=NEW for this data set.
SORTLIB DD
Defines the data set containing the load modules for the z/OS SORT/MERGE program. This DD statement is required.
SORTWKnn DD
Defines intermediate storage data sets for the z/OS SORT/MERGE program.
IEFRDER DD
Defines the IMS log data set, which must reside on a direct-access device. This statement is required.

If this data set is specified as DD DUMMY, no checkpoint/restart capability is available.

SYSPRINT DD
Defines the message and report output data set. The data set can reside on a tape, a direct-access device, or a printer, or be routed through the output stream. This statement is required.

DCB parameters for this data set are RECFM=FBA and LRECL=121. BLKSIZE must be provided on this DD statement and must be a multiple of 121.

DFSPRCOM DD
Defines the data set created by Step 1 containing the control tables.
SYSIN DD
Defines the input control data set for this job. The data set can reside on a tape, or a direct-access device, or be routed through the output stream.
SYSOUT DD
Defines the message output data set for the z/OS SORT/MERGE program. The ddname is the one specified during generation of invoked sort (normally, the ddname is SYSOUT). This data set can reside on a printer, a tape, or a direct-access device, or be routed through the output stream. This DD statement is required.
database DD
Defines the database data sets to be reorganized, all logically related database data sets, and all secondary index data sets. The ddnames must match those specified in the DBD.

If this is a HIDAM database, DD statements for the index data sets must also be supplied. The ddnames must match those specified for the index data sets in the DBD.

These data sets must reside on a direct-access device. DISP=OLD is recommended.

DFSVSAMP DD
Describes the data set that contains the buffer pool information required by the DL/I buffer handler. This DD statement is required.
DFSCTL DD
Describes the data set containing SBPARM control statements, which request activation of sequential buffering (SB).

The DFSCTL file can be either a sequential data set or a member of a PDS. The record format must be either F, FB, or FBS and the record length must be 80. The data set can reside on a direct-access device, a tape, or be routed through the input stream.

SYSABEND DD or SYSUDUMP DD
Defines a dump data set. These DD statements are optional. If both statements are present, the last occurrence is used for the dump.
RECON1 DD
Defines the first DBRC RECON data set.
RECON2 DD
Defines the second DBRC RECON data set.
RECON3 DD
Defines the optional DBRC RECON data set used when an error is encountered in RECON1 or RECON2. This RECON data set must be the same RECON data set as the control region is using.

Do not use these RECON data set ddnames if you are using dynamic allocation.

Return codes

The DFSPRCT1 and DFSPRTC2 modules generate the following return codes preceded, in the case of errors, by numbered messages to the SYSPRINT data set that more fully explain the results of program execution:
Code
Meaning
0
All requested operations have completed successfully.
4
Warning message issued.
8
Severe errors causing job termination have occurred.