HALDB Partition Definition utility (%DFSHALDB)

Use the HALDB Partition Definition utility to register HALDB master databases with DBRC, and to add, modify, and delete HALDB partitions. You can use this utility instead of the DBRC commands that provide similar HALDB management functions.

You can perform the following tasks on the HALDB master and the HALDB partitions by navigating through panels in the HALDB Partition Definition utility:
  • Register HALDB master databases with DBRC
  • Add HALDB partitions to an existing HALDB database.
  • Find, view, sort, copy, modify, delete, and print HALDB partition data.
  • Create and modify data set groups.
  • Edit HALDB information.
  • Export and import HALDB definitions.
  • View IMS™ ddname concatenations.
  • Select IMS RECON/DBDLIB libraries.

The HALDB Partition Definition utility does not significantly increase contention for the RECON data set in online IMS systems. The RECON data set is reserved only for the time it takes to process a DBRC request. It is not held for the duration of the utility execution.

You can start the HALDB Partition Definition utility from within ISPF using the following startup command: 
TSO %DFSHALDB

You can also start the HALDB Partition Definition utility by using the IMS Application Menu.

Subsections:

Restrictions

The following restrictions apply when using the HALDB Partition Definition utility:
  • The HALDB Partition Definition utility operates only on databases that are identified as HALDB databases in the DBDLIB member. If you change the DBD after the HALDB definitions are in place, you might not be able to manipulate the definitions. For example, you cannot change the number of data set groups without deleting and redefining the HALDB partition definitions.
  • The HALDB definition of a particular database cannot be updated by multiple users simultaneously. The serialization is on the name of the RECON1 data set and the name of the database.
  • This utility does not support sequential buffering (SB).

Prerequisites

Before you can use the %DFSHALDB utility to register a new HALDB master database with DBRC, you must first define the DBD for the master database by using the Database Description Generation (DBDGEN) utility.

Requirements

Currently, no requirements are documented for the %DFSHALDB utility.

Recommendations

Currently, no recommendations are documented for the %DFSHALDB utility.

Input and output

The HALDB Partition Definition utility receives input from the following sources:
  • DBD generation information is read from DBDLIB.
  • Saved definitions are retrieved from the RECON.
  • User input is solicited from interactive panels.
  • The result of an export is used as input to a subsequent import operation.
  • Configuration information is retrieved from the ISPF profile data set.
  • A data set with key strings can be used as input when HALDB partitions are defined.
  • Batch import and export parameters are specified as TSO command parameters.
The HALDB Partition Definition utility produces the following output:
  • HALDB definitions are stored in the RECON data set.
  • Interactive messages are displayed on the ISPF panel.
  • Exported HALDB definitions are saved to a user specified data set.
  • Some messages are written to a SYSOUT file.
  • HALDB definition information can be printed to the ISPF list file.

DSPXRUN EXPORT example output messages

Exporting database PARTDBA using JCL similar to that shown in Figure 4 would result in the following output:
Figure 1. %DFSHALDB output message for export
DSPM142I Start export to MEM=PARTDBA in DSN='IBMUSER.HALDB.EXPORT'
         from DBN=PARTDBA
DSPM143I The export file contains partition PAAA
DSPM143I The export file contains partition PAAB
DSPM143I The export file contains partition PAAC
DSPM143I The export file contains partition PAAD
DSPM219I Table PARTDBA was created successfully to dataset
         'IBMUSER.HALDB.EXPORT'

DSPXRUN IMPORT example output messages

Importing database PARTDBA using JCL similar to that shown in Figure 4 would result in the following output:

Figure 2. %DFSHALDB output message for import
 DSPM083I Start Import to DBN=PARTDBA from MEM=PARTDBA in 
          DSN='IBMUSER.HALDB.EXPORT' Options=2
 DSPM085I Imports start at 07/07/09 11:50
 DSPM084I Import successful for partition PAAA 
 DSPM084I Import successful for partition PAAB 
 DSPM084I Import successful for partition PAAC
 DSPM084I Import successful for partition PAAD
 DSPM082I 4 of a total 4 partitions from table PARTDBA were 
          imported to database successfully.

JCL specifications for interactive mode

The following figure shows a sample TSO logon procedure for running the %DFSHALDB utility in the interactive ISPF panel mode.

Figure 3. TSO logon procedure to run the %DFSHALDB utility in interactive mode
 
 //HALDB01  EXEC PGM=IKJEFT01,DYNAMNBR=50,REGION=6M
 //STEPLIB  DD DSN=IMS.SDFSRESL,DISP=SHR /* IMS SDFSRESL */
 //SYSPROC  DD DSN=IMS.SDFSEXEC,DISP=SHR /* IMS rexx execs */
 //         DD DSN=ISP.SISPCLIB,DISP=SHR 
 //IMS      DD DSN=your.local.DBDLIB,DISP=SHR 
 //ISPPLIB  DD DSN=IMS.SDFSPLIB,DISP=SHR /* IMS ISPF panels*/
 //         DD DSN=ISP.SISPPLIB,DISP=SHR 
 //ISPSLIB  DD DSN=IMS.SDFSSLIB,DISP=SHR /* IMS ISPF skeletons*/
 //         DD DSN=ISP.SISPSLIB,DISP=SHR 
 //ISPMLIB  DD DSN=IMS.SDFSMLIB,DISP=SHR /* IMS ISPF messages */
 //         DD DSN=ISP.SISPMLIB,DISP=SHR 
 //ISPTLIB  DD DSN=IMS.SDFSTLIB,DISP=SHR /* IMS ISPF tables*/
 //         DD DSN=ISP.SISPTLIB,DISP=SHR 
 //ISPLOG   DD SYSOUT=*,DCB=(RECFM=VA,LRECL=125,BLKSIZE=129)
 //SYSPRINT DD SYSOUT=*,DCB=(RECFM=VA,LRECL=125,BLKSIZE=129)
 //SYSOUT   DD SYSOUT=* 
 //SYSTSPRT DD SYSOUT=*,DCB=(RECFM=F,LRECL=255,BLKSIZE=255)
 //SYSPRINT DD TERM=TS,SYSOUT=A 
 //ISPCTL0  DD UNIT=SYSDA,SPACE=(CYL,(0,1)),
 //         DCB=(LRECL=80,RECFM=FB,BLKSIZE=800) 
 //ISPCTL1  DD UNIT=SYSDA,SPACE=(CYL,(0,1)),
 //         DCB=(LRECL=80,RECFM=FB,BLKSIZE=800) 
 //ISPCTL2  DD UNIT=SYSDA,SPACE=(CYL,(0,1)),
 //         DCB=(LRECL=80,RECFM=FB,BLKSIZE=800) 
 //ISPLST1  DD UNIT=SYSDA,SPACE=(CYL,(0,1)),
 //         DCB=(LRECL=121,RECFM=FBA,BLKSIZE=1210)
 //ISPLST2  DD UNIT=SYSDA,SPACE=(CYL,(0,1)),
 //         DCB=(LRECL=121,RECFM=FBA,BLKSIZE=1210)
 //ISPWRK1  DD UNIT=SYSDA,SPACE=(CYL,(0,1)),
 //         DCB=(LRECL=256,RECFM=FB,BLKSIZE=2560)
 //ISPWRK2  DD UNIT=SYSDA,SPACE=(CYL,(0,1)),
 //         DCB=(LRECL=256,RECFM=FB,BLKSIZE=2560)
 //SYSTERM  DD TERM=TS,SYSOUT=A 
 //SYSIN    DD TERM=TS
The TSO logon procedure must include:
  • DD statements from the production TSO / ISPF logon procedure
  • IMS.SDFSRESL data set in the STEPLIB DD statement
  • IMS dialog components in the appropriate ISPF DD statements

DD statements

STEPLIB DD
Points to IMS.SDFSRESL, which contains the IMS load modules.
IMS DD
Defines the library containing the DBD for the HALDB databases.
SYSPROC DD
Defines the data sets that contain CLISTs and REXX execs. The HALDB Partition Definition utility requires its execs to be in this set of data sets.
ISPPLIB DD
Defines the data sets that contain ISPF panels. The HALDB Partition Definition utility requires its panels to be in this set of data sets.
ISPMLIB DD
Defines the data sets that contain ISPF message members. The HALDB Partition Definition utility requires its message members to be in this set of data sets.
ISPTLIB DD
Defines the data sets that contain ISPF tables. The HALDB Partition Definition utility requires its tables to be in this set of data sets. In this concatenation also include the system ISPF table library.
RECON1 DD
This optional DD statement defines the first DBRC RECON data set. If it is not provided, there must be a RECON1 member in the IMS.SDFSRESL data set that identifies the RECON1 data set.
RECON2 DD
This optional DD statement defines the second DBRC RECON data set. If it is not provided, there must be a RECON2 member in the IMS.SDFSRESL data set that identifies the RECON2 data set.
RECON3 DD
This optional DD statement defines the third DBRC RECON data set. If it is not provided, there must be a RECON3 member in the IMS.SDFSRESL data set that identifies the RECON3 data set.

JCL specifications for batch import and export

The import and export functions of the HALDB Partition Definition utility can be performed in batch jobs. The JCL must include normal ISPF DD statements and start ISPF.

The JCL must include the following elements:

  • A JOB statement within which you define DD statements that are used by ISPF
  • The IMS.SDFSRESL data set in the STEPLIB DD statement
  • The IMS dialog components in the appropriate ISPF DD statements

The output from the export of a HALDB is a member of a PDS. The information about the HALDB is saved in the form of an ISPF table. The ISPF table is used as input for the import process. The export and import can be done from the ISPF panels or from batch jobs.

The batch job executes the standard ISPF command, ISPSTART, which sets up the ISPF environment and then starts the DSPXRUN command. The DSPXRUN command identifies the HALDB database, the import file to use, and the processing options.

The batch import of a HALDB can be done by submitting a batch ISPF job similar to the job shown in the following figure.

To import a database using a batch job, submit a batch ISPF job similar to the job shown in the figure below. All ISPF DD names are required. ISPF is invoked in batch, so all ISPF DDNAMES are required.

Figure 4. Sample JCL for batch import
 //* 
 //DSPXRUN  EXEC PGM=IKJEFT01,DYNAMNBR=50,REGION=6M
 //STEPLIB  DD DISP=SHR,DSN=IMS.SDFSRESL    /* IMS.SDFSRESL */
 //         DD DISP=SHR,DSN=ISP.SISPLOAD 
 //         DD DISP=SHR,DSN=ISP.SISPLPA 
 //SYSPROC  DD DISP=SHR,DSN=IMS.SDFSEXEC    /* IMS rexx execs     */
 //         DD DISP=SHR,DSN=ISP.SISPCLIB 
 //RECON1   DD DISP=SHR,DSN=IMS.RECON1 
 //RECON2   DD DISP=SHR,DSN=IMS.RECON2 
 //RECON3   DD DISP=SHR,DSN=IMS.RECON3 
 //IMS      DD DISP=SHR,DSN=IMS.DBDLIB 
 //ISPPROF  DD DSN=&&PROFILE,               /* dummy ISPF profile */
 //         UNIT=SYSDA,DISP=(NEW,DELETE), 
 //         SPACE=(3200,(30,30,1)),DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200)
 //ISPPLIB  DD DISP=SHR,DSN=ISP.SISPPENU    /* IMS ISPF panels    */
 //ISPSLIB  DD DISP=SHR,DSN=ISP.SISPSLIB    /* IMS ISPF skeletons */
 //         DD DISP=SHR,DSN=ISP.SISPSLIB 
 //ISPMLIB  DD DISP=SHR,DSN=IMS.SDFSMLIB    /* IMS ISPF messages  */
 //         DD DISP=SHR,DSN=ISP.SISPMENU 
 //ISPTLIB  DD DISP=SHR,DSN=ISP.SISPTENU    /* IMS ISPF tables    */
 //ISPLOG   DD SYSOUT=*,DCB=(RECFM=VA,LRECL=125,BLKSIZE=129) 
 //SYSPRINT DD SYSOUT=*,DCB=(RECFM=VA,LRECL=125,BLKSIZE=129) 
 //SYSOUT   DD SYSOUT=* 
 //SYSTSPRT DD SYSOUT=*,DCB=(RECFM=F,LRECL=255,BLKSIZE=255) 
 //SYSTSIN  DD *
    ISPSTART CMD( +
    DSPXRUN +
    IMPORT +
    DSN('USRT002.ISPF.PROFILE') +
    DBN(PARTDBA) +
    MEM(PARTDBA))

Using batch to export or import partition information

DD statements

STEPLIB DD
Points to IMS.SDFSRESL, which contains the IMS load modules.
IMS DD
Defines the library containing the DBD for the HALDB.
SYSPROC DD
Defines the data sets that contain CLISTs and REXX execs. The HALDB Partition Definition utility requires its execs to be in this set of data sets.
ISPMLIB DD
Defines the data sets that contain ISPF message members. The HALDB Partition Definition utility requires its message members to be in this set of data sets.
ISPTLIB DD
Defines the data sets that contain ISPF tables. The HALDB Partition Definition utility requires its tables to be in this set of data sets. In this concatenation also include the system ISPF table library.
RECON1 DD
This optional DD statement defines the first DBRC RECON data set. If it is not provided, there must be a RECON1 member in the IMS.SDFSRESL data set that identifies the RECON1 data set.
RECON2 DD
This optional DD statement defines the second DBRC RECON data set. If it is not provided, there must be a RECON2 member in the IMS.SDFSRESL data set that identifies the RECON2 data set.
RECON3 DD
This optional DD statement defines the third DBRC RECON data set. If it is not provided, there must be a RECON3 member in the IMS.SDFSRESL data set that identifies the RECON3 data set.
SYSTSIN DD
The SYSTSIN DD statement contains the TSO command that starts both ISPF and the HALDB Partition Definition utility. When it is necessary to continue to the next line, use a plus or minus sign as the last character of the line you want to continue.

Return codes

The following return codes are provided at program termination for batch import. Termination return codes are not used for the interactive dialog.
Code
Meaning
0
Successful completion.
4
Some HALDB partitions could not be imported.
8
No HALDB partitions were imported.

Some messages displayed by the HALDB Partition Definition utility are standard ISPF message prompts when the field values are not correct. ISPF messages begin with a prefix of ISR or ISP.

Parent topic: Definition and initialization utilities
Related concepts:
Using IMS utilities with HALDB Online Reorganization
HALDB partition names and numbers