DATABASE macro

Use the DATABASE macro statement to define the set of physical databases that IMS is to manage.

The DATABASE macro is optional, and IMS issues no warning if it is not included during Stage 1 processing. Databases can be added later to the online system using the commands CREATE DB and UPDATE DB.

One DATABASE macro instruction must be specified for each HSAM, HISAM, and HDAM database. Two DATABASE macro instructions are required for a HIDAM database: one for the INDEX DBD and one for the HIDAM DBD. One DATABASE macro instruction must be included for each secondary index database that refers to any database defined to the online system.

For Fast Path, a DATABASE macro statement must be included for each Main Storage Database (MSDB) and Data Entry Database (DEDB) to be processed.

A database that is defined in an ALL or MODBLKS system definition cannot be converted into a HALDB partition without a cold start of IMS. A cold start is required even if the database is deleted online. After the cold start, the database must be redefined as a HALDB partition.

A database that is defined as a HALDB partition to DBRC and IMS cannot be redefined in an ALL or MODBLKS system definition without a cold start of IMS. A cold start is required even if the database is deleted online.

This topic includes the following information:

Dynamic definition
Supported environments
Syntax
Positional parameters
DATABASE macro keyword parameters

Dynamic definition

To dynamically define the set of physical databases that IMS is to manage, you can use the CREATE DB and UPDATE DB type-2 commands. The following table compares the DATABASE macro keywords and the equivalent CREATE and UPDATE command keywords used for dynamic definition. Default values are shown in bold.

Table 1. DATABASE macro keywords and the equivalent CREATE and UPDATE command keywords used in dynamic definition
DATABASE macro keyword	CREATE \| UPDATE DB keyword equivalent
DBD=name	NAME(name)
ACCESS=EX \| RO \| RD \| UP	ACCTYPE(EXCL \| BRWS \| READ \| UPD)
RESIDENT	RESIDENT (N \| Y)

Supported environments

The DATABASE macro is optional and can be used in the IMS DBCTL and IMS DB/DC environments.

Syntax

Positional parameters

RESIDENT=

Indicates that the DMB directory control block created for this DATABASE statement should reside in storage during system and DBCTL initialization.

Fast Path makes the database control blocks resident in storage during system initialization regardless of whether the RESIDENT option is specified.

Online changes to the RESIDENT option are permitted. However, DMBs associated with new databases defined as RESIDENT are not made resident until the next IMS restart. Until that time, they are treated as nonresident. Changes to a RESIDENT DMB (from an ACBGEN) cause that DMB to be treated as nonresident until the next restart of IMS.

DATABASE macro keyword parameters

To find which parameters apply to your IMS configuration, refer to Selecting the appropriate macros to define your system.

ACCESS=

When used with the database-sharing level declared to database recovery control (DBRC), this parameter specifies the access for the defined database, that is, how the subsystem requesting access plans to use the database.

The ACCESS parameter can be modified by a /START command during IMS execution. Because this parameter can be changed using a /START DATABASE command, online changes to the ACCESS keyword have no effect until the next cold start.

You cannot specify an ACCESS value for MSDBs and GSAM. The possible ACCESS values are:

EX (exclusive): Indicates that the named database can be accessed exclusively by this IMS subsystem. This is the default for ACCESS. Concurrent access to this database by other subsystems is prohibited by DBRC. Unless this is a DEDB, PCBs that refer to this database are scheduled, regardless of the PROCOPT values specified in PSBGEN.
Concurrent image copy cannot be run against a database with ACCESS=EX. If you are running with high-speed sequential processing (HSSP), you must specify ACCESS=EX or ACCESS=UP.
RD (read): Indicates that the named database can only be read by this subsystem. The database is opened for input only. No application programs are allowed to physically update this database.
RO (read only): Indicates that the named database is read-only in this IMS subsystem. This database is opened for input only. PCBs that refer to this database are allowed only if PROCOPT=GO is specified in PSBGEN.
UP (update): Indicates that the named database can be updated and read. PCBs that refer to this database can be scheduled regardless of their PROCOPT values.
If you are running with high-speed sequential processing (HSSP), you must specify ACCESS=UP or ACCESS=EX.

DBD=

Specifies the name of one or more database descriptions (DBDs). If more than one DBD name is specified, each is assumed to have the same characteristics as any positional parameter specified or used by default. The first character of the name must be a valid alphabetic character (A through Z, #, $, or @). At execution time, the DBD must have been processed by the block builder utility program. It must exist as a member in the partitioned data set named in the IMSACB DD statement (IMS.ACBLIB). If the DBD has not been processed by the block builder utility program, and therefore, is not present in the ACBLIB data set, the database is locked at execution time. This parameter is required.

Example:

DATABASE DBD=(N1,N2,N3)