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
>>-BATCHBACK--JOB--(--jobname--)--+---------------------+------->
'-JOBID--(--job ID--)-'
>--+-------------------------------------------+----+---------+->
'-FAILED------------------------------------' '--CHECK--'
'-STEP(stepname)-+--------------------------+
'--PROCSTEP(procstepname)--'
>--+----------------------------------------------------+------->
'-DSNEXTENSION--(--alternate data set name suffix--)-'
>--+---------------+----------+-----------+--------------------->
| .-YES-. | | |
'-RCDS--+-NO--+-' '-MSGRC(rc)-'
>--+--------------------------------------+--------------------->
| .-,--------------. |
| V | |
'-SPHERENAME--(------spherename---+--)-'
>--+-------------------------------------------+---------------><
+-STOPTIME(stop date and time, LOCAL | GMT)-+
'-STOPTOD(stop block TOD,LOCAL | GMT)-------'

Keywords
CHECK
Specifies that CICS VR must list all applied records keys. CHECK
is an optional keyword. 
- 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.
MSGRC(rc)
Specifies that the Batch backout program should issue RC = rc
for CICS VR messages: DWW1709S, DWW1710S, DWW1707S, DWW1711S,
DWW1721S, and DWW1708S. The valid values for the parameter is 4 through
12. MSGRC is optional keyword. If MSGRC is not specified the Batch
backout program issues the error RC = 12.
PROCSTEP(procstepname)
PROCSTEP(procstepname) is specified when CICS VR must back out
all updates that were made beginning from the specified step in procedure
called by STEP(stepname), and all subsequent steps during the latest
execution of the batch job specified in the JOB keyword. PROCSTEP
is optional and requires that STEP(stepname) is specified . - procstepname
- Specifies the 1 - 8 character stepname specified in the EXEC PROC
step statements. The procstepname value is 1 through 8 alphanumeric
or national ($, #, @) characters. The first character must be alphabetic
or national ($, #, @).

- 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.
- 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.
Keyword |
Synonyms |
STOPTIME |
STOPDATETIME, STOPDATE and STOP |
- 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.
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.
- The VSAM sphere which is the subject of the BATCHBACK
command must be allocated to the job with disposition OLD.
If STEP(stepname) and PROCSTEP(procstepname) are specified
then stepname in STEP specifies the step name on the EXEC PROC statement,
and procstepname in PROCSTEP specifies the procedure step name in
this procedure. Nested calls are not allowed.
Examples
- Remove all updates made by the step that encountered an abend
during the last execution of batch job TEST1:
BATCHBACK JOB(TEST1) FAILED
- Remove all updates made by step STEP3 and all subsequent steps
during the last execution of batch job TEST2:
BATCHBACK JOB(TEST2) STEP(STEP3)
- Remove all updates made by the last execution of batch job TEST3.
Because the RCDSs that were allocated to CICS VR
when TEST3 was run are no longer available, RCDS(NO) is specified
and the name of the log stream that contains the proper before-image
log records is added to the MVSLOG command.
BATCHBACK JOB(TEST3)
MVSLOG(DWW.UNDOLOG)
- You might want to use the DSNEXTENSION optional parameter to periodically,
or after installation, test CICS VR's batch backout function
without affecting your production data sets. For this example, lets
examine a scenario where a batch job named JOB1 has just completed.
This batch job updates only one production data set named ACCOUNT.DATASET.ONE.
To test CICS VR batch backout without affecting the
contents of your production data set, you can perform the following
steps: