BATCHBACK: Remove updates to VSAM spheres

Use the BATCHBACK command to remove updates that were made to VSAM spheres by one or more steps in a batch job.

CICS® VR undo logging must have been performed for the VSAM spheres when the batch job was originally run to allow for CICS VR batch backout processing.

By default CICS VR will backout the whole of a job or step. In this case STOPTIME or STOPTOD is not specified and backout stops after the last relevant before-image is found.

You can perform a partial backout of a step or a job by adding STOPTIME or STOPTOD keywords to the command input in the DWWIN dd statement. The use of these keywords relies on correctly calculating the required time that you want CICS VR to stop. Use the STOPTIME and STOPTOD keywords with caution, it is not recommended for most users because CICS VR will stop at the time you have calculated regardless of the point in processing. If you perform a partial backout of a step or a job, upon successful completion take a new backup of the sphere for forward recovery purposes and discard all previous backups. The new backup is required because CICS VR will not process REDO records for partial units of work and does produce REDO records during the backout process.

Format

Read syntax diagramSkip visual syntax diagram
>>-BATCHBACK--JOB--(--jobname--)--+---------------------+------->
                                  '-JOBID--(--job ID--)-'   

>--+----------------+------------------------------------------->
   +-FAILED---------+   
   '-STEP(stepname)-'   

>--+----------------------------------------------------+------->
   '-DSNEXTENSION--(--alternate data set name suffix--)-'   

>--+---------------+-------------------------------------------->
   |       .-YES-. |   
   '-RCDS--+-NO--+-'   

>--+--------------------------------------+--------------------->
   |                .-,--------------.    |   
   |                V                |    |   
   '-SPHERENAME--(------spherename---+--)-'   

>--+-------------------------------------------+---------------><
   +-STOPTIME(stop date and time, LOCAL | GMT)-+   
   '-STOPTOD(stop block TOD,LOCAL | GMT)-------'   

Keywords

DSNEXTENSION(alternate data set name suffix)
Specifies a 1 - 8 character suffix that CICS VR appends to the end of the data set names of the VSAM spheres that CICS VR backs out. CICS VR performs all backout processing for the VSAM spheres that were updated by the specified batch job step(s) on VSAM spheres with the specified extension appended to it. The VSAM spheres with the specified extension appended to the spheres' data set names must exist prior to CICS VR batch backout processing, CICS VR does not create them.
alternate data set name suffix
Specifies the 1 - 8 character suffix that has been added to previously created copies of the VSAM spheres that CICS VR performs backout processing against. The specified extension must follow MVS™ data set naming conventions.
Note: If a value is entered for the DSNEXTENSION optional keyword, the data set with the appended extension must exist prior to backout processing. CICS VR does not create this data set.
FAILED
Specifies that CICS VR must back out all updates that were made by the step that encountered a failure during the latest execution of the batch job that was specified in the JOB keyword. The failed step for the specified batch job must have been the last step run by the specified job.

FAILED is an optional keyword. If FAILED is specified, the STEP(stepname) keyword cannot be specified. If FAILED and STEP(stepname) are not specified, CICS VR backs out all updates that were made by the latest execution of the entire batch job specified in the JOB keyword.

JOB(jobname)
Specifies the name of the job that performed the updates that you want CICS VR to back out. JOB is a required keyword and only one JOB keyword can be specified per BATCHBACK command.
jobname
Specifies the 1 - 8 character jobname specified in the JOB JCL statement of the batch job. The jobname is 1 through 8 alphanumeric or national ($, #, @) characters. The first character must be alphabetic or national ($, #, @).
JOBID(job ID)
When a JOBID is specified, only the steps of the specified JOB name with a matching JES job ID is backed out. JOBID is an optional keyword. JOBID is processed when the RCDS is specified in the batch backout job, and also when the RCDS is not available to the batch backout job.
RCDS(YES | NO)
Specifies if CICS VR uses information stored in the RCDSs specified on the DWWCONx DD statements during batch backout processing. The RCDS parameter is optional, and if it is not specified, CICS VR uses information from the RCDSs specified on the DWWCONx DD statements during batch backout processing.
YES
Specifies that CICS VR must use information stored in the RCDSs specified on the DWWCONx DD statements during batch backout processing. The RCDSs specified on the DWWCONx DD statements must be the same RCDSs that were allocated to the CICS VR server address space during execution of the batch job that performed the updates that you want to back out. IBM® recommends using information stored in the RCDSs during batch backout processing to allow for enhanced error checking and backout processing performance. YES is the default value.
If RCDS(YES) is specified or if the RCDS keyword is omitted:
  • You do not have to specify the name of the undo log that is used during batch backout processing. CICS VR automatically determines and uses the appropriate undo log.
  • On the DWWCONx DD statements in the batch backout job, you must specify the names of the RCDSs that were allocated to the CICS VR server address space during execution of the batch job you want to back out.
NO
Specifies that CICS VR uses only information stored in the log records on the undo log stream during batch backout processing. IBM recommends only specifying NO when the RCDSs that were allocated to the CICS VR server address space during execution of the batch job that performed the updates that you want to back out are no longer available. CICS VR performs additional error checking and more efficient backout processing when the RCDSs are used during batch backout processing.

If RCDS(NO) is specified, you must specify the name of the undo log that must be used during batch backout processing in the MVSLOG NAME(log stream name) command. See page 224 for more information about the MVSLOG command.

SPHERENAME(spherename)
If SPHERENAME is specified, only the VSAM spheres listed is backed out. SPHERENAME is an optional keyword. Any number of spheres can be specified, using the syntax SPHERENAME(sphere1, sphere2, ...).
STEP(stepname)
Specifies that CICS VR must back out all updates that were made by the specified step, and all subsequent steps during the latest execution of the batch job specified in the JOB keyword.
stepname
Specifies the 1 - 8 character stepname specified on the EXEC JCL statement. The stepname is 1 through 8 alphanumeric or national ($, #, @) characters. The first character must be alphabetic or national ($, #, @).

STEP(stepname) is an optional keyword. If STEP(stepname) is specified, the FAILED keyword cannot be specified. If STEP(stepname) and FAILED are not specified, CICS VR backs out all updates that were made by the latest execution of the entire batch job specified in the JOB keyword.

Start of change
STOPTIME(stop date and time, LOCAL | GMT)
Specifies the earliest timestamp of the before-images that you want to use for backout. CICS VR ignores any before-images with an earlier timestamp than the time specified in the STOPTIME keyword. CICS VR reads the log backwards and applies all before-images, for the VSAM spheres, up to this place in the log. Only one STOPTIME keyword is allowed for each BATCHBACK control statement. When the partial backout of the step or job has successfully completed you must take a new backup of the sphere.
stop date and time
Must be in the format yyyy/ddd/hh/mm/ss, where:
  • yyyy is the year
  • ddd is the day of the year (001–366)
  • hh is the hour of the day (00–23)
  • mm is the number of minutes (00–59)
  • ss is the number of seconds (00–59)
You can separate these values with a slash (/), period (.), or colon (:). You can also omit the separator character. For example:
STOPTIME(2007.159/00:30:00)
You cannot substitute commas, blanks, and so on, for the time values, but you can omit values from the right. For example, you can specify day 2007159, time 00:00:00, as follows:
STOPTIME(2007.159)
If you specify this, CICS VR assumes that the day is 2007365 and the time is 00:00:00:
LOCAL
Specifies that the date and time are in local format. LOCAL is the default value.
GMT
Specifies that the date and time are in GMT format.
End of change
Keyword Synonyms
STOPTIME STOPDATETIME, STOPDATE and STOP
Start of change
STOPTOD(stop block TOD,LOCAL | GMT)
Specifies the earliest timestamp, in hexadecimal time-of-day (TOD) format, that you want to use for backout. CICS VR ignores any before-images on the log with an earlier timestamp than the time specified in the STOPTOD keyword. CICS VR reads the log backwards and applies all before-images, for the VSAM spheres, up to this place in the log.
Only one STOPTOD keyword is allowed for each BATCHBACK control statement. If STOPTOD or STOPTIME is not specified, backout stops after the last relevant before-image found. Use the STOPTOD keyword only if the STOPTIME keyword value is not precise enough for your backout stop time. The STOPTOD keyword has no synonyms. When the partial backout of the step or job has successfully completed you must take a new backup of the sphere.
stop time of day
Must be 16 hex characters. Here is an example of a STOPTOD keyword: STOPTOD(AC47C0403792C101)
LOCAL
Specifies that the TOD value is in local format. LOCAL is the default value.
GMT
Specifies that the TOD value is in GMT format.
End of change

Usage Notes

Consider the following points when using the BATCHBACK command:
  • Use STOPTIME or STOPTOD with caution. In most cases these parameters are not required.
  • Only one BATCHBACK command can be specified per job step that starts the DWWBACK program.
  • CICS VR backs out all updates made to all VSAM spheres that had CICS VR undo logging enabled when the batch job specified was originally run. If some VSAM spheres did not have undo logging enabled when the specified batch job was originally run, CICS VR does not back out the updates made by the batch job to those VSAM spheres. Because CICS VR is unaware of any batch update activity for VSAM data sets that do not have logging enabled, a message warning of this situation is not produced.
  • To perform proper batch backout processing, be sure that no updates were made to the VSAM spheres after execution of the specified batch job or be sure that they were previously backed out.
  • If batch backout processing is to back out records that were added by the specified batch job to one or more ESDS VSAM spheres, you must specify the name of an ESDS delete exit as a keyword to the DEFEXIT ESDSDELETE(ESDS delete exit name) command.
  • Batch backout processing only accesses the VSAM sphere through the base cluster. If the complete upgrade set exists during batch backout processing, the alternate indexes are updated by VSAM while CICS VR updates the base cluster. If only the base cluster exists during batch backout, or the alternate indexes are not part of the upgrade set, recreate the alternate indexes and rebuild them using the access method service's (AMS) BLDINDEX command after batch backout processing completes successfully.
  • Batch backout processing can only back out updates made to VSAM spheres accessed in non-RLS mode by batch jobs.
  • Batch backout processing does not back out updates made by CICS.
  • Start of changeThe VSAM sphere which is the subject of the BATCHBACK command must be allocated to the job with disposition OLD.End of change

Examples