IPR Reload JCL requirements

The following table summarizes the DD statements. Actual JCL requirements follow the table.

EXEC

Must be in this form:

//name  EXEC  PGM=HPSCMAIN,
//            PARM='FUNC=RL,DBD=dbdname'

Specify HPSCMAIN as the program name. The PARM= parameter keywords are as follows:

FUNC=RL

Invokes the IPR Reload utility function to reload the database. This parameter is required.

DBD=dbdname

dbdname is the name of the DBD that includes the database to be reloaded. This parameter is required.

Optionally, you can specify the following keywords to specify the job step environment:

DBRC=

Specifies whether the IPR Reload utility uses DBRC.

Y

DBRC is used.

N

DBRC is not used unless the DBRC=FORCE option is specified during IMS system generation.

If this parameter is not specified, the default setting determined by IMS system generation is used.

To reload a HALDB, specify DBRC=Y.

IMSPLEX=name

Specifies the IMSplex name that is to be used by IMS DBRC SCI Registration. This parameter is 1- to 5-characters.

DBRCGRP=ccc

Specifies the DBRC group identifier that is to be used by IMS DBRC SCI Registration. This parameter is 3 characters.

SWAP=

Makes the address space swappable or non-swappable.

Y

The address space is made swappable.

N

The address space is made non-swappable.

The default is N.

IRLM=

Specifies whether the IPR Reload utility uses IRLM.

Y

IRLM is used.

N

IRLM is not used.

If this parameter is not specified, the default setting determined by IMS system generation is used.

IRLMNM= irlm

Specifies the IRLM subsystem name (a 1-to-4-character alphanumeric name), if IRLM=Y is specified.

GSGNAME=gsgname

Specifies the name of the global service group (GSG).

This parameter is optional.

DFSDF=ccc

Specifies the 3-character suffix of the DFSDFxxx member of the IMS.PROCLIB data set. You must also specify the PROCLIB DD statement.

STEPLIB DD

Points to the following libraries:

• IMS Database Reorganization Expert load module library (mandatory)
• IMS HP Load load module library (mandatory)
• IMS Library Integrity Utilities load module library (either one is required when DECODEDBD=YES)
• IMS RESLIB library (mandatory)
• The load module library that contains user routines (optional)
• The library that contains DFSMDA members for dynamic allocation of data sets (optional)
• The SGLXLOAD library of IMS Tools Base (optional)

  To reload a database in an IMS-managed ACBs environment or offload eligible workloads to zIIP processors, you must add the SGLXLOAD library of IMS Tools Base to the STEPLIB DD concatenation.

• IMS Catalog Definition exit routine (DFS3CDX0) library (optional)

  To reload a database in an IMS-managed ACBs environment without specifying the DFSDF= parameter keyword to the EXEC statement or reload an IMS catalog database that is not registered in the RECON data sets, you must add the IMS Catalog Definition exit routine library to the STEPLIB DD concatenation.

This DD statement is required.

IMSDALIB DD

Specifies a partitioned data set or data sets that contains the dynamic allocation members for the database, index and RECON data sets. Allocation of the database, index and the RECON data sets will be attempted in the following order:

1. The DD statements coded in the JCL stream
2. Dynamic allocation members in the IMSDALIB concatenation
3. Dynamic allocation members in JOBLIB or STEPLIB concatenation

For dynamic allocation of HALDB databases, the RECON data sets (and not this DD statement) are used instead of this DD statement.

IMS DD

Describes the library containing the DBD referred to in the PARM field of the EXEC statement. This data set must reside on a direct-access device.

This DD statement is required unless the IMS management of ACBs is enabled. When the IMS management of ACBs is enabled, IMS system ignores the IMS DD statement.

PROCLIB DD

Points to the IMS.PROCLIB data set. If DFSDF=ccc is specified on the EXEC statement, you must specify this DD statement and ensure that the DFSDFccc member exists in the IMS.PROCLIB data set.

DFSACBPD DD

Defines the control statement data set to be used in an IMS-managed ACBs environment. This DD statement is optional. STAGING is the only valid keyword.

When the IMS management of ACBs is enabled, IMS retrieves the DBDs from the IMS catalog. If you unload a database and make offline changes to the database definition, you can reload either the active changes from the IMS catalog directory data sets or the pending changes from the catalog staging data sets.

When the IMS management of ACBs is enabled, by default, IPR Reload utility obtains the active database definition from the IMS catalog directory. To override the default behavior and obtain the pending ACBs from the staging data sets in IMS catalog, specify the keyword STAGING on the DFSACBPD DD statement.

When the IMS management of ACBs is not enabled, the DFSACBPD DD statement is ignored.

DFSUINPT DD

Describes the input data set containing the data to be reloaded.This is the data set created by the IPR Unload utility or other equivalent utility. The data set must reside on either a tape or a direct-access device.

DFSURCDS DD

Defines the control data set for this program.The data set must be the output generated by the IMS Database Prereorganization utility (DFSURPR0). This DD statement must be included if logical relationships exist.

This data set must reside on either a tape or a direct-access device.

DFSVSAMP DD

Describes the data set that contains the buffer pool information that is required by the IMS DL/I buffer handler. This data set is required. For more information about control statement format, see IMS System Definition.

Notes:

1. When the DFSVSAMP DD card is omitted, DL/I Buffer Pool is not allocated.
2. DFSVSAMP DD is optional unless you are reloading HALDB or are using the DL/I call in the user exit routine.
3. You must specify DFSVSAMP DD when reloading HALDB or when using the DL/I call in the user exit routine.

HPSIN DD

Defines an optional data set that contains control statements specifying the optional functions of the IPR Reload utility.

DDEFPDS DD

Defines the optional data set that contains the IDCAMS commands for deleting and defining the database data sets to be processed by the IPR Reload utility. The IPR Reload utility searches for the delete and define statements for each database data set in the member that has the same name as the database DD name.

The member must contain only the delete and define statements.

Requirements:

• To delete and define database data sets by specifying this DD statement, the load module library of STEPLIB must be authorized through the Authorized Program Facility (APF).
• To delete and define HALDB data sets by specifying this DD statement, the input unloaded data set must be created by the IPR Unload utility with the CHECKREC=YES option. The unloaded data set must not be concatenated.

RECONx DD

This statement provides RECON1, RECON2, and RECON3 DD statements under the same conditions as for standard IMS jobs. If RECON data sets are allocated dynamically, do not specify these DD statements.

IBM® recommends that you use the IPR Reload utility to allocate these data sets dynamically.

database DD

Defines the database data set to be reorganized. You need one statement for each data set that appears in the DBD that describes this database. The ddname must match the ddname in the DBD.

For a HIDAM database, DD statements must also exist for the data sets that represent the index. The DD statements that relate to the index must contain ddnames specified in the DBD for the index database. No DD statements are required for whatever secondary indexes that might be associated with this database.

For a HISAM database, DD statements must exist for both the primary data set (KSDS) and the overflow (ESDS) data sets. The DD name for primary and the overflow data sets must be the same as the ddname in the DBD that was referenced when this data set was unloaded.

This data set must reside on a direct-access device.

For VSAM database data sets, the SPEED option for DEFINE CLUSTER is strongly recommended. The SPEED option improves performance of the IPR Reload utility.

The IPR Reload utility optimizes the buffer specification for the database data set by itself. You do not need to specify the AMP= parameter or the DCB=(NCP=) parameter for the DD statement.

Note: If you use dynamic allocation, do not use the DD statement for the database data sets.

For HALDBs, no DD statements are necessary for any database data set because the data sets are always dynamically allocated.

DFSURWF1 DD

Describes the work data set to be created during reload. The data set is used as input to the following utilities to resolve logical or secondary index relationships:

• IMS Index Builder
• IBM IMS HP Prefix Resolution
• IMS Database Prefix Resolution utility

This DD statement is required if at least one of the following conditions are met:

• The database is HDAM, HIDAM, or HISAM and it has logical relationship.
• The database has a secondary index and INDEXBLD=NO is specified, but the HPSRSIDX DD statement is not coded.

In these cases, if WF1REC=NO is specified, you can omit the DD statement. In other cases, the DD statement is not required.

Notes:

1. If WF1REC=NO is specified, you can omit this DD statement. If the preceding condition is not met, this DD statement is not required.
2. If you omit the DFSURWF1 DD statement and specify the WF1DSN statement, IPR Reload allocates the DFSURWF1 data set dynamically. You can specify the attributes of the data set by using the WF1SPACE, WF1UNIT, and WF1VOL statements.

You can specify DUMMY if the database being reloaded is neither involved in a logical relationship nor with a secondary index.

If the HPSRSIDX DD statement is specified, this data set contains all updated data for segments involved in logical relationships, which is used as input to utilities to resolve logical relationships.

The DCB parameters for the DD statement must include RECFM=VB and BLKSIZE. The specification must be the same as that for the work data set of the user's initial load program or for the Database Scan utility (DFSURGS0). A value of LRECL=900 is recommended, but a smaller value (as small as 300) can be used if no secondary indexes are present or if HPSRSIDX DD statement is specified.

The data set must reside on either a tape or a direct-access device.

HPSRPnnn DD

Describes the WFP work data sets. WFP data sets are work data sets that can be used by Index Builder to rebuild partitioned secondary indexes (PSINDEXes). These data sets are created while the IPR Reload utility reloads HALDB partitions. One work data set is created for each HALDB partition.

If you want the IPR Reload utility to dynamically allocate WFP data sets, omit this DD statement.

For nnn, specify a 3-digit decimal number in the range of 001 - 999. The value can also be T00 or T01. T01 represents 1000, and T01 represents 1001. If you designate the IPR Reload utility to dynamically allocate the WFP data sets, the IPR Reload utility uses sequence numbers for nnn.

The data sets must reside on a direct-access device.

Create WFP data sets when all of the following conditions are met:

• The database has PSINDEXes.
• You want to rebuild the PSINDEXes by using IMS Index Builder in a subsequent job step or in another job.
• You want to avoid scanning the database while rebuilding indexes with IMS Index Builder.

If you are not sure whether the HALDB database contains empty partitions, use the unloaded data set that is created by the IPR Unload utility with the CHECKREC=YES option. Otherwise, WFP data sets are not created for the empty partitions.

Naming convention for WFP data sets

If you specify the names of WFP data sets by using HPSRPnnn DD statements, ensure that the data set names on the DSN parameters conform to the following naming convention.

The prefix for the WFP data sets is specified by the WFPHLQ control statement. For each HPSRPnnn DD statement specified, specify the data set name as follows:

DSN=WFPHLQ_value.partition_name.WFP

For example, if you specify WFPHLQ=IMSTOOLS.WORK.HMPORDP1 to define the prefix, and if you specify HPSRP001 and HPSRP002 DD statements for partitions that are named PART001 and PART002, the DSN parameters for the WFP data sets must be specified as follows:

DSN=IMSTOOLS.WORK.HMPORDB1.PART001.WFP
DSN=IMSTOOLS.WORK.HMPORDB1.PART002.WFP

If you do not specify the HPSRPnnn DD statement, the IPR Reload utility allocates the data sets dynamically by using the values summarized in the following table.

Table 2. Dynamic allocation parameters used for WFP data sets

Parameter	Value	Description
DDN	HPSRPnnn	nnn: Sequence number
DSN	hlq.partition_name.WFP	hlq: The value that is specified on the WFPHLQ control statement partition_name: The partition name of the primary database WFP: Fixed value
DISP	NEW,CATLG,DELETE
UNIT	unit_name	The value that is specified on the WFPUNIT control statement. If the control statement is not specified, SYSALLDA is used.
SPACE	{(TRK, or CYL), primary_alloc, secondary_alloc,RLSE}	The value that is specified on the WFPSPACE control statement. If the control statement is not specified, the region size is estimated based on the allocation size of the partition data set.
RECFM	FB
LRECL	7250
VOL=SER	volume_name or *	The value that is specified on the WFPVOL control statement. If the control statement is not specified, the VOLUME parameter for the DYNALLOC macro is not set.
DSNTYPE	LARGE

When the IPR Reload utility attempts to dynamically allocate a WFP data set and if the WFP data set already exists with the intended data set name, the IPR Reload utility deletes the existing data set and creates the data set with the same name.

HPSRSIDX DD

Defines an optional output work data set. If it is specified and secondary indexes are present in the DBDs being processed, the data set is used as input to utilities to resolve secondary index relationships. The use of this data set increases the performance of utilities to resolve secondary index because it has fewer records to read. DCB parameters specified within this program are RECFM=VB and LRECL=900. BLKSIZE must be provided on the HPSRSIDX DD statement. The data set must reside on either a tape or a direct-access device. This DD statement is not required if the database has no secondary index or INDEXBLD=YES is specified.

OVERFLOW DD

Defines an optional sequential data set that is used as a temporary storage to keep database blocks that are directed to the overflow area during HDAM RAA reloading. Such blocks are written into the overflow area after RAA reloading is completed. This data set is used only when both OADSPR=Y and HPIO=N are specified. The SPACE parameter for the DD statement must be large enough to hold all CIs or blocks in the overflow area. The DCB parameters must include RECFM=VB. This data set must reside on either a tape or a direct-access device. If both OADSPR=Y and HPIO=N are specified and this DD statement is not specified, the IPR Reload utility attempts to allocate dynamically on a direct-access device the value calculated internally according to the following method.

Method of calculating size for dynamic allocation: The number of database blocks directed to the overflow area during HDAM RAA reloading cannot be estimated in advance. For optimization, the IPR Reload utility calculates the cylinders for OVERFLOW DD, which can be 25% of RAA cylinders. The IPR Reload utility uses the same value to calculate both primary and secondary values. If the calculated value is fewer than 10 cylinders, 10 cylinders are used.

The way to maintain the blocks in OVERFLOW DD is different from the one in an actual database data set, so the number of cylinders for the OVERFLOW DD is not directly comparable with the 25% of RAA cylinders.

For calculation, the IPR Reload utility uses the 3390 device type geometry regardless of the actual device type of OVERFLOW DD because the device type cannot be known before allocation. If a 3380 or a 9345 DASD is used, for example, the effective percentage of RAA of the allocation amount is a little smaller, and will be approximately 20%.

However, there is no formula to estimate the space requirement for OVERFLOW DD beforehand. The size of OVERFLOW DD depends on the amount of segments that is to be directed to the overflow part of the database. But the size equal to the overflow part of the original database is enough, until you change the DBD definition or the randomizer.

SORTWKnn DD

These are intermediate storage data sets that are used by DFSORT. If SORT=YES or SORTHIDAM=YES is specified, you can define these data sets and adjust the size of workspace that is used for the sort process. You can specify multiple data sets, 'nn' showing its serial number. This specification is optional. If you do not specify the SORTWKnn DD statements, these data sets are dynamically allocated by DFSORT.

• For a (P)HDAM database, the size is estimated based on the size of RAA.
• For a HIDAM database, the size is estimated based on the primary allocation size of the primary data set group of the HIDAM database.
• For a PHIDAM database, the size is estimated based on the number of partitions.

If the number of unloaded records is provided by the RECNUM statement, this value supersedes other values and is used for estimation.

HPSRISMG DD

This optional output data set contains messages issued by DFSORT. This data set is used only when ILDSBLD=YES,DSPR is specified. If the DD statement is omitted, the data set is allocated dynamically.

HPSRILEA DD

HPSRILEB DD

These data sets are used by DFSORT, as substitute for SORTIN data sets, when ILDSBLD=YES,DSPR is specified. If you do not specify the statement, the data sets are allocated dynamically with sizes estimated based on the allocation size of ILDS.

To avoid space shortage problems that might be caused by extension of the data sets, the size estimation is adjusted as follows:

• If the high used RBA of ILDS is greater than the primary space amount, the equivalent amount is specified as the primary space amount.
• If the secondary space amount is less than 1/5 of the high used RBA of ILDS, the equivalent amount is specified as the secondary space amount.
• If the primary or secondary space amount of ILDS is less than 100 cylinders, 100 cylinder is used as the space amount.
• The data set is allocated with volume count so that it can be extended on up to 10 volumes.

You can specify the data class and the storage class for HPSRILEA and HPSRILEB by using ILEDATAC and ILESTORC control statements.

A dummy data set or the DISP=MOD parameter cannot be specified on the HPSRILEA DD or HPSRILEB DD statement.

For more information about SORTIN data sets, see the DFSORT Application Programming Guide.

HPSRWKnn DD

These data sets are used by DFSORT, as substitute for SORTWK data sets, when ILDSBLD=YES,DSPR is specified. nn shows its serial number. If you do not specify the statement, the data sets are allocated dynamically by DFSORT.

For more information, see DFSORT Application Programming Guide.

SEQERROR DD

Defines a sequential output data set in which segment data in key sequence error is to be kept. This data set is required only if SEQERROR=SAVE is specified. This data set saves segments in key sequence error and their hierarchical dependent segments. If the DCB parameter is specified on the DD statement, the record format VB (RECFM=VB) is required. Do not specify the logical record length or the block size of the data set.

HPSOUT DD

Defines the basic statistics output data set. The data set can reside on a tape, a direct-access device, or it can be routed through the output stream.

HPSRAMSO DD

Defines the output data set for the Result of Database Data Set Allocation report. The data set can reside on a tape, a direct-access device, or it can be routed through the output stream. If the DD statement is not coded, it is dynamically allocated to the SYSOUT stream of the output class that is specified by the MSGCLASS parameter on the JOB statement.

HPSSNAP DD

Defines a snap dump data set. It contains printed dumps of the DBD for user reference. The snap dump is activated with the DBDSNAP=YES specification in the HPSIN data set. The DUMMY statement can be specified if no snap dump is required.

SYSUDUMP DD

Defines a dump data set. Most errors encountered ends the IPR Reload utility by issuing an ABEND macro with the DUMP operand. Only a SYSUDUMP DD statement is needed. The SYSABEND DD statement is not required.

Notes:

1. The DFSCTL data set of the IMS version is not supported.
2. Any DD name that starts with SYS, DFS, HPS, or FAB is reserved for system use.

The IPR Reload utility uses a performance default of the access method buffer number for each input and output data set. The summary of the default values is shown in the following table.