Copyright Digital Equipment Corp. All rights reserved.
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