UPDATE DB command

Subsections:

• Environment
• Syntax
• Keywords
• Usage notes
• Equivalent IMS type-1 commands
• Output fields
• Return and reason codes
• Examples

Environment

The following table lists the environments (DB/DC, DBCTL, and DCCTL) from which the UPDATE DB command and keywords can be issued.

Syntax

                              .-,-------.        
                              V         |        
>>-+-UPDATE-+--DB--NAME--+-(----dbname*-+--)-+------------------>
   '-UPD----'            '-(*)---------------'   

>--+-START--+-(ACCESS)--+--------------------------+--+---------+-+-+-->
   |        |           '-SET(ACCTYPE(-+-BRWS-+-))-'  '-AREA(*)-' | |   
   |        |                          +-EXCL-+                   | |   
   |        |                          +-READ-+                   | |   
   |        |                          '-UPD--'                   | |   
   |        '-(QUIESCE)--+-------------------+--------------------' |   
   |                     '-SET(TIMEOUT(nnn))-'                      |   
   +-STOP--+-(ACCESS)--+--------------------------------------------+   
   |       +-(SCHD)----+                                            |   
   |       +-(UPDATES)-+                                            |   
   |       '-(QUIESCE)-'                                            |   
   +-SET(LOCK(-+-ON--+-))-------------------------------------------+   
   |           '-OFF-'                                              |   
   '-SET(RESIDENT(-+-N-+-))-----------------------------------------'   
                   '-Y-'                                                

                                    .-SCOPE(ALL)----.   
>--+-----------------------------+--+---------------+----------><
   |         .-,-------------.   |  '-SCOPE(ACTIVE)-'   
   |         V               |   |                      
   '-OPTION(---+-ALLRSP----+-+-)-'                      
               +-DBALLOC---+                            
               +-FEOV------+                            
               +-HOLD------+                            
               +-NOBACKOUT-+                            
               +-NODBALLOC-+                            
               +-NOFEOV----+                            
               +-NOHOLD----+                            
               +-NOOPEN----+                            
               +-NORAND----+                            
               +-OPEN------+                            
               '-PFA-------'                            

Keywords

The following keywords are valid for the UPDATE DB command:

AREA(*)

Specifies the areas of the databases that are to be processed or, if you specify AREA(*), indicates that the command applies to all the areas in the database.

The UPDATE DB START(ACCESS) AREA(*) command starts the DEDB and all of its areas and allows scheduling of new applications against the DEDB.

The AREA(*) keyword is ignored for non-DEDB databases. You cannot specify both the AREA(*) and the NAME(*) keywords. If you specify the AREA(*) keyword with the START(ACCESS) SET(ACCTYPE) keyword, all the DEDB areas are restarted after they are stopped by the START(ACCESS) SET(ACCTYPE) keyword.

NAME()

Specifies the 1-8 character name of the database (DBD name). Wildcards can be specified in the name. The name is a repeatable parameter. If the NAME parameter specified is a specific or wildcard name, command responses are returned for all the resource names that are processed. For NAME(*) command responses are returned only for the resource names that resulted in an error. OPTION(ALLRSP) can be specified with NAME(*) to obtain the command responses for all the resource names that are processed.

NAME(*) is the designed method on IMSplex commands to enable the user to specify that the command applies to all the database resources.

The database names that match the generic or wildcard parameter are processed. For specific or wildcard names, response lines are returned for all the database names that are processed.

When the database specified is a DEDB, a response line is returned for the DEDB name. A response line is also returned for all the areas of a DEDB that resulted in errors. A response line is not returned for the areas of a DEDB for which the command action is successful.

OPTION()

Specifies additional functions to be performed along with the UPDATE DB command.

ALLRSP

Indicates that the response lines are to be returned for all resources that are processed on the command. The default action is to return response lines only for the resources that resulted in an error. It is only valid with NAME(*) or AREA(*). ALLRSP is ignored for other NAME values.

DBALLOC

Indicates that the database is to be allocated when it is started.

DBALLOC can be specified with START(ACCESS) only. DBALLOC is the default action when specific database names are specified on the command. Only one of DBALLOC or NODBALLOC can be specified.

OPTION(DBALLOC) is not valid for a HALDB master.

FEOV

Indicates to force end of volume after the command processing is complete.

The IMS™ log switches to the next OLDS, and a simple checkpoint is taken unless specified with STOP(QUIESCE). This switch is marked as a recovery point for log archiving purposes. A simple checkpoint is not taken when specified with STOP(QUIESCE).

FEOV is valid only with START(QUIESCE) OPTION(NOHOLD), STOP(QUIESCE), STOP(UPDATES), or STOP(ACCESS), and does not apply to an RSR tracker.

OPTION(FEOV) is the default when specified with START(QUIESCE) OPTION(NOHOLD) or STOP(QUIESCE).

When START(QUIESCE) or STOP(QUIESCE) is specified, OPTION(FEOV) is the default; that is, the end of volume will be forced after the quiesce point has been reached. The logs are switched before the quiesce is released so that any new updates occur on the new IMS log. Switching of the logs occurs when STOP(QUIESCE) is issued to release a quiesce from a previous START(QUIESCE) OPTION(HOLD).

HOLD

Specifies that after the quiesce has been achieved successfully, the database should remain quiesced. A subsequent STOP(QUIESCE) would be required to release the quiesce on the database.

OPTION(HOLD) is valid only with the START(QUIESCE) keyword. OPTION(HOLD) is mutually exclusive with OPTION(NOHOLD).

NOBACKOUT

Indicates to suppress backout restart for a database not registered in DBRC.

NOBACKOUT can be specified with START(ACCESS) only and is not valid with NAME(*). OPTION(NOBACKOUT) is not valid for a HALDB master.

NODBALLOC

Indicates that the database is not to be allocated when it is started.

The database is allocated when it is scheduled. NODBALLOC can be specified with START(ACCESS) only. NODBALLOC is the default action when NAME(*) is specified. Only one of DBALLOC or NODBALLOC can be specified. OPTION(NODBALLOC) is ignored for HALDB masters.

NOFEOV

Indicates to not force end of volume after the command processing is complete. The IMS log does not switch to the next OLDS and a simple checkpoint is not taken.

OPTION(NOFEOV) can be specified only with START(QUIESCE) OPTION(NOHOLD), STOP(ACCESS), STOP(QUIESCE), or STOP(UPDATES). OPTION(NOFEOV) is the default except when START(QUIESCE) or STOP(QUIESCE) is specified.

NOHOLD

Specifies that after the quiesce has been achieved successfully the database should automatically release the quiesce. If either HOLD or NOHOLD is not specified, NOHOLD is assumed.

OPTION(NOHOLD) is valid only with the START(QUIESCE) keyword. OPTION(NOHOLD) is mutually exclusive with OPTION(HOLD).

NOOPEN

Indicates that the database is not to be opened when it is started.

NOOPEN can only be specified with START(ACCESS). NOOPEN is the default action unless the database has EEQE's.

Only one of OPEN or NOOPEN can be specified. OPTION(NOOPEN) is not valid for a HALDB master.

NORAND

Indicates that the randomizer stays loaded while the UPDATE DB STOP(ACCESS) command is being processed.

This option solves the problem of the Extended Common Service Area (ECSA) becoming fragmented by continuous unloading and reloading of randomizers.

Restriction: OPTION(NORAND) only works for Fast Path DEDBs. It is ignored for full-function databases.

OPTION(NORAND) status is not maintained in the RM resource structure if global database status is maintained. If an UPD DB STOP(ACCESS) OPTION(NORAND) command is issued for a Fast Path DEDB, the STOACC status is saved in the RM resource structure. The randomizer is unloaded when the global STOACC status is applied.

OPEN

Indicates that the database is to be opened when it is started. OPEN can be specified only with START(ACCESS). Specifying START(ACCESS) OPTION(OPEN) causes the randomizer routine or the selection partition routine to be loaded.

The randomizer is loaded into memory the first time it is referenced by a database. If no other database references the randomizer and the randomizer is deleted from memory, the randomizer is deleted from memory.

OPEN cannot be specified with NAME(*) or if NODBALLOC is specified. Either OPEN or NOOPEN can be specified. OPTION(OPEN) is not valid for a HALDB master, but the partition structure rebuild is done if structure rebuild is needed and if only one HALDB master was specified in the command. No rebuild is attempted if there is more than one database name listed in the command.

The UPDATE DB AREA(*) START(ACCESS) OPTION(OPEN) command starts and opens all areas under one or more DEDBs specified in the NAME() keyword even if the areas are not registered on DBRC as PREOPEN. The OPTION(OPEN) is processed locally by all IMS systems that receive the command and is not maintained as a global status in RM.

PFA

Sets or resets the prevent further authorization (PFA) or the read-only status in the RECON for the database. Use the PFA option with UPDATE DB START(ACCESS) to enable access to a database. Use the PFA option with the UPDATE DB STOP (ACCESS|SCHD|UPDATES) command to prevent access to a database. PFA is optional. If you specify OPTION(PFA), the command master updates the RECON data set only if the command is successful at the master IMS. All other IMS systems that receive the command process is locally. OPTION(PFA) is not valid with SET(LOCK(ON|OFF)).

SCOPE()

Specifies where IMS should apply the change.

ALL

Changes are applied to the IMS systems that are currently active and to which the command is routed. Changes are also applied globally by updating the value maintained by RM. The global status that RM saves can be propagated across some IMS restarts. When an IMS system starts, it obtains global status information from RM. Maintaining global status in RM allows IMS systems to start without a specific setting or status for an area.

If the status or attribute that this command is updating is not maintained globally by RM, then the command is processed as if SCOPE(ACTIVE) is specified. If this command updates status or attributes that are both global and local, RM only updates the global status or attributes.

You must specify if the global area status must be maintained in RM. You can specify this during IMS initialization in either 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.

Restriction: SCOPE(ALL) does not apply to the quiesce function. The scope of a quiesce is always all instances of the database usage across the IMSplex. There is not a global status of QUIESCE for a database. For START(QUIESCE) and STOP(QUIESCE), SCOPE(ALL) is the same as SCOPE(ACTIVE).

ACTIVE

Changes are applied to the active IMS systems to which the command is routed to. Any global status information maintained in the RM resource structure is not changed by the SCOPE(ACTIVE) command.

Restriction: SCOPE(ACTIVE) does not apply to the quiesce function. The scope of a quiesce is always all instances of the database usage across the IMSplex.

RM maintains global status information for some database attributes and values. IMS updates those values in RM based on commands or other internal events. When SCOPE(ALL) is specified, every IMS system that processes the command updates information in its local control blocks. Only the IMS command master calls RM to update the information globally.

The UPDATE DB command keywords that update information locally in the active IMS system and globally in RM when SCOPE(ALL) is specified include:

• START(ACCESS)
• START(ACCESS) SET(ACCTYPE())
• STOP(ACCESS|SCHD|UPDATES)
• SET(LOCK(ON|OFF))

If global status is maintained, UPD DB START(ACCESS) STOP(ACCESS,SCHD,UPDATES) SCOPE(ALL) writes an X'4C' log record to include global status and global time stamp.

SET()

Specifies the attribute values to be changed or sets the database state.

ACCTYPE

Specifies the access intent for the named database. ACCTYPE() can only be specified if START(ACCESS) is also specified. This keyword overrides the database access intent specified at system definition.

If an UPDATE DB START(ACCESS) SET(ACCTYPE) command is issued for a HALDB master database, the access intent for the master database is set. The access intent settings for the partitions in the database are not affected. If an UPDATE DB START(ACCESS) SET(ACCTYPE) command is issued for one or more HALDB partitions, the access intent for the partitions is set. The access intent for the master database is not affected.

Because each partition has the access limitation of both itself and the master database, you might have to update the access intent of the partitions when you update the access intent of the master database. For example, if the master database and the partitions all have an access intent of read (READ) and you want to change the access intent for the master database and all of the partitions to update (UPD), issue the UPDATE DB START(ACCESS) SET(ACCTYPE) command for the master database and each of the partitions.

BRWS

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

EXCL

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

READ

The database is available for read-only processing in this IMS subsystem. Programs with update intent can be scheduled, but cannot update the database. Access type READ differs from access type BRWS 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.

UPD

The database is for update as well as read processing in the IMS subsystem.

RESIDENT

Specifies the resident option. The RESIDENT(N) option takes effect right away. The RESIDENT(Y) option takes effect at the next restart, unless the database was updated as RESIDENT(Y) after the checkpoint from which this IMS is performing emergency restart. A database defined as a DEDB in ACBLIB always sets the RESIDENT(Y) attribute when the DEDB is loaded, regardless of the RESIDENT value specified. RESIDENT(N) is rejected for a DEDB.

N

The DMB associated with the named database resource is not made resident in storage. The DMB is loaded at scheduling time.

Y

The DMB associated with the named database resource is made resident in storage at the next IMS restart. At the next IMS restart, IMS loads the DMB and initializes it. A resident database is accessed in local storage, which eliminates I/O to the ACBLIB. In an online environment, the DMB control blocks are stored in the ACBLIB. If the DLI/SAS address space exists, DLI/SAS loads the DMB, otherwise, it is the IMS control region that loads it. This makes the DMB dependent on the existence of the corresponding database resource.

The database must be stopped in order for this attribute to be changed. You may need to issue a /DBR DB command or an UPDATE DB STOP(ACCESS) command to stop the database before issuing an UPDATE DB SET(RESIDENT(Y|N)) command.

An UPDATE command specified with SET(RESIDENT) is not valid if online change for MODBLKS is enabled (DFSDFxxx or DFSCGxxx defined with MODBLKS=OLC, or MODBLKS not defined). The UPDATE DB command changes a MODBLKS database to dynamic, if the RESIDENT attribute is changed. These commands are recoverable.

LOCK

Locks and unlocks the specified database. NAME(*) cannot be specified with SET(LOCK(ON|OFF)).

ON

Locks and prevents subsequently scheduled programs from accessing the database, without affecting currently scheduled programs. The database is not closed.

For a shared secondary index database, an UPDATE DB SET(LOCK(ON)) on the first secondary index or subsequent secondary indexes affects only the named database.

OFF

Unlocks the specified databases and resets the effect of an UPDATE DB SET(LOCK(ON)) command. An UPDATE DB SET(LOCK(OFF)) on the first secondary index or subsequent secondary indexes affects only the named database.

TIMEOUT(nnn)

Specifies the number of seconds to wait before a timeout occurs in a database quiesce. The timeout value can be 1 - 999 seconds. The TIMEOUT parameter value can override the DBQUIESCETO parameter in the DFSCGxxx member of the IMS PROCLIB data set. If the TIMEOUT parameter is omitted and the DBQUIESCETO parameter is not specified, the default timeout value is 30 seconds. The TIMEOUT keyword is valid only with the START(QUIESCE) keyword.

START()

Specifies the attributes that are to be started.

ACCESS

The UPDATE DB START(ACCESS) command starts the database and permits access from transactions or programs. The UPDATE DB START(ACCESS) command resets the actions done by a prior UPDATE DB STOP(ACCESS), UPDATE DB STOP(SCHD), or UPDATE DB STOP(UPDATE). The access intent is set to the database access intent specified at system definition unless SET(ACCTYPE) is specified.

The UPDATE DB START(ACCESS) command can be used to allocate or reallocate all databases other than DEDBs. For a DEDB, an UPDATE AREA command can be used to allocate or reallocate the DEDB areas.

For a DEDB, the UPDATE DB START(ACCESS) command also causes any unloaded randomizer that was specified in the DBD source to be reloaded.

When the UPDATE DB START(ACCESS) command is specified for a HALDB partition, the partition is not allocated unless it has EEQEs, the OPEN keyword is specified, or it was previously authorized but not allocated. The action taken to allocate the data sets is dependent on the status of the master database and its availability.

If the UPDATE DB START(ACCESS) command is issued for a HALDB master database, access to the partitions is enabled if the partitions are not stopped or offline. The command updates the status of the master database. The command does not update the status of the partitions. If a partition is stopped or offline, it remains stopped or offline and must be explicitly started. If the ACCTYPE parameter is used, the access intent setting for the master database is set, but the access intent settings for the partitions in the database are not affected.

If the UPDATE DB START(ACCESS) command is issued for a HALDB partition, the command updates the status of the partition. The command does not update the status of the master database. If the ACCTYPE parameter is used, the access intent setting for the partition is set, but the access intent setting for the master database is not affected.

The UPDATE DB START(ACCESS) command may reset the USTOPPED status for transactions that are suspended. If the transaction is suspended and its processing program has access to the started database, the UPDATE DB START(ACCESS) command results in the USTOPPED attribute being reset. Any messages on the suspend queue for that transaction is transferred to the normal processing queue.

If there was a prior dynamic backout or emergency restart backout failure, then the UPDATE DB START(ACCESS) command attempts to perform the backout again.

If the database is registered to DBRC, then DBRC is informed when batch backout is successfully executed, and the failing backout is not attempted again when an UPDATE DB START(ACCESS) command is issued.

The UPDATE DB START(ACCESS) command is not processed for the databases being accessed by batch programs.

For a HIDAM database, the UPDATE DB START(ACCESS) command must be issued for both the index and the data area DBD. If a backout failure occurs for this database, the command causes the backout to be attempted again.

On an RSR tracker, the UPDATE DB START(ACCESS) command can be used to resume tracking for those databases that were stopped by a tracking subsystem processing. The command can also be used to start online forward recovery (OFR) for those databases that are not current with mainline tracking.

For shared secondary index databases, the UPDATE DB START(ACCESS) can be issued on the first secondary index or subsequent secondary indexes to undo the actions of the prior UPDATE DB STOP(SCHD) and UPDATE DB STOP(UPDATES) commands.

Additional functions can be performed with START(ACCESS) by specifying the OPTION keyword. OPTION(DBALLOC | NODBALLOC), OPTION(NOBACKOUT), OPTION(NOOPEN | OPEN) can be specified along with START(ACCESS). The OPTION keyword is not valid for a HALDB master.

QUIESCE

Specifies that the databases named on the command are to be quiesced to establish a new recovery point. The scope of a quiesce is always all instances of the database usage across the IMSplex. There is no quiesce that would apply only to a subset of the IMSplex.

STOP()

Specifies the attributes that are to be stopped.

ACCESS

Starts offline processing of the database. This processing closes and deallocates the database and deauthorizes the database to DBRC. An UPDATE DB START(ACCESS) command is required to reset the effect of an UPDATE DB STOP(ACCESS).

Specifying UPDATE DB STOP(ACCESS), UPDATE DB STOP(UPDATES), or UPDATE DB STOP(SCHD) can cause the randomizer routine or the selection partition routine to be deleted from memory.

OPTION(NOFEOV) is the default action for STOP(ACCESS). The IMS log is not switched to the next OLDS and a simple checkpoint is not taken. OPTION(FEOV) can be specified on the command to switch to the next OLDS and take an IMS simple checkpoint.

If the UPDATE DB STOP(ACCESS) command is issued for a HALDB master database, processing acts on the entire database. That is, IMS closes and deallocates all partition data sets and unauthorizes all partitions in the database. The command updates the status of the master database. The command does not update the status of the partitions.

If the UPDATE DB STOP(ACCESS) command is issued for a partition, all data sets in the partition are closed and deallocated and the partition is deauthorized. The command also updates the status of the partition. The command does not update the status of the master database. Issue the UPDATE DB STOP(ACCESS) for a partition only if you are stopping access to a subset of the partitions in a HALDB database. If you are stopping access to the entire database, issue the command for the master database, not for the partitions.

The UPDATE DB STOP(ACCESS) command can be used on a database readiness level (DLT) tracker to take shadow areas and databases offline for image copy and recovery. The command can also be used to stop online forward recovery (OFR) in progress for the specified database.

The UPDATE DB STOP(ACCESS) command does not deallocate a data set if a VSAM data set hardware error occurred. For shared secondary index databases, an UPDATE DB STOP(ACCESS) on the first secondary index affects all databases sharing the secondary index data set. An UPDATE DB STOP(ACCESS) command on the subsequent secondary indexes affects only the named database.

QUIESCE

Specifies that the databases named on the command should be made available again by releasing the quiesce on the databases.

Unlike START(QUIESCE), where each database resource listed must be quiesced in order for the command to complete successfully, STOP(QUIESCE) continues to process each listed resource even if some resources are not in quiesced state or cannot be released from quiesced state. For those resources that are not in quiesced state or cannot be released from quiesced state, the command returns a response line for each of those resources.

SCHD

Stops or prevents subsequently scheduled programs from accessing the database, without affecting currently scheduled programs. The database is not closed.

An UPDATE DB START(ACCESS) command can be used to reset the effect of an UPDATE DB STOP(SCHD) command.

If the command is issued for a DEDB or MSDB, programs using the database will not be scheduled. For other databases, the programs will still be scheduled. If the INIT call was issued, however, a call against the database will result in either a 3303 pseudoabend or a BA status code.

When the UPDATE DB STOP(SCHD) command is issued for a database that is in use by an MPP region, the command is processed after the region completes processing the current message. After the current message processing is complete, the application program receives a QC status indicating no more messages even if there are messages to be processed.

When the UPDATE DB STOP(SCHD) command is issued for a database that is in use by a BMP region, the command is rejected.

If the UPDATE DB STOP(SCHD) command is issued for a HALDB master database, access to all partitions in the database is stopped for subsequently scheduled programs. The command updates the status for the master database. The command does not update the status of the partitions.

If the UPDATE DB STOP(SCHD) command is issued for a HALDB partition, the status of the partition is updated. The command does not update the status of the master database. Use the UPDATE DB STOP(SCHD) command only for a partition or a subset of partitions in a HALDB database that you want to stop. To stop the entire database, issue the command for the master database, not for the partition.

In a DBCTL system, CCTL can specify LONG or SHORT when it schedules a PSB. When the UPDATE DB STOP(SCHD) command is issued for a database that is in use by a LONG thread, the command is rejected. When the command is issued for a database that is in use by a SHORT thread, the thread completes before the command is processed.

For a shared secondary index database, an UPDATE DB STOP(SCHD) on the first secondary index or subsequent secondary indexes affects only the named databases.

UPDATES

Stops or prevents transactions or programs from updating the specified DL/I database.

STOP(UPDATES) is not valid for DEDBs or MSDBs.

An UPDATE DB START(ACCESS) command is required to reset the effect of an UPDATE DB STOP(UPDATES) command.

When the UPDATE DB STOP(UPDATES) command is processed, the message processing regions using the specified database are terminated at the conclusion of processing their transactions in preparation to close the database and enable the databases to be opened input only. As the message processing regions terminate programs, the data sets of the database are closed.

OPTION(FEOV) forces the IMS log to switch to the next OLDS. This switch is marked as a recovery point for log archiving purposes. IMS also issues a simple checkpoint. OPTION(NOFEOV), which is the default, overrides this action.

After the command is processed, the scheduling of transactions is resumed. No transactions will be allowed to update the specified databases. Programs with update intent will be scheduled, but update calls to DL/I databases will result in a 3303 pseudoabend, a BA, or BB status code. The pseudoabend or status codes appear only if the application program informed IMS through the INIT STATUS GROUPA or GROUPB call that it is prepared to accept status codes regarding data unavailability.

An UPDATE DB STOP(UPDATES) on the first secondary index affects all databases sharing the secondary index data set. An UPDATE DB STOP(UPDATES) on subsequent secondary indexes affects only the named database.

If the UPDATE DB STOP(UPDATES) command is issued for a HALDB master database, all partition data sets are closed and reopened and all partitions in the database are reauthorized. The command also updates the status of the master database. It does not update the status of the partitions.

If the UPDATE DB STOP(UPDATES) command is issued for a partition, all data sets in the partition are closed and reopened and the partition is reauthorized. The command also updates the status of the partition. The command does not update the status of the master database. Issue the UPDATE DB STOP(UPDATES) for a partition only if you want to stop updates for a subset of the partitions in a HALDB database. To stop updates for the entire database, issue the command for the master database, not for the partition.

Usage notes

The UPDATE DB command can only be specified through the OM API and can only be processed by the DB/DC and DBCTL environments. When the UPDATE DB command is issued, it only applies to the IMS system to which it is routed. The command is not processed by other IMS systems in the IMSplex that share the database but do not receive the command. OM selects one IMS as the command master.

The command is not allowed on the XRF alternate system, RSR tracker, or FDBR region.

Resources exist for the life of IMS unless they are deleted using a DELETE command or online change for MODBLKS. Resource updates are recoverable across an IMS warm start or emergency restart. Updates to database runtime resource definition attributes such as RESIDENT are lost if IMS is cold started, unless cold start imports definitions that were exported while IMS was up.

Each database is updated individually, unlike the online change process where either all databases are updated or no databases are updated. Some runtime resource definition values for a database can only be updated if the database is not in use. If the database is in use, the update fails. An exception to this rule is status. You can update the status of a database while it is in use. In a sysplex environment with multiple IMS systems, the update might succeed on some IMS systems and fail on others.

Runtime resource definition attributes include the following: RESIDENT.

An UPDATE DB command that changes runtime resource definition attributes such as the RESIDENT attribute is rejected for MSDBs and DEDBs.

The UPDATE DB command returns CCTXT with a nonzero completion code. The CCTXT can be up to 32 bytes, and it includes information about what the completion code means. The UPDATE DB SCOPE(ALL) command returns a response line with the completion code for the global status update. The CCTXT for that code is GBL CC.

If all the attributes specified by the UPDATE command are already defined for the resource, no update is actually made, no resources are quiesced, no log record is created, and a completion code of zero is returned. This avoids unnecessary overhead when no action needs to be taken.

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.

If received during an UPD DB NAME(partname) START(ACCESS) command, where partname is a HALDB partition that was added and partition structure rebuild has not been done, then issue an UPD DB NAME(haldbmst) START(ACCESS) OPTION(OPEN), where haldbmst is the partition's master, followed by an UPD DB NAME(partname) START(ACCESS) command or issue a call for a key in the key range of the new or redefined partition. This will invoke partition structure rebuild and allow the partition to be used.

Equivalent IMS type-1 commands

Output fields

Return and reason codes

An IMS return and reason code is returned to OM by the UPDATE DB command. The OM return and reason codes that may be returned as a result of the UPDATE DB command are standard for all commands entered through the OM API.

The following table includes the return and reason codes and a brief explanation of the codes. The return or reason code returned for the command might also indicate an error from a CSL request.

Table 4. Return and reason codes for the UPDATE DB command

Return code	Reason code	Meaning
X'00000000'	X'00000000'	Command completed successfully. The command output contains a line for each resource, accompanied by its completion code. If NAME(*) is specified without OPTION(ALLRSP), no output lines are returned. See the completion code table for details.
X'00000008'	X'00002004'	An invalid keyword or filter, or more than one keyword is specified on the UPDATE DB command.
X'00000008'	X'00002008'	Invalid number of keywords. Either a SET, START, or STOP keyword is required.
X'00000008'	X'00002011'	UPDATE DB command processing terminated because you cannot specify more than one keyword with the NAME(*) keyword.
X'00000008'	X'00002014'	The UPDATE DB command is not processed because an invalid character is found in the database name parameter.
X'00000008'	X'00002040'	More than one filter or keyword value is specified on the UPDATE DB command. Either more than one keyword or an invalid combination of filters was specified. For example, UPDATE DB NAME(dbname) START(ACCESS) OPTION(NORAND) or UPDATE DB NAME(dbname) STOP(UPDATES) OPTION(NORAND)
X'00000008'	X'00002048'	Invalid SET attribute.
X'0000000C'	X'00003000'	Command was successful for some resources but failed for others. The command output contains a line for each resource, accompanied by its completion code. If NAME(*) is specified without OPTION(ALLRSP), output lines are only returned for resources with nonzero completion codes. See the completion code table for details.
X'0000000C'	X'00003004'	Command was not successful for any of the resources. The command output contains a line for each resource, accompanied by its completion code. The completion code indicates the reason for the error with the resource name. The completion codes that can be returned by the UPDATE DB command are listed in the UPDATE DB completion code table.
X'00000010'	X'00004000'	The UPDATE DB command is not processed as restart is in progress.
X'00000010'	X'0000400C'	Command is not valid on the XRF alternate.
X'00000010'	X'00004014'	Command is not valid on the RSR tracker.
X'00000010'	X'00004024'	The UPDATE DB command is not processed because Fast Path is not installed.
X'00000010'	X'00004120'	Online change phase is in progress.
X'00000010'	X'00004124'	An UPDATE DB command that specified either START(QUIESCE) or STOP(QUIESCE) was rejected, because another process of the same type, such as another command with QUIESCE specified, was already in progress. Wait until the other process has completed.
X'00000010'	X'000041F0'	The UPDATE DB command is not processed because an IMS Checkpoint is in progress.
X'00000010'	X'000041F4'	The UPDATE DB command is not processed because an MSDB Checkpoint is in progress.
X'00000010'	X'000041F8'	The UPDATE DB command is not processed because a takeover is in progress.
X'00000010'	X'00004200'	Commands are not processed because IMS shutdown is in progress.
X'00000010'	X'00004208'	Invalid command for RMENV=NO.
X'00000010'	X'00004300'	Command is not allowed because online change for MODBLKS is enabled (DFSDFxxx or DFSCGxxx defined with MODBLKS=OLC, or MODBLKS not defined).
X'00000010'	X'00004320'	The UPDATE DB command is not processed because another UPDATE DB START(QUIESCE) or UPDATE DB STOP(QUIESCE) command is in progress.
X'00000010'	X'00004325'	DB quiesce phase is in progress.
X'00000010'	X'00004400'	MINVERS in the RECON data sets is not 11.1.
X'00000014'	X'00005004'	DFSOCMD response buffer could not be obtained.
X'00000014'	X'00005008'	DFSPOOL storage could not be obtained.
X'00000014'	X'00005000'	The UPD DB command processing terminated because IMODULE GETSTOR storage could not be obtained.
X'00000014'	X'0000500C'	AWE could not be obtained.
X'00000014'	X'00005014'	The UPDATE DB command processing terminated because BCB storage could not be obtained.
X'00000014'	X'0000501C'	The UPD DB command processing terminated because IMODULE GETMAIN storage could not be obtained.
X'00000014'	X'00005FFF'	The UPDATE DB command processing terminated because of an internal error.

Completion codes

The following table includes an explanation of the completion codes. Errors unique to the processing of UPDATE DB command are returned as completion codes. A completion code is returned for each action against an individual resource.

Table 5. Completion codes for the UPDATE DB command

Completion code	Completion code text	Meaning
0		The command completed successfully for the resource.
8	COMMAND COMPLETE FOR SOME	Some. The command completed with error for some of the AREAS of the DEDB. Response lines for the area names in error are returned.
C	COMMAND COMPLETE FOR NONE	None. The command completed with error for all the AREAs of the DEDB. Response lines for the area names in error are returned. This error is returned when all the databases could not be quiesced.
10	NO RESOURCES FOUND	Database name is invalid, or the wildcard parameter specified does not match any database names.
17	ANOTHER CMD IN PROGRESS	This error is returned when the quiesce could not be started because another database command was in progress.
23	DB STOP ACCESS IN PROGRESS	A /DBRECOVERY, or UPDATE DB STOP(ACCESS) command to stop database access is in progress. This takes the database offline.
25	DB STOP UPDATES IN PROGRESS	A /DBDUMP or UPDATE DB STOP(UPDATES) command to stop database updates is in progress.
26	DEDB STOP IN PROGRESS	/DBRECOVERY, /STOP, or UPDATE DB STOP(SCHD) command to stop database scheduling is in progress for a DEDB.
31	NOT ALLOWED FOR A DEDB	Database is a DEDB. The command entered is not valid for the DEDB in the IMS environment.
32	NOT ALLOWED FOR AN MSDB	Database is an MSDB. The command entered is not valid for the MSDB in the IMS environment.
33	NOT ALLOWED FOR A HALDB MASTER	Command invalid HALDB master. The command OPTION is invalid for the HALDB master but partition structure rebuild will be done if structure rebuild is needed and if only one HALDB master was specified in the command. No rebuild will be attempted if there is more than one database name listed in the command. If there are multiple database names listed in the command and all are invalid except the HALDB master, then rebuild will be attempted if needed.
48	NOT ALLOWED FOR IMS RESOURCE	The specified UPDATE command is not allowed for an IMS descriptor or resource. DFSDSDB1 is an example of an IMS descriptor. The only IMS descriptor attribute you can update is DEFAULT(Y).
53	NO RM ADDRESS SPACE	This error is returned when the command could not be processed because the RM address space is not present.
55	NO FAST PATH INSTALLED	No Fast Path installed. The command failed because Fast Path is not installed.
56	FF DB + LSO=Y + TRK = ERROR	Command is invalid on the RSR tracker because of the LSO=Y option.
65	DMB POOL STORAGE ERROR	DMB pool storage error. The command failed because of DMB pool storage request failure.
66	DMB POOL FULL	DMB pool full. The command failed because the DMB pool was full.
6C	NOT ALLOWED FOR A HALDB PARTITION	An UPDATE command specified a change to the residency option for a HALDB partition. The residency option is valid only for the master and not the partitions.
6F	REFERENCED BY PROGRAM	An UPDATE DB command is issued to change the resident option. There is a currently scheduled program that is referencing that database. The UPDATE command fails.
76	RECOVER CMD ACTIVE	/RECOVER START command is in progress to recover one or more databases with the database recovery services.
81	DBRC ERROR	DBRC error.
8C	RESOURCE IS STOPPED	The database is stopped. The database might be stopped by a command, such as UPDATE DB, /STOP DB, or /DBRECOVERY, or for some other reason, such as an error.
90	INTERNAL ERROR	Internal error. The command entered is not processed because of an internal error.
91	TIMEOUT ERROR	This error is returned when the quiesce could not be completed within the timeout period.
92	COMMAND PROCESSING ERROR	Command processing error. The command entered is not processed because of an error. A unique completion code could not be generated to explain the error. The message number and the return code that could not be converted to a completion code are listed in the error text.
A0	DYNAMIC ALLOCATION FAILED	Dynamic allocation failed. The command entered has not completed processing because the dynamic allocation failed for the DB. Some of the command processing might be completed before the error is detected.
A1	DB IS AUTHORIZED BY BATCH	Database is authorized by batch. The command entered has not completed processing because the database is authorized by batch. Some of the command processing might be completed before the error is detected.
A2	DB IS AUTHORIZED BY ANOTHER IMS	Database is authorized by another IMS. The command entered has not completed processing because the database is authorized by another active or abnormally terminated IMS and its authorization state is incompatible with the current authorization request.
A3	AUTHORIZATION CHANGE FAILED	Authorization change failed. The DBRC CHNGAUTH request resulted in an error.
A4	DATABASE NOT REGISTERED TO DBRC	Database not registered to DBRC. The command processing has not completed because the database is not registered to DBRC. Some of the command processing might be completed before the error is detected.
A5	PREVENT FURTHER AUTH ON	Prevent further authorization ON. The command entered has not completed processing because the database or area is defined to DBRC as prevent further authorization. Some of the command processing might be completed before the error is detected.
A6	INVALID DATABASE RECORD IN RECON	Invalid database record in the RECON data set. The command entered has not completed processing because an invalid parameter was found during the evaluation process of the database usage compatibility. The database record might be invalid in the RECON data set. Some of the command processing might be completed before the error is detected.
A7	DBRC UNAUTH FAILED FOR CHNGAUTH	DBRC unauthorization failed during change authorization. The command entered has not completed processing because of an error during UNAUTH processing for the change authorization request.
A8	INVALID DB RECORD IN RECON	Invalid database record in RECON. An UPDATE DB SET(ACCTYPE) command is entered to change the database authorization level. An encoded state of zero is returned by DBRC during the change authorization processing. Some of the command processing might be completed before the error is detected.
A9	DB OR AREA AUTHORIZATION ERROR	Database or area authorization error. For a database, the command entered has not completed processing because of a database authorization error. For an area, area authorization to DBRC failed. Some of the command processing might be completed before the error is detected.
AA	DB IN USE-BMP	The UPDATE DB command was not successful because the database is in use by a BMP. Some of the command processing might be completed before the error is detected.
AB	DB IN USE-DBCTL LONG THREAD	The UPDATE DB command was not successful because the database is in use by a long-running DBCTL thread. Some of the command processing might be completed before the error is detected.
AC	FP AREA HELD-LONG BUSY WAIT	The UPDATE DB command was not successful because the AREA of the DEDB is in long-busy wait. Some of the command processing might be completed before the error is detected.
AD	DYNAMIC UNALLOCATION FAILED	The UPDATE DB command was not successful due to a dynamic unallocation error. Some of the command processing might be completed before the error is detected.
AE	DYNAMIC ALLOCATION ERROR	The UPDATE DB command was not successful due to a dynamic allocation error. No SVC99 is issued. Some of the command processing might be completed before the error is detected.
C1	OLR DDIR MISSING OR DFSPNT ZERO	Unknown DMB referenced for database. The command cannot be processed because an unknown data management block is referenced for the database. Refer to the DFS564I message put out to the system console to identify the DMB name that cannot be referenced.
CC	OLR IS ACTIVE FOR DATABASE	OLR is active for database. The command failed as OLR is active for the database.
D0	DATABASE CLOSE ERROR	Database close error. The command processing failed because of a database close error.
D1	DATABASE WRITE ERROR	Database write error. The command processing failed because of a database write error.
D2	DATABASE NEEDS BACKOUT	Database needs backout. The command processing failed as the database needs backout.
D3	DATABASE OR AREA NEEDS RECOVERY	Database or AREA needs recovery. The command processing failed as the database or area needs recovery.
D4	DATABASE NEEDS IMAGE COPY	Database needs image copy. The command processing failed as the database needs image copy.
D5	DATABASE HAS NO BACKOUTS	Database has no backouts. The command processing failed as there are no backouts for the database.
D6	DATABASE IN USE	Database in use. A SET(ACCTYPE) is specified for the DEDB and the authorization level cannot be changed as the DEDB is in use in a region.
D7	DB I/O PREVENTION NOT COMPLETE	Database I/O prevention not complete. The database cannot be started as it is extended because of an XRF takeover and the I/O prevention is not complete.
D8	DATABASE BACKOUTS PENDING	Database backouts pending. The access type specified for the database cannot be changed as restartable backouts are pending for the database.
D9	DATABASE/AREA OPEN FAILED	Database open failed. The command failed because of an error opening the database. Refer to DFS0730I messages to determine the reason of the failure.
DA	DATABASE BEING RECALLED BY HSM	Database being recalled from HSM. The command processing failed because the database is being recalled from HSM.
DB	PARTITION OPEN FAILED	Partition open failed. The partitions open failed because the master is offline. This can also occur if the partition has been deleted and partition structure rebuild has occurred. Partition structure rebuild can be accomplished by issuing an UPD DB NAME(haldbmst) START(ACCESS) OPTION(OPEN) command, where haldbmst is the partition's master, or by issuing a qualified GU call for a key in the key range of the partition. List.recon can be used to determine if the partition exists or has been deleted.
DC	HALDB PARTITION BUILD FAILURE	Database partition build failure. The database partitions build for the DDIR or DMB failed. Refer to the DFS0415I message sent to the system console to determine the reason of the failure.
DD	HALDB PARTITION INIT FAILURE	Database partition initialization failed. The database partition initialization for the DDIR or DMB failed. Refer to the DFS0415 message sent to the system console for the details.
DE	ACBLIB READ FAILURE	ACBLIB read failure. The command is not processed because there was an error reading the ACBLIB.
DF	DB DIRECTORY INIT FAILURE	Database directory initialization failed. The command is not processed because of a database directory initialization failure.
E0	DATABASE OR AREA IN RECOVERY	Database or area in recovery. The command is not processed because the database or area is in recovery.
E1	DB MUST BE STOPPED AND OFFLINE	The database must be stopped and taken offline in order for the attribute to be changed. You might need to issue a /DBR DB command or an UPDATE DB STOP(ACCESS) command to stop the database and take it offline before issuing the UPDATE DB SET(RESIDENT(Y|N)) command.
E2	PARALLEL DB OPEN NOT COMPLETE	Restart parallel DB open not complete. The command is not processed because the restart parallel DB open is not complete for the database.
E5	PARTICIPANT UNABLE TO QUIESCE	This error is returned when the quiesce could not be completed successfully across the IMSplex. The IMS with this completion code was the quiesce participant that was not able to be quiesced.
E6	QUIESCE COMMUNICATION FAILURE	This error is returned when the quiesce could not be completed because of a failure to communicate across the IMSplex. There could be a problem with RM, OM, or SCI that has caused the communication failure to occur.
E7	CMD NOT ALLOWED	This error is returned when the database command could not be processed because a quiesce command was in progress.
E8	DATABASE HAS INTENT TO REORGANIZE	This error is returned when the quiesce could not be started because the RECON data sets indicate that there is an intent to reorganize the database.
E9	DB IN WRONG STATE TO BE QUIESCED	This error is returned when the named resource is in the wrong state for quiesce processing to proceed.
EE	DATABASE BACKOUT ERROR	Database backout error. The command processing failed because of a database backout error.
EF	DATABASE IS IN ERROR	Database is in error. The command entered is not processed because the database is in error.
F0	NO AREA LOCK	No AREA lock. The command processing failed as the area lock could not be obtained.
F1	AREA NOT STOPPED	Area not stopped. The command entered is not processed because the AREA is not stopped.
F2	PRELOAD IS ACTIVE FOR AREA	Preload is active for AREA. The command entered is not processed because the AREA is not stopped.
F3	UNRESOLVED INDOUBTS FOR AREA	Unresolved indoubts for AREA. The command entered is not processed because unresolved indoubts exist for the AREA.
F4	ALLOCATION FAILED	Allocation failed. Allocation failed for the AREA name.
F5	AREA NEEDS RECOVERY	AREA needs recovery. The command processing failed because the area needs recovery.
F6	ADS NUMBER DISCREPANCY	ADS number discrepancy. The command failed for the AREA because there is a discrepancy between the number of ADS allocated by IMS and the number of ADS known to DBRC. Correct the discrepancy and reissue the command to deallocate the data sets.
F7	AREA IS NOT LOADED INTO CF	Area is not loaded into CF. The AREA OPEN failed and is not loaded into the Coupling Facility.
F8	AREA HAS I/O TOLERATED CI	Area has I/O tolerated CI. The command is not processed because the AREA has an I/O tolerated CI.
F9	AREA HAS 2ND CI EEQE	Area has 2nd CI EEQE. The command is not processed because the AREA has a 2nd CI EEQE.
FC	UTILITY ACTIVE ON AREA	This error is returned when the area is in use by a utility.
FD	AREA HAS EEQE	This error is returned when the area has an extended error queue element (EEQE).
FE	AREA HAS EQE	This error is returned when the area has an error queue element (EQE).
196	DB has an in-doubt EEQE	This error is returned when an UPDATE DB STOP(ACCESS) command is issued against a database that has an in-doubt EEQE and the NODBR keyword was specified in the DFSVSMxx member of the IMS PROCLIB data set.
1D7	IMPORT CHANGE LIST ERROR	The resource is in the process of being imported from the change list in the IMSRSC repository or was not successfully imported from the change list. The resource cannot be updated until it is successfully imported from the repository.