DD statements for the Build Index function

List of DD statements

The following table summarizes the DD statements for the Build Index function.

Input DD statements

The following input DD statements are used for the Build Index function.

JOBLIB/STEPLIB DD

This DD statement is a required DD statement that defines the following input data sets:

• The FPA load module library (required).
• The library that contains DFSMDA dynamic allocation members for the RECON data set. When DBRC=YES is specified and the RECONn DD statement is omitted, this DD statement is required.
• The library that contains a default site default member (HFPCSITE) to determine the data set name and the member of the site default table.
• The IMS load module library (required).
• The library that contains the user-defined data entry database partition selection exit routine that was specified on the XDFLD PSELRTN= parameter during DBD generation for the DEDB.
• The library that contains the secondary index database maintenance exit routine that was specified on the XDFLD EXTRTN= parameter during DBD generation for the DEDB.
• The IMS Tools Base library (SHKTLOAD), if you specify the ITKBSRVR keyword.
• The IMS Tools Base library (SGLXLOAD), if you specify the IMSCATHLQ keyword.
• The IMS Library Integrity Utilities library, if you want to activate Integrity Checker.

FPA must be run as an APF-authorized program. All the data sets that are listed within the JOBLIB or the STEPLIB concatenation must also be APF-authorized. If you use DFSMDA members and the DFSMDA members are in a non-APF authorized library, you can specify the DFSMDA library on the IMSDALIB DD statement.

For more information about user-defined data entry database partition selection exit routines and secondary index database maintenance exit routines, see IMS Exit Routines.

IMSACB DD

This DD statement is an optional DD statement that defines the library that contains the DMB for the database. The IMSACB DD statements (IMSACB, IMSACBA, IMSACBB, MODSTAT, MODSTAT2, and OLCSTAT) can be used to identify the active ACB library. When both OLCSTAT or MODSTAT and MODSTAT2 are found, FPA checks the time stamp and determines the latest one.

The active IMSACB library is determined according to the following rules:

1. Check IMSACB DD statement in the JCL statement.
2. Check OLCSTAT DD statement in the JCL statement.
3. Check MODSTAT and MODSTAT2 DD statement in the JCL statement.
4. Allocate OLCSTAT dynamically and check the OLCSTAT member.
5. Allocate MODSTAT and MODSTAT2 dynamically and check the MODSTAT and MODSTAT2 members.

If you specify the IMSCATHLQ keyword, IMSACB DD statements are not used. The IMS directory is used instead of the ACB library.

IMSACBA DD

This DD statement is an optional DD statement that defines the library that contains the DMB for the database. This statement must be provided if MODSTAT and MODSTAT2, or the OLCSTAT DD statement is specified.

IMSACBB DD

This DD statement is an optional DD statement that defines the library that contains the DMB for the database. This statement must be provided if MODSTAT and MODSTAT2, or the OLCSTAT DD statement is specified.

IMSDALIB DD

This DD statement is an optional DD statement that defines the IMSDALIB data set. This DD statement is useful when the data set for dynamic allocation members is not APF-authorized.

MODSTAT DD

This DD statement is an optional DD statement that defines the MODSTAT data set. When this statement is specified, the IMSACBA and IMSACBB DD statements must be specified instead of the ACBLIB DD statement.

Note on dynamic allocation:

If this statement is not specified in the JCL statements when the data set is required, the data set is allocated dynamically by using a DFSMDA member. You can build the DFSMDA member for the MODSTAT library by using a TYPE=DATABASE statement of the DFSMDA macro.

MODSTAT2 DD

This DD statement is an optional DD statement that defines the MODSTAT2 data set. When this statement is specified, the IMSACBA and IMSACBB DD statements must be specified instead of the ACBLIB DD statement.

Note on dynamic allocation:

If this statement is not specified in the JCL statements when the data set is required, the data set is allocated dynamically by using a DFSMDA member. You can build the DFSMDA member for the MODSTAT2 library by using a TYPE=DATABASE statement of the DFSMDA macro.

OLCSTAT DD

This DD statement is an optional DD statement that defines the OLCSTAT data set. When this statement is specified, the IMSACBA and IMSACBB DD statements must be specified instead of the ACBLIB DD statement.

Note on dynamic allocation:

If this statement is not specified in the JCL statements when the data set is required, the data set is allocated dynamically by using a DFSMDA member. You can build the DFSMDA member for the OLCSTAT library by using a TYPE=DATABASE statement of the DFSMDA macro.

IMS DD

This DD statement is required when DBRC=YES is specified for the GLOBAL command. This statement defines the library that contains the DBD that describes the secondary index databases. This statement is used when the NOTIFY.REORG command is issued to DBRC.

If you specify the IMSCATHLQ keyword, IMS DD statement is not used. The IMS directory is used instead of the library that contains the DBD.

IMSRESLB DD

This DD statement is an optional DD statement that defines the libraries that contain the randomizer routines, compression routines, user-defined data entry database partition selection exit routine and secondary index database maintenance exit routine that are specified in the ACB member (specified by the IMSACB DD statements). If the IMSRESLB DD statement is specified in the JCL statement, only the randomizer and compression routines are loaded directly from the IMSRESLB DD statement. If the IMSRESLB DD statement is not specified in the JCL statement, these resources are loaded from the JOBLIB or the STEPLIB DD statement.

The IMS version of IMSRESLB DD statement must be the same as those of IMSACB DD.

All the data sets that are listed within the IMSRESLB concatenation must be APF-authorized.

addnname/areaname DD

This DD statement is a required DD statement that defines an input data set, which is the VSAM ESDS or image copy for an area to be processed. The ddname used must be the ddname for the area that is defined in the input ACB library (IMSACB DD). There can be multiple addnname DD statements for each area included in the process request.

The input data set can that is used by FPA is determined by the following elements:

• The IDSNMASK keyword parameter of the INDEXBLD command
• When the GLOBAL DBRC=YES option is specified, the ADS information in the DBRC RECON data sets (only for VSAM ESDS data sets)
• The area name member in the IMS DFSMDA library (only for VSAM ESDS data sets)

Or it can be specified with one of the following DD statements explicitly:

• //addnname DD JCL statement
• //areaname DD JCL statement

If an area data set is used for the INDEXBLD command input, it must be error free (that is, it has no EQEs). And if the area is registered with DBRC, the data set must have no EEQEs.

The following figure shows how FPA determines area data set names.

HFPSYSIN DD

This DD statement is a required DD statement that defines the input control statement that specifies the FPA functions.

The HFPSYSIN DD statement can be coded as a standard SYSIN file, a sequential data set, or a PDS member. LRECL=80 is required for the DCB of this data set. Only one command, besides the GLOBAL command, can be specified in HFPSYSIN. FPA analyzes the command syntax in columns 1 - 72. Columns 73 - 80 are regarded as comment.

For details about coding the HFPSYSIN DD statement, see Utility control statements for the Build Index function.

HFPCSITE DD

This DD statement is an optional DD statement. The HFPCSITE DD statement can be used to define the data set name of the site default table. When the SITE_DSNAME keyword is specified in the HFPSYSIN DD statement, the HFPCSITE DD statement is allocated dynamically. HFPCSITE DD in the JCL is mutually exclusive with the SITE_DSNAME keyword in the HFPSYSIN DD statement. The data set attribute of HFPCSITE DD is PDS.

Output DD statements

The following output DD statements are used for the Build Index function.

index DD

This DD statement is a required output DD statement when DFSMDA members for index databases are not used. This DD statement defines the VSAM KSDS data set to be loaded.

The DD name must be the DD name for the secondary index database that is defined in the input ACB library (IMSACB DD). Multiple index DD statements can be specified for each secondary index database that is built by the Build Index function.

The output data set that is used by FPA is determined by the following elements:

• The name of the secondary index database member in the IMS DFSMDA library
• The index DD JCL statement

indexovrflw DD

This DD statement is a required output DD statement when DFSMDA members for index databases are not used. This DD statement defines the VSAM ESDS data set to be loaded.

The DD name must be the DD name for the secondary index database that is defined in the input ACB library (IMSACB DD). Multiple indexovrflw DD statements can be specified for each secondary index database that is built by the Build Index function.

The output data set that is used by FPA is determined by the following elements:

• The name of the secondary index database member in the IMS DFSMDA library
• The indexovrflw DD JCL statement

The following figure shows how FPA determines data set names for secondary index databases.

HFPPRINT DD

This DD statement is an optional DD statement that defines the processing log output data set. The data set contains the processing messages that are issued by FPA.

The following DCB attributes of the file are set by the FPA main task:

• RECFM=FBA
• LRECL=133
• BLKSIZE=1330

Do not code the DCB information in your JCL statement. The output data set must be a standard SYSOUT or a sequential data set. You cannot specify DUMMY.

The HFPPRINT data set contains 133-byte, fixed-length records. It is recommended that you code your DD statement as follows:

//HFPPRINT DD SYSOUT=A

Note on dynamic allocation:

When this statement is not specified in the JCL statements, FPA dynamically allocates the data set by using SYSOUT=*.

The following figure shows an example of the processing messages that are issued for the INDEXBLD command.

IMS HPFP UTILITIES                                        "Processing messages"                                        PAGE:       1
5698-FPP V2R1                                                                                                    2021-11-22 13:03:37
HFPC0001I COMMAND ANALYZE PROCESSING STARTED.
HFPC0005I DBRC=NO IS SPECIFIED.
          - EEQE DETECTION IS NOT PERFORMED.
HFPF0001I INDEXBLD PROCESSING STARTED FOR DATABASE: DEDBJN23                           
HFPB0001I INDEXBLD SCAN PROCESSING STARTED FOR AREA NO: 1, AREANAME: DB23AR0           
HFPB0002I INDEXBLD SCAN PROCESSING COMPLETED FOR AREA NO: 1, AREANAME: DB23AR0         
HFPB0003I INDEXBLD LOAD PROCESSING STARTED FOR SECONDARY INDEX DBDNAME: ITHISM02       
HFPB0004I INDEXBLD LOAD PROCESSING COMPLETED FOR SECONDARY INDEX DBDNAME: ITHISM02     
HFPF0002I INDEXBLD PROCESSING COMPLETED FOR DATABASE: DEDBJN23                         
HFPL0001I REPORT STARTED FOR COMMAND: INDEXBLD, DATABASE: DEDBJN23                     
HFPL0002I REPORT COMPLETED FOR COMMAND: INDEXBLD, DATABASE: DEDBJN23 

HFPRPTS DD

This DD statement is an optional DD statement that defines the report output data set. The data set contains the reports that can be used to verify the process of the command. The following DCB attributes of the file are set by the FPA main task:

• RECFM=FBA
• LRECL=133
• BLKSIZE=1330

Do not code the DCB information in your JCL statement. The output data set must be a standard SYSOUT or a sequential data set.

The following reports are generated in this data set:

• Audit report
• Processing report
• DBD Definition report
• Secondary Index Definition report
• Secondary Index Processing report
• Secondary Index Duplicate Key report (when duplicate keys are found)

The HFPRPTS data set contains 133-byte, fixed-length records. It is recommended that you code your DD statement as follows:

//HFPRPTS DD SYSOUT=A

Note on dynamic allocation:

When this statement is not specified in the JCL statements, FPA dynamically allocates the data set by using SYSOUT=*.

HFPABEND DD

This DD statement is an optional DD statement. It defines a snap dump output data set that is used for diagnostic purposes. This data set might be used when the FPA job ends abnormally. Do not code the DCB information in your JCL statement. The output data set must be a standard SYSOUT or a sequential data set.

Note on dynamic allocation:

When this statement is not specified in the JCL statements, FPA dynamically allocates the data set by using SYSOUT=*.

UtttSMSG DD

This DD statement is an optional DD statement. However, this DD statement is required when DFSORT is used. This statement defines an output data set for storing DFSORT messages. For the condition for running DFSORT and the naming rules for the DD names, see the description of UtttWKnn DD.

Note on dynamic allocation:

When this statement is not specified in the JCL statements, FPA dynamically allocates the data set by using SYSOUT=*.

S0nnnnnR DD

These DD statements are optional DD statements. They point to the duplicate pointer segment record data sets, which are the output data sets for storing duplicate pointer segment records.

The DD statements are used only when you request to save duplicate pointer segment records (DUPKEYACT=SAVE) and the duplicate keys are found while building the secondary index databases.

nnnnn is a sequential number that FPA assigns to each secondary index database. FPA assigns a sequential number in the order the secondary index databases appear on the LCHILD statements in the DBDGEN source. The value can be in the range of 00001 - 25755.

These data sets can be allocated dynamically by one of the following methods:

• The DSNAME keyword parameter of the FILECTL subcommand
• The DUPKEYDSNMASK keyword parameter of the INDEXBLD command

Input/Output DD statements

The following input/output DD statements are used for the Build Index function.

RECON1/RECON2/RECON3 DD

These statements define the DBRC RECON data sets. These DD statements are required DD statements when both of the following conditions are met:

• DBRC=YES is specified for the GLOBAL command
• DFSMDA members for RECONn data sets are not used

The RECONn data set must be the same data set that is used in the IMS control region. Because FPA issues a signon, a signoff, an authorization call, and an unauthorization call to DBRC, it updates RECONn data sets.

Note on dynamic allocation:

If this statement is not specified in the JCL statements when the data set is necessary, the data set is allocated dynamically by using a DFSMDA member.

UtttWKnn

These DD statements are optional DD statements. These are intermediate storage data sets that are used by DFSORT. For more information about coding the SORTWKnn DD statements, see DFSORT Application Programming Guide.

The adequate size of storage data sets is 1.5 to 2 times the input file size. In the Build Index function, the input file is the pointer segments that are put into the secondary index database. The size of the file is computed by multiplying the length of the pointer segments that are put into the secondary index database by the number of pointer segments. Allocating twice the space used by the SORTIN data set is usually adequate for each work data set. This data set is allocated dynamically by OS. When the SORTIN is too large for sort, a B37 abend occurs. In this case, this is a required DD.

Do not specify DISP=MOD for these DD statements.

The naming rules of the ddnames are as follows:

ttt:

The hundredths, tenths, and units digits of n for n-th output thread subtask

Note: When a subtask ends processing a secondary index database, it starts processing the next secondary index database. For this reason, the n-th output thread subtask does not always process the n-th output data set.

nn:

Specifies the number of the SORT work data sets. This value must be in the range of 01 - 03.

Note on dynamic allocation:

If this statement is not specified in the JCL statement when these data sets are necessary, FPA allocates them dynamically.

S0nnnnn0 DD

These DD statements are optional DD statements. They point to the build pointer segment record data sets that store build pointer segment records.

• In scan mode, these statements define the output data sets for generating build pointer segment records.
• In load mode, these statements define the input data sets that contain the generated build pointer segment records.
• In scan load mode, these statements define the intermediate work data sets for storing pointer segments until the segments are loaded to the secondary index databases.

nnnnn is a sequential number that FPA assigns to each secondary index database. FPA assigns a sequential number in the order the secondary index databases appear on the LCHILD statements in the DBDGEN source. The value can be in the range of 00001 - 25755.

If the symbolic variable &IDXGRP is specified on the DSNAME keyword of the BLDMFILECTL subcommand or the BUILDDSNMASK keyword of the INDEXBUILD command, FPA generates a build pointer segment record data set for each index instead of for each partition. FPA assigns a sequential number only to the first secondary index database in a partition group, in the order it appears on the LCHILD statements in the DBDGEN source. The value can be in the range of 00001 - 25755.

These data sets can be allocated dynamically by one of the following methods:

• The BUILDDSNMASK keyword parameter of the INDEXBLD command
• The DSNAME keyword parameter of the BLDMFILECTL subcommand

For a description and space requirements for build pointer segment records, see Build pointer segment records.