HALDB Partition Data Set Initialization utility (DFSUPNT0)

Use the HALDB Partition Data Set Initialization utility (DFSUPNT0) to initialize HALDB partitions.

The DFSUPNT0 utility normally initializes only partitions that are flagged in the RECON data set as needing to be initialized (PINIT=Y); however, you can have the DFSUPNT0 utility initialize partitions unconditionally, which initializes partitions even when they are recorded in the RECON data set as PINIT=N. Any data in a partition that is initialized unconditionally is lost.

You can specify either HALDB master database names, partition names, or both:

  • If a HALDB master database name is specified, then all of the partitions in the database that are identified in the RECON data set as requiring partition initialization are initialized.
  • If a HALDB partition name is specified as a SYSIN statement, then initialization for that partition is done unconditionally, and PINIT=N is set in the partition record in the RECON data set.
  • If a DFSOVRDS DD statement is specified, then all partitions in a HALDB database are unconditionally initialized.

The DFSUPNT0 utility is recommended for use with existing HALDB databases because the utility provides complete checking and validation of each partition by IMS. To initialize partitions when converting a database to HALDB, you can also use the Database Prereorganization utility (DFSURPR0).

You can specify a HALDB master database name on the EXEC parameter list submitted to the IMS Region Controller or as a statement in the SYSIN data set. If you use SYSIN statements you can specify multiple HALDB master database and partition names.

You can specify partition names only as statements in the SYSIN data set. You can specify multiple partition names.

The DFSUPNT0 utility can be executed as multiple job tasks. Specifying each partition in a separate DFSUPNT0 job and then running those jobs simultaneously can greatly improve the overall partition initialization process.

You can also run multiple jobs without specifying partition names, but this is not recommended. Each task attempts to initialize all required partitions found in RECON and serializes around the initialization function using a system enqueue. After a successful enqueue, DBRC is queried for a list of partitions requiring initialization. Partitions requiring initialization different from the ones at job batch initialization time are ignored. Partitions that required initialization at batch initialization time but no longer require it are ignored. Only partitions that still require initialization after the enqueue are initialized.

Subsections:

Restrictions

The DFSUPNT0 utility will work on full-function HALDB databases only.

Utilities that alter databases cannot be run while the database is quiesced.

Prerequisites

Before you run the DFSUPNT0 utility, you must define all data sets to z/OS® that will by dynamically allocated by the DFSUPNT0 utility.

Requirements

To run the DFSUPNT0 utility you must satisfy various operational requirements.

The following requirements apply when using the HALDB Partition Data Set Initialization utility:
  • Data sets are dynamically allocated and must have been previously defined.
  • DBRC is required.
  • RECON DD statements are required if not dynamically allocated.
  • Do not code JCL DD statements for partition data sets. Partition data sets must be dynamically allocated by IMS based on information from the RECON.

Recommendations

The DFSUPNT0 utility is recommended for use with existing HALDB databases. The utility provides complete checking and validation of each partition by IMS. To initialize partitions when converting a database to HALDB, you can also use the Database Prereorganization utility (DFSURPR0).

To improve overall performance of the partition initialization process for a HALDB database, use separate DFSUPNT0 jobs to initialize each partition in a HALDB database and then run those jobs simultaneously.

Input and output

The primary inputs to the DFSUPNT0 utility are partitions requiring initialization. The partition data sets do not need to be allocated.

The primary outputs of the DFSUPNT0 utility are initialized partitions.

Return codes

The following return codes are provided at program termination:
Code
Meaning
0
Successful completion.
8
Processing error or the format of the DFSOVRDS DD statement is incorrect.
12
Invalid input or IMS control block.
16
Environment or user error.
32
Abend returned from attach of IMS.
99
Internal logic error.

JCL specifications

The DFSUPNT0 utility is executed as a standard z/OS job. The JCL specifications for the DFSUPNT0 utility include a JOB statement, the EXEC statement, and the DD statements. One or more utility control statements must be/can be included with the JCL statements.

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

EXEC statement

Two EXEC statements are possible; one is without a SYSIN, and one is with a SYSIN. Only a master database name can be passed on the EXEC statement. Partition names are only allowed as SYSIN statements.

For the examples in this topic, if you are using DBRC without dynamic allocation, you must add the DD statements to the sample JCL, as shown in the figure below:

//RECON1   DD  DSNAME=RECON1,DISP=SHR 
//RECON2   DD  DSNAME=RECON2,DISP=SHR 
//RECON3   DD  DSNAME=RECON3,DISP=SHR
In the following example, a master database name HDODB1 is specified in the EXEC statement: 
PARM=(ULU,DFSUPNT0,HDODB1,,,,,,,,,SYS3,,Y,N)
Without a SYSIN, the EXEC statements must be in the form shown in the following example: 
//PINIT01  EXEC PGM=DFSRRC00,REGION=2048K,
//             PARM=(ULU,DFSUPNT0,HDODB1,,,,,,,,,SYS3,,Y,N)
//STEPLIB   DD DSN=IMS.SDFSRESL  
//DFSRESLB  DD DSN=IMS.SDFSRESL,DISP=SHR
//IMS       DD DSN=IMS.DBDLIB,DISP=SHR
//RECON1    DD DSN=IMS.RECON1,DISP=SHR
//RECON2    DD DSN=IMS.RECON2,DISP=SHR
//RECON3    DD DSN=IMS.RECON3,DISP=SHR
//DFSVSAMP  DD input for VSAM and OSAM buffers and options
//SYSUDUMP  DD SYSOUT=A
//SYSPRINT  DD SYSOUT=A
//SYSIN DD  DUMMY
/*

With a SYSIN, the EXEC statements must be in the form shown in the following example:

//PINIT02  EXEC PGM=DFSUPNT0,REGION=2048K
//STEPLIB  DD DSN=IMS.SDFSRESL
//STEPCAT  DD DSN=VCATSHR,DISP=SHR
//DFSRESLB DD DSN=IMS.SDFSRESL,DISP=SHR
//IMS      DD DSN=IMS.DBDLIB,DISP=SHR
//RECON1   DD DSN=IMS.RECON1,DISP=SHR
//RECON2   DD DSN=IMS.RECON2,DISP=SHR
//RECON3   DD DSN=IMS.RECON3,DISP=SHR
//DFSVSAMP DD input for VSAM and OSAM buffers and options
//SYSUDUMP DD SYSOUT=A
//SYSPRINT DD SYSOUT=A
//SYSIN DD *
DBVHDJ05
DBOHIDK5
/*

This JCL initialized all database partitions recorded in RECON as PINIT for HALDB master databases DBVHDJ05 and DB0HIDK5. If a partition name is specified for a HALDB master database, the partition is initialized unconditionally and is recorded in RECON with PINIT off.

DD statements

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 that contains the IMS SVC modules.
IMS DD
Defines the libraries containing the DBD and PSB that describe the database to be analyzed. These data sets must reside on a direct-access device. This statement is required and must always define the DBD library. The PSB library is only required when PARM=DLI is specified.
RECON1 DD
Defines the first DBRC RECON data set.
RECON2 DD
Defines the second DBRC RECON data set. This RECON data set must be included if the area is registered in the 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.
Note: Do not use these RECON data set ddnames if you are using dynamic allocation.
SYSIN DD
Defines the input control data set for this program. The data set can reside on tape, on a direct-access device, or be routed through the input stream. LRECL and BLKSIZE must both be 80.
SYSPRINT DD
Defines the message output data set. The data set can reside on a printer, a tape, or a direct-access device, or be routed through the output stream.

DCB parameters specified within this program are RECFM=FB, LRECL=120. If BLKSIZE is specified, it must be a multiple of 120.

This DD statement is required.

The SYSPRINT data set is also used to return error messages to the user.

The following figure is an example of DFS391I output to SYSPRINT:

Figure 1. DFS391I output to SYSPRINT 
DFS391I PARTITION INITIALIZATION UTILITY
DFS391I SYSIN CONTROL CARDS
DFS391I POHIDJB
DFS391I PHVNTKA
DFS391I POHIDJC
DFS391I POHIDJA
DFS391I END OF SYSIN CONTROL CARDS
SYSUDUMP DD
Defines a dump data set.
DFSVSAMP DD
Describes the data set that contains the buffer information required by the DL/I Buffer Handler.
DFSOVRDS DD
Defines the option for unconditional partition initialization. You can initialize a HALDB database and all of its partitions by using this override option, even when the PARTITION INIT NEEDED flag in the RECON is not set to Y.

The only valid input for the DFSOVRDS DD statement is the character string INITALL or DD DUMMY. Any input other than INITALL or DD DUMMY causes the utility to issue a WTO message DFS1987I with reason code 19: THE DFSOVRDS DD CARD HAS AN INVALID INPUT.

The format of the DFSOVRDS DD statement is shown in the following figure.

Figure 2. DD statement for unconditional partition initialization 
//DFSOVRDS DD *
INITALL
Attention: All previously existing partition data for all the HALDB partitions is lost. Any input other than the string INITALL will be ignored by the utility, as if DFSOVRDS DD is not specified.