UPDATE DBDESC command

Updating a descriptor changes only the attributes explicitly specified on the UPDATE command. Attributes not specified retain their existing values. Any database resource or descriptor can be created using this descriptor as a model, by specifying the CREATE command with LIKE(DESC(descriptor_name)). Any descriptor or resource that was already created using this descriptor is not updated.

Subsections:

• Environment
• Syntax
• Keywords
• Usage notes
• Output fields
• Return, reason, and completion codes
• Examples

Environment

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

Syntax

                             .-,-----.                
                             V       |                
>>-+-UPDATE-+--DBDESC--NAME(---name*-+-)--+-| A |-+------------->
   '-UPD----'                             '-| B |-'   

>--+----------------+------------------------------------------><
   '-OPTION(ALLRSP)-'   

A

        .-,---------------------------.     
        V                             |     
|--SET(---+---ACCTYPE(-+-BRWS-+-)---+-+-)-----------------------|
          |            +-EXCL-+     |       
          |            +-READ-+     |       
          |            '-UPD--'     |       
          '-DEFAULT(Y)--------------'       

B

        .-,-------------------------.     
        V                           |     
|--SET(---+---RESIDENT(-+-N-+-)---+-+-)-------------------------|
          |             '-Y-'     |       
          '-DEFAULT(Y)------------'       

Keywords

The following keywords are valid for the UPDATE DBDESC command:

NAME

Specifies the 1-8 character name of the database descriptor 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 descriptor names that are processed. For NAME(*) command responses are returned only for the descriptor names that resulted in an error. OPTION(ALLRSP) can be specified with NAME(*) to obtain the command responses for all the descriptor names that are processed.

OPTION

Specifies additional functions to be performed along with the command.

ALLRSP

Indicates that the response lines are to be returned for all descriptors that are processed on the command. The default action is to return response lines only for the descriptors that resulted in an error. It is only valid with names that include a wildcard character. ALLRSP is ignored for other NAME values.

SET

Specifies the attribute values to be changed.

ACCTYPE

Specifies the access intent for a database created using this descriptor.

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 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.

DEFAULT(Y)

Specifies this descriptor as the default, which resets the existing default descriptor to DEFAULT(N). When a descriptor is created without the LIKE keyword, any attribute not specified on the CREATE command takes the value defined in the default descriptor. Only one descriptor can be defined as the default for a resource type. IMS defines a database descriptor called DFSDSDB1, where all attributes are defined with the default value. Defining a user-defined descriptor to be the default overrides the current default descriptor. Since only one database descriptor can be the default at one time, only one database name can be specified with DEFAULT(Y).

RESIDENT

Specifies the resident option of a database created using this descriptor. 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 from 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.

Usage notes

Descriptors exist for the life of the IMS unless they are deleted using a DELETE command. Descriptors are recoverable across an IMS warm start or emergency restart. Descriptors are lost if IMS is cold started, unless cold start imports definitions that were exported while IMS was up.

If all the attributes specified by the UPDATE command are already defined for the descriptor, no update is actually made, no descriptors 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.

The UPDATE DBDESC command can be issued only through the OM API. This command applies to DB/DC and DBCTL systems.

The UPDATE DBDESC commands are not valid on the XRF alternate, RSR tracker, or FDBR region. The UPDATE DBDESC commands are not valid if online change for MODBLKS is enabled (DFSDFxxx or DFSCGxxx defined with MODBLKS=OLC, or MODBLKS not defined).

This command is recoverable.

Each descriptor is updated individually. Individual updating does not work like online change where either all descriptors are updated or no descriptors are updated. Descriptors can be successfully updated if they are not currently in use. If a descriptor is in use, the update fails. In a sysplex environment, the update might succeed on some IMS systems and fail on others. A descriptor is in use if another command is in progress that references the command.

If the descriptor is the IMS-defined database descriptor (DFSDSDB1), the only attribute that can be updated is the DEFAULT attribute.

Output fields

Return, reason, and completion codes

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.

Errors unique to the processing of this command are returned as completion codes. The following table includes an explanation of the completion codes.

Table 4. Completion codes for the UPDATE DBDESC command

Completion code	Completion code text	Meaning
0		Command completed successfully for database resource or database resource descriptor.
17	ANOTHER CMD IN PROGRESS	None. The command completed with error for all the Areas of the DEDB. Response lines for the area names in error are returned.
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).
6C	NOT ALLOWED FOR A HALDB PARTITION	The 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.
8A	WILDCARD PARAMETER NOT SUPPORTED	A wildcard parameter was specified with DEFAULT(Y). Only one descriptor can be the default at a time.
1D7	IMPORT CHANGE LIST ERROR	The descriptor 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 descriptor cannot be updated until it is successfully imported from the repository.