HELPLIB.HLB  —  RECOVER
    Invokes the RMS Recovery Utility. Applicable only if you have the
    RMS Journaling option. See the OpenVMS RMS Journaling Manual.

    The RMS Recovery Utility (RECOVER/RMS_FILE) restores RMS files
    after the files have become lost or the data in them has become
    unusable. You can use RECOVER/RMS_FILE to redo operations (with
    after-image journaling, using a previously made backup file),
    or to undo operations (with before-image journaling, using the
    actual data file).

    Format

                       { /FORWARD }
      RECOVER/RMS_FILE { /BACKWARD}  filespec[,...]
                       {          }

1  –  Parameter

 filespec[,...]

    Specifies the file to be recovered. Wildcard characters (* and %)
    are allowed in the directory specification, file name, file type,
    and version number fields. If you specify more than one file,
    separate the file specifications with commas.

    For recovery using after-image journaling, use the backup copy
    of the data file as the file specification. For recovery using
    before-image journaling, use the original data file as the file
    specification.

    The file specification cannot include a node name, since the
    RECOVER/RMS_FILE command is not valid for network access.

2  –  Qualifiers

2.1    /BACKWARD

    Rolls a file backward to a previous state. Use the /BACKWARD
    qualifier to recover a file using a journal that has before-image
    journal entries for the data file that you specify.

    To specify a date and time to which the file is to be rolled
    backward, use the /UNTIL qualifier. You should normally use this
    qualifier for before-image recovery; if you do not use the /UNTIL
    qualifier when you specify the /BACKWARD qualifier, the file is
    automatically rolled back to the time when the first entry was
    made in your before-image journal.

    The file is rolled back using the before-image journal that was
    specified when the file was marked for journaling with the SET
    FILE/BI_JOURNAL command. You can override this default by using
    the /JOURNAL qualifier.

    You must always specify either the /BACKWARD or the /FORWARD
    qualifier, but you cannot specify both.

    When you use before-image recovery for a file that also uses
    recovery unit journaling, the RMS Recovery Utility ensures
    that the data consistency provided by recovery unit journaling
    is maintained. The before-image journal includes records of a
    transaction being started, prepared, committed, or aborted.

    If you use the RECOVER/BACKWARD command to roll back a file that
    is also marked for recovery unit journaling, the file is rolled
    back and includes modifications for all transactions that were
    completed (committed) on or before the ending time of the before-
    image recovery, as follows:

    o  If, at the time before-image recovery is to end, there are no
       active transactions, then before-image recovery takes place in
       the same way as when there is no recovery unit journaling.

    o  If one or more transactions are active at the time before-
       image recovery is to end, only those modifications made within
       transactions that were completed (committed) on or before the
       ending time are included in the file.

       For example, suppose you issue the command RECOVER/BACKWARD
       /UNTIL=10:30 for a file marked for both before-image and
       recovery unit journaling. When before-image recovery is
       complete, the rolled-back file will include all modifications
       that were made within those transactions that completed on or
       before 10:30.

    o  If you apply before-image recovery to a file that is used in a
       multifile application, then you must use the /UNTIL qualifier
       with the RECOVER/BACKWARD command in order to specify a
       time to which the file is rolled back. You should then roll
       back each of the files in the application to the same time
       specified for the first file. If you do not use the same time
       value for the /UNTIL qualifier, then the modifications for one
       or more transactions may be restored to some of your files,
       but not to others.

       If you attempt to recover a file used in a multifile
       application that uses more than one before-image journal,
       the journals must be recovered in their entirety to assure
       transaction consistency. If you use the /UNTIL qualifier, the
       recovered files may still be inconsistent.

    When the recovery operation is complete, the RMS Recovery Utility
    displays the time of the last record it processed (rolled back).
    This is generally the time of the first record modification
    after the ending time (as specified with the /UNTIL qualifier);
    however, it could be an earlier time if there were one or more
    incomplete transactions at the ending time of the before-
    image recovery. In this case, modifications made within such
    transactions are automatically undone as part of the before-image
    recovery operation, and the time of the last record processed
    would reflect the first record modified within one of those
    transactions.

2.2    /BEFORE

       /BEFORE[=time]

    Selects only those files dated prior to the specified time.
    You can specify time as an absolute time, as a combination of
    absolute and delta times, or as one of the following keywords:
    TODAY (default), TOMORROW, or YESTERDAY. To indicate the time
    attribute to be used as the basis for selection, specify one
    of the following qualifiers with /BEFORE: /BACKUP, /CREATED
    (default), /EXPIRED, or /MODIFIED.

    For complete information on specifying time values, see the
    OpenVMS User's Manual.

2.3    /BI_BUFFER_SIZE

       /BI_BUFFER_SIZE=blocks

    Specifies the number of blocks that RMS recovery reads for each
    I/O from the journal. This qualifier is similar in concept to the
    multiblock count field (RAB$B_MBC) in RMS. The blocks parameter
    is the size of the buffer used to read the before-image journal.
    The parameter can takes values of 1 to 127 blocks.

    Use the /BI_BUFFER_SIZE qualifier to tune your application and
    improve performance during recovery. For more information on
    how to tune your application using this value, see the Designing
    Files/Units of Input/Output section in the Guide to OpenVMS File
    Applications and the OpenVMS Record Management Services Reference
    Manual.

    You can use the /BI_BUFFER_SIZE qualifier only when you specify
    the /BACKWARD qualifier.

2.4    /BY_OWNER

       /BY_OWNER[=uic]

    Selects only those files whose owner user identification code
    (UIC) matches the specified owner UIC. The default UIC is that of
    the current process.

    Specify the UIC using standard UIC format as described in the VMS
    DCL Concepts Manual.

2.5    /CACHE_SIZE

       /CACHE_SIZE=buckets

    Specifies the number of indexed file buckets that are retained
    by in-memory cache during a recovery operation. Use the /CACHE_
    SIZE qualifier to set the size of a cache in order to improve
    performance when recovering indexed files. In general, the
    performance of the recovery operation improves as the cache size
    grows larger. However, other system considerations could affect
    the ideal size.

    The /CACHE_SIZE qualifier is similar in concept to the
    multibuffer count field (RAB$B_MBF) in RMS. For more information
    on how to tune your application using this value, see the Guide
    to OpenVMS File Applications and the OpenVMS Record Management
    Services Reference Manual.

    The /CACHE_SIZE qualifier applies only to indexed files. You can
    use this qualifier with either /BACKWARD or /FORWARD recovery.

2.6    /CREATED

       /CREATED (default)

    Modifies the time value specified with the /BEFORE or /SINCE
    qualifier. The /CREATED qualifier selects files based on their
    dates of creation. This qualifier is incompatible with the other
    qualifiers that allow you to select files according to time
    attributes: /BACKUP, /EXPIRED, and /MODIFIED. If you specify
    none of these four time qualifiers, the default is /CREATED.

2.7    /EXCLUDE

       /EXCLUDE=(file-spec[,...])

    Excludes the specified files from the recovery operation. You can
    include a directory but not a device in the file specification.
    Wildcard characters are allowed in the file specification.
    However, you cannot use relative version numbers to exclude a
    specific version. If you provide only one file specification, you
    can omit the parentheses.

2.8    /FORWARD

    Rolls a file forward from a previous state. Use the /FORWARD
    qualifier to recover a backup file by using the after-image
    journaling information contained in a journal.

    You must always specify either /FORWARD or /BACKWARD, but you
    cannot specify both.

    When you use the /FORWARD qualifier, you must use a backup copy
    of the original data file as the file specification in your
    RECOVER/RMS_FILE command line.

    The re-doing operation starts at the time the most recent backup
    was made (assuming that the /RECORD qualifier was used), and the
    backup file is rolled forward until the time of the most recent
    entry in the journal. You can override the latter value with the
    /UNTIL qualifier.

    The file is rolled forward using the after-image journal that was
    specified when the file was marked for journaling with the SET
    FILE/AI_JOURNAL command. If the after-image journal has been
    moved from its original directory, or if it has a different
    file name, or if it has been restored to disk from magnetic
    tape, then you must use the /JOURNAL qualifier to identify the
    journal. If you have more than one journal (for example, if you
    did not use the BACKUP/RECORD command immediately after creating
    a new journal), then you must use a series of as many RECOVER
    /FORWARD commands as there are journals. The RMS Recovery Utility
    automatically knows which journal to use (unless it has been
    moved or restored from a backup copy, in which case you must
    use the /JOURNAL qualifier), and it also prompts you to issue
    a subsequent RECOVER/FORWARD command by displaying a message
    indicating that another journal is to be processed.

    When the after-image recovery operation is complete, you must re-
    mark the restored file for after-image journaling before it can
    be used for further processing using after-image journaling. Re-
    marking the file for after-image journaling sets the "journaling
    enabled" bit in the file header, which had automatically been
    turned off by the Backup Utility when the backup copy was made.
    Immediately after re-marking the restored file for after-image
    journaling, you should also make a backup copy of it.

    When you use after-image recovery for a file that also uses
    recovery unit journaling, the RMS Recovery Utility ensures
    that the data consistency provided by recovery unit journaling
    is maintained. The after-image journal includes records of a
    transaction being started, prepared, committed, or aborted.

    If you use the RECOVER/FORWARD command to roll forward a file
    (that is, the backup copy of a data file) that is also marked
    for recovery unit journaling, the file is rolled forward and
    includes modifications for all transactions that were completed
    (committed) on or before the ending time of the after-image
    recovery, as follows:

    o  If, at the time after-image recovery is to end, there are no
       active transactions, then after-image recovery takes place in
       the same way as when there is no recovery unit journaling.

    o  If one or more transactions are active at the time after-
       image recovery is to end, only those modifications made within
       transactions that were completed (committed) on or before the
       ending time are applied to the file.

       For example, suppose you issue the command RECOVER/FORWARD
       /UNTIL=10:30 for the backup copy of a file marked for both
       after-image and recovery unit journaling. When after-image
       recovery is complete, the restored file will include all
       modifications that were made within those transactions that
       completed on or before 10:30.

    o  If your application uses more than one file, the following
       conditions apply to the use of the /UNTIL qualifier:

       -  If you do not use the /UNTIL qualifier with the first
          backup copy that you restore with the RECOVER/FORWARD
          command, you need only restore those files in the
          application that are corrupted or lost. However, in this
          case, do not use the /UNTIL qualifier with any of the files
          that you restore, in order to maintain data consistency
          among all of those files.

       -  If you do use the /UNTIL qualifier with the first file
          that you restore with the RECOVER/FORWARD command, then
          you must restore every file in the application, and you
          must use the /UNTIL qualifier with the same time value for
          each file. If you do not use the same time value for the
          /UNTIL qualifier, then the modifications for one or more
          transactions may be restored to some of your files, but not
          to others.

          If you attempt to recover a file used in a multifile
          application that uses more than one after-image journal,
          the journals must be recovered in their entirety to assure
          transaction consistency. If you use the /UNTIL qualifier,
          the recovered files may still be inconsistent.

2.9    /JOURNAL

       /JOURNAL=journal-filespec

    Specifies the journal that is to be used for recovery operations.
    By default, the RMS Recovery Utility uses the file specification
    for the journal that was specified when the data file was marked
    for journaling (with the SET FILE/AI_JOURNAL or the SET FILE/BI_
    JOURNAL command). To override the default and specify a different
    file specification for the same journal, use the /JOURNAL
    qualifier. The default file specification for the journal is
    filename.RMS$JOURNAL. You can use the /JOURNAL qualifier if the
    journal is in a different location from that originally specified
    in the SET FILE command (for example, if the original journal
    becomes unusable and a backup copy of the journal is on another
    volume).

    You can only use a journal that contains valid after-image or
    before-image data for the specified file.

    If you have a series of journals that are to be used in the
    recovery operation, and the journals have the same file
    specifications as when the SET FILE commands were issued, then
    you do not need to use the /JOURNAL qualifier. In this case,
    simply use a series of RECOVER commands, as explained in OpenVMS
    RMS Journaling Manual.

2.10    /LOG

       /LOG
       /NOLOG (default)

    Generates a log of the recovery operation. When you use the
    /LOG qualifier, the RMS Recovery Utility displays the number
    of records that were processed during the recovery operation,
    and the date and time of the last record that was processed
    (recovered).

2.11    /MODIFIED

    Modifies the time value specified with the /BEFORE or /SINCE
    qualifier. The /MODIFIED qualifier selects files according to
    the dates on which they were last modified. This qualifier is
    incompatible with the other qualifiers that allow you to select
    files according to time attributes: /BACKUP, /CREATED, and
    /EXPIRED. If you specify none of these four time modifiers, the
    default is /CREATED.

2.12    /SINCE

       /SINCE[=time]

    Selects only those files dated after the specified time. You
    can specify time as an absolute time, a combination of absolute
    and delta times, or as one of the following keywords: TODAY
    (default), TOMORROW, or YESTERDAY. Specify one of the following
    qualifiers with /BEFORE to indicate the time attribute to be
    used as the basis for selection: /BACKUP, /CREATED (default),
    /EXPIRED, or /MODIFIED.

    For complete information on specifying time values, see the
    OpenVMS User's Manual.

2.13    /UNTIL

       /UNTIL=time

    Specifies the ending date and time for an after-image or before-
    image recovery operation. Specify the date and time using either
    absolute time or delta time. See the OpenVMS Glossary for more
    information about specifying absolute or delta time. The /UNTIL
    qualifier functions as follows:

    o  For after-image recovery, the /UNTIL qualifier specifies the
       date and time up to which the backup copy of the data file is
       to be restored. If you do not use the /UNTIL qualifier with
       after-image recovery, then all updates through the most recent
       update recorded in the after-image journal are restored.

    o  For before-image recovery, the /UNTIL qualifier specifies the
       date and time to which the data file is rolled back. That is,
       all modifications to the data file from the present time to
       the time specified with the /UNTIL qualifier are removed. In
       most cases, you should use the /UNTIL qualifier with before-
       image recovery; if you do not, then all modifications recorded
       in the before-image journal are removed.

    If you are recovering a file that is also marked for recovery
    unit journaling, the following rules apply:

    o  For applications using only one file, if the time specified
       with the /UNTIL qualifier (or the most recent modification in
       an after-image recovery if /UNTIL is not used) is a point at
       which there are no active transactions for the file, then
       the file is restored to the time specified by the /UNTIL
       qualifier.

    o  If one or more transactions were active at the time specified
       by /UNTIL, only those modifications made within transactions
       that were completed (committed) on or before that time are
       applied to the file. For example, suppose you issue the
       command RECOVER/FORWARD/UNTIL=10:30 for the backup copy of a
       file marked for both after-image and recovery unit journaling.
       Then, the restored file will include all modifications that
       were made within those transactions that completed on or
       before 10:30. (The same rule applies to before-image recovery:
       only those modifications made within transactions that were
       completed before the /UNTIL time are included in the restored
       file.)

    o  For applications using after-image recovery in which more than
       one file is associated with record streams connected to the
       same transaction, you should exercise care in choosing whether
       or not to use the /UNTIL qualifier. If you do not use the
       /UNTIL qualifier with the first backup copy that you restore
       with after-image journaling, you need only restore those files
       in the application that are corrupted or lost. In this case,
       do not use the /UNTIL qualifier with any of the files that
       you restore. However, if you do use the /UNTIL qualifier with
       the first file that you restore, then you must restore each
       file in the application, using the /UNTIL qualifier with the
       same time value for each file. If you do not use the same time
       value for the /UNTIL qualifier, then the modifications for one
       or more transactions may be restored to some of your files,
       but not to others.

    o  For applications using before-image recovery in which more
       than one file is associated with record streams connected
       to the same transaction, use the /UNTIL qualifier with the
       command RECOVER/BACKWARD in order to specify a time to which
       the file is rolled back. Then restore each of the files in
       the application to the same time specified for the first file,
       in order to ensure that the modifications for one or more
       transactions are not restored to some of your files, but not
       to others.

    o  If you attempt to recover a file used in a multifile
       application that uses more than one after-image or before-
       image journal, the journals must be recovered in their
       entirety to assure transaction consistency. If you use
       the /UNTIL qualifier, the recovered files may still be
       inconsistent.

                                      NOTE

          The /UNTIL qualifier is a positional qualifier. For
          example, if you enter the following command, the file
          FILE-1 will be recovered up to the present, and file
          FILE-2 will be recovered until "yesterday."

          $ RECOVER/FORWARD FILE-1,FILE-2/UNTIL=YESTERDAY

3  –  Examples

    1.$ RECOVER/RMS_FILE/BACKWARD/LOG/UNTIL=30-JUN-1990 WEEKLY.DAT

      %RMSREC-I-FILBACKWARD, $DISK1:[PAYROLL]WEEKLY.DAT;17 rolled backward
      %RMSREC-I-DATETIME, date/time of last record processed:
                30-JUN-1990 07:41:23.27
      %RMSREC-I-NUMRECS, 936 records processed

      This command rolls the file WEEKLY.DAT backward until 30 June
      1990 (default time of day of 00:00). The Recovery Utility
      automatically uses the before-image journal that was specified
      (or implied) with the most recent SET FILE/BI_JOURNAL command
      for the file SALES.DAT. The /LOG qualifier instructs the RMS
      Recovery Utility to display the number of records processed
      (that is, undone) and the date and time that the last record
      was written.

      After this command is executed, the file WEEKLY.DAT is the same
      as it was at midnight, 30 June 1990.

    2.$ DIRECTORY/SIZE ACCOUNTS_PAYABLE.RMS$JOURNAL

       ACCOUNTS_PAYABLE.RMS$JOURNAL;1      108

      $ RECOVER/RMS_FILE/BACKWARD/BI_BUFFER_SIZE=108 ACCOUNTS_PAYABLE.DAT

      This example shows that the journal called ACCOUNTS_
      PAYABLE.RMS$JOURNAL has a size of 108 blocks. The RECOVER/RMS_
      FILE/BI_BUFFER=108 command sets the buffer to be 108 blocks.

    3.$ RECOVER/FORWARD/UNTIL=30-JUN-1990/LOG WEEKLY_BACKUP.DAT

      %RMSREC-I-FILFORWARD, $DISK1:[PAYROLL]WEEKLY_BACKUP.DAT;17 rolled
                forward
      %RMSREC-I-DATETIME, date/time of last record processed:
                30-JUN-1990 15:23:44.30
      %RMSREC-I-NUMRECS, 2554 records processed

      This command rolls the file WEEKLY_BACKUP.DAT forward,
      beginning at the time that the file was created by the Backup
      Utility. It is rolled forward until 30 June 1990 (using the
      default time of day 00:00). Using the /LOG qualifier provides
      information about the number of records processed and the date
      and time of the last record that was restored. This RECOVER
      command assumes the default qualifier /RMS_FILE.

      After this operation, the file WEEKLY_BACKUP.DAT is the same as
      the data file for which it was the backup copy (WEEKLY.DAT)
      at midnight on 30 June 1990. In order to use the restored
      file WEEKLY_BACKUP.DAT for further processing in which after-
      image journaling will take place, you must re-mark the file for
      after-image journaling.

    4.$ RECOVER/RMS_FILE/FORWARD/LOG BACKUP.DAT

      %RMSREC-I-FILFORWARD, $DISK1:[PAYROLL]BACKUP.DAT;17 rolled forward
      %RMSREC-I-DATETIME, date/time of last record processed:
                4-MAY-1990 11:28:29.74
      %RMSREC-I-NUMRECS, 3490 records processed

      This command rolls the file forward, beginning at the point
      at which the last backup was made (using the BACKUP/RECORD
      command) and continuing through the last record that was
      written to the journal. At this point, the recovered file has
      the same data as the data file on 4 May at 11:28, with the file
      characteristics of the backup file.

    5.$ RECOVER/FORWARD/JOURNAL=ARCHIVE_DISK:INVENTORY INVENTORY.BCK

      In this example, the after-image journal called ARCHIVE_
      DISK:INVENTORY.RMS$JOURNAL is applied to the file
      INVENTORY.BCK, which is a backup copy of a data file. In this
      case, ARCHIVE_DISK:INVENTORY.RMS$JOURNAL might be either a
      backup copy of a valid after-image journal, or the original
      journal itself which had been moved to a different volume. The
      /RMS_FILE qualifier is used by default.
Close Help