/START DB command

The /START DB command can be used to allocate or reallocate all databases other than DEDBs. The /START AREA command must be entered to allocate or deallocate DEDB areas.

Subsections:

• Environment
• Syntax
• Keywords
• Usage notes
• Equivalent IMS type-2 commands
• Examples

Environment

The following table lists the environments (DB/DC, DBCTL, and DCCTL) in which you can use the commands and keywords.

Syntax

>>-+-/START-+--------------------------------------------------->
   '-/STA---'   

         .--------.                                  
         V        |    .-LOCAL-.                     
>--DB--+---dbname-+--+-+-------+--| A |-+--| C |-+-------------><
       |             '-GLOBAL-----------'        |   
       |      .-LOCAL-.                          |   
       '-ALL--+-------+--| A |--| B |------------'   

A

|--+----------------+-------------------------------------------|
   '-ACCESS=-+-RO-+-'   
             +-RD-+     
             +-UP-+     
             '-EX-'     

B

   .-NODBALLOC-.   
|--+-DBALLOC---+------------------------------------------------|

C

                  .-DBALLOC---.  .-NOOPEN-.   
|--+-----------+--+-NODBALLOC-+--+--------+---------------------|
   '-NOBACKOUT-'                 '-OPEN---'   

Keywords

The following keywords are valid for the /START DB command:

ACCESS

Specifies the type of access that is intended for the named database. This keyword overrides the database access that is specified at system definition. Changing the ACCESS parameter of a DEDB is allowed only when all the AREAS in the DEDB are not authorized by the subsystem.

Changing the access intent of a database with the /START DB ACCESS= command causes any VSO areas of the database to be removed from virtual storage. Because the access intent of a DEDB cannot be changed while any of its areas are authorized to an IMS™ subsystem, IMS closes any open areas before it processes the command. If a VSO area is closed as a result of the command, it is also removed from the data space.

The /START AREA command must be used to reactivate the VSO options (VSO and PREOPEN) and PRELOAD option for the area. If an area is opened as a result of an access request rather than by the /START AREA command, it is opened as a non-VSO area.

Non-VSO areas with the PREOPEN option are closed as a result of the /START DB ACCESS= command. These areas are reopened either at the next access request for the area or by the /START AREA command.

The GLOBAL and ACCESS keywords are mutually exclusive. The /START command is rejected if both keywords are specified.

Issuing a /START DB command with the ACCESS parameter is not valid for an MSBD.

The meanings of the ACCESS parameter values are:

RO

Specifies that the named database is available for read-only processing on this IMS subsystem. The only programs that can use the database on this subsystem are those that have a PCB processing option of GO (PROCOPT=GO). Programs that access the data by using the GO processing option might see uncommitted data, because a sharing IMS subsystem could be updating the database, which is opened for input only.

RD

Specifies that the named database is available for read-only processing in this IMS subsystem. Programs with update intent can be scheduled, but cannot update the database. ACCESS of RD differs from ACCESS of RO in that the data is read with integrity (locking is performed) and all programs can access the data, not just those with a processing option of GO. The database is opened for read-only processing.

UP

Specifies that the named database is for update and read processing in the IMS subsystem.

EX

Specifies that the named database is to be used exclusively by this IMS subsystem. This exclusive access is guaranteed only when the database is registered to DBRC.

DBALLOC

Indicates that the specified databases are to be allocated. DBALLOC is the default except for /START DB ALL commands.

NODBALLOC

Indicates that the specified databases are not to be allocated. The databases will be allocated when they are scheduled. NODBALLOC is the default for /START DB ALL commands.

GLOBAL

Specifies that the command applies to all subsystems that are sharing the database. GLOBAL requires that IRLM be active. The command is rejected if IRLM is not active.

If the database is registered in the RECON data set, the /START DB GLOBAL command will reset the prohibit authorization flag to off (PROHIBIT AUTH = OFF).

The /START DB GLOBAL command is processed by the IMS system where the command was initiated. This system will process the command locally and then request IRLM NOTIFY to route and process the command on sharing IMS systems.

If global DB status is maintained, the global status that is maintained in RM is also updated. The global status is set to STA.

If the command is entered from OM API, the global status is updated by the command master IMS. If the command is not entered from OM API, the IMS that initiated the GLOBAL command updates the global status in RM.

You must specify whether the global database status must be maintained in RM. You can specify this during IMS initialization in the DFSDFxxx or DFSCGxxx PROCLIB member with PLEXPARM(GSTSDB(Y)). You can also change it dynamically using the UPD IMS SET(PLEXPARM(GSTSDB(Y)) command. If you do not specify that global database status is to be maintained, the GLOBAL keyword is processed as in prior releases, and the global status is not updated.

If global status in RM is successfully updated, message DFS0988I for RSRCTYPE=DB is issued. If global status is not successfully updated, message DFS3308I is issued, indicating RM failure, and no command response lines are generated. Any RM error is traced to the OCMD trace table. Users can issue a QRY DB STATUS(GLOBAL) command to obtain the global status of the resources in RM.

The X'4C' log record for databases is updated to include both global status and global command time stamp. It includes the DEDB name for the area.

The GLOBAL keyword and the ALL parameter are mutually exclusive. The /START command is rejected if both ALL and GLOBAL are specified.

The GLOBAL keyword is not supported on an RSR tracking subsystem.

If the GLOBAL keyword on a command is entered from an OM API, the command should only be routed to one IMS system in the IMSplex. The IMS that receives the command from OM will make DBRC calls to update the RECON with GLOBAL status. It will also request IRLM NOTIFY to route and process the command on sharing IMS systems, and then process the command locally.

Messages that are produced on the NOTIFIED systems will be displayed only on the system console and will not be routed back to the OM API that originally entered the command.

If multiple IMS systems have been explicitly specified in the route list, the master IMS system will process the command as described previously. However, the non-master IMS systems, to which OM routes the command, will reject the command with the following return and reason code listed in the following table:

Table 2. Return and reason code for GLOBAL keyword issued from the OM API

Return code	Reason code	Meaning
X'00000004'	X'00001000'	The command contained the GLOBAL keyword and was routed to more than one IMS system in the IMSplex. The non-master IMS systems will reject this command when OM routes the command to them. The master IMS system will process this command and use IRLM NOTIFY to route and process the command on the non-master IMS systems. See the discussion under the GLOBAL keyword.

LOCAL

Specifies that the command applies only to the IMS subsystem in which the command is entered. This command does not affect any other subsystem sharing the database.

LOCAL is the default.

NOBACKOUT

Suppresses backout restart for a database not registered in DBRC. If there was a prior dynamic backout or emergency restart backout failure, then a /START, command will attempt to perform the backout again. However, if the log data required to perform the backout has been archived, the backout must be performed by executing the Batch Backout utility.

If the database is registered in DBRC and is using share control, then DBRC is informed when batch backout is successfully executed, and the failing backout will not be attempted again when the /START command is issued.

If the database is registered in DBRC and is using recovery control, DBRC is not informed when batch backout is successfully executed. You must specify the NOBACKOUT keyword to inform IMS that it does not have to attempt to execute the failed backout again.

NOBACKOUT is not valid with the ALL parameter.

OPEN | NOOPEN

Indicates that the named databases should be opened or should not be opened as part of the /START DB processing. NOOPEN is the default except when the database has EEQEs or the database was previously authorized but not allocated. If the database has EEQEs or was previously authorized but not allocated, then the database will be opened until the NOOPEN keyword is specified. Operators need to be aware of the results of issuing this command. Check the return code in message DFS0488I.

Specifying /START DB OPTION(OPEN) can cause the randomizer routine or the selection partition routine to load.

Restriction: The OPEN parameter is not supported:

• On a HALDB master. The command will result in message DFS0488I RC=57, but if only one HALDB master database was specified in the command, the online partition structures of the HALDB master database will be rebuilt if needed. No rebuild will be attempted if more than one database name is listed in the command.
• In an RSR environment.
• On an XRF alternate.
• With keywords ALL, GLOBAL, or NODBALLOC.

Usage notes

For a DEDB, the /START DB command also causes any unloaded randomizer, which is specified in the DBD source, to be reloaded.

You can use the UPD DB START(ACCESS) AREA(*) command to allocate the areas of a DEDB.

When you issue the CREATE DB command for a DEDB, you must specify RESIDENT(Y). DEDBs are always resident. The residency default for the CREATE DB command is non-resident.

After a DEDB is created, you must start it before you can use it in a similar manner as when you add a DEDB or change a DEDB using the online change (OLC) process. After an OLC process that either adds a DEDB or changes a DEDB, the DEDB and the areas must be started. The /START DB command or the UPD DB command will start the database and load the randomizer. The /START AREA command or the UPD AREA command will start the individual areas.

When the name that is specified is for a partition, the action that is taken to allocate data sets varies. The action varies depending on the status of the master database and whether the DMB for the master database is already loaded. If a partition has the /DBRECOVERY command called against it, then the partition cannot be allocated by the /START command even if the DBALLOC keyword is specified. The partition can be allocated by the /START command if the OPEN keyword is used or if the database has EEQEs. The partition will get allocated at first reference if the partition cannot be allocated by the /START command, the OPEN keyword is not used, and the database does not have EEQEs. This applies to partitioned PHDAM and PHIDAM database types.

PHDAM or PHIDAM partitions that had the /DBRECOVERY command issued against them, cannot be allocated with the /START DB DBALLOC command. However, if the partition databases have EEQEs, or the OPEN keyword is used with the /START DB command, or the databases were previously authorized but not allocated, the partitions can be allocated. If you do not use the OPEN keyword, the PSINDEX partition is allocated and the PHDAM and PHIDAM partitions are not allocated until they are authorized.

When a /START DB command is issued for all transactions whose processing program has access to a successfully started database, the USTOPPED attribute will be reset and any messages on the suspend queue for that transaction will be transferred to the normal queue.

If one or more of the named databases requires backout or recovery, and the database is registered in DBRC, the database that require backout or recovery is dropped from the command and the remainder of the databases continue processing. If the database is not registered in DBRC, specify the NOBACKOUT keyword to inform IMS that it does not have to attempt to execute the failed backout again.

To start a HIDAM database, both the index and the data area DBD names must be specified. If a backout failure occurred for this database, the /START command causes the backout to be attempted again.

If a DL/I database is in use by a batch message processing (BMP) region when the /START DB command is issued, a DFS0565I message is returned to the master terminal, the command is ignored for the database indicated in the message, and processing continues for any other databases that are specified in the command. The master terminal operators must wait until the BMP program ends before they reissue the /START DB command to start the database indicated in the DFS0565I message. However, if allocation of a database fails during the scheduling or processing of a BMP region, the /START DB command for that database is processed while the BMP region is still active, and a DFS0565I message is not issued.

For databases on an RSR tracking subsystem, /START DB is used to resume tracking for those databases that were stopped by a tracking subsystem processing. The /START DB command also starts online forward recovery (OFR) for those databases that are not current with mainline tracking.

The /START DB ALL command causes message DFS0488I to be issued. All databases that were defined during the system definition process will be started if possible.

When you enter this command, the database name can be an existing non-HALDB, a HALDB master, or a HALDB partition. A command against a HALDB partition operates exactly like a command against a non-HALDB except for the /START DB command and the UPDATE DB START(ACCESS) command. A HALDB partition is not allocated during the command unless it was previously authorized but not allocated, the OPEN keyword was specified, or the partition has EEQEs. The partition is allocated at first reference.

For HALDB databases, IMS tracks partition statuses and master database statuses separately. For example, a partition can be stopped, but its master database can be started. Alternatively, the partition can be started, but its master database can be stopped. Before opening, authorizing, or scheduling a partition, IMS always examines the status of the partition and the master database. If either the partition or the master database has a status that prevents the action, IMS does not perform the action.

Commands that are issued with a partition name affect only the status of the partition. Commands that are issued against the master database affect only the status of the master database. Therefore, a start of a master database does not update the status of its partitions. If the partitions are stopped, they remain stopped. When a HALDB partition is explicitly stopped, it must be explicitly started again. The type-1 commands with the keyword ALL, type-2 commands with NAME(*), and commands against a HALDB master do not change the STOPPED (shown as STOACC, STOSCHD, or STOUPDS on QUERY DB) and LOCKED indicators in each HALDB partition.

When the command target is a HALDB master, processing acts on all HALDB partitions. For example, if the IMS command is UPDATE DB STOP(ACCESS) on the HALDB master, all of the HALDB partitions are closed, deallocated, and deauthorized. However, the stopped status is only set in the master database. If a QUERY DB command is issued, only the HALDB master displays a status of STOACC (each HALDB partition does not display STOACC unless it was itself stopped). If a UPDATE DB STOP(ACCESS) command was issued against a HALDB master, the display output of a /DISPLAY DB command shows the HALDB master (as STOPPED), but does not display the status of the partitions.

The /START DB command is not allowed for a database that is marked bad with the NOTINIT-48-REPOCHGLIST reason code because the IMS change list processing is not complete for the database or the change list processing failed.

Equivalent IMS type-2 commands

The following table shows variations of the /START DB command and the IMS type-2 commands that perform similar functions.