HELPLIB.HLB  —  SET  FILE  /RU_JOURNAL
    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.
Close Help