Creating HALDB databases with the HALDB Partition Definition utility

The HALDB Partition Definition utility (%DFSHALDB) is an ISPF application that allows you to manage IMS™ HALDB partitions.

Prerequisite: Before you can use the HALDB Partition Definition utility to define the partitions of a HALDB database, you must define the HALDB master database by using the Database Description Generation (DBDGEN) utility.

Creating HALDB partitions with the Partition Definition utility

When you define the first HALDB partition, you must also register the HALDB master database in the DBRC RECON data set. You can use either the HALDB Partition Definition utility or the DBRC INIT.DB and INIT.PART commands to do this.

The HALDB Partition Definition utility does not impact RECON data set contention of online IMS subsystems. 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.

When defining HALDB partitions using the Partition Definition utility, you must provide information such as the partition name, data set prefix name, and high key value. Whenever possible, the Partition Definition utility provides default values for required fields.

Automatic and manual HALDB partition definition

You can choose either automatic or manual partition definition by specifying Yes or No in the Automatic Definition field in the Processing Options section of the Partition Default Information panel.

Entering Yes in the Automatic Definition field specifies that the Partition Definition utility automatically defines your HALDB partitions. You must have previously created a data set and it must contain your HALDB partition selection strings. Specify the name of the data set in the Input data set field.

Entering No in the Automatic Definition field specifies that you define your HALDB partitions manually.

You can still use an input data set when you define HALDB partitions manually.

The steps for defining a new HALDB are as follows:

Make the dialog data sets available to the TSO user. You can add the data sets to a LOGON procedure or use TSO commands to allocate them. You can use the TSOLIB command to add data sets to the STEPLIB. The following table shows which file names and data sets need to be allocated. Be sure to use your own high level qualifiers.

Table 1. File names and data sets to allocate
File name	Sample data set names	Disposition
STEPLIB	IMS.SDFSRESL	N/A
SYSPROC	IMS.SDFSEXEC	SHR
ISPMLIB	IMS.SDFSMLIB	SHR
ISPPLIB	IMS.SDFSPLIB	SHR
ISPTLIB	IMS.SDFSTLIB	SHR
IMS	IMS.DBDLIB	SHR

If you use a logon procedure, you must log on again and specify logon with the new procedure. If you use allocation commands, they must be issued outside of ISPF. After you allocate the data sets and restart ISPF, restart the Install/IVP dialog, return to this task description, and continue with the remaining steps.

Start the HALDB Partition Definition utility from the ISPF command line by issuing the following command: TSO %DFSHALDB

Specify the name of the database. Fill in the first partition name as shown in the following example. Fill in the data set name prefix using the data set name for your data set instead of the high level qualifier shown in the example. You should, however, specify the last qualifier as IVPDB1A to match cluster names previously allocated.

Recommendation: When naming your partitions, use a naming sequence that allows you to add new names later without disrupting the sequence. For example, if you name your partitions xxxx010, xxxx020 and xxxx030 and then later split partition xxxx020 because it has grown too large, you can name the new partition xxxx025 without disrupting the order of your naming sequence.

Figure 1. Partition Default Information

Help
---------------------------------------------------------------
                 Partition Default Information

Type the field values.  Then press Enter to continue.

Database Name . . . . . . . IVPDB1

                      Processing Options
Automatic Definition . . . .No
Input data set . . . . . . . 
Use defaults for DS groups .No

                     Defaults for Partitions
Partition Name . . . . . . .IVPDB11
Data set name prefix . . . .IXUEXEHQ.IVPDB1A

Free Space
  Free block freq. factor . 0
  Free space percentage . . 0

                     Defaults for data set groups
Block Size . . . . . . . . .8192

DBRC options
   Max. image copies . . . .2
   Recovery period . . . . .0
   Recovery utility JCL . . RECOVJCL
   Default JCL . . . . . . .________
   Image Copy JCL . . . . . ICJCL
   Online image copy JCL . .OICJCL
   Receive JCL . . . . . . .RECVJCL
   Reusable? . . . . . . . .No

To exit the application, press F3

Command = = = >

Define your partitions in the Change Partition panel. Make sure that the name of the partition and the data set name prefix are correct and then define a high key for the partition.
The high key identifies the highest root key of any record that the partition can contain and is represented by a hexadecimal value that you enter directly into the Partition High Key field of the Change Partition panel. Press F5 to accept the hexadecimal value and display its alphanumeric equivalent in the right section of the Partition High Key field.

You can enter the partition high key value using alphanumeric characters by pressing F5 before making any changes in the hexadecimal section of the Partition High Key field. This displays the ISPF editing panel. The alphanumeric input you enter in the editing panel displays in both hexadecimal and alphanumeric formats in the Change Partition Panel when you press F3 to save and exit the ISPF editor.

The last partition you define for a HALDB database should have a high key value of X'FF'. This ensures that the keys of all records entered into the HALDB database will be lower than the highest high key in the HALDB database. The Partition Definition utility fills all remaining bytes in the Partition High Key field with hexadecimal X'FF'. If the partition with the highest high key in the database has a key value other than X'FF's, any attempt to access or insert a database record with a key higher than the high key specified results in an FM status code for the call. Application programs written for non-HALDB databases are unlikely to expect this status code.

When you finish defining the partition high key, press enter to create the partition. The Change Partition panel remains active so that you can create additional partitions. To create additional partitions, you must change the partition name and the partition high key.

The following figure shows the Change Partition panel. The Partition High Key field includes sample input.
Figure 2. Change Partition panel
```
Help
---------------------------------------------------------------
                       Change Partition
Type the field values. Then press Enter.

Database name..........IVPDB1
Partition name.........IVPDB11
Partition ID...........1
Data set name prefix...IXUEXEHQ.IVPDB1A
Partition Status......._______


Partition High Key
  +00 57801850 00F7F4F2 40C5A585 99879985 | ...&.742 Evergre | 
  +10 859540E3 85999981                   | en Terra         | 

Free Space
   Free block freq. factor...0
   Free space percentage.....0

Attributes for data set group A
   Block Size................8192

DBRC options
   Max. image copies.........2
   Recovery period...........0
   Recovery utility JCL......_________
   Image copy JCL............ICJCL
   Online image copy JCL.....OICJCL
   Receive JCL...............RECVJCL
   Reusable?.................No


Command  = = = > 
```
When you finish defining partitions, press the cancel key (F12) to exit the Change Partition panel. A list of partitions defined in the current session displays.
To exit the HALDB Partition Definition utility entirely, press F12 again.