ROLLBACK Utility

The ROLLBACK utility restores all or part of a database to a previous state by applying before images from the journal file.
idmscu19
The ROLLBACK utility restores all or part of a database to a previous state by applying before images from the journal file.
If requested, the ROLLBACK utility verifies the after images in the journal file against the contents of the database before applying the before images.
 This article describes the following information:
Authorization
To
You Need This Privilege
On
Roll back an area
DBAWRITE
The area
Roll back a segment
DBAWRITE
All affected areas of the segment
Roll back a file
DBAWRITE
All affected areas associated with the file
Roll back a database
DBAWRITE
All affected areas of the database
Syntax
►►─── ROLLBACK ───────────────────────────────────────────────────────────────►             ┌──────────── , ───────────┐  ►─┬─ FILE ─▼─ segment-name.file-name ─┴─┬────────────────────────────────────►    │        ┌──────────── , ───────────┐ │    ├─ AREA ─▼─ segment-name.area-name ─┴─┤    │           ┌─────── , ──────┐        │    ├─ SEGMENT ─▼─ segment-name ─┴────────┤    └─ DMCL ──────────────────────────────┘  ►─┬─ ACTIVE ─┬───────────────────────────────────────────────────────────────►    └─ ALL ────┘  ►─┬────────────────┬─────────────────────────────────────────────────────────►    ├─ SEQUENTIAL ◄──┤    └─ SORTED ───────┘  ►─┬───────────────────────────┬──────────────────────────────────────────────►    └─ VERIFY ─┬──────────────┬─┘               └─ DATABASE ◄──┘  ►─┬─────────┬────────────────────────────────────────────────────────────────►    └─ UTC────┘  ►─┬──────────────────────────────────┬───────────────────────────────────────►    └─ STOP AT ' ─┬─ date-time ─┬─ ' ──┘                  ├─ date ──────┤                  └─ time ──────┘  ►─┬─────────────┬────────────────────────────────────────────────────────────►◄    └─ HOTBACKUP ─┘
Parameters
  • FILE
    Rolls back one or more files. Recovery by file does not unlock any areas associated with the files.
  • segment-name
    Specifies the segment associated with the file.
  • file-name
    Specifies the name of the file.
  • AREA
    Rolls back and unlocks one or more specified areas.
  • segment-name
    Identifies the segment associated with the area.
  • area-name
    Specifies the name of the area.
  • SEGMENT
    Rolls back and unlocks all areas associated with the specified segments.
  • segment-name
    Specifies the name of the segment.
  • DMCL
    Rolls back all areas defined in the DMCL identified in the SYSIDMS parameter file.
  • ACTIVE
    • If you do not specify a STOP time, before images are appliedonly for transactions that remain open at the end of the journal file. Before images are not applied for incomplete distributed transactions whose state is InDoubt at the end of the journal file (unless a section recovery control file entry overrides this behavior by specifying BACKOUT for one or more of the transactions).
    • If you do specify a STOP time, before images are applied for all transactions until the STOP time is reached, and then processing continues only with open transactions. Before images are not applied for incomplete distributed transactions whose state is InDoubt at the stop time (unless a section recovery control file entry overrides this behavior by specifying BACKOUT for one or more of the transactions).
  • ALL
    • If you do not specify a STOP time, before images are appliedfor all transactions in the journal file.
    • If you do specify a STOP time, before images are applied for all transactions until the STOP time is reached, and then processing continues only with open transactions.
  • SEQUENTIAL
    Applies before images in the sequence in which they occur starting from the end of the journal file, reading backwards.
    SEQUENTIAL is the default.
  • SORTED
    Sorts the before images in the journal file by database key and copies back only the earliest before image for any database key.
    All the database keys on a given database page will be copied back together. Each page will be accessed once.
    By default, if you do not specify SORTED, the before images will be copied back sequentially.
    When recovering VSAM KSDS files, do not use the SORTEDoption. You must use SEQUENTIAL.
  • VERIFY DATABASE
    Verifies the after images in the journal file before applying the before images. If an after image in the journal file does not match the contents of the database, the roll back operation will terminate with an error.
    By default, if you do not specify VERIFY, before images are copied back without first verifying the after images.
    The optional DATABASE keyword is included for consistency with the ROLLFORWARD utility statement and has no impact on the processing of the VERIFY option.
  • STOP AT
    Directs processing to stop as soon as possible after reaching a specified date and time in the journal file.
    By default, processing will stop when the beginning of the journal file is reached.
  • date
    Specifies the date, in one of the following formats:
    • yyyy-mm-dd
    • mm/dd/yyyy
    • dd.mm.yyyy
    In these formats, the following rules apply:
    • yyyy
      specifies the year.
      yyyy
      must be an integer in the range 0001 through 9999. Leading zeros are optional.
    • mm
      specifies the month within the year.
      mm
      must be an integer in the range 01 through 12. Leading zeros are optional.
    • dd
      specifies the day within the month.
      dd
      must be an integer in the range 01 through 31. Leading zeros are optional.
    The combined values of
    yyyy
    ,
    mm
    , and
    dd
    must represent a valid date. For example, 1988-02-29 is a valid date. 1989-02-29 is not.
  • date-time
    Specifies the date and time, where:
    • The format for specifying the DATE-TIME is:
      yyyy-mm-dd-hh.mm.ss.ffffff
    • The rules for specifying the DATE component of DATE-TIME are the same as for DATE described previously. The rules for specifying the TIME component of DATE-TIME are:
      • hh
        specifies the hour on a 24-hour clock.
        hh
        must be an integer in the range 00 through 23. Leading zeros are optional.
      • mm
        specifies the number of minutes past the hour.
        mm
        must be an integer in the range 00 through 59. Leading zeros are optional.
      • Ss
        specifies the number of seconds past the minute.
        Ss
        must be an integer in the range 00 through 59. Leading zeros are optional.
      • ffffff
        specifies the number of millionths of a second past the specified second.
        ffffff
        is optional; if you include it, it must be an integer in the range 000000 through 999999. The default value is 000000. Trailing zeros are optional.
  • time
    Specifies the time in one of the following formats:
    • hh.mm.ss
    • hh:mm:ss
    The rules for specifying TIME are the same as those listed for DATE-TIME.
    When TIME is specified, the date defaults to the current date.
  • HOTBACKUP
    Forces ROLLBACK to also restore images for aborted run units.
  • UTC
    Specifies that Start and Stop times are interpreted as UTC times instead of local times.
Usage
How to submit the ROLLBACK statement
You submit the ROLLBACK statement only through the batch command facility. When submitting ROLLBACK statements, you must run the batch command facility in local mode.
Vary any area being rolled back offline to all DC/UCF systems.
When to use ROLLBACK
The ROLLBACK utility is most commonly used after a local mode update job has abnormally terminated or has been run incorrectly, resulting in incorrect data being introduced into the database. In this case, use the ROLLBACK utility to restore the affected parts of the database to an earlier, uncorrupted, state.
Both the database and the journal must be available and readable to run the ROLLBACK utility.
When not to use ROLLBACK
If the database is unusable or incomplete because of a physical I/O error, then you cannot use the ROLLBACK utility.
In this case, use a backup copy of the database and run ROLLFORWARD.
For more information about when and how to use the ROLLBACK and ROLLFORWARD utilities, see Administrating CA IDMS Database.
How ROLLBACK works
The ROLLBACK utility starts with the current state of the database. It uses before images from a tape or journal file to restore progressively earlier states of the database, file, segment, or area.
You can run the ROLLBACK utility
sequentially
, applying before images in reverse order. Or you can run the ROLLBACK utility in
sorted
mode. In sorted mode, the ROLLBACK utility applies the earliest before image of any record being restored.
ROLLBACK uses one journal file
The journal file is a sequential file that can reside on disk or tape. If you have multiple journal files, you must consolidate them, in the order in which they were created, to a single file and use the single file with the ROLLBACK utility.
Disk journal file
If the journal file is on disk, it cannot be read backwards in certain operating systems. To accommodate this, a SYSIDMS PARM has been created, ROLLBACK3490. To utilize this feature, the journal file must be sorted on the first UTC timestamp of each journal block, in a descending order. In this manner, the ROLLBACK utility, using the ROLLBACK3490 feature, reads each block forward, but is actually getting the blocks in descending order. Although the blocks are in descending order, the journal records within the blocks are in ascending order. As ROLLBACK reads each block in descending order, it processes each journal block from the end to the beginning. So even though the journal file is a sequential file on disk, sorted descending, ROLLBACK is processing the journal records in a descending order. To sort the journal blocks in descending order, use the following sort parm:
SORT FIELDS=(13,16,BI,D)
  • In CMS, you do not need to use the ROLLBACK3490 parameter, but you must presort the journal images as described previously regardless of whether the journal files reside on disk or tape.
  • If you decide to use the ROLLBACK3490 feature, or are using CMS, then you must sort the file in descending order prior to running the ROLLBACK utility, even if you are using 'sorted mode.'
Tape journal file
If you want the journal file on tape, you can put the file on tape by using the ARCHIVE JOURNAL utility, or by using a tape journal to begin with. If you have multiple tape journal files, you must concatenate them, in the order in which they were created, to a single file; and use the single file with the ROLLBACK utility.
If the tape file requires more than one tape volume, the volumes must be mounted in the order in which they were created.
Depending on the version of z/OS that you are using and whether the tape volumes are labeled, you might need to mount either the first tape volume produced or all tape volumes produced before they can be read backwards.
ROLLBACK and VSAM files
You can run the ROLLBACK utility against most native VSAM files. However, because VSAM does not support deleting ESDS file records, the ROLLBACK statement cannot be used on a native VSAM ESDS file that might cause the ROLLBACK utility to try to delete a record. Therefore, a run unit that has added records to an ESDS file can only be recovered by restoring the file to an earlier time and then executing the ROLLFORWARD utility.
For more information about CA IDMS/DB and native VSAM files, see Administrating CA IDMS Database.
When to use sequential mode
Use sequential mode if the journal file is very small or very large. If the journal file is small, you get no advantage from sorting. If the journal file is very large, it could require more sort space than you have available.
When to use sorted mode
Use sorted mode unless you have a strong reason not to. Be sure you have enough sorting space available. If there is not enough sort space available during ROLLBACK processing, the operation terminates with an error. The database will not be affected.
When to use VERIFY
Specify VERIFY only when rolling back an intact database. If you specify VERIFY when recovering from an abended job or an abended central version, the ROLLBACK utility terminates with an error.
VERIFY is ignored if you specify SORTED.
Recovering large numbers of files
For z/OS users, the maximum number of files that can be accessed by a central version is greater than the number that can be accessed by a local mode batch job. This has implications for section recovery. If more than 3,273 files must be recovered, it will be necessary to execute the ROLLBACK utility multiple times in separate job steps, recovering a subset of the areas or segments in each execution.
When to use HOTBACKUP
Specify HOTBACKUP when restoring a database from a hot backup. For more information about hot backup, see the CA IDMS Database Administration section.
ROLLBACK and Distributed Transactions
ROLLBACK reports on distributed transactions and supports the use of an input section recovery control file. The input recovery control file is used to complete InDoubt distributed transactions. For more information, see JCL Considerations and the "Common Facilities for Distributed Transactions" section.
For considerations associated with distributed transactions during recovery operations, see Administrating CA IDMS Database.
JCL Considerations
When you submit a ROLLBACK statement through the batch command facility, the JCL to execute the facility must include statements to define:
  • The tape or journal file
  • All files that map to areas being restored
  • Any file that includes space management pages of areas mapped to by files being restored
To use a section recovery input control file, include a CTRLIN file definition or DD statement in the IDMSBCF execution JCL. The format of this file is fixed block with a record length of 80.
For more information about the generic JCL used to execute the batch command facility, see the section for your operating system in this section.
Examples
The following example directs the ROLLBACK utility to apply all the before images on the journal file for the EMPDEMO segment and to sort the before images by database key.
 rollback segment empdemo all sorted;
Sample Output
When the ROLLBACK operation is completed, the following listing is generated.
 IDMSBCF                                              IDMS Batch Command Facility                            mm/dd/yy   PAGE 1  ROLLBACK SEGMENT EMPDEMO ALL SORTED;  RECORDS RESTORED TO AREA EMPDEMO.EMP-DEMO-REGION                734  RECORDS RESTORED TO AREA EMPDEMO.INS-DEMO-REGION                169  RECORDS RESTORED TO AREA EMPDEMO.ORG-DEMO-REGION                438  TOTAL RECORDS RESTORED              1341  BLOCK COUNT         0  BACKWARD      702  RECORD COUNT        0  BACKWARD     5512  Status = 1        Extended Reason Code = 2367     Messages follow:  DB002367 C1M353: Warning: area EMPDEMO.EMP-DEMO-REGION was not locked.  DB002367 C1M353: Warning: area EMPDEMO.INS-DEMO-REGION was not locked.  DB002367 C1M353: Warning: area EMPDEMO.ORG-DEMO-REGION was not locked.
More Information