/DBRECOVERY command

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 command and keywords.

Syntax

Keywords

The following keywords are valid for the /DBRECOVERY command:

AREA

Specifies the DEDB areas (but not DEDBs) to be processed by the /DBRECOVERY command. The /DBRECOVERY AREA command stops the accessing and updating of specified DEDB areas and closes them.

The /START AREA command can be used to reopen and reallocate the areas closed by /DBRECOVERY AREA command.

The /DBRECOVERY command for Fast Path Virtual Storage Option (VSO) areas in a z/OS® data space removes the areas from the data space and forces updates to be written back to DASD.

While the database is being quiesced, this command cannot be processed successfully.

DATAGRP

Specifies a group of DL/I databases and Fast Path DEDBs to be processed by the /DBRECOVERY command. Use the INIT.DBDSGRP command with the GRPNAME and DBGRP keywords to define the data group in the RECON data set.

Recommendation: Although you can use DBDS groups as well as database groups for this command, you should use database groups whenever possible to eliminate the overhead of converting the DBDS group to a database group.

DB

Specifies the DL/I databases and Fast Path DEDBs (and inclusive areas) to be processed by the /DBRECOVERY command. MSDBs cannot be specified with /DBRECOVERY. The /DBRECOVERY DB command allows scheduling of transactions or programs that use the database to continue after successful completion of the command. However, calls to DEDB databases will receive an FH status code. If the application program is prepared to accept status codes regarding data unavailability through the INIT STATUS GROUPA or GROUPB call, calls to DL/I databases will result in either a 3303 pseudoabend, a BA, or BB status code.

When the /DBRECOVERY DB command is entered, the data sets of the databases named in the command are closed. The /DBRECOVERY DB command dynamically deallocates the IMS databases. For DEDBs, the randomizer is unloaded and removed from storage. You can use the UPD DB STOP(ACCESS) OPTION(NORAND) command to prevent the randomizer from being unloaded.

If a DL/I database is in use by a batch message processing region when the /DBRECOVERY command is issued, a DFS0565I message is returned to the master terminal, the command is ignored for the database named in the message, and processing continues for any other databases specified in the command. The master terminal operator must wait until the BMP ends before reissuing the /DBRECOVERY command to close the databases named in any DFS0565I messages. DEDB databases will accept the /DBRECOVERY command while actively being used by a batch message processing region. However, all further calls to the database will receive an FH status code.

The region identified in the DFS0565I message can also be an MPP region. The error message can be issued in order to break a potential deadlock condition between Online Change, a /DBR, or /STA command against a database being used by the MPP, and an application running in the MPP issuing an ICMD or CMD call.

The /START DB command is used to reallocate the databases closed by the /DBRECOVERY DB command except for HALDB partitions. A HALDB partition can be reallocated if the partition has EEQEs, the partition was previously authorized but not allocated, or the OPEN keyword on the /START DB command was used. HALDB partitions are allocated at first reference. For DEDBs, a /START DB command also causes a reload of the randomizer.

For DBCTL, when CCTL schedules a PSB, the DBCTL thread SCHED request defines the thread as LONG or SHORT. If the database is currently scheduled to a LONG thread, the command is rejected; otherwise, the thread is allowed to complete its current commit cycle before the database is acted upon. This results in either a commit point or transaction termination.

While the database is being quiesced, this command cannot be processed successfully.

The /DBRECOVERY 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.

GLOBAL

Applies when the database is registered to DBRC and specifies that the command applies to all sharing online subsystems. You can use the /DBRECOVERY GLOBAL command to close the database so that it can be taken offline when this command successfully completes in all online subsystems. If the database is registered in the RECON data set, the prohibit authorization flag will be set (PROHIBIT AUTH = ON), and DBRC will prevent any further authorization of the database. This is equivalent to the CHANGE.DB DBD(xxx) NOAUTH DBRC command.

The /DBRECOVERY 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 or AREA status is maintained, the global status maintained in RM is also updated. The global status is set to STOACC.

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.

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) or QUERY AREA STATUS(GLOBAL) 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. A new log record for DEDB areas, X'594C', includes both global status and global command time stamp.

The GLOBAL keyword and the ALL parameter are mutually exclusive. The /DBRECOVERY command will be rejected if both GLOBAL and ALL are specified. The IRLM must be active when the GLOBAL keyword is used. If IRLM is not active, the command is rejected.

If the command with GLOBAL is entered from OM API, the command master IMS becomes the initiating system. The command IMS will process the command locally first and then 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.

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

If the command is routed to multiple IMS systems, the non-master IMS systems to which OM routes the command, will reject the command with the return and reason codes shown 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.

Restriction: When the GLOBAL keyword is specified, the command is performed for the named database only. If the command is to be performed for a HIDAM database and its index, both must be named.

The GLOBAL keyword cannot be combined with the DATAGRP keyword.

LOCAL

Specifies that the command applies only to the subsystem in which the command is entered. This command does not affect any other subsystem sharing the database or area. Use the LOCAL keyword to increase usability for the other system sharing the database or area. LOCAL is the default.

NOFEOV

Specifies that there is no forced end of volume, so that the log does not switch to the next OLDS and simple checkpoint is not taken.

NOPFA

Specifies to skip the call to DBRC that sets the Prohibit Authorization flag in the RECON data set for the database or area. You can use this keyword when you need to authorize the database for use after it is offline, for example, for offline utilities. By using this keyword, DBRC does not prevent further authorizations for the database or area.

NOPFA can be specified only with the GLOBAL keyword.

Usage notes

The /DBRECOVERY command can be used on HALDB databases.

Use of the ALL parameter indicates that the command applies to all databases, even those not opened.

The /DBRECOVERY command closes and deallocates the databases, and deauthorizes them with DBRC. Once the database or area referenced by /DBRECOVERY is closed, the IMS log switches to the next OLDS (unless you specify the NOFEOV keyword). This switch to the next OLDS is marked as a recovery point for log archiving purposes. IMS issues a simple checkpoint.

The /DBRECOVERY command deletes the randomizer routine from memory.

IMS databases, DEDBs, and DEDB areas closed by the master terminal operator with the /DBRECOVERY command can be used as input to the offline IMS Database Recovery utility. The Database Recovery utility runs in a batch region.

If the /DBRECOVERY command does not deallocate a data set because a VSAM data set hardware error occurred, use the VARY nnn,OFFLINE,FORCE command to deallocate the data set (where nnn is the number of the device).

This command can be issued to an IMSplex using the Batch SPOC utility.

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 and the UPDATE DB START(ACCESS) commands. 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 NODBR keyword can be specified in the DFSVSMxx member of the IMS PROCLIB data set to prevent a /DBRECOVERY command from processing against a database that has in-doubt EEQEs. NODBR does not apply to Fast Path databases.

Equivalent IMS type-2 commands

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