Database Description (DBD) Generation utility

Use the Database Description Generation (DBDGEN) utility to define a database so that it can be used by an application program.

A database description (DBD) is a DL/I control block containing all of the database information needed by an application program.

You create a database description (DBD) by coding special macro instructions. These macros become the input to the DBDGEN utility.

You can use only one physical DBD to describe each physical database; otherwise, a user abend, such as 0850, 0852, or 0853 occurs. At execution time, DL/I uses the DBD to create a set of internal control blocks.

The DBDGEN utility defines each DBD with the following database information:

Segment types
Physical and logical relationships between segment types
Database organization and access method
Physical characteristics of the database
Define the name and data options of selected exit routines
Metadata that describes the database and the data stored in the database

Subsections:

Restrictions
Prerequisites
Requirements
Recommendations
Input and output

Restrictions

Currently, no restrictions are documented for the DBDGEN utility.

Prerequisites

Currently, no prerequisites are documented for the DBDGEN utility.

Requirements

There are strict rules for structuring DBDGEN input. A separate input set is required for each database.

Recommendations

If your IMS™ system does not manage runtime application control blocks (ACB) by using the catalog, you must regenerate DBDs by using the DBDGEN utility after you import resources into z/OS by using IMS Explorer. For example, if you import a COBOL copybook definition or a new database definition to z/OS, you must use the DBDGEN utility to regenerate your database descriptions.

Input and output

The DBDGEN program accepts several types of control statements.

The DBD statement names the database being described and provides DL/I with information concerning database organization.
The DATASET statement is used only in non-DEDB DBDGEN input record structures. The DATASET statement defines a data set group within a database. One or more DATASET statements follow the DBD statement.
The AREA statement is used only in DEDB DBDGEN input record structures. The AREA statement defines an area within a database. One or more AREA statements follow the DBD statement.
The SEGM statement defines the segments of the specified database. The SEGM statement is used with the following statements:
- FIELD
- XDFLD
- LCHILD
- DFSMARSH
- DFSMAP
- DFSCASE
Each statement defines different aspects of a segment or the fields in a segment.
The DBDGEN statement indicates the end of DBDGEN control statements.
FINISH is an optional statement retained in the input stream for compatibility.
The END statement indicates to the z/OS® assembler that the end of the input statements has been reached.

Three types of printed output and a load module, which becomes a member of the partitioned data set named IMS.DBDLIB, are produced by a DBD generation. Each of these outputs is described in the following sections.

Control statement listing

This is a listing of the input statement images to this job step.

Diagnostics

Errors discovered during the processing of each statement result in diagnostic messages. These messages are printed immediately following the image of the last statement that is read. The message can reference either the statement immediately preceding it or the preceding group of statements. It is also possible that more than one message could be printed for each statement.

In this case, these messages follow each other on the output listing. After all the statements have been read, a further check is made of the reasonableness of the entire deck. This might result in one or more additional diagnostic messages.

Any discovered error results in the diagnostic messages being printed, the statements being listed, and the other outputs being suppressed. However, all the statements are read and checked before the DBD generation execution is terminated. The bind step of DBD generation is not processed if a statement error has been found.

Assembler listing

An assembler language listing of the DBD macro expansion created by DBD generation execution is provided. You can eliminate a printout of this listing by including an assembler language PRINT NOGEN statement.

If the DBD generation is for a database that uses VSAM as the operating system access method, a page in the assembler listing will provide recommended values for some of the parameters necessary to define the data sets of the database to VSAM. CONTROLINTERVALSIZE and RECORDSIZE values other than those recommended might be desired for special reasons, such as performance improvement. RECORDSIZE needs to be changed appropriately for all ESDS definitions.

If the control interval size is not specified (see the SIZE parameter in the GSAM row in Table 2), it defaults to the size recommended in this assembler listing. The following example shows the output produced for a HISAM database. The parameters provided are in the format required for Access Method Services statements. The first DEFINE provides parameters for the key sequenced data set (KSDS) and the second DEFINE provides parameters for the entry sequenced data set (ESDS).

To provide a complete definition for a VSAM data set, you must add parameters for data set name (NAME), space allocation (CYL), and volume assignment (VOLUMES) to those provided by DBD generation. Optional parameters such as FREESPACE and WRITECHECK can be included if desired.

Example of Access Method Services parameters from DBD generation

If you use the /DBD command to allow an offline dump of a VSAM database, you must use SHARE OPTIONS(3) in the VSAM DEFINE operation for the data sets of the database. The following figure shows an example of Access Method Services parameters from DBD generation.

+*,* * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+*,*
+*,     RECOMMENDED VSAM DEFINE CLUSTER PARAMETERS
+*,*
+*,* * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+*,* * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+*,*                   *NOTE 1
+*,     DEFINE CLUSTER (NAME(DDI3I1) -
+*,*           INDEXED KEYS (6, 10) -
+*,*           RECORDSIZE (680,680) -
+*,*           DATA (CONTROLINTERVALSIZE (4096))
+*,*  *NOTE 1: SHOULD SPECIFY DSNAME FOR DDI3I1
+*,* * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+*,* * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+*,*                   *NOTE 2
+*,*    DEFINE CLUSTER (NAME(DDI3O1) NONINDEXED -
+*,*           RECORDSIZE (680,680) -
+*,*           CONTROLINTERVALSIZE (4096))
+*,*  *NOTE 2: SHOULD SPECIFY DSNAME FOR DDI301
+*,* * * * * * * * * * * * * * * * * * * * * * * * * * * * *

Segment flag codes

Segment flags are printed in DBD generation output to confirm what has been generated by that particular DBD generation. The flags, when interpreted, tell you which pointer options were generated; the segment insert, delete, and replace rules specified; whether physical child pointers have been reserved in this segment's prefix; and how many physical children are related to the segment. Segment flags appear in the output as an assembler language defined constant (DC) statement. The constant is defined as 8 hexadecimal digits followed by the comment, SEGMENT FLAGS. Each pair of digits in the constant is a hexadecimal byte. To interpret the constant, convert the first 6 digits to binary values, and the last 2 digits to decimal values as shown in the following figure.

         CONVERTED
BYTE     VALUE         DESCRIPTION
 
 0                     POINTER POSITIONS GENERATED:
 
         1.......      CTR (Counter)
         .1......      Physical twin forward
         .11.....      Physical twin forward and backward
         ...1....      Physical parent
         ....1...      Logical twin forward
         ....11..      Logical twin forward and backward
         ......1.      Logical parent
         .1.....1      Hierarchic forward
         .11....1      Hierarchic forward and backward
 
 1                     SEGMENT PROCESSING RULES:
 
         10......      Insert physical
         01......      Insert virtual
         11......      Insert logical
         ..10....      Insert nonsequential last
         ..01....      Insert nonsequential first
         ..11....      Insert nonsequential here at current position
         ....10..      Replace physical
         ....01..      Replace virtual
         ....11..      Replace logical
         ......10      Delete physical
         ......01      Delete virtual
         ......11      Delete logical
         ......00      Bivirtual delete
 
2        ..XX.XXX      Reserved
      1.......      Segment is paired
         .1......      Segment is a direct dependent in a FP DEDB
         ....1...      Segment's parent has two physical child
                       pointers; hierarchic pointers were not specified
 
3        0-254         Number of physical children of this segment
                       pointed to by physical child pointers

Segment prefix format description

Convert the values to binary and decimal representations:

  Byte 0   Byte 1    Byte 2    Byte 3
   FE       FD        08       0A
11111110  11111101  00001000   10

Byte 0: Segment has counter, physical twin forward and backward, logical twin forward and backward, physical parent, and logical parent pointers.
Byte 1: The insert and replace rules specified are logical, and the delete rule specified is virtual. Nonsequenced inserts at current position.
Byte 2: Two 4-byte fields are reserved for physical child pointers in the parent of this segment.
Byte 3: This segment is the parent of 10 physical children.

Output from DBD generation contains the statement:

DC  X'FEFD080A'  SEGMENT FLAGS

Load module

DBD generation is a two-step operating system job. Step 1 is a macro assembly execution which produces an object module that becomes input to Step 2. Step 2 is a bind of the object module, which produces a load module that becomes a member of the IMS.DBDLIB library.

DBD generation error conditions

If operands or parameters other than those shown for each type of database are coded, or if operands or parameters that are necessary are omitted, one or more of the following conditions can occur:

DBD generation issues diagnostic messages that:
- Flag operands or parameters that are not shown for the type of database being defined
- Indicate that operands or parameters that are required for the type of database being defined were omitted
DBD generation completes, but DL/I ignores the control information that was generated by the specification of operands or parameters that are not shown for the type of database that was defined.
DBD generation completes, but DL/I is unable to create and access the defined database because (a) conflicting control information was specified when attempting to interrelate databases, or (b) segment relationships describing the application program's view of the database were not properly defined in the DBD generation.
DBD generation completes, and DL/I creates and accesses a database. However, the results provided to you are not those you desired. This condition can occur because the default actions taken by DL/I in response to finding missing or conflicting control information are actions that you had not considered during DBD generation.