Recover
Recovers before or after images of historical resource definitions from the journal.
Request format
<CCV530>
<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>
</CCV530>
- 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.
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.
- The current resource definition must match the after image of
the most recent of the selected changes.
Response format
<CCV530>
<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>
</CCV530>
- 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.
- 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).
Security key
API command (READ access authority):
(1) >>-prefix.REC.object_type.CCONFIG.location_name----------------><
- location_name is the name of the CICS configuration where the change occurred (stored in the BAImage journal record).
Resource definitions (ALTER access authority):
>>-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:
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:
Return code | Reason code | Description |
---|---|---|
04 | CD | Resource definition already in the state required for recovery. |
04 | E5 | Recovery skipped for ineligible duplicate. Either:
|
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:
|
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.