JCL requirements

EXEC and DD statements

The following table summarizes DD statements. Explanations of JCL parameters follow the table.

Table 1. DD statements and record format for IMS HP Load

DDNAME	Use	Format	Need
STEPLIB	Input		Required (Note 1)
IMSDALIB	Input	Same as that used in the IMS control region startup JCL stream	Optional
IMS	Input		Optional
PROCLIB	Input		Optional
DFSACBPD	Input	LRECL=80	Optional
SYSIN	Input	LRECL=80	Optional
DFSRESLB	Input		Optional
DFSUINPT	Input	(Note 2)	Required
DFSURCDS	Input	LRECL=1600	Optional
DFSVSAMP	Input	LRECL=80	Optional
FRRIN	Input	LRECL=80	Optional
DDEFPDS	Input	RECFM=FB LRECL=80	Optional
RECONx	Input/Output		Optional for Non-HALDB Required for HALDB
database	Output	(Note 2)	Optional (Note 3)
DFSURWF1	Output	RECFM=VB LRECL=900	Optional
HPSRPnnn	Output	RECFM=FB, LRECL=7250	Optional (Note 4)
HPSRSIDX	Output	RECFM=VB LRECL=900	Optional
OVERFLOW	Input/Output	RECFM=VB (Note 2)	Optional
HPSRISMG	Output	LRECL=133	Optional
SEQERROR	Output	RECFM=VB	Optional (Note 5)
SYSPRINT	Output	LRECL=81	Required
HPSRAMSO	Output	LRECL=133	Optional
SNAP	Output	LRECL=133	Optional
SYSUDUMP	Output	LRECL=133	Optional
SORTWKnn	Input/Output		Optional
HPSRILEA	Input/Output		Optional
HPSRILEB	Input/Output		Optional
HPSRWKnn	Input/Output		Optional
Notes: When you specify HPIO=YES or when you delete and define database data sets by specifying the DDEFPDS DD statement, the load module library of STEPLIB must be authorized through the Authorized Program Facility (APF). Large format data set can be specified. If you use dynamic allocation, do not use the DD statements for these data sets. HPSRPnnn DD statements are effective only when the WFPHLQ control statement is specified. This data set is required only if the SEQERROR=SAVE control statement is specified.

EXEC

Must be in the following form:

//name EXEC  PGM=HPSRRC00,PARM=’ULU,DFSURGL0,dbdname’

dbdname is the name of the DBD that includes the database to be reloaded. The general IMS positional parameters, such as DBRC and SWAP, can follow the dbdname.

To reload a HALDB, you must set DBRC=Y.

If you do not use the functions that require authorization for the STEPLIB DD (for example, HPIO, COMPAUTH, and DDEFPDS), you can specify DFSRRC00 as follows:

//name  EXEC  PGM=DFSRRC00,PARM=’ULU,DFSURGL0,dbdname’

To reload a database in an IMS-managed ACBs environment, either modify the EXEC statement or the STEPLIB DD statement as follows:

• Specify an additional EXEC parameter, DFSDF, as shown in the following example:

  //name EXEC PGM=HPSRRC00,PARM=(ULU,DFSURGL0,dbdname, 
  //       ,,,,,,,,,,Y,N,,,,,,,,,,,,'DFSDF=CAT') 
  

  Replace the 3-character suffix CAT with the suffix of the DFSDFxxx member that enables IMS-managed ACBs.

• Place the IMS Catalog Definition exit routine (DFS3CDX0) in the STEPLIB DD concatenation.

With either method, you must allocate the catalog partition definition data set when reloading a database with DBRC=NO. To do so, add the DFSHDBSC DD statement or the DFSMDA member with the TYPE=CATDBDEF statement.

To reload an IMS catalog database that is not registered to the RECON data set, either modify the EXEC statement or the STEPLIB DD statement as follows:

• Specify an additional EXEC parameter, DFSDF, as shown in the following example:

  //name     EXEC PGM=HPSRRC00,PARM=(ULU,DFSURGL0,DFSCD000, 
  //           ,,,,,,,,,,N,N,,,,,,,,,,,,'DFSDF=CAT')

  Replace the 3-character suffix CAT with the suffix of the DFSDFxxx member that specifies the unregistered IMS catalog database name.
• Place the IMS Catalog Definition exit routine (DFS3CDX0) in the STEPLIB DD concatenation.

With either method, you must allocate the catalog partition definition data set. To do so, add the DFSHDBSC DD statement or the DFSMDA member with the TYPE=CATDBDEF statement.

STEPLIB DD

Points to two library data sets that must be in the following order:

//STEPLIB  DD    DISP=SHR,DSNAME=pgmlib
           DD    DISP=SHR,DSNAME=IMSESA.RESLIB

pgmlib is the name of the library that contains the load module of IMS HP Load. IMSESA.RESLIB is the name of the library that contains the load modules of IMS.

To reload a database in an IMS-managed ACBs environment or offload eligible workloads to zIIP processors, the name of the SGLXLOAD library of IMS Tools Base must also be specified on the STEPLIB DD statement.

If you specify HPIO=YES, ZIIPMODE=COND, COMPAUTH=YES, or DDEFPDS DD, the load module libraries that are specified on the STEPLIB DD must be APF-authorized.

IMSDALIB DD

Specifies a partitioned data set or data sets that contain the dynamic allocation members for the database, index, and the RECON data sets.

Allocation of the database, index, and the RECON data sets are attempted in the following order:

1. DD statements that are 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 are used instead of the IMSDALIB DD statement.

IMS DD

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

If the IMS management of ACBs is enabled, the IMS DD statement is ignored.

PROCLIB DD

Points to the IMS.PROCLIB data set.

If you specify DFSDF=xxx in the EXEC statement, you must also specify this DD statement, and the DFSDFxxx member must exist 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 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, IMS HP Load 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.

SYSIN DD

Specifies the STAGING keyword to obtain the pending ACBs from the IMS catalog staging data set before they are activated. The STAGING keyword can either be specified with this DD statement or with the DFSACBPD DD statement.

DFSRESLB DD

Points to an authorized library that contains IMS SVC modules. For an IMS HP Load job, IMSESA.RESLIB and any data set that is concatenated to it on the DFSRESLB DD statement must be authorized through the Authorized Program Facility (APF). If you do not specify IMSESA.RESLIB in the STEPLIB DD statement or if a library that is concatenated to the STEPLIB DD statement is not APF-authorized, the DFSRESLB DD statement is needed.

For more information, see IMS System Definition.

DFSUINPT DD

Describes the input data set that contains the data to be reloaded. This data set must be created by the unload utilities of IMS High Performance Unload or an equivalent utility. The data set must reside either on a tape or a direct-access device.

DFSURCDS DD

Defines the control data set for this program. The data set must be the output that is generated by the IMS Database Prereorganization utility (DFSURPR0).

This DD statement is applicable only for logical relationships and must be included if logical relationships exist.

This data set must reside either on 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. For more information about the control statement format, see IMS Database Administration.

Notes:

• If the DFSVSAMP DD statement is omitted, the DL/I Buffer Pool is not allocated.
• You must specify the DFSVSAMP DD statement when you reload a HALDB or when you use DL/I calls in the user exit routine.

FRRIN DD

Defines the optional data set that contains control statements that specify optional functions of IMS HP Load.

DDEFPDS DD

Defines the optional data set that contains the IDCAMS commands for deleting and defining the database data sets to be processed by IMS HP Load. IMS HP Load 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).
• Program HPSRRC00 must be specified on the EXEC statement.
• To delete and define HALDB data sets by specifying this DD statement, the input unloaded data set must be created by IMS HP Unload with the CHECKREC=YES option. The unloaded data set must not be concatenated.

RECON1 DD

Defines the first Data Base Recovery Control (DBRC) RECON data set.

RECON2 DD

Defines the second DBRC RECON data set.

RECON3 DD

Defines the optional DBRC RECON data set that is 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.

Restriction: If you use dynamic allocation, do not specify these RECON data set DD statements.

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 an 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 any secondary indexes that are 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 names for primary and the overflow data sets must be the same as the ddnames in the DBD that was referred to when this data set was unloaded.

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

Recommendation: For VSAM database data sets, the SPEED option for DEFINE CLUSTER is strongly recommended. The SPEED option improves the performance of IMS HP Load.

IMS HP Load 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.

Restriction: If you use dynamic allocation, do not specify the DD statements for the database data sets.

For HALDBs, no database DD statements are necessary for any database data sets 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
• IMS High Performance Prefix Resolution
• IMS Database Prefix Resolution utility

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

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

Notes:

• If WF1REC=NO is specified, you can omit this DD statement. If the preceding condition is not met, this DD statement is not required.
• If you omit the DFSURWF1 DD statement and specify the WF1DSN statement, IMS HP Load allocates the DFSURWF1 data set dynamically. You can specify the attributes of the data set by using WF1SPACE, WF1UNIT, and WF1VOLUME statements.

If HPSRSIDX DD is specified, only the records of logical relationships are written to this data set, and it can be used as an input for utilities to resolve logical relationships.

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

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 the default and recommended, but a smaller value (as small as 300) can be used if no secondary indexes are present or if HPSRSIDX DD is specified.

The data set must reside either on 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 partition secondary indexes (PSINDEXes). These data sets are created while IMS HP Load reloads HALDB partitions. One work data set is created for each HALDB partition.

If you want IMS HP Load to dynamically allocate WFP data sets, omit this DD statement.

For nnn, specify a 3-digit decimal number from 001 to 999. The value can also be T00 or T01. T01 represents 1000, and T01 represents 1001. If you designate IMS HP Load to dynamically allocate the WFP data sets, IMS HP Load 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 are going to rebuild 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 IMS HP Unload 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 this statement, IMS HP Load allocates the data sets dynamically by using the values summarized in the following table.

Table 2. DYNALLOC parameters for dynamically allocating 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 IMS HP Load attempts to dynamically allocate a WFP data set and if the WFP data set already exists with the intended data set name, IMS HP Load deletes the existing data set and creates the data set with the same name.

HPSRSIDX DD

Defines the 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 relationships 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 necessary if the database has no secondary index or INDEXBLD=YES is specified for the IPR Driver.

OVERFLOW DD

Defines the 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, IMS HP Load attempts to allocate it dynamically on a direct-access device using the value calculated internally with the following method.

Method for calculating the 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, IMS HP Load calculates the cylinders for OVERFLOW DD, which can be 25% of RAA cylinders. IMS HP Load uses the same value to calculate both primary and secondary values. If the calculated value is less 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, IMS HP Load uses the 3390 device type geometry regardless of the actual device type of OVERFLOW DD because the device type cannot be known prior to 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 number 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.

HPSRISMG DD

This optional output data set contains the messages that are 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.

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, the record format VB (RECFM=VB) is required. Do not specify the logical record length or the block size of the data set.

SYSPRINT DD

Defines the statistics output data set. The data set can reside on a tape or 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 this DD statement is not coded, the data set is dynamically allocated to the SYSOUT stream of the output class that is specified by the MSGCLASS parameter on the JOB statement.

SNAP DD

Defines a snap dump data set. It contains printed dumps of the DBD for your reference. The snap dump is activated by the DBDSNAP=YES specification in the FRRIN data set. If no snap dump is required, the DUMMY statement can be specified.

SYSUDUMP DD

Defines a dump data set. Most errors encountered end the IMS HP Load job by issuing an ABEND macro with the DUMP operand. Only a SYSUDUMP DD is needed. The SYSABEND DD statement is not required.

SORTWKnn DD

These data sets are intermediate storage data sets used by DFSORT. If SORT=YES or SORTHIDAM=YES is specified, you can define these data sets and adjust the size of work space 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 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 will be used for estimation.

If the estimated size is extremely large or extremely small, specify SORTWKnn DD explicitly.

For more information about how to code SORTWKnn DD statements, see the DFSORT Application Programming Guide.

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 on the basis of 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 data sets by using ILEDATAC and ILESTORC control statements.

A dummy data set or the DISP=MOD parameter cannot be specified for the HPSRILEA DD and the HPSRILEB DD statements.

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. Here, nn is its serial number. If you do not specify the statement, the data sets are allocated dynamically by DFSORT.

For more information, see the DFSORT Application Programming Guide.

Default values for the data set access method buffer

IMS HP Load uses a performance default of the access method buffer number for each input and output data set. The following table lists the default values.