UPDATE AREA command

When the UPDATE AREA command is issued, the command is processed only by the IMS™ to which it is routed. The command does not preload or preopen areas on other IMS systems in the IMSplex that share the area. The UPDATE AREA command is routed 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.

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 AREA command and keywords can be issued.

Syntax

                              .-,-------------.       
                              V               |       
>>-+-UPDATE-+--AREA--NAME-+-(---+-areaname--+-+-)-+------------->
   '-UPD----'             |     '-areaname*-'     |   
                          '-(*)-------------------'   

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

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

Keywords

The following keywords are valid for the UPDATE AREA command:

NAME()

Specifies the names of the specific areas that are to be processed or a group of areas to be processed.

Wildcard parameters can be specified. The area names that match the generic or wildcard parameter are processed. For specific or wildcard names, response lines are returned for all the area names that are processed.

NAME(*) indicates that the command is to be applied to all the areas in the system. When the NAME(*) is specified, the response lines are returned for only the area names that resulted in an error. If OPTION(ALLRSP) is specified with NAME(*), response lines are returned for all the area names that are 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 areas that are processed on the command. ALLRSP is only valid with NAME(*). The default action is to return response lines only for the areas that resulted in an error.

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(ACCESS), or STOP(QUIESCE), and 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 area should remain quiesced. A subsequent STOP(QUIESCE) would be required to release the quiesce on the DEDB area. HOLD is valid only with the START(QUIESCE) keyword. This keyword is mutually exclusive with the NOHOLD keyword.

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 area should automatically release the quiesce. If neither HOLD nor NOHOLD is specified, NOHOLD is assumed. NOHOLD is valid only with the START(QUIESCE) keyword. This keyword is mutually exclusive with the HOLD keyword.

OPEN

Specifies to open the DEDB area data sets that are specified on the NAME() parameter, even if the area is 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) status in the RECON data set for the DEDB area. Use the PFA option with UPDATE AREA START(ACCESS) to enable access to a DEDB area. Use the PFA option with UPDATE AREA STOP (ACCESS|SCHD) to prevent access to a DEDB area. If you specify OPTION(PFA), the command master IMS updates the RECON only if the command is successful at the master IMS.

SCOPE()

Specifies where IMS should apply the change. The default is ALL.

ALL

Changes are applied to the active IMS systems to which the command is routed. If you specify that global area status is to be maintained, changes are also applied globally by updating the value maintained by RM. The RM status is updated only by the command master IMS. If global area status is not maintained, the command action is same as the SCOPE(ACTIVE) command.

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

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.

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

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

• START(ACCESS)
• STOP(SCHD)
• STOP(ACCESS)

SET()

Specifies the attribute values to be changed.

ACCTYPE()

Specifies the access intent for the named area. This keyword can be specified only if START(ACCESS) is specified. This keyword overrides the database access intent of its DEDB.

You can specify one of the following keywords:

BRWS

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

EXCL

Specifies that the named area is to be used exclusively by this IMS subsystem. This exclusive access is guaranteed only when the area is registered to DBRC.

READ

Specifies that the named area is available for read processing in this IMS subsystem. Programs with update intent can be scheduled, but cannot update the area. 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 area is opened for read.

UPD

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

TIMEOUT(nnn)

Specifies the number of seconds to wait before a timeout occurs in a DEDB area 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 the specific areas of a DEDB to be allocated or reallocated.

An UPDATE AREA START(ACCESS) can be issued on an RSR tracker to resume tracking for those areas that were stopped or had tracking errors. In addition, Online Forward Recovery (OFR) is started for areas that are not current with mainline tracking.

For Virtual Storage Option (VSO) areas, the UPDATE AREA START(ACCESS) can be used to preopen areas that are defined with the PREOPEN option. For VSO areas defined with the PRELOAD option, the command causes the areas to be loaded into the z/OS® data space or an XES structure depending on the share level of the area. The command has no effect on VSO areas that are in virtual storage.

QUIESCE

Specifies that the DEDB areas 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 area 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

Stops the access and updating of the specified DEDB areas and closes them.

The UPDATE AREA STOP(ACCESS) command for VSO areas removes the areas from the data space or XES structure and forces updates to be written back to DASD.

An UPDATE AREA START(ACCESS) command is required to open and reallocate the areas closed by the UPDATE AREA STOP(ACCESS) command.

QUIESCE

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

Unlike START(QUIESCE), where each area 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 data sets associated to the areas are to be closed and deallocated.

Note: An UPDATE AREA START(ACCESS) is required to reallocate the areas stopped by the UPDATE AREA STOP(SCHD) command.

If UPDATE AREA STOP(SCHD) is processed during HSSP processing, the area will be released after the current commit processing completes. Any image copy option in process when the command is issued can affect the continued system operation.

For VSO DEDB areas that are in a z/OS data space or XES structure, the UPDATE AREA STOP(SCHD) command action results in the removal of the VSO areas from the data space or XES structure and the writing of updates to DASD.

Usage notes

The UPDATE AREA command can only be specified using the OM API. The command is also not allowed on the XRF alternate.

The UPDATE AREA STOP(SCHD) command and the UPDATE AREA START(ACCESS) SET(ACCTYPE()) command are not allowed on any RSR tracker. However, the commands UPDATE AREA START(ACCESS) or UPDATE AREA STOP(ACCESS) are allowed only on a database level RSR tracker.

The UPDATE AREA START(ACCESS) and UPDATE AREA STOP(SCHD) commands are recoverable, and a X'22' log record is written, but the UPDATE AREA STOP(ACCESS) command is not recoverable.

A new log record, X'594C', is written for every DEDB area to which the UPDATE AREA command applies. It also includes global status and the global command time stamp.

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

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 AREA 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 AREA command. The OM return and reason codes that may be returned as a result of the UPDATE AREA 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 AREA command

Return code	Reason code	Meaning
X'00000000'	X'00000000'	The UPDATE AREA command completed successfully.
X'00000008'	X'00002014'	The UPDATE AREA command is not processed because an invalid character is found in the area name parameter.
X'00000008'	X'00002040'	Either more than one keyword or an invalid combination of filters was specified on the UPDATE AREA command. For example, the following keyword combinations are incorrect: START(ACCESS) and STOP(ACCESS) STOP(ACCESS) and OPTION(OPEN) STOP(SCHD) and OPTION(OPEN) OPTION(NOFEOV,FEOV) Check the input command and reenter the correct combinations.
X'00000008'	X'00005000'	The UPD AREA command processing terminated because IMODULE GETSTOR storage could not be obtained.
X'0000000C'	X'00003000'	The UPDATE AREA command is successful for at least one resource name. The UPDATE AREA command was not successful for one or more resource names. The completion code indicates the reason for the error with the resource name. The completion codes that can be returned by the UPDATE AREA command are listed in Table 5.
X'0000000C'	X'00003004'	The UPDATE AREA command was not successful for all the resource name(s) specified. The completion code indicates the reason for the error with the resource name. The completion codes that can be returned by the UPDATE AREA command are listed in Table 5.
X'00000010'	X'0000400C'	The UPDATE AREA command is not processed because the command variation entered is not valid on the XRF alternate.
X'00000010'	X'00004014'	The UPDATE AREA command is not processed because the function is not valid on the RSR tracker.
X'00000010'	X'00004024'	The UPDATE AREA command is not processed because Fast Path is not installed.
X'00000010'	X'00004025'	The UPDATE AREA command is rejected because no Fast Path areas are defined.
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'00005001'	The UPDATE AREA command processing terminated because WKAP or MAIN pool storage could not be obtained.
X'00000014'	X'00005004'	The UPDATE AREA command processing terminated because a DFSCOMD response buffer could not be obtained.
X'00000014'	X'00005008'	The UPDATE AREA command processing terminated because a DFSPOOL storage could not be obtained.
X'00000014'	X'0000500C'	The UPDATE AREA command processing terminated because AWE could not be obtained.
X'00000014'	X'00005FFF'	The UPDATE AREA 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 AREA command are returned as completion codes. A completion code is returned for each action against an individual resource.