ROLLFORWARD

The ROLLFORWARD utility restores a backup copy of all or part of a database to a subsequent condition by applying after images from the journal file.
idmscu19
The ROLLFORWARD utility restores a backup copy of all or part of a database to a subsequent condition by applying after images from the journal file.
If requested, the ROLLFORWARD statement verifies the before images in the journal file against the contents of the database before applying the after images.
This article describes the following information:
2
2
Authorization
To
You Need This Privilege
On
Roll forward an area
DBAWRITE
The area
Roll forward a segment
DBAWRITE
All affected areas of the segment
Roll forward a file
DBAWRITE
All affected areas that are associated with the file
Roll forward by DMCL
DBAWRITE
All affected areas within the DMCL
Roll forward FROM EXTRACT
DBAWRITE
All areas being recovered
Syntax
  ►►─── ROLLFORWARD ────────────────────────────────────────────────────────────►             ┌──────────── , ───────────┐  ►─┬─ FILE ─▼─ segment-name.file-name ─┴─┬────────────────────────────────────►    │        ┌──────────── , ───────────┐ │    ├─ AREA ─▼─ segment-name.area-name ─┴─┤    │           ┌─────── , ──────┐        │    ├─ SEGMENT ─▼─ segment-name ─┴────────┤    └─ DMCL ──────────────────────────────┘  ►─┬─ rollforward-options ───────┬────────────────────────────────────────────►◄    └─ FROM EXTRACT ──── ddname ──┘  
Expansion of rollforward-options
►►─┬─ COMPLETED ─┬────────────────────────────────────────────────────────────►    └─ ALL ───────┘  ►─┬──────────────┬───────────────────────────────────────────────────────────►    ├─ SEQUENTIAL ─┤    └─ SORTED ─────┘    ►─┬──────────────────────────────────────────────────────────┬───────────────►    └─ VERIFY ──┬───────────────────────────────────┬──────────┘                │ ┌─────────────────────────────┐   │                └─▼─┬─ DATABASE ───────────────┬┴───┘                    └─ QUIESCE ─┬────────────┬─┘                                ├─ NONE ─────┤                                ├─ LIMITED ◄─┤                                └─ FULL ─────┘  ►─┬─────────┬────────────────────────────────────────────────────────────────►    └─ UTC────┘    ►─┬─────────────────────────────────────┬────────────────────────────────────►    └─ START AT ── ' ─┬─ date-time ─┬─ ' ─┘                      ├─ date ──────┤                      └─ time ──────┘  ►─┬────────────────────────────────────┬─────────────────────────────────────►◄    └─ STOP AT ── ' ─┬─ date-time ─┬─ ' ─┘                     ├─ date ──────┤                     └─ time ──────┘  
Parameters
  • FILE
    Specifies that one or more files is to be restored. Areas that are associated with the specified files are not unlocked.
  • segment-name
    Specifies the segment that is associated with the file.
  • file-name
    Specifies the name of the file.
  • AREA
    Specifies that one or more areas are to be restored and unlocked.
  • segment-name
    Identifies the segment that is associated with the area.
  • area-name
    Specifies the name of the area.
  • SEGMENT
    Specifies to restore and unlock all areas that are associated with the specified segments.
  • segment-name
    Specifies the name of the segment.
  • DMCL
    Restores all areas that are defined by the DMCL specified in the SYSIDMS parameter file.
  • rollforward-options
    Specifies options that are used to rollforward from a standard archive journal tape.
    Expansion of
    rollforward-options
    immediately follows the main statement syntax.
  • FROM EXTRACT
    Specifies that an extract journal is used for input instead of a standard archive journal tape.
    This option excludes use of the SORTED/SEQUENTIAL, VERIFY, ALL/COMPLETED, and STOP AT options because these options have no effect on the already created extract file.
  • ddname
    Specifies the external name for the input extract file.
  • COMPLETED
    • If you do not specify a STOP time, after images are applied only for transactions that are completed before the end of the journal file. After images are 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, after images are applied for all transactions that have been completed up to the first checkpoint record after the STOP time. After images are 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, after images are applied for all transactions in the journal file.
    • If you do specify a STOP time, after images are applied until a point at or after the specified time where there are no active transactions. If no such point is found, processing stops at the end of the journal file.
  • SEQUENTIAL
    After images are applied in the sequence in which they occur in the journal file.
    SEQUENTIAL is the default.
    Backward file reads are not supported under z/VM. If an aborted transaction is encountered, a backward read may be attempted, in which case it fails. For this reason, it is safer for z/VM users to specify SORTED.
  • SORTED
    Specifies that after images are to be sorted in the journal file by database key and only the latest after image for any database key is applied.
    All the database keys on a given database page are copied back together. Thus, each page is accessed once.
    By default, if you do not specify SORTED, the after images are copied back sequentially.
    You cannot use the SORTED option with VSAM KSDS files.A native VSAM KSDS file must be recovered using the SEQUENTIAL option.
  • VERIFY
    Indicates that the validity of the specified conditions should be checked. If the VERIFY option is not specified, checking is not performed. If VERIFY is specified without DATABASE or QUIESCE, DATABASE is the default.
    • DATABASE -- Specifies that before images are to be verified in the journal file before the after images are applied. If a before image in the journal file does not match the contents of the database, the rollforward operation terminates with an error.
      By default, if database validity checking is not in effect, after images are copied back without first verifying the before images.
    • QUIESCE -- Specifies the level of quiesce point verification that is performed.
      • NONE -- Specifies that no quiesce point verification should be done. If "START AT" is specified, NONE is treated as LIMITED.
      • LIMITED -- Default. Specifies that limited quiesce point verification be performed.
      • FULL -- Specifies that the strictest form of quiesce point verification be performed.
  • START AT
    Specifies that the operation should start only after reaching a specified date and time in the journal file. Only images for transactions that begin after the specified start time is applied. By default, processing starts at the beginning of the journal file.
  • STOP AT
    Specifies that the operation should stop as soon as possible after reaching a specified date and time in the journal file.
    By default, processing stops when the end 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 listed for DATE-TIME.
    When TIME is specified, the date defaults to the current date.
  • UTC
    Specifies that Start and Stop times are interpreted as UTC times instead of local times.
Usage
How to submit ROLLFORWARD
You submit the ROLLFORWARD statement only through the batch command facility. When submitting ROLLFORWARD statements, you must run the batch command facility in local mode.
Vary any area being rolled forward offline to all central versions.
When to use ROLLFORWARD
The ROLLFORWARD utility is most commonly used to restore a database to its condition before some hardware problem corrupted the database. In this case, use a backup copy of the database that was created before the problem occurred.
You must have a backup of the database from a time before the problem, and all relevant journals.
How ROLLFORWARD works
The ROLLFORWARD operation starts with a former state of the database, as captured by a backup. ROLLFORWARD uses after images from a tape or journal file to restore progressively later states of the database, file, segment, or area.
ROLLFORWARD uses one journal file
The journal file is a sequential file that can reside on disk or tape depending on which options are specified. If you specify SEQUENTIAL, the journal file must reside on tape. If you specify SORTED, the journal file 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 ROLLFORWARD utility.
If the file requires more than one tape volume, the volumes must be mounted in order.
ROLLFORWARD and VSAM files
You can run the ROLLFORWARD utility against native VSAM files.
When to use sorted mode
Use sorted mode unless you have a strong reason not to. Be sure that you have enough sort space available before executing the ROLLFORWARD utility. If, however, you run out of sort space, the ROLLFORWARD operation terminates with an error, and the database is not affected.
ROLLFORWARD FROM EXTRACT
  • Purpose
    -- Much of the work of recovery can be performed by EXTRACT JOURNAL during a noncritical time. The actual recovery that is done by ROLLFORWARD is fast because the extract file contains only the records that are needed for recovery, in correct sort order.
  • Extract data
    -- Data in the extract file is selected and sorted before the actual recovery is done by ROLLFORWARD. A second sort is performed by ROLLFORWARD so that only the most recent image for each db-key is applied to the database.
  • Multiple input files
    -- Multiple input files can be processed as standard concatenated files; they do not need to be merged into one file before processing.
  • Tape file
    -- Because the extract file does not need to be read backwards, it does not need to be on tape.
Controlling the starting point of the rollforward operation
If no START AT parameter is specified, the rollforward operation starts with the first journal image on the input file(s). If START AT is specified, the rollforward operation starts with the first checkpoint record (BGIN, COMT, ENDJ, ABRT, or CKPT) whose timestamp is on or after the specified start time.
Specifying a start time may save recovery time and also circumvent issues that are associated with aborted recovery units that span the start of the input file. It further enables the rollforward operation to begin processing at a quiesce point that does not correspond with a journal file boundary.
Quiesce point verification
A quiesce point is a point in time during which there is no update activity for some portion of a database. To perform a correct recovery, you must begin the recovery operation at a quiesce point for the portion of the database being recovered. To assist in this effort, the rollforward utility provides two levels of quiesce point verification: limited and full.
Quiesce point verification is always performed during a rollforward operation. Verification is done by checking for the existence of spanned recovery units, which are recovery units that are active at the start of the rollforward operation. A recovery unit is represented by journal images starting with a BGIN or COMT checkpoint and ending with a COMT, ENDJ, or ABRT checkpoint. If a spanned recovery unit updates the specified portion of the database, then the rollforward operation is not starting at a quiesce point. If this situation is detected, the rollforward operation terminates with an error.
However, it is not always possible to know whether a spanned recovery unit affects the specified portion of the database or not. If the initial BGIN or COMT checkpoint record for a recovery unit is not contained on the archive file being processed, then it is not possible to determine whether it updated the specified portion of the database. Such a recovery unit is referred to as an indoubt recovery unit.
The following time line example illustrates what is meant by an indoubt recovery unit. The journal images for recovery unit
R
are written to the journal file at the times shown. If the archive file includes images starting at time T1, then
R
is not an indoubt recovery unit because the archive file contains all journal images that are written for
R
since its inception. Similarly, if the archive file starts at time T3,
R
is not an indoubt recovery unit, because the archive file contains no images for
R
whatsoever. However, if the archive file starts at time T2, then
R
is an indoubt recovery unit, because the archive file does not contain all journal images that are written since its inception.
                                                          ROLLFORWARD_TimeLine_Graphic.PNG
If an indoubt recovery unit does not span the start of the rollforward operation, its existence does not matter. But if an indoubt recovery unit is also a spanned recovery unit, then the rollforward operation may not be starting at a quiesce point.
The action that is taken if an indoubt spanned recovery unit is encountered depends on whether limited or full quiesce point verification is in effect. Under full verification, the rollforward operation terminates with an error. Under limited verification, a warning message is issued identifying the recovery unit, but processing continues.
Warning messages that are produced under limited verification should be examined to ensure that the identified recovery units in fact did not affect the specified portion of the database. If there is any doubt, the PRINT JOURNAL utility statement should be used to gain more information about the indoubt recovery units. If, after researching the situation, it is found that an indoubt recovery unit did update the specified portion of the database, the affected portion of the database must be restored, and the rollforward operation repeated. You must locate a quiesce point corresponding to a backup of the specified portion of the database and begin the rollforward operation from that point.
When to use full or limited verification
Full quiesce point verification should be used only if you expect that no indoubt spanned recovery units are active at the starting point of the rollforward operation. The only way to ensure this is to process archive files that were created immediately following a quiesce of update activity across all areas. One way to establish such a quiesce point is to shut down a central version. Another way is to use the DCMT QUIESCE command and specify a DBNAME that includes every area in the DMCL.
Limited quiesce point verification can be used when processing the archive files produced immediately following a quiesce operation for the portion of the database being recovered. One way to do this is to use the DCMT QUIESCE SEGMENT command to quiesce a segment and then use limited quiesce point verification when recovering all or a portion of that segment.
When to use VERIFY DATABASE
Specify VERIFY DATABASE only when rolling forward from an intact database.
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 is necessary to execute the ROLLFORWARD utility multiple times in separate job steps, recovering a subset of the areas or segments in each execution.
ROLLFORWARD and Distributed Transactions
ROLLFORWARD reports on distributed transactions and supports the use of input and output section recovery control files. Unless ALL is specified, the input section recovery control file is used to complete InDoubt distributed transactions. If an output section recovery control file is included in the JCL, unless FROM EXTRACT is specified, an entry is written for each incomplete distributed transaction . For more information, see JCL Considerations and the "Common Facilities for Distributed Transactions" section.
JCL Considerations
When you submit a ROLLFORWARD statement through the batch command facility, the JCL to execute the facility must include statements to define:
  • The tape or journal file or journal extract file
  • All files that map to areas being restored
  • Any file that includes space management pages of areas that are mapped to by files being restored
  • Sort work and message files if the sort option is selected or if recovering from a journal extract file
To use a section recovery input control file, include a CTRLIN file definition or DD statement in the IDMSBCF execution JCL. To use a section recovery output control file, include a CTRLOUT file definition or DD statement in the IDMSBCF execution JCL. The format of both of these files 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 ROLLFORWARD utility to restore the EMPDEMO segment using the SORTED option.
rollforward segment empdemo all sorted;
The following example directs the ROLLFORWARD utility to read an extract file from SYS005 and apply only the images that belong to file USERDB.EMPF1:
rollforward file userdb.empf1 from extract sys005;
Sample Output
The ROLLFORWARD utility generates the following listing after executing the statement in the first example.
 IDMSBCF                                              IDMS Batch Command Facility                            mm/dd/yy   PAGE 1  ROLLFORWARD SEGMENT EMPDEMO ALL SORTED;  RECORDS RESTORED TO AREA EMPDEMO.EMP-DEMO-REGION              1,030  RECORDS RESTORED TO AREA EMPDEMO.INS-DEMO-REGION                199  RECORDS RESTORED TO AREA EMPDEMO.ORG-DEMO-REGION                581  TOTAL RECORDS RESTORED              1810  BLOCK COUNT       702  BACKWARD        0  RECORD COUNT     5512  BACKWARD        0  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
For more information, see  Administrating CA IDMS Database.