IMS DBD: Database Description Complete Guide

The DBD (Database Description) is the blueprint of an IMS database. It defines everything about the database's structure — the hierarchy of segments, the fields within each segment, the access method used for physical storage, and the relationships between segments. Every IMS program that accesses a database works from a DBD.

What a DBD Contains

A DBD is assembled from a set of macros that define:

Database name and access method (DBD macro)
Dataset groups (DATASET macro) — the physical z/OS datasets that store the data
Segment definitions (SEGM macro) — each segment type in the hierarchy
Field definitions (FIELD macro) — the fields within each segment
Database end (DBDGEN, FINISH, END macros)

Basic DBD Structure

hlasm

         DBD   NAME=CUSTDB,ACCESS=HIDAM
*
         DATASET DD1=CUSTDB01,DEVICE=3390,SIZE=2048
*
* Root segment: CUSTOMER
         SEGM  NAME=CUSTOMER,BYTES=200,FREQ=1000
         FIELD NAME=(CUST-KEY,SEQ,U),BYTES=10,START=1,TYPE=C
         FIELD NAME=CUST-NAME,BYTES=40,START=11,TYPE=C
         FIELD NAME=CUST-ADDR,BYTES=80,START=51,TYPE=C
         FIELD NAME=CUST-PHONE,BYTES=15,START=131,TYPE=C
*
* First child: ACCOUNT (child of CUSTOMER)
         SEGM  NAME=ACCOUNT,PARENT=CUSTOMER,BYTES=100,FREQ=5
         FIELD NAME=(ACCT-KEY,SEQ,U),BYTES=15,START=1,TYPE=C
         FIELD NAME=ACCT-TYPE,BYTES=3,START=16,TYPE=C
         FIELD NAME=ACCT-BAL,BYTES=12,START=19,TYPE=P
*
* Second child: TRANSACTION (child of ACCOUNT)
         SEGM  NAME=TRANSACT,PARENT=ACCOUNT,BYTES=80,FREQ=50
         FIELD NAME=(TRANS-KEY,SEQ),BYTES=10,START=1,TYPE=C
         FIELD NAME=TRANS-AMT,BYTES=12,START=11,TYPE=P
         FIELD NAME=TRANS-DATE,BYTES=8,START=23,TYPE=C
*
* Second child of CUSTOMER: ADDRESS
         SEGM  NAME=ADDRESS,PARENT=CUSTOMER,BYTES=150,FREQ=2
         FIELD NAME=ADDR-TYPE,BYTES=10,START=1,TYPE=C
         FIELD NAME=ADDR-LINE1,BYTES=50,START=11,TYPE=C
*
         DBDGEN
         FINISH
         END

The DBD Macro

The opening DBD macro names the database and specifies the access method:

hlasm

DBD NAME=CUSTDB,ACCESS=HIDAM

NAME — the database name referenced in PSBs and DL/I calls
ACCESS — the access method: HSAM, HISAM, HDAM, HIDAM, INDEX, DEDB, or MSDB

The DATASET Macro

DATASET defines the z/OS datasets used to store the database:

hlasm

DATASET DD1=CUSTDB01,DEVICE=3390,SIZE=2048

DD1 — the DD name in the JCL that points to the physical dataset
DEVICE — device type (3390 for standard DASD)
SIZE — block size in bytes

HDAM and HIDAM databases require separate datasets for the index (CUSTDBI for a database named CUSTDB).

The SEGM Macro

Each SEGM macro defines one segment type:

hlasm

SEGM NAME=ACCOUNT,PARENT=CUSTOMER,BYTES=100,FREQ=5

Key parameters:

NAME — segment type name (1-8 characters)
PARENT — the parent segment type (omit for the root)
BYTES — segment length in bytes
FREQ — estimated average number of occurrences per parent (used for buffer pool calculations)

The FIELD Macro

FIELD macros define the fields within a segment:

hlasm

FIELD NAME=(CUST-KEY,SEQ,U),BYTES=10,START=1,TYPE=C

Key parameters:

NAME — the field name; if this is a sequence field, append ,SEQ; if unique, append ,U
BYTES — field length in bytes
START — byte position within the segment (starting at 1)
TYPE — data type: C (character), P (packed decimal), X (hexadecimal), Z (zoned decimal)

The SEQ designation tells IMS to maintain segment occurrences in sorted order by this field. U means the key value must be unique within a parent.

Generating the DBD (DBDGEN)

After writing the DBD macros, you generate the DBD using the DBDGEN utility in a JCL job:

jcl

//DBDGEN   EXEC DBDGEN
//SYSIN    DD DSN=YOUR.SOURCE.LIBRARY(CUSTDB),DISP=SHR
//DBDLIB   DD DSN=IMS.DBDLIB,DISP=SHR

The DBDGEN process:

Assembles the DBD macros
Links the assembled DBD into DBDLIB
The DBD is now available for PSB generation and ACBGEN

After DBD Changes: ACBGEN

Any time a DBD changes, you must run ACBGEN to rebuild the Application Control Blocks that merge DBDs and PSBs. Programs use ACBs at runtime, not the raw DBDs and PSBs directly.

Frequently Asked Questions

Q: Can I change a segment length in a DBD without rebuilding the database? No. Changing a segment's BYTES length in the DBD requires unloading the database, regenerating the DBD, reloading the data in the new format, and recompiling all programs that map to that segment. Segment layout changes are expensive in IMS — this is why careful upfront design is critical.

Q: What is the maximum number of segment types in an IMS database? IMS supports up to 255 segment types per database. In practice, most production IMS databases have far fewer — typically 5 to 30 segment types. Very large hierarchies become difficult to navigate and maintain.

Q: How do I find out what segments exist in an existing IMS database? The DBD source in your source library is the authoritative reference. If source is unavailable, the DBDLIB member can be decompiled using IBM's IMS Explorer or third-party tools. The DBD member in DBDLIB contains all segment and field definitions in a compiled form.

Part of the IMS Mastery Course — Module 5 of 22.