Recover

Recovers before or after images of historical resource definitions from the journal.

Request format

<CCV510>
  <Recover>
    <LocationCriteria>
      <LocationType> Journal </LocationType>
    </LocationCriteria>

    <ObjectCriteria>
      <ListCount> element_count </ListCount>  1 
      <ListElement>  2 
        <ObjName> resource_name </ObjName>
        <ObjGroup> resource_group </ObjGroup>
        <ObjType> resource_type </ObjType>
        <ObjectInstance> object_instance </ObjectInstance>
      </ListElement>

      More list elements…

    </ObjectCriteria>

    <ProcessParms>
      <RecoverImage> Before | After </RecoverImage>  3 
      <RollbackOption> No | Yes </RollbackOption>  4 
    </ProcessParms>

  </Recover>
</CCV510>
 1 
The element_count must match the number of list elements.
 2 
Each <ListElement> must uniquely identify a change that you want to undo or redo: that is, a before/after image (BAImage) object in the journal. You must specify the name, group, type, and object instance of each BAImage with no wildcards.

You cannot recover changes to CICSPlex® SM relationships, such as Add and Remove (that is, changes to xxxINGRP resource definition types). However, you can recover changes to the resource definition types List, ResGroup, and ResDesc.

If the resource type is ResDesc or List, then the <ObjGroup> element is ignored, and may be omitted.

Tip: Use a List command to get the details of a set of BAImage objects, and then use the response from that List command response to specify the list elements for this Recover command.
 3 
Specify whether to recover the before image (undo the change) or the after image (redo the change).
Note:
  • Recovering the after image of a deletion, or the before image of a creation, deletes the current resource definition, if it exists.
  • If you select multiple changes for the same resource definition (same name, type, group, and CICS configuration), then:
    • Choosing to recover after images recovers the after image of the most recent of the selected changes for that resource definition.
    • Choosing to recover before images recovers the before image for the oldest of the selected changes for that resource definition.
 4 
The rollback option applies only when recovering before images.
The rollback option protects you from unintentionally overwriting changes that are outside of the set you have selected. Specifically, the rollback option ensures that the selected changes for a resource definition form an unbroken chain that begins at the current resource definition and ends at the before image of the oldest selected change. The chain is unbroken if the following two conditions are true:
  • The current resource definition must match the after image of the most recent of the selected changes.

    If no current resource definition exists (it has been deleted), then the after image of the most recent of the selected changes must be empty (reflecting the deletion).

  • The before image of the most recent of the selected changes must match the after image of the second most recent; the before image of the second most recent must match the after image of the third most recent; and so on, until the oldest of the selected changes, whose after image must match the before image of the second oldest.
To match, two items must have the same attribute values and the same change date.

If you omit the <RollbackOption> element when recovering before images, the before images are recovered with no rollback processing.

When recovering after images, omit the <RollbackOption> element; if you specify this element, it is ignored.

Response format

<CCV510>
  <Recover>
    <OutputData>
      <ReturnCode> return_code </ReturnCode>  1 
      <ReasonCode> reason_code </ReasonCode>
      <TaskNo> CICS_task_number </TaskNo>
 
      <ListCount> element_count </ListCount>
      <ListElement>  2 
        <ReturnCode> return_code </ReturnCode>
        <ReasonCode> reason_code </ReasonCode>
        <ObjName> resource_name </ObjName>
        <ObjType> resource_type </ObjType>
        <ObjGroup> resource_group </ObjGroup>
        <Config> CICS_configuration </Config>
        <ObjectInstance> object_instance </ObjectInstance>
        <Action> CREATE | UPDATE | DELETE | SKIP </Action>  3 
      </ListElement>
 
      More list elements…
 
    </OutputData>
  </Recover>
</CCV510>
 1 
The response contains a return code and a reason code for the entire command (known as the "rollup" return and reason codes) and a return code and a reason code for each list element.
 2 
The response contains the list elements specified in the request, in the same order. In addition to the details specified in the request, the response includes the name of the CICS configuration for each change.
 3 
<Action> indicates the action that the Recover command performed for this change:
CREATE
The Recover command created the resource definition, because no current version existed.
UPDATE
The Recover command updated the existing resource definition.
DELETE
The Recover command deleted the existing resource definition.
SKIP
No action performed. Possible reasons include:
  • The set of changes specified in the Recover request included multiple instances of the same resource definition (same name, type, group, and in the same CICS configuration).

    When recovering before images, the Recover command skips all except the oldest of the selected changes for a resource definition.

    When recovering after images, the Recover command skips all except the most recent of the selected changes for a resource definition.

  • An error occurred while attempting recovery. For example, a security violation or a break in the rollback chain.

Security key

API command (READ access authority):

Read syntax diagramSkip visual syntax diagram
                                                (1)   
>>-prefix.REC.object_type.CCONFIG.location_name----------------><

Notes:
  1. location_name is the name of the CICS configuration where the change occurred (stored in the BAImage journal record).

Resource definitions (ALTER access authority):

Read syntax diagramSkip visual syntax diagram
>>-prefix.target_CICS_config.group.type.name-------------------><

Return and reason codes

The following tables describe combinations of return and reason codes that are specific to the Recover API command. For a complete list of reason codes that can be generated by this and other API commands, see Reason codes.

The following table describes rollup return and reason codes for the entire command:

Table 1. Recover API command: rollup return and reason codes
Return code Reason code Description
04 EB Some of the objects failed recovery.
08 EC All of the objects failed recovery.

The following table describes return and reason codes for each list element:

Table 2. Recover API command: rollup return and reason codes
Return code Reason code Description
04 CD Resource definition already in the state required for recovery.
04 E5 Recovery skipped for ineligible duplicate.

Either:

  • The Recover command was recovering before images, and this was not the oldest of the selected BAImage objects for the resource definition

    or

  • The Recover command was recovering after images, and this was not the most recent of the selected BAImage objects for the resource definition
08 03 BAImage object not found in journal.
04 E6 Recovery skipped deletion of non-existent definition.

To recover an empty image (the before image of a creation, or the after image of a deletion), the Recovery command was going to delete the current resource definition. However, the resource definition no longer exists, so the Recover command performed no action.

08 E7 Recovery failed because the rollback chain was broken.

This reason code identifies the BAImage object that would have been recovered if the rollback chain was unbroken.

Reason code E9 identifies the BAImage object that broke the rollback chain.

08 E8 Object data inconsistent with the object instance BAImage.

Either:

  • The combination of name, group, and type specified in the request do not match the object instance specified in the request

    or

  • The BAImage object has a return code greater than 4.

    You can only recover BAImage objects with a return code of 4 or less. That is, you can only recover changes that succeeded; you cannot recover failed attempts to change a resource definition.

08 E9 Recovery rollback chain broken by this BAImage object.

The before image of this BAImage does not match the after image of the next most recent selected BAImage for the resource definition.

08 EA Recovery failed because the target CICSPlex SM resource group for recovery contains a different version of this resource definition.

Usage

For details on how the CICS® Configuration Manager ISPF dialog interface uses the Recover command, see Recovering historical versions of multiple resource definitions.

Note: In the ISPF dialog, if you enter the REC (Recover) line action next to multiple changes, then all of those changes must be for the same CICS configuration. However, the Recover API command has no such restriction: each change in a Recover API command request can be for a different CICS configuration.

Reference Reference

Feedback


Timestamp icon Last updated: Friday, 1 November 2013


http://pic.dhe.ibm.com/infocenter/cicsts/v5r1/topic//ccv-api-cmd-recover.htm