UPDATE DATAGRP command

Subsections:

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

Environment

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

Syntax

>>-+-UPDATE-+--DATAGRP--NAME(datagrpname)----------------------->
   '-UPD----'                               

>--+-START-+-(ACCESS)--+--------------------------+-+-+--------->
   |       |           '-SET(ACCTYPE(-+-BRWS-+-))-' | |   
   |       |                          +-EXCL-+      | |   
   |       |                          +-READ-+      | |   
   |       |                          '-UPD--'      | |   
   |       '-(QUIESCE)--+-------------------+-------' |   
   |                    '-SET(TIMEOUT(nnn))-'         |   
   '-STOP(-+-ACCESS--+-)------------------------------'   
           +-QUIESCE-+                                    
           '-SCHD----'                                    

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

Keywords

The following keywords are valid for the UPDATE DATAGRP command:

NAME()

Specifies the name of the data group to be processed.

OPTION()

Specifies the additional functions to be performed. Following is a list of additional functions:

ALLRSP

Indicates that the response lines are to be returned for all the members of the data group (all databases, areas, or both) that are processed on the command.

The default action is to return response lines only for the databases and areas or both that resulted in an error. A response line with the data group name is always returned.

DBALLOC

Indicates that the databases in the data group are to be allocated when they are started.

DBALLOC can only be specified with START(ACCESS).

Only one of DBALLOC or NODBALLOC can be specified.

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) or STOP(ACCESS) or STOP(QUIESCE).

FEOV is not valid on an RSR tracker.

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

For quiesce processing, the end of volume will be forced after the quiesce point has been reached, causing the logs to be switched before the quiesce is released, so that any new updates occur on the new IMS log. This occurs during the stop quiesce processing of a START(QUIESCE) OPTION(NOHOLD) or when a 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 data group members should remain quiesced. A subsequent STOP(QUIESCE) would be required to release the quiesce on the data group members. This keyword is only valid with the START(QUIESCE) keyword. HOLD is mutually exclusive with NOHOLD.

NODBALLOC

Indicates that the databases in the data group are not to be allocated when they are started. The databases will be allocated when they are scheduled.

NODBALLOC can only be specified with START(ACCESS). NODBALLOC is the default action for UPDATE DATAGRP command if OPTION(DBALLOC) is not specified.

Only one of DBALLOC or NODBALLOC can be specified.

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.

NOFEOV is valid only with START(QUIESCE) OPTION(NOHOLD), STOP(ACCESS), or STOP(QUIESCE). OPTION(NOFEOV) is the default when specified with STOP(ACCESS).

NOHOLD

Specifies that after the quiesce has been achieved successfully the data group members should automatically release the quiesce. If you do not specify either HOLD or NOHOLD, NOHOLD is assumed. This keyword is only valid with the START(QUIESCE) keyword. NOHOLD is mutually exclusive with HOLD.

SCOPE()

Specifies where IMS should apply the change.

ACTIVE

SCOPE(ACTIVE) specifies that the changes are to be applied to the IMS systems that are currently active and to which the command is routed.

This option does not apply to the quiesce function. The scope of a quiesce is always all instances of the data group usage across the IMSplex. There is no quiesce which would only apply to a subset of the IMSplex.

ALL

SCOPE(ALL) specifies that the changes are to be applied to the active IMS systems.

This option does not apply to the quiesce function. The scope of a quiesce is always all instances of the data group members usage across the IMSplex. There is not a global status of QUIESCE for a data group or its members. Using SCOPE(ALL) for a START(QUIESCE) or STOP(QUIESCE) does not change the global status for the data group members.

Currently, ACTIVE and ALL produce the same results.

SET()

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

ACCTYPE

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

BRWS

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 using the GO processing option might see uncommitted data because another program could be updating the database. The database is opened for read-only processing.

EXCL

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.

READ

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. ACCTYPE of READ differs from ACCTYPE of 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

Specifies that the named database is available for update as well as read processing in this IMS subsystem.

TIMEOUT(nnn)

Specifies the number of seconds to wait before a timeout occurs in a data group 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

Specifies that the members of the specified data group name are to be started. See UPDATE AREA START(ACCESS) and UPDATE DB START(ACCESS) for a description of the actions performed on the databases and areas in the data group.

Additional functions to be performed along with START(ACCESS) can be specified using the OPTION keyword.

An UPDATE DATAGRP START(ACCESS) command with SET(ACCTYPE) or OPTION(DBALLOC | NODBALLOC | NOBACKOUT | OPEN | NOOPEN) is invalid on the RSR tracker.

QUIESCE

Specifies that the data group named on the command is to be quiesced to establish a new recovery point. The scope of a quiesce is always all instances of the data group usage across the IMSplex.

STOP()

Specifies the attributes to be stopped.

ACCESS

Specifies that offline processing is to be done for the members of the specified data group. See UPDATE AREA STOP(ACCESS) and UPDATE DB STOP(ACCESS) for a description of the actions performed on the databases and areas in the data group.

QUIESCE

Specifies that the data group named on the command should be made available again by releasing the quiesce on the data group members.

Unlike START(QUIESCE), where each data group 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

Specifies that the members of the specified data group name are to be stopped. See UPDATE AREA STOP(ACCESS) and UPDATE DB STOP(ACCESS) for a description of the actions performed on the databases and areas in the data group.

Usage notes

The UPDATE DATAGRP command can only be specified through the OM API and can be processed only by the DB/DC and DBCTL environments. In addition, the UPDATE DATAGRP command is not allowed on the XRF alternate.

When the UPDATE DATAGRP command is issued, it only applies to the IMS system to which it is routed. It does not apply to the other IMS systems in the IMSplex that share the database or areas in the data group. The routing of the UPDATE DATAGRP command is done by OM. OM routes the command to all active DB/DC or DBCTL IMS systems, unless specific routing is specified. OM selects one IMS as the command master.

A response line is returned for the data group name from each IMS. Response lines are also returned for each data group member that resulted in an error. No response lines are returned for the data group members that are processed successfully unless OPTION(ALLRSP) is specified.

A data group is defined in the RECON data set by using the INIT.DBDSGRP command with the parameters GRPNAME and DBGRP (to define a DB group), MEMBERS (to define a DBDS group), or RECOVGRP (to define a recovery group). The DATAGRP keyword on the UPDATE command can specify either a DBDS group or a DB group (DL/I databases or DEDB areas).

If the ACCESS keyword is specified on the UPDATE DATAGRP command along with the DBDS group name, the ACCESS keyword is not applied to the Fast Path DEDB databases associated with the Fast Path DEDB areas in the DBDS group. If the intent is to use the ACCESS keyword for Fast Path DEDB databases, the DATAGRP parameter must be a data group name that does not contain area names.

While the database is being quiesced, this command with keywords other than STOP(QUIESCE) cannot be processed successfully.

Equivalent IMS type-1 commands

The following table shows variations of the UPDATE DATAGRP command and the type-1 IMS commands that perform similar functions.

Output fields

Return, reason, and completion codes

An IMS return and reason code is returned to OM by the UPDATE DATAGRP command. The OM return and reason codes that may be returned as a result of the UPDATE DATAGRP 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 3. Return and reason codes for the UPDATE DATAGRP command

Return code	Reason code	Meaning
X'00000000'	X'00000000'	The UPDATE DATAGRP command completed successfully.
X'00000008'	X'00002004'	An invalid keyword or more than one keyword is specified on the UPDATE DATAGRP command.
X'00000008'	X'00002014'	The UPDATE DATAGRP command is not processed because an invalid character is found in the data group name.
X'00000008'	X'00002040'	More than one filter or keyword value is specified on the UPDATE DATAGRP command. Either more than one keyword or an invalid combination of filters was specified. For example, START(ACCESS) and STOP(ACCESS) was specified, or OPTION(DBALLOC,NODBALLOC) was specified. Check the input command and reenter the correct combinations.
X'00000008'	X'00005000'	The UPD DATAGRP command processing terminated because IMODULE GETSTOR storage could not be obtained.
X'00000008'	X'0000501C'	The UPD DATAGRP command processing terminated because IMODULE GETMAIN storage could not be obtained.
X'0000000C'	X'00003000'	The UPDATE DATAGRP command is successful for at least one member in the data group. The UPDATE DATAGRP command is not successful for one or more members in the data group. The completion code indicates the reason for the error with the data group member name. The completion codes that can be returned by the UPDATE DATAGRP command are listed in the UPDATE DATAGRP completion code table.
X'0000000C'	X'00003004'	The UPDATE DATAGRP command is not successful for all the members in the data group. The completion code indicates the reason for the error with the data group member name. The completion codes that can be returned by the UPDATE DATAGRP command are listed in the UPDATE DATAGRP completion code table.
X'00000010'	X'0000400C'	The UPDATE DATAGRP command is not processed because it is not valid on the XRF alternate.
X'00000010'	X'00004014'	The UPDATE DATAGRP command is not processed because it is not valid on the RSR tracker.
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'00004400'	MINVERS in the RECON data sets is not 11.1.
X'00000014'	X'00005004'	The UPDATE DATAGRP command processing terminated because a DFSOCMD response buffer could not be obtained.
X'00000014'	X'00005008'	The UPDATE DATAGRP command processing terminated because DFSPOOL storage could not be obtained.
X'00000014'	X'0000500C'	The UPDATE DATAGRP command processing terminated because AWE could not be obtained.
X'00000014'	X'00005014'	The UPDATE DATAGRP command processing terminated because BCB storage could not be obtained.
X'00000014'	X'00005FFF'	The UPDATE DATAGRP command processing terminated because of an internal error.
X'02000008'	X'0000203C'	An invalid TIMEOUT value is specified. The value must be a numeric value between 1 and 999.

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