Marc's Place

1  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[,...]
                      {          }
 

2  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
 

/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.
 

/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.
 

/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.
 

/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.
 

/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.
 

/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.
 

/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.
 

/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.
 

/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.
 

/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).
 

/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.
 

/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.
 

/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
 

2  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.
Software development, photography, jokes, ....

Sites by me

Hosting Favorites

Blogroll

Marc's Place

1 RECOVER
