Requires read (R), write (W), and control access. Being the owner
of the file is one way to get control access.
Marks an RMS file for recovery unit journaling.
The SET FILE command is not supported for remote files. You
must use the SET FILE command from the system where the file
is located.
For more information, see the RMS Journaling documentation.
Format
SET FILE/[NO]RU_JOURNAL[=volume-name] data-filespec[,...]
1 – Parameters
volume-name
Specifies the volume on which the recovery unit journals will be
located, using one of the following keywords:
o DEVICE=device_name specifies a device name or logical name.
o LABEL=volume-label specifies a volume label.
By default, recovery unit journals are created temporarily in the
[SYSJNL] directory on the same volume as the file that is being
journaled. (If such a directory does not exist, RMS journaling
creates it automatically.) You can change the device on which the
recovery unit journals are created by using either the DEVICE or
LABEL keyword.
Use the DEVICE keyword to specify the location of recovery unit
journals using a device name or a logical name. Use the LABEL
keyword to specify the location of recovery unit journals using a
volume label. You can only use one of these two keywords (LABEL
or DEVICE) to specify the recovery unit journal location. In
either case, only the volume label is actually stored with the
file.
At run time, RMS attempts to translate the logical name
DISK$volume_label when creating a recovery unit journal. This
is the default logical name created by the Mount Utility when you
mount the disk using the /SYSTEM or /CLUSTER qualifier. If you do
not mount the disk using the /SYSTEM or /CLUSTER qualifier, you
must define the logical name DISK$volume_label using the DEFINE
command with the /SYSTEM and /EXECUTIVE_MODE qualifiers. You
must have the SYSNAM (system logical name) or the SYSPRV (system
privilege) privilege to use the /SYSTEM qualifier.
NOTE
The logical name DISK$volume_label can point to any
disk device on the system that is mounted and has for
its volume label an executive-mode logical name in the
form DISK$volume_label with the concealed and terminal
attributes.
data-filespec[,...]
Specifies the file that is to be marked for recovery unit
journaling. If a data file has been marked for recovery unit
journaling with this command, DECdtm transaction services
($START_TRANS, $END_TRANS, and $ABORT_TRANS) must be used by
an application program to define transactions whenever data in
this file is modified.
If you specify more than one file, separate the file
specifications with commas. The asterisk (*) and the percent
sign (%) wildcard characters are allowed. The file specification
cannot include a node name, since the SET FILE command is not
valid for network access.
2 – Description
The SET FILE/RU_JOURNAL command marks an RMS file for recovery
unit journaling. To use recovery unit journaling for a data file,
a data file must be marked for recovery unit journaling with the
SET FILE/RU_JOURNAL command, and transactions must be defined
in an application program using DECdtm transaction services. You
can also use this command to specify the default volume on which
recovery unit journals will be created for this file.
Use the SET FILE/NORU_JOURNAL command to unmark a file for
recovery unit journaling. After you use the SET FILE/NORU_JOURNAL
command for a file, modifications to that data file will no
longer be written to a recovery unit journal.
If you wish to delete a file that has been marked for recovery
unit journaling, you must use the SET FILE/NORU_JOURNAL command
before you can delete the file.
There is no reason other than performance to keep recovery unit
journals on a different volume from the file being journaled.
Unlike after-image journaling, which protects against a system
failure such as a head crash that causes a loss of data, recovery
unit journaling ensures that a predefined set of operations are
either done in their entirety, or not done at all. In the event
of an abnormal termination of the application, such as a system
crash or a Ctrl/Y, any incomplete transactions are automatically
rolled back (undone). Because all recovery unit journals must
be available before the data files can be rolled back, locating
recovery unit journals on a volume where availability might be
low could reduce the availability of the data files that use
those recovery unit journals.
Specifying a location for recovery unit journals for a file
does not guarantee that the recovery unit journals will always
be located on the named device or volume. For any active
transaction, there is always only one recovery unit journal for
local files. Thus, if many files are involved in a transaction, a
single recovery unit journal is used, even if different locations
for the journals had been specified (for individual files) with
different SET FILE/RU_JOURNAL commands.
Remote files are an exception to this rule. Each remote file
associated with a transaction has its own recovery unit and
recovery unit journal. The recovery unit journal resides on the
remote system. The volume is chosen in the same way as for local
files. Remote files have no effect in determining where the local
recovery unit journal resides.
A journal is not deleted when the transaction has been completed.
Recovery unit journals are automatically deleted only when
all of the files involved in the transaction are closed and
the application exits. RMS journaling automatically creates a
recovery unit journal at run time, whenever the first record
stream associates with a transaction. All record streams in
the process associated with the same transaction share a single
recovery unit journal. Once a recovery unit journal is created,
it can be reused for another transaction by the process that
created it. A recovery unit journal is created only when there is
no available recovery unit journal opened by the process for the
current transaction.
3 – Examples
1.$ SET FILE/RU_JOURNAL FINANCE_DISK:[PAYROLL]WEEKLY.DAT
This command marks the file WEEKLY.DAT for recovery unit
journaling. Any operation within an application that modifies
this file must be in a defined transaction (defined by DECdtm
transaction services).
2.$ SET FILE/AI_JOURNAL=(FILE=JNL_DISK:, CREATE)-
_$ /RU_JOURNAL/LOG OVERDUE.DAT
%SET-I-JCREATED, journal JNL_DISK:[PAYABLE]OVERDUE.RMS$JOURNAL;1
created
%SET-I-FILMARKAI, WORK_DISK:[PAYABLE]OVERDUE.DAT;1 marked for RMS
after-image journaling
-SET-I-JFILE, using journal JNL_DISK:[PAYABLE]OVERDUE.RMS$JOURNAL;1
%SET-I-FILMARKRU, WORK_DISK:[PAYABLE]OVERDUE.DAT;1 marked for RMS
recovery-unit journaling
%SET-I-MODIFIED, WORK_DISK:[PAYABLE]OVERDUE.DAT;1 modified
$ SET FILE/AI_JOURNAL=(FILE=JNL_DISK:OVERDUE)-
_$ /RU_JOURNAL/LOG CURRENT.DAT
%SET-I-FILMARKAI, WORK_DISK:[PAYABLE]CURRENT.DAT;1 marked for RMS
after-image journaling
-SET-I-JFILE, using journal JNL_DISK:[PAYABLE]OVERDUE.RMS$JOURNAL;1
%SET-I-FILMARKRU, WORK_DISK:[PAYABLE]CURRENT.DAT;1 marked for RMS
recovery-unit journaling
%SET-I-MODIFIED, WORK_DISK:[PAYABLE]CURRENT.DAT;1 modified
In this example, the files OVERDUE.DAT and CURRENT.DAT are
marked for after-image and recovery unit journaling using two
SET FILE commands. In this example, a single journal (JNL_
DISK:[PAYABLE]OVERDUE.RMS$JOURNAL) is used for after-image
journaling.
The first SET FILE command uses the /CREATE
qualifier to create a new after-image journal, JNL_
DISK:[PAYABLE]OVERDUE.RMS$JOURNAL, for the file OVERDUE.DAT.
The file specification uses the current default directory
[PAYABLE] and the default file extension RMS$JOURNAL.
The second SET FILE command marks the file CURRENT.DAT for
after-image and recovery unit journaling, checks the disk JNL_
DISK to see whether an after-image journal already exists, and
uses the existing journal JNL_DISK:[PAYABLE]OVERDUE.RMS$JOURNAL
for the file CURRENT.DAT.