DBD statements

The format of the DBD macro instruction for each database type is shown in the following examples.

DBD statement parameter descriptions

DBD

Identifies this statement as the DBD control statement.

NAME=

Specifies the name of the database being described. The name can be from 1 to 8 alphanumeric characters. Do not give a database the same name as an existing PSB or program view. Using an existing name can cause unpredictable results.

If an existing name is used, an error occurs during ACB generation.

This name can be the same as that specified in the DD1 parameter of the first DATASET control statement.

For a shared secondary index database, the names of up to 16 secondary index DBDs can be specified.

DBVER=

A numeric value from 1 to 2147483647 that identifies a specific version of a DBD when multiple DBDs are used by application programs to access the same database.

The value specified on the DBVER keyword must be one greater than the highest DBVER value of any prior version of the DBD that is stored in the database record in the IMS catalog.

The DBVER keyword is optional. If the DBVER keyword is omitted, the version of the DBD is 0, even if database versioning is not enabled.

The DBVER keyword is valid only for the following database types:

• DEDB
• HDAM
• HIDAM
• PHDAM
• PHIDAM

ACCESS=

Specifies the DL/I access method and the operating system access method to be used for this database. This keyword also defines the secondary index database as a HALDB. The different access methods are:

HSAM

Hierarchical sequential access method (HSAM). When HSAM is specified, and only one segment type is defined in the HSAM database, this parameter defaults to SHSAM.

SHSAM

Simple HSAM database that contains only one fixed-length segment type. When a simple HSAM database is defined, no prefix is required in occurrences of the segment type to enable IMS to process the database.

GSAM

Generalized sequential access method (GSAM). BSAM or VSAM can be specified as the operating system access method. VSAM is the default. When GSAM is specified, no SEGM control statement is allowed in the DBD.

HISAM

Hierarchical index sequential access method (HISAM). VSAM can be specified as the operating system access method. It is the default.

SHISAM

Simple HISAM database that contains only one fixed-length segment type. A simple HISAM database can only be specified when VSAM is specified as the operating system access method. When a simple HISAM database is defined, no prefix is required in occurrences of the segment type to enable IMS to process the database.

HDAM

Hierarchical direct access method (HDAM). OSAM or VSAM can be specified as the operating system access method. VSAM is the default.

PHDAM

Partitioned hierarchical direct access method (PHDAM). OSAM or VSAM can be specified as the operating system access method. VSAM is the default.

HIDAM

Hierarchical indexed direct access method (HIDAM). OSAM or VSAM can be specified as the operating system access method. VSAM is the default.

PHIDAM

Partitioned hierarchical indexed direct access method (PHIDAM). OSAM or VSAM can be specified as the operating system access method. VSAM is the default.

MSDB

Main storage database (MSDB).

DEDB

Data entry database (DEDB).

INDEX

Creates the primary index to occurrences of the root segment type in a HIDAM database, or creates a secondary index to a segment type in a HISAM, HDAM, or HIDAM database. For the primary or secondary index to a HIDAM database, VSAM must be specified as the operating system access method.

The INDEX parameter is also used to create a secondary index for a DEDB database. In such a case, VSAM and SHISAM are both valid operating system access types.

The INDEX parameter is not used to define the primary index of a PHIDAM database.

PSINDEX

Creates the partitioned secondary index to a segment type in PHDAM and PHIDAM databases. VSAM must be specified as the operating system access method. VSAM is the default.

LOGICAL

A logical database comprises logical concatenations of some or all of one or more physical databases. Logical databases must reference existing physical databases.

PROT | NOPROT

Specifies if a secondary index database uses index pointer protection. This optional parameter ensures the integrity of all fields in index pointer segments that are used by IMS. Use of this parameter prevents an application program from doing a replace operation on any field within an index pointer segment except for fields within the user data portion of index pointer segments. Delete operations are still enabled for index pointer segments. If a delete is issued for an index pointer segment, the index target segment pointer in the index pointer segment is deleted. However, the index source segment that caused the index pointer segment to be created originally is not deleted.

If index pointer protection is not used, an application program can replace all fields within an index pointer segment except the constant, search, and subsequence fields. Inserts to an index database are invalid under all conditions.

By default, a secondary index database uses index pointer protection.

DOSCOMP

Indicates if this is a DLI/DOS index database. Must be specified if the database is an index, and it was created using DLI/DOS. DLI/DOS index databases contain a segment code as part of the prefix. Specifying that a database is a DLI/DOS index database causes IMS to expect this code to be present in the defined database, and to process in a way that preserves this code. This includes providing a segment code for new segments being inserted. DLI/DOS databases must use VSAM and cannot be PHDAM, PHIDAM, or PSINDEX databases.

PSNAME=

Specifies the module that selects the HALDB partition for PSINDEX, PHDAM, or PHIDAM databases. The parameter is a HALDB partition selection exit routine module name. This parameter is only valid when the access type for the database is PSINDEX, PHDAM, or PHIDAM.

Exception: A user-provided HALDB partition selection routine is not needed if root key ranges define HALDB partition membership.

RMNAME=

Specifies a module name that is used to manage the data that is stored in a DEDB or in the primary data set group of an HDAM or PHDAM database. This parameter is only valid when the database access type is HDAM, PHDAM, or DEDB. A randomizing module controls root segment placement in or retrieval from the DEDB, HDAM, or PHDAM database. One or more modules, called randomizing modules, can be utilized within the IMS system. A particular database has only one randomizing module associated with it. A generalized module, which uses user-supplied parameters to perform randomizing for a particular database, can be written to service several databases. The purpose of a randomizing module is to convert a value supplied by an application program for root segment placement in, or retrieval from, a DEDB, HDAM, or PHDAM database into a relative block number and anchor point number. You can randomize within an area by selecting a two-stage randomizer. When you select a two-stage randomizer, the number of root anchor points in an area can be changed without having to stop all areas in the DEDB with the /DBRECOVERY command.

For PHDAM databases, the randomizer module names and values become the default for each partition. You can set a different randomizer name and values for each partition during HALDB partition definition. HALDB partition selection is done prior to invoking the randomizing module. The randomizing module selects locations only within a partition.

mod

The module name is the 1- to 8-character alphanumeric name of a user-supplied randomizing module that is used to store and access segments in this DEDB, PHDAM, or HDAM database. Select a two-stage randomizer by specifying the randomizer name in the module name parameter and 2 in the anchor point parameter.

anch

The purpose of the anch value is different depending on whether you are defining a Fast Path DEDB database or a full-function HDAM or PHDAM database.

This parameter must be an unsigned decimal integer. The default value of this parameter is one.

For a DEDB database, the value of anch specifies the type of randomizer. A value of 1 indicates a single-stage randomizer. A value of 2 indicates a two-stage randomizer. Any other value is invalid.

For HDAM and PHDAM databases, the value of anch specifies the number of root anchor points desired in each control interval or block in the root addressable area of the HDAM or PHDAM database. Typical values are from 1 to 5 and the value cannot exceed 255.

When accessing a HDAM or PHDAM database, if a user randomizing routine produces an anchor point number greater than the number specified for this parameter, the highest-numbered anchor point in the control interval or block is used. When a randomizing routine produces an IMS anchor point number of zero, IMS uses anchor point one in the control interval or block.

rbn

Specifies the maximum relative block number value that you want to allow a randomizing module to produce for this database. This parameter is for HDAM or PHDAM databases only. This value determines the number of control intervals or blocks in the root addressable area of an HDAM or PHDAM database. This parameter must be an unsigned decimal integer whose value does not exceed 2²⁴-1. If this parameter is omitted, no upper limit check is performed on the relative block number created by the randomizing module. If this parameter is specified, but the specified randomizing module produces an relative block number greater than this parameter, the highest control interval or block in the root addressable area is used by IMS. If a user randomizing module produces a block number of zero, the control interval or block one is used by IMS.

In an HDAM or PHDAM data set, the first bit map is in the first block of the first extent of the data set. In an HDAM or PHDAM database, the first control interval or block of the first extent of the data set specified for each data set group is used for a bit map. In a VSAM data set, the second control interval is used for the bit map and the first control interval is reserved. IMS adds one to the block calculated by the randomizer.

bytes

Specifies the maximum number of bytes of database record that can be stored into the root addressable area in a series of inserts unbroken by a call to another database record. This parameter is for HDAM and PHDAM databases only. If this parameter is omitted, no limit is placed on the maximum number of bytes of a database record that can be inserted into this database's root segment addressable area. The bytes parameter must be an unsigned decimal integer whose value does not exceed 2²⁴-1. When the maximum relative block number parameter is omitted, this parameter is ignored. In this case, there is no limit on the number of bytes of a database record that can be inserted into the root addressable area.

If this parameter is specified for an HDAM or PHDAM database and the length of the database record is larger, the remainder of the record is inserted into the overflow area following the current end-of-file (EOF). This operation requires that enough space be available after the current EOF to contain the remainder of all database records that exceed the value of this parameter. If sufficient space is not available in the overflow area following the current EOF, the database records are inserted randomly in the database.

XCI

Specifies whether this DEDB uses the Extended Call Interface when making calls to the randomizer. This option allows the randomizer to be called in three different ways. On initialization of IMS or during a /START DB command, IMS will first load the randomizer and then make an INIT call to the randomizer to invoke its initialization routines. During a /DBR DB command, IMS will make a TERM call to the randomizer to invoke the termination routines before unloading the randomizer. The normal randomizing call to the randomizer is made when the application issues a GU or ISRT call on a root segment. The XCI option is only valid for DEDBs.

PASSWD=

Prevents accidental access of IMS databases by non-IMS programs.

YES

Specifying PASSWDYES causes DL/I to use the database name as the VSAM password when opening any data set for this database. This parameter is only valid for databases that use VSAM as the access method. You cannot use the database name as the password for the LOGICAL or DEDB database types. When the user defines the VSAM data sets for this database using the DEFINE statement of z/OS® Access Method Services, the control level (CONTROLPW) or master level (MASTERPW) password must be the same as the DBDNAME for this DBD. All data sets associated with this DBD must use the same password.

For the IMS DB/DC system, all VSAM OPENs bypass password checking and thus avoid operator password prompting. For the IMS DB system, VSAM password checking is performed. In the batch environment, operator password prompting occurs if automatic password protection is not specified, and the data set is password protected at the control level (CONTROLPW) with passwords not equal to the database name.

NO

Specifying PASSWDNO indicates that the database name should not be used as the VSAM password. This is the default behavior.

EXIT=

Specifies that the Data Capture exit routine is used. You can specify multiple exit routine names on a single DBD statement. You can select different data options for each exit routine. The order that you list the exit routines within the parameter determines the order the exit routines are called for the segment.

When specified on the DBD statement, the EXIT= parameter applies to all segments within the physical database that do not have the EXIT= parameter on the SEGM statement. The following physical databases are supported by this exit routine:

• HISAM
• SHISAM
• HDAM
• PHDAM
• HIDAM
• PHIDAM
• DEDB

If the exit routine is not specified for a supported database organization or a supported segment type, DBDGEN fails.

If the job name of a CCTL or ODBM address space is specified on the SUPPDCAPNAME= parameter, which is in the DATABASE section of the DFSDFxxx member of the IMS PROCLIB data set, the exit routine is not called for data updates invoked by the specified job, even if a Data Capture exit routine is specified on the EXIT= parameter.

The EXIT= parameter can also be specified on the SEGM statement.

exit_name

Specifies the name of the exit routine that processes the data. This parameter is required. The name must follow standard naming conventions. A maximum of 8 alphanumeric characters is allowed. You can specify an asterisk (*) instead of an exit routine name to indicate that you want logging only. If this is done, the logging parameter default is LOG. If you do specify an exit routine, the logging parameter default is NOLOG. All of the following operands are optional.

KEY | NOKEY

Specifies whether the exit routine is passed the physical concatenated key. This key identifies the physical segment that is updated by the application.

KEY

Specifies the exit routine is passed the physical concatenated key.

KEY is the default.

NOKEY

Can be specified when the physical concatenated key is not required for the exit routine.

DATA | NODATA

Specifies whether the physical segment data is passed to the exit routine for updating.

DATA

Specifies that the physical segment data is passed to the exit routine for updating. When DATA is specified and a Segment Edit/Compression exit routine is also used, the data passed is expanded data.

DATA is the default.

NODATA

Can be specified when the exit routine does not require segment data. Use NODATA to avoid the overhead that is created from saving physical segment data.

NOPATH | PATH

Specifies whether the exit routine requires data from segments in the physical root's hierarchical path.

NOPATH

Indicates that the exit routine does not require data from segments in the physical root's hierarchical path. NOPATH is an efficient way to avoid the processing time that is needed to retrieve path data.

NOPATH is the default.

PATH

Can be specified when the data from each segment in the physical root's hierarchical path must be passed to the exit routine for an updated segment. Use PATH to allow an application to separately access several segments for insertion, replacement, or deletion.

You can use the PATH option when information from segments in the path is needed to compose the Db2 for z/OS primary key. The Db2 for z/OS primary key would then be used in a propagation request for a dependent segment update. Typically, you need this kind of segment information when the parent contains the key information and the dependent contains additional data that would not fit in the parent segment.

You can also use PATH when additional processing is necessary. It could be that you are not accessing several segments with one call; for example, you did not invoke the D command code. In this case, additional processing is necessary if the application is to access each segment with a separate call.

DLET | NODLET

Specifies whether X'99' log records are written for DLET calls.

Note: DLET or NODLET can only be specified for a DEDB.

If you specify this parameter in the SEGM statement, it overrides the specification for the DBD statement.

DLET

X'99' log records are written for DLET calls.

DLET is the default.

NODLET

No X'99' log records are written for DLET calls.

BEFORE | NOBEFORE

Specifies whether the before data is included in X'99' log records for REPL calls.

Note: BEFORE or NOBEFORE can only be specified for a DEDB.

If you specify this parameter in the SEGM statement, it overrides the specification for the DBD statement.

BEFORE

Before data is included in X'99' log records for REPL calls.

BEFORE is the default.

NOBEFORE

No before data is included in X'99' log records for REPL calls.

CASCADE | NOCASCADE

Specifies whether the exit routine is called when DL/I deletes this segment.

CASCADE

Indicates that the exit routine is called when DL/I deletes this segment because the application deleted a parent segment. Using CASCADE ensures that data is captured for the defined segment.

CASCADE is the default.

The CASCADE parameter has three suboptions. These suboptions control the way data is passed to the exit routine. If you specify suboptions, you must enclose the CASCADE parameter and the suboptions within parentheses.

KEY | NOKEY

Specifies whether the physical concatenated key is passed to the exit.

KEY

Passes the physical concatenated key to the exit. This key identifies the segment being deleted by a cascade delete.

KEY is the default.

NOKEY

Can be used when the exit routine does not require the physical concatenated key of the segment being deleted.

DATA | NODATA

Specifies whether segment data is passed to the exit routine for a cascade delete.

DATA

Passes segment data to the exit routine for a cascade delete. DATA also identifies the segment being deleted when the physical concatenated key is unable to do so.

DATA is the default.

NODATA

Can be specified when the exit routine does not require segment data. NODATA reduces the significant storage and performance requirements that result from saving physical segment data.

NOPATH | PATH

Specifies whether the exit routine requires segment data in the physical root's hierarchical path.

NOPATH

Indicates that the exit routine does not require segment data in the physical root's hierarchical path. Use NOPATH to eliminate the substantial amount of path data needed for a cascade delete.

NOPATH is the default.

PATH

Can be specified to allow an application to separately access several segments for a cascade delete.

NOCASCADE

Indicates that the exit routine is not called when DL/I deletes this segment. Cascade delete is not necessary when a segment without dependents is deleted.

Note: If any (CASCADE B) suboptions are specified with NOCASCADE in an EXIT= parameter, they will be ignored, and the value for those suboptions will be set to NOxxxx.

LOG | NOLOG

Specifies whether data capture control blocks or data is written to the IMS system log.

LOG

Requests that the data capture control blocks and data be written to the IMS system log.

For more information, see Asynchronous data propagation.

NOLOG

Indicates that no data capture control blocks or data is written to the IMS system log.

NOSSPCMD | SSPCMD

An optional parameter that indicates whether command codes related to Fast Path subset pointers (SSP) be captured. The default is NOSSPCMD. It is recommended that this option be specified only on segments that involve subset pointers.

The following table indicates which command codes are captured for a given DL/I call:

Table 1. Command codes that are captured for DL/I calls

DL/I call	Details
G* (get calls)	M, S, W, Z. R is captured if at least one of M, S, W, or Z is also on the same SSA, or along with the PATH data if PATH is requested.
REPL	M, S, W, Z
DLET	Z
ISRT	M, S, W, Z. R is captured if the segment is being inserted or if it was specified on an SSA of a segment not being inserted but PATH data is requested.

NOINPOS | INPOS

An optional parameter to request that the next twin data be captured on an ISRT call. The default is NOINPOS. The twin data of the twin that follows an inserted segment will be captured if INPOS is specified and the following conditions are true:

• An ISRT of a non-unique segment is made.
• An ISRT rule of HERE is used.

If the new segment is the only twin instance or last in the twin chain, no twin data will be captured.

NOFLD | FLD

An optional parameter to request that updates that are made by a DEDB FLD call be captured. This option is valid only for a DEDB. The information captured is logged only in the X'9904' log records if option LOG is specified. It is not passed to the Data Capture exit routine.

VERSION=

Specifies a character string used to identify the DBD. The exit routine is passed this character string so it can determine the DBD version used to update the database.

character string

The character-string length can be up to 255 bytes. There are no checks to ensure that the proper values have been inserted. Therefore, it is important that the variable-length character string be updated whenever the DBD changes.

If you do not specify a character string, a 13-character time stamp is generated by DBDGEN. It represents the date and time the DBDGEN was completed. Its format is:

MM/DD/YYHH.MM

Where:

MM

The month

DD

The day of the month

YY

The last two digits of the year

HH

The hour on a 24-hour clock

MM

The minutes

DATXEXIT=

Allows a user exit, DFSDBUX1, to be used by an application while processing this database. The default is NO.

Allows the Data Conversion user exit routine (DFSDBUX1) to be used by an application while it is processing this database. The default is DATXEXITNO.

If DATXEXITYES is specified, the user exit DFSDBUX1 is called at the beginning and at the end of each database call. If DFSDBUX1 is not loaded, IMODULE is called to load it.

If DATXEXITNO is specified, the DFSDBUX1 user exit routine can be called, provided DFSDBUX1 is located in the SDFSRESL. If DFSDBUX1 does not need to be called again for the database definition, X'FF' is returned in the SRCHFLAG field in the JCB, and DFSDLA00 dynamically marks the database definition as not requiring the exit. In this case, the user exit is not called again for that database definition for the duration of the IMS session, unless the DMB is purged from the DMB pool.

FPINDEX=

Specifies whether an index database is a secondary index for a primary Fast Path DEDB database. By default, an index database is not a secondary index.

Valid values are NO, null, and YES. NO and null are equivalent. The default is NO (or null).

ENCODING=

An optional 1- to 25-character field that specifies the default encoding of all character data in this database.

The default code page is Cp1047, which specifies EBCDIC encoding.

This value cannot contain the following characters:

• Single or double quotation marks
• Blanks
• Less than (< ) and greater than ( >) symbols
• Ampersands (&)

This value can be overridden in individual segments or fields.

REMARKS=

Optional user comments. A 1-character to 256-character field.

If your comments contain special characters, such as commas or blank spaces, enclose the full comment string in single quotation marks.

The value specified on the REMARKS keyword cannot contain the following characters:

• Single quotation marks, except when they are used to enclose the full comment string. If a single quotation mark is entered before the end of the full comment string, the remainder of the comment string is truncated. The following examples show correct and incorrect usages of single quotation marks on the REMARKS keyword:

  CORRECT

  REMARKS='These remarks apply to the XYZ application'

  INCORRECT

  REMARKS='These remarks apply to the 'XYZ' application'

• Double quotation marks.
• Less than (<) symbols.
• Greater than (>) symbols.
• Ampersands (&).