/DBDUMP 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

                      .--------.                            
                      V        |  .-LOCAL-------------.     
>>-+-/DBDUMP-+--DB--+---dbname-+--+-------------------+-+------->
   '-/DBD----'      |             '-GLOBAL--+-------+-' |   
                    |                       '-NOPFA-'   |   
                    '-+-MSDB-+--+-------+---------------'   
                      '-ALL--'  '-LOCAL-'                   

>--+--------+--------------------------------------------------><
   '-NOFEOV-'   

Keywords

The following keywords are valid for the /DBDUMP command:

DB

Specifies the databases to which the /DBDUMP command applies. When the /DBDUMP command is entered, the message processing regions using the specified databases are terminated at the conclusion of processing their current transactions, in preparation to close the database and enable it to be opened for input only.

If a DL/I database specified in the command is being used by a batch message processing region, an error message is returned to the master terminal. When this message is issued, the command is ignored for the database named in the message; processing continues for the other databases specified in the command. The master terminal operator must wait until the batch message processing concludes processing before reentering the command.

As the message processing regions terminate programs, the data sets of the named databases in the command are closed. The IMS™ log switches to the next OLDS. This switch to the next OLDS is marked as a recovery point for log archiving purposes. IMS issues a simple checkpoint. The scheduling of transactions is then resumed, although no transactions will be allowed to update the specified databases. Programs with update intent will be scheduled, but update calls to the database will result in a 3303 pseudoabend or a BA status if the INIT call was issued.

/DBDUMP can be used to dump all the MSDBs to the MSDB dump data set by specifying the reserved parameter MSDB with the DB keyword when entering the /DBDUMP DB command or by entering the /DBDUMP DB ALL command. The MSDBs dumped to the MSDB dump data set can be used as input to the MSDB Dump Recovery utility. A specific MSDB cannot be a parameter of the DB keyword.

The /START DB command resets the effect of the /DBDUMP command. The /START command is not required for MSDBs, because the data for these databases resides in processor storage, and the databases are never closed.

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 before the database is acted upon. This results in either a commit point or transaction termination.

GLOBAL

Applies when an IRLM is active and specifies that the command applies to all online subsystems sharing the database. The /DBDUMP command with the GLOBAL keyword puts the database in read status and prevents transactions from updating the database in all online subsystems that share the database.

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

If global database status is maintained, the global status maintained in RM is also updated. The global status is set to STOUPDS.

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) command to set the global status of the resources in RM.

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

The GLOBAL keyword is mutually exclusive with the ALL parameter or the MSDB parameter and causes the command to be rejected if both parameters are specified. The GLOBAL keyword requires that IRLM be active and will cause the command to be rejected if IRLM is not active.

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 which 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 the 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 only applies to the subsystem in which the command is entered. This command does not affect any other subsystem sharing the database. The LOCAL keyword can be used to restrict concurrent updates. LOCAL is the default.

NOFEOV

Specifies that there is no forced end of volume, so that the IMS log does not switch to the next OLDS. If NOFEOV is specified without the MSDB keyword, a simple checkpoint is not taken.

NOPFA

Specifies that the call to DBRC that sets the Read Only flag in the RECON data set for the database or partition is to be skipped. You can use this keyword when you need to authorize the database for update after the command has been processed. By using this keyword, DBRC does not prevent authorizations for update for the database or partition. NOPFA can be specified only with the GLOBAL keyword.

Usage notes

The /DBDUMP command can be used on HALDB databases.

In an IMSplex, the output of the /DBD command is changed when the command is entered through the OM API. In this case, the DFS058I message is not returned to OM. The command response returned to OM contains one or more of the following messages as appropriate to the database type and the command completion.

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

Full Function Database messages: DFS132, DFS160, DFS216, DFS0488I, DFS1407, DFS2026, DFS3318I, DFS3320I, DFS3321I, DFS3325I, DFS3462I, DFS3463I, DFS3466I

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 with the exception of the /START DATABASE 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 /DBDUMP 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 /DBDUMP command and the IMS type-2 commands that perform similar functions.