After-image journaling lets you redo changes that were applied to a data file.

When a file is marked for after-image journaling, a continuous record of all changes that are made to that file is maintained in a journal.

If a data file becomes unusable, either because the files were corrupted (for example, by a disk head crash) or because the files were lost (for example, due to inadvertent deletion), you can use after-image recovery to restore the file. In after-image recovery, the data file is rolled forward by reapplying the journalled changes to a backup copy of the file.

The following diagram illustrates the overall operation of after-image journaling and recovery.

Before-image journaling lets you undo changes that were applied to a data file and restore the records to a previous state.

When a file is marked for before-image journaling, a continuous history of the state of the records in the file is maintained in a journal.

If bad data is introduced into the file (for example, through operator error or communications problems), you can use before-image recovery to restore the file to a previous, valid state. In before-image recovery, the data file is rolled backward from the current time to a point prior to the introduction of the bad data.

The following diagram illustrates the overall operation of before-image journaling and recovery.

Recovery unit journaling lets you ensure the internal consistency of data being used by an application by defining a set of related RMS operations within the application, called a transaction, that must either be completed in its entirety, or not performed at all.

A typical transaction is a transfer of funds that involves debiting one account and crediting a second account. If a system failure occurs during a funds transfer, causing the first account to be debited without crediting the second account, recovery unit journaling rolls back both accounts to their previous, consistent state.

A recovery unit consists of all the RMS operations performed by a single process within a transaction. A transaction can include more than one recovery unit.

When a file is marked for recovery unit journaling, a continuous history of the state of each record involved in a transaction is maintained in a journal until that transaction is completed.

If a transaction is not successfully completed, before the records accessed in the transaction are made available for further processing, recovery unit recovery restores those records to their states prior to the beginning of the transaction.

The following diagram illustrates the overall operation of recovery unit journaling and recovery.

The /RU_JOURNAL qualifier provides information about recovery unit journaling for the file that you analyze. If a file is unavailable because it is part of an unresolved transaction (for example, because a recovery unit journal or a data file that was included in the transaction is unavailable), you can use the ANALYZE/RMS_FILE/RU_JOURNAL command to identify the recovery unit journal and all data files involved in the transaction. This command is the only means of access to the RMS file until the transaction is resolved.

Your process must have both CMEXEC privilege and access to the [SYSJNL] directory (either SYSPRV [system privilege] privilege, or access for UIC [1,4]) to use the ANALYZE/RMS_FILE/RU_JOURNAL command.

Example

$ ANALYZE/RMS_FILE/RU_JOURNAL CHECKING.DAT

Check RMS File Integrity       30-MAY-1990 09:33:14.35
DISK$WORK:[ACCOUNTING]CHECKING.DAT;1

FILE HEADER
   .
   .
   .

        Journaling Enabled:  Recovery Unit

RMS FILE ATTRIBUTES
   .
   .
   .

        Recovery Unit Journaling
                Default RU Journal Volume: none specified

ACTIVE RMS RECOVERY UNITS  
        Journal Spec: DISK$WORK:[SYSJNL]RMS$79400083.RMS$JOURNAL;1  
        Journal Creation Date: 30-MAY-1990 08:21:05.83
        Transaction ID: (hex) 8144F8A0 00934716 4C74A6CA 00000000
        Recovery Unit Start Time: 30-MAY-1990 09:14:03.68
        Recovery Unit PID: 79400083
        File(s) involved in this Recovery Unit:  

                File Spec: DISK$WORK:[ACCOUNTING]CHECKING.DAT;1  
                Volume name: WORK
                File ID: (974,40,0)
                Creation Date: 22-MAR-1990 09:30:36.82
                Status:  Normal

        Recovery Unit State:  Started  

The analysis uncovered NO errors.

The following table explains the numbered items in the example.

Phase	Meaning	Actions Required
	The heading Active RMS Recovery Units lists all active recovery units that involve the file. If the file that you analyze has been marked for recovery unit journaling but has no active recovery units, then the ANALYZE/ RMS_FILE/RU_JOURNAL command displays a message stating "No Active RMS Recovery Units" after the Active RMS Recovery Unit heading.
	The Journal Spec field provides the file specification for the recovery unit journal that was in use for the file CHECKING.DAT.	Verify that the volume DISK$WORK is on line and available, and that the [SYSJNL] directory is available and contains the journal named.
	If the file name in the ANALYZE/RMS_FILE/RU_JOURNAL command has one or more active transactions, the output of the command lists all of the files with record streams joined to each of those 5 4 3 2 1 transactions.	Verify that any file listed as being in the recovery unit is available.
	In this case, there is only one file connected to the transaction.
	The Recovery Unit State field provides the primary information about the status of recovery units and the possible reasons for the unavailability of the file.

If there are active recovery units on the file, then the active recovery units will be in one of the following states, as indicated in the Recovery Unit State field:

You can also use the DIRECTORY/FULL command to determine whether journaling is enabled or disabled (by the Backup utility [BACKUP]) for a particular file. Remember that when a file is backed up using BACKUP, the backup copy of the file is marked for journaling (in the same way that the original file is marked for journaling), but journaling is automatically disabled.

Example: DIRECTORY/FULL command

For example, suppose that file DISK1:[PERSONAL]SAVINGS.DAT had been marked for after-image, before-image, and recovery unit journaling, and it was then backed up using BACKUP. The DIRECTORY/FULL output for the original file and its backed-up version might look like the following example:

$ SET FILE/AI_JOURNAL=(FILE=JOURNAL_DISK:CHECKING) SAVINGS.DAT
$ SET FILE/BI_JOURNAL/RU_JOURNAL SAVINGS.DAT
$ BACKUP/RECORD SAVINGS.DAT JOURNAL_DISK:SAVINGS.BCK
$ DIRECTORY/FULL SAVINGS.DAT

Directory DISK1:[PERSONAL]

SAVINGS.DAT;1                 File ID:  (675,35,0)
Size:            6/6          Owner:    [200,201]
Created:  27-JAN-1990 12:54   Revised:  19-MAY-1990 14:31 (17)
Expires:   <None specified>   Backup:   12-MAY-1990 07:57
File organization:  Indexed, Prolog: 3, Using 1 key
File attributes:    Allocation: 6, Extend: 0, Maximum bucket size: 2,
                    Global buffer count: 0, No version limit
Record format:      Fixed length 18 byte records
Record attributes:  Carriage return carriage control
Journaling enabled: AI, BI, RU
AI journal:    JOURNAL_DISK:[PERSONAL]CHECKING.RMS$JOURNAL;1
BI journal:    DISK1:[PERSONAL]SAVINGS.RMS$JOURNAL;1
File protection:    System:RWE, Owner:RWED, Group:RE, World:RE

Total of 1 file, 426/426 blocks.
$ DIRECTORY/FULL SAVINGS.BCK

Directory JOURNAL_DISK:[PERSONAL]
SAVINGS.BCK;1                File ID:  (906,37,0)
Size:            6/6          Owner:    [200,201]
Created:  27-JAN-1990 12:54   Revised:  12-MAY-1990 07:50 (17)
Expires:   <None specified>   Backup:   12-MAY-1990 07:57
File organization:  Indexed, Prolog: 3, Using 1 key
File attributes:    Allocation: 6, Extend: 0, Maximum bucket size: 2,
                    Global buffer count: 0, No version limit
Record format:      Fixed length 18 byte records
Record attributes:  Carriage return carriage control
Journaling enabled: AI (disabled by BACKUP), BI (disabled by BACKUP), RU
AI journal:    JOURNAL_DISK:[PERSONAL]CHECKING.RMS$JOURNAL;1
BI journal:    DISK1:[PERSONAL]SAVINGS.RMS$JOURNAL;1
File protection:    System:RWE, Owner:RWED, Group:RE, World:RE

Total of 1 file, 424/424 blocks.

The output for SAVINGS.BCK indicates that the file is marked for after-image and before-image journaling, but that journaling is disabled because the file is a backup copy.

To mark a file for after-image journaling, use the DCL command SET FILE/AI_JOURNAL. This command specifies that all modifications to the file be recorded in a journal.

Example

For example, to mark the file FINANCE_DISK:SALES.DAT for after-image journaling, use the following command:

$ SET FILE/AI_JOURNAL FINANCE_DISK:SALES.DAT

Restrictions

You must use the SET FILE/AI_JOURNAL command from the system where the file is located, which may be different from the system where the application is run.

The file to be journalled must be available with exclusive access (that is, it must already exist and not be currently opened by any process).

To discontinue the use of after-image journaling for a file, use the SET FILE/NOAI_JOURNAL command to unmark the file. For example:

$ SET FILE/NOAI_JOURNAL FINANCE_DISK:SALES.DAT

You must use the SET FILE/NOAI_JOURNAL command before deleting a file that is marked for after-image journaling.

If you issue more than one SET FILE/AI_JOURNAL command for the same file, only the most recent command applies. You cannot mark a file for afterimage journaling to more than one journal at a time. However, you can use the command SET FILE/AI_JOURNAL=FILE to change the journal for a file that is already marked for after-image journaling.

Example

For example, suppose that the file SALES.DAT was originally marked for after-image journaling using the keyword FILE=JNL_DISK: to use the journal JNL_DISK:SALES.RMS$JOURNAL. You can change the journal to a new journal, JNL_DISK:WEEKLY.RMS$JOURNAL, with the following command:

$ SET FILE/AI_JOURNAL=(FILE=JNL_DISK:WEEKLY,CREATE) SALES.DAT

If after-image recovery is required, the RMS Recovery utility uses both the old and newly created journals to restore your file. To save disk space and improve performance during the recovery operation, make a backup copy of the modified file that points to the new journal. Once you have created a new journal and made a backup copy of the modified file, you can delete the previous backup copy of the file and the original journal.

If you are using after-image journaling to protect against a loss of data due to device failure, you should always maintain your after-image journal on a different volume from the one where your data file resides. Then, if a disk head crash or other similar event occurs that corrupts data on one of the volumes, either the original file or its journal and backup copy will remain intact.

The default file specification for an after-image journal is the same as the file specification of the file that you mark for after-image journaling, except that its file type is .RMS$JOURNAL. To maintain the journal on a different volume from the data file, be sure to override the default device specification when you use the FILE keyword. If you mark a file for after-image journaling and specify a journal that is on the same volume as the file, a warning message (INVAILDEV) is issued.

Example

For example, suppose that you want to use after-image journaling on the file FINANCE_DISK:[PAYROLL]WEEKLY.DAT, and that you want to keep the journal on the volume JOURNAL_DISK. To mark this file for after-image journaling and create a new journal, use the following command:

$ SET FILE/AI_JOURNAL=(FILE=JOURNAL_DISK:,CREATE) -
_$ FINANCE_DISK:[PAYROLL]WEEKLY.DAT

This command creates a journal with the file specification JOURNAL_ DISK:[PAYROLL]WEEKLY.RMS$JOURNAL.

When you create a journal for after-image journaling, the file protection for the journal is determined as follows:

Since the file protection for an after-image journal is not necessarily the same as any of the files marked for after-image journaling, two problems can arise:

To avoid both of these problems, ensure that the file protection or ACL for the journal allows write access to all users who might have write access to any of the data files in your application, but only to those users.

Each file can point to only one after-image journal at any one time. However, a single after-image journal can record changes from many files. If recovery is required, you can restore any or all of the files by using the single journal.

For performance reasons, you may want to limit the number of journals that you use. In general, you can reduce the amount of journaling-related I/O in your application by reducing the number of journals.

Example

The following example illustrates how to associate more than one file with a single journal:

$ SET FILE/AI_JOURNAL=(FILE=JOURNAL_DISK:WEEKLY,CREATE) -
_$ FINANCE_DISK:PAYROLL.DAT
$ SET FILE/AI_JOURNAL=(FILE=JOURNAL_DISK:WEEKLY) -
_$ FINANCE_DISK:EXPENSES.DAT
$ SET FILE/AI_JOURNAL=(FILE=JOURNAL_DISK:WEEKLY) -
_$ SALES_DISK:SALES.DAT

The first SET FILE/AI_JOURNAL command in this sequence marks the file FINANCE_DISK:PAYROLL.DAT for after-image journaling, and creates the journal JOURNAL_DISK:WEEKLY.RMS$JOURNAL (in the current default directory).

The second and third SET FILE/AI_JOURNAL commands mark the files EXPENSES.DAT and SALES.DAT for after-image journaling, and set JOURNAL_ DISK:WEEKLY.RMS$JOURNAL to be the journal for each of these as well.

Note that the data files are on different volumes (FINANCE_DISK and SALES_ DISK), and that the single journal is on a different volume (JOURNAL_DISK) from both data files.

When you create a journal, you can set the initial size and the default extension quantity for the journal to help optimize the performance of your application. Use the ALLOCATION and EXTENSION keywords with the SET FILE_AI_ JOURNAL command to set the size parameters.

ALLOCATION keyword

The ALLOCATION keyword specifies, in blocks, the initial size of the journal. If you do not use the ALLOCATION keyword when you create a journal, the journal will have a small initial allocation.

EXTENSION keyword

The EXTENSION keyword specifies, in blocks, an extension quantity for the journal. If you do not use the EXTENSION keyword when you create a journal, RMS calculates its own EXTENSION value for the journal.

Example: setting journal size

For example, the following SET FILE command specifies an initial allocation of 100 blocks and an extension quantity of 20 blocks:

$ SET FILE/AI_JOURNAL=(FILE=JOURNAL_DISK:,CREATE,ALLOCATION=100, -
_$ EXTENSION=20) FINANCE_DISK:[PAYROLL]WEEKLY.DAT

For more information about using the ALLOCATION and EXTENSION keywords, see the VSI OpenVMS Guide to OpenVMS File Applications.

The backup copy must be made using the BACKUP command. Do not use the COPY command for this, because the copy you make will not have the proper file attributes. When you back up your file, the Backup utility must have exclusive access to the file, so do not use the /IGNORE=INTERLOCK qualifier with the BACKUP command.

You must make the backup copy of the file after you mark the file for after-image journaling, because file header information specific to journaling is generated when you mark the file for journaling, and this information must be included in the backup copy.

After-image recovery begins at the point where the most recent backup was made. Use the /RECORD qualifier with the BACKUP command to place a marker in the journal where the last backup was made; this reduces the processing required for after-image recovery.

If you back up a file, but do not use the /RECORD qualifier, you can still recover your data using after-image recovery; however, the recovery process will take longer, because you will redo more operations.

Example

For example, suppose that you used the following command to mark the file FINANCE_DISK:WEEKLY.DAT for after-image journaling:

$ SET FILE/AI_JOURNAL=(FILE=JOURNAL_DISK:) WEEKLY.DAT

To back up the file WEEKLY.DAT to a tape on device MTA0, issue the following command:

$ BACKUP/RECORD FINANCE_DISK:[PAYROLL]WEEKLY.DAT -
_$ MTA0:WEEKLY.BCK/LABEL=FIN_BCK

When you back up a file marked for after-image journaling, the backup copy is marked for after-image journaling, and a bit in the file header is set as disabled for journaling. The backup copy has the same attributes as the original file, except that the backup file cannot be opened for write operations. If the backup copy were not disabled for after-image journaling, then the journal would contain not only the changes to the original file, but also any data written to the backup copy during a recovery operation.

If you attempt to write to the backup copy of a file that has been marked for journaling, RMS returns an error message (with the status RMS$_JND) saying that the file has been marked for journaling and that journaling is disabled.

If you are using both after-image and recovery unit journaling, and an RMS I/O operation fails with an unexpected I/O error message, abort the transaction immediately. Aborting the transaction makes the after-image journal consistent with the data file.

If you are using only after-image journaling, the data file and the journal are not made consistent automatically. You can make them consistent by either replacing the journal or restoring the data file, as shown in the following table.

After-image recovery requires the following:

To invoke after-image recovery for a file, use the DCL command RECOVER/RMS_ FILE/FORWARD, using the backup copy of the file as the parameter to the command. Use the /UNTIL qualifier to specify the date and time to which the file is to be rolled forward.

Example

For example, suppose you mark a file for after-image journaling and then make a backup copy of the file with the following commands:

$ SET FILE/AI_JOURNAL=(FILE=JOURNAL_DISK:) -
_$ FINANCE_DISK:[PAYROLL]WEEKLY.DAT
$ BACKUP/RECORD FINANCE_DISK:[PAYROLL]WEEKLY.DAT -
_$ BACKUP_DISK:WEEKLY.BCK

Subsequently, a hardware failure on FINANCE_DISK corrupts the file WEEKLY.DAT. To recover the updates that were made to WEEKLY.DAT, enter the following command:

$ RECOVER/RMS_FILE/FORWARD BACKUP_DISK:WEEKLY.BCK

By default, the RECOVER/RMS_FILE command uses the journal that was assigned to the file by the SET FILE/AI_JOURNAL command. In the previous example, the journal JOURNAL_DISK:[PAYROLL]WEEKLY.RMS$JOURNAL is used.

You must use the /JOURNAL qualifier to identify the after-image journal, if the journal:

After-image recovery always begins at the first entry in the journal after the most recent BACKUP/RECORD command for the data file. If there has never been a BACKUP/RECORD command for the data file, after-image recovery begins with the first entry in the journal.

By default, after-image recovery continues up to the point of the most recent entry in the journal. However, there may be instances where you want to override this default, such as when you suspect that a recent data entry has corrupted the data file. You can specify the time at which after-image recovery is stopped using the /UNTIL qualifier, as follows:

$ RECOVER/RMS_FILE/FORWARD/UNTIL=8:00 WEEKLY.BCK

In this example, after-image recovery begins at the point where the most recent BACKUP/RECORD command was issued, and it continues only until 8:00 a.m. of the current day.

If you restore a file to its state at a specific time using the /UNTIL qualifier, you can perform subsequent after-image recoveries only if you specify a later time with the /UNTIL qualifier.

For example, if you had rolled the backup copy forward to 10:00 a.m., you could then roll the file forward further (for example, to 11:00 a.m.). Once you have rolled the file forward to 11:00 a.m., however, you cannot roll it backward to an earlier time, because the journal no longer contains updates that were made before 11:00 a.m.

If more than one file becomes corrupted, you can recover the files using one or multiple RECOVER commands, whether or not the same after-image journals were used for all files.

For example, suppose you mark two files for after-image journaling and back up the files, as follows:

$ SET FILE/AI_JOURNAL=(FILE=JOURNAL_DISK:WEEKLY_PAY,CREATE) -
_$ FINANCE_DISK:PAYROLL.DAT
$ BACKUP/RECORD FINANCE_DISK:PAYROLL.DAT BACKUP_DISK:PAYROLL.BCK
$ SET FILE/AI_JOURNAL=(FILE=JOURNAL_DISK:WEEKLY_EXPENSE,CREATE) -
_$ FINANCE_DISK:EXPENSES.DAT
$ BACKUP/RECORD FINANCE_DISK:EXPENSES.DAT BACKUP_DISK:EXPENSES.BCK

Subsequently, a system failure corrupts both PAYROLL.DAT and EXPENSES.DAT. To recover the lost updates, you can enter the following commands:

$ RECOVER/RMS_FILE/FORWARD BACKUP_DISK:PAYROLL.BCK
$ RECOVER/RMS_FILE/FORWARD BACKUP_DISK:EXPENSES.BCK

or:

$ RECOVER/RMS_FILE/FORWARD BACKUP_DISK:PAYROLL.BCK, -
_$ BACKUP_DISK:EXPENSES.BCK

In the latter case, the RMS Recovery utility uses the respective journals for each of the files.

If you have used a series of journals for after-image journaling and have not made a backup copy of your data file after the most recent SET FILE command that created or identified a new journal, you can still use after-image recovery, as long as:

To use after-image recovery, enter the same RECOVER command as if there were only a single journal; however, you must enter the command as many times as you have journals. The first RECOVER command uses the journal in effect when the most recent BACKUP/RECORD command was used, and subsequent RECOVER commands use the respective after-image journals. Whenever there are one or more journals remaining to be processed, the RMS Recovery utility issues an informational message to that effect.

Example

For example, suppose that you have used the following sequence of commands, where the ellipsis represents a period when changes were made to the file WEEKLY.DAT:

$ SET FILE/AI_JOURNAL=(FILE=BCK_DISK:FIRST_JNL,CREATE) WEEKLY.DAT
$ BACKUP/RECORD WEEKLY.DAT BCK_DISK:WEEKLY.BCK
   .
   .
   .
$ SET FILE /AI_JOURNAL=(FILE=BCK_DISK:SECOND_JNL,CREATE) WEEKLY.DAT
   .
   .
   .

It then becomes necessary to recover the file, and you enter the recover commands in the following example:

$ RECOVER/FORWARD/LOG BCK_DISK:WEEKLY.BCK   
%RMSREC-I-NXTJNLFIL, next journal to be processed is
BCK_DISK:SECOND_JNL.RMS$JOURNAL;1
%RMSREC-I-FILFORWARD, BCK_DISK:WEEKLY.BCK rolled forward
%RMSREC-I-DATETIME, date/time of last record processed: 26-JUL-1990
14:47:08.75
%RMSREC-I-NUMRECS, 282 records processed
$
$ RECOVER/FORWARD/LOG BCK_DISK:WEEKLY.BCK "   
%RMSREC-I-FILFORWARD, BCK_DISK:WEEKLY.BCK rolled forward
%RMSREC-I-DATETIME, date/time of last record processed: 6-AUG-1990
10:22:37.48
%RMSREC-I-NUMRECS, 523 records processed

After the first RECOVER command (), the RMS Recovery utility informs you that an additional journal (SECOND_JNL.RMS$JOURNAL) remains to be processed. No such message is issued after the next RECOVER command (), which means that the current after-image journal is the final one to be processed.

When you issue the RECOVER/RMS_FILE/FORWARD command, the RMS Recovery utility does not change any of the file attributes of the backup copy that it restores. Because the backup copy is disabled for journaling, the restored file is also disabled for journaling.

To use after-image journaling with the restored file, you must re-enable afterimage journaling for the file, by using the following procedure:

Example

For example, suppose that you start after-image journaling and back up your data file with the following commands:

$ SET FILE/AI_JOURNAL=(FILE=JOURNAL_DISK:) FINANCE_DISK:[PAYROLL] -
_$ WEEKLY.DAT
$ BACKUP/RECORD FINANCE_DISK:[PAYROLL]WEEKLY.DAT BACKUP_DISK:WEEKLY.BCK

Then, after a system failure, you use the following command to recover the file:

$ RECOVER/RMS_FILE/FORWARD BACKUP_DISK:[PAYROLL]WEEKLY.BCK

The RMS Recovery utility modifies the file BACKUP_DISK:WEEKLY.BCK to restore the data that was lost from the original file. The restored file is marked for journaling because the original file was marked for journaling, but it is also disabled for journaling because it was a backup copy. To use this file as your data file (replacing the old WEEKLY.DAT), issue the following sequence of commands:

$ COPY BACKUP_DISK:[PAYROLL]WEEKLY.BCK FINANCE_DISK:[PAYROLL]WEEKLY.DAT
$ SET FILE/AI_JOURNAL=(FILE=JOURNAL_DISK:) FINANCE_DISK:[PAYROLL] -
_$ WEEKLY.DAT

$ BACKUP/RECORD FINANCE_DISK:[PAYROLL]WEEKLY.DAT BACKUP_DISK:WEEKLY.BCK

To discontinue the use of before-image journaling for a file, use the SET FILE/NOBI_JOURNAL command to unmark the file. For example:

$ SET FILE/NOBI_JOURNAL SALES_DISK:WEEKLY.DAT

You must use the SET FILE/NOBI_JOURNAL command before deleting a file that is marked for before-image journaling.

If you issue more than one SET FILE/BI_JOURNAL command for the same file, only the most recent command applies. You cannot mark a file for before-image journaling to more than one journal at a time. However, you can use the SET FILE/BI_JOURNAL=FILE command to change the journal for a file that is already marked for before-image journaling.

Example

For example, suppose that the file SALES.DAT was originally marked for before-image journaling using the default journal specification, SALES.RMS$JOURNAL. You can change the journal to a new journal, WEEKLY.RMS$JOURNAL, with the following command:

$ SET FILE /BI_JOURNAL=(FILE=WEEKLY,CREATE) SALES.DAT

Unlike after-image journaling, there is no need (for data integrity purposes) to keep your data file and journal on different volumes. In before-image journaling, where you are removing bad data from a file that has not been physically corrupted, you are not concerned with the possibility of a device failure.

Example

For example, suppose that you want to use before-image journaling on the file [SALES]WEEKLY.DAT. To mark this file for before-image journaling and create a new journal, use the following command:

$ SET FILE/BI_JOURNAL=(FILE=JOURNAL_DISK:,CREATE) -
_$ FINANCE_DISK:[SALES]WEEKLY.DAT

This command marks the file WEEKLY.DAT for before-image journaling, and it creates the journal WEEKLY.RMS$JOURNAL on the volume JOURNAL_DISK with the default directory specification. Thus, the file specification for the journal will be JOURNAL_DISK:[SALES]WEEKLY.RMS$JOURNAL.

The security and access issues for before-image journals are the same as for after-image journals. The file protection and ACL for the journal that you create are based on either an existing version of the journal or on the default file protection for the process that creates the journal. The file protection is not based on the file protection of the data file that you mark for before-image journaling.

For more information, see the section Section 3.3.3 in Chapter 3.

Each file can point to only one before-image journal at any one time. However, a single before-image journal can record changes from many files. If recovery is required, you can restore any or all of the files by using the single journal.

For performance reasons, you may want to limit the number of journals that you use. In general, you can reduce the amount of journaling-related I/O in your application by reducing the number of journals.

Example

The following example illustrates how to associate more than one file with a single journal:

$ SET FILE/BI_JOURNAL=(FILE=WEEKLY,CREATE) FINANCE_DISK:PAYROLL.DAT
$ SET FILE/BI_JOURNAL=(FILE=WEEKLY) FINANCE_DISK:EXPENSES.DAT
$ SET FILE/BI_JOURNAL=(FILE=FINANCE_DISK:WEEKLY) SALES_DISK:SALES.DAT

The first SET FILE/BI_JOURNAL command in this sequence marks the file FINANCE_DISK:PAYROLL.DAT for before-image journaling, and creates the journal FINANCE_DISK:WEEKLY.RMS$JOURNAL (in the current default directory). The second and third SET FILE/BI_JOURNAL commands mark the files EXPENSES.DAT and SALES.DAT for before-image journaling, and set FINANCE_DISK:WEEKLY.RMS$JOURNAL to be the journal for each of these as well.

When you create a journal, you can set the initial size and the default extension quantity for the journal to help optimize the performance of your application. Use the ALLOCATION and EXTENSION keywords to set the size parameters.

ALLOCATION keyword

The ALLOCATION keyword specifies, in blocks, the initial size of the journal. If you do not use the ALLOCATION keyword when you create a journal, then the journal will have a small initial allocation.

EXTENSION keyword

The EXTENSION keyword specifies, in blocks, an extension quantity for the journal. If you do not use the EXTENSION keyword when you create a journal, RMS calculates its own EXTENSION value for the journal.

Example: setting journal size

For example, the following SET FILE command specifies an initial allocation of 100 blocks and an extension quantity of 20 blocks:

$ SET FILE/BI_JOURNAL=(FILE=JOURNAL_DISK:,CREATE,ALLOCATION=100, -
_$ EXTENSION=20) FINANCE_DISK:[PAYROLL]WEEKLY.DAT

For more information about using the ALLOCATION and EXTENSION keywords, see the VSI OpenVMS Guide to OpenVMS File Applications.

To invoke before-image recovery for a file, use the DCL command RECOVER/RMS_FILE/BACKWARD, using the data file as the parameter to the command. Use the /UNTIL qualifier to specify the date and time to which the data file is to be rolled back.

Example

For example, suppose that you mark a file for before-image journaling with the following command:

$ SET FILE/BI_JOURNAL=(FILE=JOURNAL_DISK:WEEKLY,CREATE) -
_$ WORK_DISK:WEEKLY.DAT

Subsequently, a data entry operator enters information that causes the data in WEEKLY.DAT to be invalid. To restore WEEKLY.DAT to its condition at a previous date and time (for example, its state as of 8:30 a.m. of the current day), enter the following command:

$ RECOVER/RMS_FILE/BACKWARD/UNTIL=8:30 WORK_DISK:WEEKLY.DAT

By default, the RECOVER/RMS_FILE command uses the journal that was assigned to the file by the SET FILE/BI_JOURNAL command. In the previous example, the journal JOURNAL_DISK:WEEKLY.RMS$JOURNAL would be used.

You must use the /JOURNAL qualifier to identify the before-image journal, if the journal:

Before-image recovery begins by undoing the most recent change, then continuing to undo changes (rolling back the file) to the date and time specified by the /UNTIL qualifier.

If you use the RECOVER/RMS_FILE/BACKWARD command without using the /UNTIL qualifier, the data file is automatically rolled back to the point where the first entry was made in the journal being used.

In before-image recovery, there are no restrictions on using the /UNTIL qualifier on successive RECOVER/BACKWARD commands to specify earlier or later times. That is, you can roll back a file until 9:00 a.m., then issue a command to roll the file back until 11:00 a.m. the same day. This is possible because before-image journaling continues to take place during before-image recovery.

If you are not sure when the bad or incorrect data was introduced into the data file, you can issue a series of before-image recovery commands to roll back the data file to successively earlier dates and times.

If more than one data file becomes corrupted, you can recover the files using one or multiple RECOVER commands, whether or not the same before-image journals were used for all files.

For example, suppose you mark two files for before-image journaling, as follows:

$ SET FILE/BI_JOURNAL=(FILE=WEEKLY_PAY,CREATE) PAYROLL.DAT
$ SET FILE/BI_JOURNAL=(FILE=WEEKLY_EXPENSE,CREATE) EXPENSES.DAT

Then, some line noise corrupts records in both of the files. To restore the files to their states as of noon on March 17, 1990, enter the following commands:

$ RECOVER/RMS_FILE/BACKWARD/UNTIL=17-MAR-1990:12 PAYROLL.DAT
$ RECOVER/RMS_FILE/BACKWARD/UNTIL=17-MAR-1990:12 EXPENSES.DAT

or:

$ RECOVER/RMS_FILE/BACKWARD/UNTIL=17-MAR-1990:12 PAYROLL.DAT, -
_$ EXPENSES.DAT

In the latter case, the RMS Recovery utility uses the respective journals for each of the files.

If you have used a series of journals for before-image journaling and you use a time value for /UNTIL that is prior to the most recent journal, then you will have to issue a series of RECOVER/BACKWARD commands.

Example

For example, suppose that you have used the following sequence of commands, where the ellipsis represents a time period when changes were made to the file WEEKLY.DAT:

$ SET FILE/BI_JOURNAL=(FILE=WORK_DISK:[SALES]FIRST_JNL,CREATE) WEEKLY.DAT
   .
   .
   .
$ SET FILE/BI_JOURNAL=(FILE=WORK_DISK:[SALES]SECOND_JNL,CREATE) -
_$ WEEKLY.DAT
   .
   .
   .

Then it becomes necessary to use before-image recovery. You give the same RECOVER command as if there were only a single journal; however, you must use as many RECOVER commands as you have journals. The first RECOVER command automatically uses the journal in effect when the most recent SET FILE/BI_JOURNAL command was used, and subsequent RECOVER commands automatically use the respective before-image journals. Whenever there are one or more journals remaining to be processed, the RMS Recovery utility issues an informational message to that effect. For example:

$ RECOVER/BACKWARD/UNTIL=26-JUL-1990:14/LOG WEEKLY.DAT    
%RMSREC-I-NXTJNLFIL, next journal to be processed is
WORK_DISK:[SALES]FIRST_JNL.RMS$JOURNAL;1
%RMSREC-I-FILBACKWARD, WORK_DISK:[SALES]WEEKLY.BCK rolled backward
%RMSREC-I-DATETIME, date/time of last record processed: 6-AUG-1990
10:37:47.25
%RMSREC-I-NUMRECS, 523 records processed
$
$ RECOVER/BACKWARD/UNTIL=26-JUL-1990:14/LOG WEEKLY.DAT    
%RMSREC-I-FILBACKWARD, WORK_DISK:[SALES]WEEKLY.DAT rolled backward
%RMSREC-I-DATETIME, date/time of last record processed: 26-JUL-1990
14:46:41.53
%RMSREC-I-NUMRECS, 328 records processed

After the first RECOVER command (), the RMS Recovery utility informs you that an additional journal (FIRST_JNL.RMS$JOURNAL) remains to be processed. No such message is issued after the next RECOVER command (), which means that the current before-image journal is the final one to be processed.

During before-image recovery, data files are available only to the RMS Recovery utility, and no other updates can be made to them. When before-image recovery is complete, you can use both the data files and the before-image journal without any further actions.

A transaction is a group of related operations that occur in an application program. The operations within a transaction either will all be completed or will not be done at all, as described in the following table.

Transactions are defined using the DECdtm transaction services.

File records that are changed within a transaction cannot be accessed for further processing outside the transaction (for example, by another process) until the transaction is complete.

An RMS recovery unit is a set of RMS operations within a transaction that are performed in the context of a single process. RMS recovery units are started automatically by RMS and are committed or aborted along with the transaction to which they belong.

Both local and remote files can be associated with a transaction. If a transaction includes remote files, each remote file has its own recovery unit, which is journalled and recovered transparently by RMS on the remote node.

In recovery unit journaling, a copy of the original state of each record changed in a recovery unit is kept in a temporary recovery unit journal. If a transaction includes files accessed by more than one process, each process has its own recovery unit journal.

The status of records changed in a transaction and of the recovery unit journal is summarized in the following table.

DECdtm software coordinates transactions among participating resource managers. RMS is considered a resource manager by DECdtm. (DEC Rdb and VAX DBMS are two other resource managers that can participate in transactions managed by DECdtm.) For more information on DECdtm, see the VSI OpenVMS System Manager's Manual and the VSI OpenVMS Programming Concepts Manual.

If RMS is running in more than one process (typically, on different nodes connected by a network), each instance of RMS is considered a different resource manager. A transaction can involve one or more resource managers within a single process, resource managers within multiple processes on the same node, or resource managers within multiple processes on different nodes within a network.

Each resource manager is responsible for providing recovery capabilities for its own recoverable resources by performing transaction logging or journaling. The DECdtm transaction manager is responsible for notifying all resource managers participating in a transaction of all relevant transitions between transaction states. DECdtm keeps track of the state of each transaction in case a system or process fails before the transaction is completed. When a resource manager attempts to recover a resource that has been involved in a failed transaction, the resource manager may need to ask DECdtm for the state of a transaction to determine whether to make the effects of the transaction on this resource permanent or to remove them.

Restrictions on recovery unit journaling

All files involved in a transaction must be on nodes that support DECdtm (that is, each node must be running VMS Version 5.4 or later) and that are licensed for RMS Journaling.

At the end of a transaction, the DECdtm transaction manager directs RMS to commit the transaction. DECdtm supports both one- and two-phase commit protocols.

Two-phase commit protocol

To ensure that distributed transactions are either completed or, in the case of failure, rolled back, DECdtm provides a two-phase commit protocol for the $END_TRANS service. The two-phase commit protocol ensures that all resource managers participating in a transaction commit the transaction consistently, even when each resource manager is using a separate recovery unit journal. These are the phases of a two-phase commit protocol:

One-phase commit protocol

DECdtm also provides a one-phase commit protocol, in which RMS commits the transaction immediately, without using the prepare phase of the two-phase commit protocol. RMS then performs any cleanup required and writes commit records to its journals.

The one-phase commit protocol can be used if all of the following conditions are present in the transaction:

To mark a file for recovery unit journaling, use the DCL command SET FILE/RU_ JOURNAL. This command starts recovery unit journaling for the file when the appropriate DECdtm transaction services are included in the application program.

Example

For example, to mark the file FINANCE_DISK:[PAYROLL]WEEKLY.DAT for recovery unit journaling, use the following command:

$ SET FILE/RU_JOURNAL FINANCE_DISK:[PAYROLL]WEEKLY.DAT

Restriction

You must use the SET FILE/RU_JOURNAL command from the system where the file is located, which may be different from the system where the application is run.

If an application program defines a transaction that includes a file that is not marked for recovery unit journaling, then the transaction services have no effect on that file when the program is executed. The transaction services return success messages (because the services themselves were successfully called), even though no recovery unit journaling is actually taking place.

To discontinue the use of before-image journaling for a file, use the SET FILE/NOBI_JOURNAL command to unmark the file. For example:

$ SET FILE/NORU_JOURNAL SALES_DISK:WEEKLY.DAT

You must use the SET FILE/NORU_JOURNAL command before deleting a file that is marked for recovery unit journaling.

Recovery unit journals are temporary files; they are created and deleted automatically by RMS Journaling. RMS Journaling automatically creates a recovery unit journal when the first record stream associates with a transaction, even if the transaction does not modify any records.

A single recovery unit journal is used for all local files, but each remote file associated with the transaction has its own recovery unit journal.

When a transaction ends, the recovery unit journals used for that transaction become idle. Idle recovery unit journals are not deleted until the application exits. This provides improved performance for an application that uses multiple transactions.

Each recovery unit has exclusive use of a separate recovery unit journal. Under certain circumstances, however, a journal can be used later by the same process. The following table shows how a journal can be reused by RMS.

Recovery unit journals are always created in the [SYSJNL] directory, which is inaccessible to nonprivileged users. In general, you should not modify the file protection for either the [SYSJNL] directory or the journals that are placed in it.

Specifying a location for the recovery unit journal for a file does not guarantee that the recovery unit journal will be located on the named device or volume. Any active transaction has 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 were specified (for individual files) with different SET FILE/RU_JOURNAL commands.

The placement of the recovery unit journal can influence both the performance and the availability of your application. Placing a journal on a volume separate from all data files may improve performance. Remember that the application depends on both volumes being available, to access both the data file and its journal.

You can determine the volume placement for a recovery unit journal by using three different methods:

By default, the recovery unit journal is on the same volume as the file associated with the first record stream that joins the transaction. If RMS journaling does not find a [SYSJNL] directory, it creates one. The file name for the recovery unit journal has the form RMS$process_id (where process_id is the hexadecimal representation of the process ID) and a file type of RMS$JOURNAL.

When multiple files are used in a transaction, recovery unit journals are assigned as follows:

Example

For example, the following pseudocode illustrates an application that uses the files FINANCE_DISK:SALES.DAT and PAYROLL_DISK:WEEKLY.DAT, which have been marked for recovery unit journaling:

$OPEN FINANCE_DISK:SALES.DAT 
$CONNECT sales-stream to SALES.DAT
$OPEN PAYROLL_DISK:WEEKLY.DAT
$CONNECT weekly-stream to WEEKLY.DAT
$START_TRANS 
$GET payroll-record using weekly-stream 
$GET sales-record using sales-stream 
$UPDATE payroll-record
$UPDATE sales-record
$END_TRANS

The following table explains the numbered items in the example.

Stage	What Happens
	The first file opened is FINANCE_DISK:SALES.DAT.
	When the $START_TRANS service is called, a transaction begins.
	When the first record stream joins the transaction, RMS Journaling looks for the [SYSJNL] directory on PAYROLL _DISK. A journal is chosen as follows:
	If a recovery unit journal is...	THEN...
	not found	a journal is automatically created
	open on volume PAYROLL_DISK for the process running the application	that journal is used.
	When the second stream is associated with the transaction, it uses the recovery unit journal selected for the first record 4 stream at the previous stage.

In this example, the recovery unit journaling for files PAYROLL_ DISK:WEEKLY.DAT and FINANCE_DISK:SALES.DAT is recorded in the same recovery unit journal, located on PAYROLL_DISK:[SYSJNL]. Even if you had specified the location of the recovery unit journal for the file SALES.DAT (with the DEVICE or LABEL keywords to the SET FILE/RU_JOURNAL command), the location of the recovery unit journal would be determined by the file WEEKLY.DAT, the first file to join the transaction.

You can override the default volume for recovery unit journals by using either the DEVICE or LABEL keywords with the SET FILE/RU_JOURNAL command on a file by file basis. For example:

 SET FILE filename/RU_JOURNAL=(LABEL=(volume_label)

If a stream connected to the file is the first stream in the process to associate with a given transaction, then the recovery unit journal is created on the device DISK$volume_label. The logical name DISK$volume_label can have different equivalence names for different processes.

For more information about using the keywords DEVICE and LABEL with the SET FILE/RU_JOURNAL command, see Chapter 8.

You can also control the placement of a recovery unit journal by using the set-mode XABITM item list entry XAB$_RUJVOLNAM.

When an RMS record service associates a stream with a transaction, and this is the first stream in the process to associate with that specific transaction, then RMS checks to see if the set-mode XABITM item list entry XAB$_RUJVOLNAM is specified with the caller’s RAB. If the XAB$_RUJVOLNAM item list entry is found, the volume name it specifies is prefixed with the string "DISK$", and the resultant string is used to determine the location of the recovery unit journal.

The item list entry XAB$_RUJVOLNAM overrides both the default recovery unit journal placement and a setting specified by using the SET FILE/RU_ JOURNAL=DEVICE or the SET FILE/RU_JOURNAL=LABEL command.

Appendix A lists the support for individual RMS services when they are applied to a file that is marked for recovery unit journaling.

If records are appended to a write-shared sequential file containing fixed-length records using recovery unit journaling, and the transaction is not committed (either the $ABORT_TRANS service is called, or a system failure occurs), recovery unit recovery overwrites each appended record in the transaction with zeros. Subsequent readers of the file will read these zeroed records. This behavior is necessary, because other shared accessors may also have appended records to the file following the zeroed records, and those other record numbers cannot be changed. There is no support for deleted records in sequential files.

When a file is marked for recovery unit journaling, any modifications to that file by an application must be within a transaction. If changes are attempted outside the context of a transaction, a run-time error with the status RMS$_NRU is returned.

Use the following DECdtm transaction services to define the beginning and end of a transaction and to cancel a transaction.

In this manual, these services will be referred to as $START_TRANS or the Start Transaction service, and so on.

If you start a transaction with $START_TRANS, you must end it with $END_ TRANS or $ABORT_TRANS.

The Start Transaction service, $START_TRANS, starts a transaction and returns a transaction identifier (TID), which uniquely identifies the transaction.

The Start Transaction and Wait service $START_TRANSW is identical to $START_TRANS, but completes synchronously.

The End Transaction service, $END_TRANS, commits a transaction to complete. Use the $END_TRANS service when you reach the end of a series of operations that are to be completed either in their entirety or not at all.

The End Transaction service uses the two-phase commit protocol, coordinated by the DECdtm transaction manager, to commit the transaction.

The End Transaction and Wait service $END_TRANSW is identical to $END_ TRANS, but completes synchronously. Unlike the asynchronous version, $END_ TRANSW returns its status after DECdtm issues the order to commit.

The Abort Transaction service, $ABORT_TRANS, terminates a transaction and restores all records modified during the transaction to their states before the transaction was started. The service invalidates the transaction ID and instructs all participating resource managers to nullify all the actions of the transaction.

If a call to $ABORT_TRANS aborts the transaction, RMS automatically restores the record stream context to its state before the transaction began.

After you abort a transaction, all records modified during the transaction can be accessed for further processing.

The Abort Transaction and Wait service $ABORT_TRANSW is identical to $ABORT_TRANS, but completes synchronously.

You must call the transaction services in your application program according to the syntax rules of the programming language that you are using.

You can also run the sample applications on line.

For more information on how to use these services, see the VSI OpenVMS System Services Reference Manual and the documentation for your programming language.

The $ABORT_TRANS service can be called by any resource manager (such as RMS) participating in the transaction, as summarized in the following table.

A record stream is a logical channel associated with a file. It is generated either by an explicit call to the RMS Connect service, $CONNECT, or by an implicit call to $CONNECT (for example, when you use an OPEN call in a high-level language such as VAX COBOL).

An RMS record stream can become associated with a transaction when one of the following RMS services is executed:

These services can associate a stream with a transaction because their work is considered part of the transaction and can be undone if the transaction is aborted.

To be associated with a transaction, a record stream must:

When an application first calls one of the previously mentioned RMS services for a file that is marked for recovery unit journaling, RMS tries to associate the record stream with a transaction in one of two ways:

If a set-mode XABITM with a XAB$_TID item list entry is specified with the caller’s record access block (RAB), RMS associates the record stream with the transaction whose TID is pointed to by the XAB$_TID item list entry.

When you use a high-level language, you can generally use the mask DDTM$M_ NONDEFAULT to set the bit that indicates you are using the XAB$_TID method.

This method is particularly useful for server processes, which are likely to be running multiple transactions concurrently. This method is easy to implement and has low run-time overhead. However, this method may not be available if the application language (for example, COBOL) does not provide access to the RAB.

Examples

The following example shows how a stream can be associated with a specific transaction by using a XABITM:

struct RAB rab1; 
struct XABITM xabitm1;
struct ITMLST xabitm_tid;

struct {
    char filler [ddtm$s_tid];
} tid1;

rab1.rab$l_xab = &xabitm1; 
   .
   .
   .
xabitm1.xab$b_mode = xab$k_setmode;
xabitm1.xab$l_itemlist = &xabitm_tid;
   .
   .
   .
xabitm_tid.itm$w_itmcod = xab$_tid;
xabitm_tid.itm$w_bufsiz = ddtm$s_tid;
xabitm_tid.itm$l_bufadr = &tid1;
   .
   .
   .                  
status = sys$start_transw(0,ddtm$m_nondefault,&iosb,0,0,&tid1); 
status = sys$get(&rab1); 
   .
   .
   .
status = sys$update(&rab1);
status = sys$end_transw(0,0,&iosb,0,0,&tid1);

The following table explains the numbered items in the example.

Stage	What Happens
	RAB1 is a RAB that has been used to connect a record stream to an RMS file that is marked for recovery unit journaling.
	RAB1 specifies a set−mode XABITM that contains a XAB$_TID item list entry, which in turn specifies the address for a TID.
	The $START_TRANSW transaction service starts a transaction and returns a TID to the variable TID1.
	This example does not rely on the default−transaction mechanism for associating record streams, so the transaction is made current by setting the flag DDTM$M_NONDEFAULT to 1.
	When the $GET service is called, RMS processes the XABITM XAB$_TID item list entry, and the record stream is associated with the transaction specified by the TID in the variable TID1.

If there is no XABITM with a XAB$_TID item list entry specified, RMS associates the record stream with the default transaction. The default transaction is established when the $START_TRANS service is called and the DDTM$M_ NONDEFAULT bit in the flags argument is 0. When the default transaction is ended by using the $END_TRANS or $ABORT_TRANS services, the default transaction becomes undefined.

Examples

The following example shows how a stream can be associated using the default transaction:

struct RAB rab1; 

struct {
    char filler [ddtm$s_tid];
} tid1;
   .
   .
   .
status = sys$start_transw(0,0,&iosb,0,0,&tid1); 
status = sys$get(&rab1); 
   .
   .
   .
status = sys$update(&rab1);
status = sys$end_transw(0,0,&iosb,0,0,&tid1); 

The following table explains the numbered items in the example.

Stage	What Happens
	RAB1 is a RAB that has been used to connect a record stream to an RMS file that is marked for recovery unit journaling.
	The transaction service $START_TRANSW starts a transaction makes it the default transaction for this process (since the call to $START_TRANSW does not set the flag DDTM$M _NONDEFAULT to 1) returns a transaction identifier (TID) to the variable TID1
	When the $GET service is called, the record stream is associated with the default transaction.
	The $END_TRANSW transaction service commits and ends the transaction.

If RMS is unable to select a transaction with either a XAB$_TID item list entry or the default transaction, it responds as follows:

When a record stream joins a transaction, RMS stores the current record stream context, including the following:

The transaction service $END_TRANS commits and ends a transaction. When this service is called, DECdtm sends a ‘‘prepare to commit’’ message to all the resource managers participating in the transaction, including RMS.

Busy Streams. If any stream associated with the transaction is still busy, or if RMS encounters an error, RMS refuses to commit by voting NO. When DECdtm receives a NO vote, the following processes take place:

RMS refuses to commit a transaction with associated busy streams, because the outcome of a record operation on a busy stream is not yet determined. Thus, if the application is using asynchronous RMS record operations within a transaction, the application must use the RMS service $WAIT on all associated streams before calling $END_TRANS to commit the transaction.

Only Idle Streams. If all record streams associated with the transaction are idle, RMS proceeds with the preparation to commit. An error during the preparation results in a NO vote. When DECdtm orders RMS to commit, the RMS recovery unit is committed, and all record streams associated with the transaction become disassociated.

The transaction service $ABORT_TRANS aborts a transaction. The effects of the transaction are undone and the transaction is ended. When this service is called, DECdtm sends an order to abort to all participating resource managers, including RMS. RMS waits for all record streams associated with the specified transaction to complete any pending activity before proceeding with the abort. When the transaction has been aborted, all record streams associated with the transaction become disassociated.

If a call to $ABORT_TRANS aborts the transaction, RMS automatically restores the record stream context to its state before the transaction began.

In in-place recovery, the local process performs the recovery as a result of an explicit call to $ABORT_TRANS or of an abnormal termination of the application image. (In the latter case, RMS calls $ABORT_TRANS for all record streams joined to active transactions.)

In detached recovery, RMS creates a detached process to recover files marked for recovery unit journaling, as a result of process deletion or a node crash. If any process in a VMS cluster system is terminated abnormally with transactions involving an RMS file still active, then detached recovery is required on that file.

When a process is terminated abnormally, active transactions associated with the process are said to be orphaned. When detached recovery is initiated for a file, the detached recovery process adopts any orphaned transactions involving that file.

Detached recovery restores a particular file to a consistent state by undoing the effects of all active transactions whose owning processes were abnormally terminated. Thus, detached recovery can undo the effects of more than one aborted transaction.

Detached recovery is started in one of two ways:

Detached recovery can be either asynchronous or synchronous.

In asynchronous recovery, the detached recovery process performs the following steps to recover a file:

Detached recovery is asynchronous by default. In certain circumstances, synchronous recovery is used.

In synchronous recovery, the detached recovery process does not acquire record locks, but it prohibits access to the file by any other process until recovery is complete. Synchronous recovery is used in the following circumstances:

Full recovery unit recovery cannot take place unless the recovery unit journal and each of the files involved in the recovery unit are available; however, partial recovery is still possible if some of the files are available.

When detached recovery receives a request to recover a file, it tries to recover the effects of all orphaned transactions that involve the file. The specific file for which RMS requests recovery is called the primary file. In addition to the changes made to the primary file, each of the orphaned transactions can also include changes to a number of other files. These additional files are called secondary files.

Recovery of secondary files is not required to allow access to the primary file. If detached recovery cannot access a secondary file that is referenced in a recovery unit journal for one of the orphaned transactions, then detached recovery cannot adopt that transaction. In this case, detached recovery recovers that particular recovery unit journal in synchronous mode and omits all operations that involve the inaccessible secondary file. Omitting a secondary file is permissible, because it is only necessary to recover the primary file to satisfy the client’s request. All the information necessary to recover the secondary file is left in the recovery unit journal for eventual use in recovering that file.

In several situations, recovery unit recovery can be blocked. These include:

In most cases, RMS recovery knows what action to take with a transaction, because a prepare and a commit (or abort) record are included in the recovery unit journal. An in-doubt condition arises if RMS recovery finds a prepare record but does not find a commit or abort record. This happens when a failure occurs after the prepare phase, but before a commit or abort record is written to the recovery unit journal. At this point, RMS is in doubt, because it does not know whether the transaction should be committed or aborted. RMS asks the DECdtm transaction manager for the information required to resolve the issue. The information returned by DECdtm instructs RMS recovery to either commit or abort the transaction.

There are cases when DECdtm cannot determine the outcome of an in-doubt transaction for an indeterminate period of time. If this condition arises, the transaction is said to be in a limbo state.

When detached recovery queries the DECdtm transaction manager about the state of an in-doubt transaction, detached recovery waits until DECdtm can determine whether the transaction should be committed or aborted. If DECdtm cannot determine the result of the transaction (for example, because another node is down), the duration of the wait may be a short or long time, depending on the reason DECdtm cannot gather the information it needs.

RMS does not allow access to records that were modified until the file is properly recovered. However, access to other records in these files is allowed, because the file is in a consistent state once detached recovery reacquires all the record locks on the orphaned transactions. In addition, DECdtm allows the user to force the resolution of limbo transactions by using the REPAIR command in the Log Manager Control Program (LMCP) utility. For more information on LMCP, see the VSI OpenVMS System Management Utilities Reference Manual.

Sometimes the recovery unit journal or one or more other files joined to the recovery unit will be unavailable for recovery. In this case, the ANALYZE/RMS_ FILE/RU_JOURNAL command will give Not Available as the recovery unit state. (Note that the file specifications for the recovery unit journal and any other file connected to the recovery unit are listed in the output for the ANALYZE/RMS_ FILE/RU_JOURNAL command.)

If the volume where the recovery unit journal is located is temporarily unavailable, you can wait until the volume is on line and the recovery unit journal is again available. Once the recovery unit journal is available, you will be able to start detached recovery.

In some cases, the recovery unit journal may be permanently unavailable (for example, if the volume has experienced a failure such as a disk head crash, or if the journal has been deleted). Should this occur, the file may contain inconsistent data (due to partially completed transactions). If you have used after-image journaling with the file, then you can recover the file (using the backup copy and the RMS Recovery utility), and restore all changes made up to the time of the beginning of the last transaction. If after-image journaling has not been used, then you can gain access to the data file using the SET FILE/RU_ACTIVE/RU_ FACILITY command. Remember, however, that the data in the file may be inconsistent.

During a transaction, any record locking required by the application is done immediately.

In addition, when a file marked for recovery unit journaling is accessed within a transaction, the records that are accessed are locked automatically by RMS until the end of the transaction. This prevents other processes from accessing potentially inconsistent data.

The status of record locks during a transaction is determined as follows:

When the transaction is completed with a call to $END_TRANS, all records involved in the transaction are set to the lock states that would have occurred if recovery unit journaling had not been used in the application program.

When a transaction ends with a call to $ABORT_TRANS (either explicitly in the application or because of an abnormal program interruption), all record locks are returned to their states at the beginning of the transaction.

Example

Suppose that your application included the following pseudocode:

$GET record-1 
$START_TRANS 
$GET record-2 
$UPDATE record-1 
$UPDATE record-2 
$RELEASE record-2 
$GET record-2 
$ON ERROR ABORT_TRANS 
$END_TRANS 

The following table explains the numbered items in the example.

Stage	What Happens	Record Lock Status
	The first record (record−1) is retrieved.	Record−1 is locked.
	The transaction begins.	–––
	A second record (record−2) is retrieved.	Record−2 is locked.
	Both records are modified.	Record−1 and record−2 are both locked.
	The $RELEASE service is called for record−2.	Record−2 is not released, because the transaction is still ongoing. However, RMS returns a success status for the call to $RELEASE.
	Record−2 is retrieved a second time.	Record−2 remains locked.
	The transaction ends with a call to $ABORT_TRANS.	Record−1 is locked, and record−2 is released, because those were their states at the beginning of the transaction ()
	The transaction ends with a call to $END_TRANS.	Record−1 is released, because it would have been in a released state if recovery unit journaling were not used in the application. Record−2 remains locked.

Errors encountered by RMS services performed within a transaction are reported to the caller. In most cases, the correct way of dealing with such errors is for the application to abort the transaction. However, this may not always be the case, so this decision is left up to the application designer.

The DECdtm two-phase commit protocol requires that once a transaction is prepared, RMS must assure that it can either commit or abort its contribution to that transaction. However, unexpected errors can occur in these contexts.

Sometimes RMS is unable to indicate the details of the error condition back to the caller or user. In these cases, RMS sends the extended status for such failures to the Operator Communication Manager (OPCOM). Therefore, it is essential to have OPCOM running on your processor if you are using recovery unit journaling. (By default, OPCOM starts automatically during the system startup procedure.)

Each line of the extended status of an error message is sent as a separate message to OPCOM. If the system manager has enabled the console terminal as an operator terminal, a sequence of messages appears on the console terminal. (See the description of the REPLY command in the VSI OpenVMS DCL Dictionary for information about enabling the console terminal as an operator terminal.)

The first message of each message sequence is a header message identifying the RMS Journaling software component signaling the message sequence. The second message includes the transaction identifier (TID) of the transaction that caused the error.

The format of the TID is nonstandard, but the conversion from one format to the other is straightforward. If the bytes of the TID are labeled PONMLKJIHGFEDCBA from highest byte address (P) to lowest byte address (A), the RMS TID display and the standard format are as follows:

The following table shows recovery actions in response to errors during different phases of a transaction.

Example: full disk

If the disk containing one of the data files becomes full during an $ABORT_ TRANS operation, the RMS recovery unit handler sends the following messages to OPCOM:

%%%%%%%%%%%OPCOM 11-MAY-1990 10:46:31.30 %%%%%%%%%%%
Message from user FRENCH
%RMS-E-RUH, error during RMS recovery unit handler

%%%%%%%%%%%OPCOM 11-MAY-1990 10:46:32.31 %%%%%%%%%%%
Message from user FRENCH
-RMS-E-ERRRUHABO, error during RU handler abort of TID F1032FA000900B0E (process ID 23C01485)

%%%%%%%%%%%OPCOM 11-MAY-1990 10:46:33.32 %%%%%%%%%%%
Message from user FRENCH
-RMS-I-RUHOBJ, object name WORKDISK:[FRENCH.MAY]DATA.DAT;10

%%%%%%%%%%%OPCOM 11-MAY-1990 10:46:34.26 %%%%%%%%%%% Message from user FRENCH
-RMSREC-F-WRITERR, error writing to file

The first message in the sequence is the header message for all recovery unit handler message sequences.

The second message indicates that the recovery unit handler was unable to abort the transaction. It lists the TID of the transaction and the process identification (PID) of the process initiating recovery.

The third message lists the file specification of the file that is causing the problem.

The last message indicates the problem: the RMS recovery unit handler is unable to write to the file.

Example: device off line

If the device is off line when in-place recovery is called by the $ABORT_TRANS service, the following message sequence is output to OPCOM along with the messages sent by the RMS recovery unit handler:

%%%%%%%%%%%OPCOM 11-MAY-1990 11:46:31.31 %%%%%%%%%%%
Message from user FRENCH
%RMSREC-F-OPRHDRINP, error occurred during in-place RU Recovery; process ID (PID) 012C9054

%%%%%%%%%%%OPCOM 11-MAY-1990 11:46:32.19 %%%%%%%%%%%
Message from user FRENCH
%RMSREC-F-WRITEERR, error writing to file

%%%%%%%%%%%OPCOM 11-MAY-1990 11:46:33.36 %%%%%%%%%%%
Message from user FRENCH
-RMSREC-F-FILE, file WORKDISK:[FRENCH.MAY]DATA.DAT;6

%%%%%%%%%%%OPCOM 11-MAY-1990 11:46:34.14 %%%%%%%%%%%
Message from user FRENCH
-RMS-E-DNR, device not ready, not mounted, or unavailable

The first message of the sequence is the header message for all in-place recovery message sequences.

The second message indicates that RMS in-place recovery has failed because it is unable to write to the data file.

The third message shows the file specification of the file that is causing the problem.

The last message indicates the problem: the device on which the file is stored is not ready, not mounted, or unavailable.

Example: invalid volume name

If you defined an invalid logical name for the disk on which the recovery unit journal resides, detached recovery would send the following messages to OPCOM:

%%%%%%%%%%%OPCOM 11-MAY-1990 12:46:32.19 %%%%%%%%%%%
Message from user FRENCH
%RMSREC-F-OPRHDRDET, error occurred during detached RU Recovery; initiated by process
ID (PID) 34C12784

%%%%%%%%%%%OPCOM 11-MAY-1990 12:46:33.07 %%%%%%%%%%%
Message from user FRENCH
%RMSREC-F-NORULOGNAM, Recovery Unit volume logical name (DISK$volume_name) not defined correctly

%%%%%%%%%%%OPCOM 11-MAY-1990 12:46:34.13 %%%%%%%%%%%
Message from user FRENCH
-RMSREC-F-INVLOGNAM, error translating logical name BADNAME:

The first message in the sequence is the header message for all detached recovery message sequences.

The second message informs you that the logical name for the recovery unit volume is not defined correctly.

The final message provides the reason for the problem: BADNAME is not the correct logical name for the recovery unit volume.

To mark a file for after-image and before-image journaling, you can either issue separate SET FILE/AI_JOURNAL and SET FILE/BI_JOURNAL commands, or you can issue a single SET FILE command that includes both the /AI_JOURNAL and /BI_JOURNAL qualifiers and their keywords.

If you want to use a single journal for after-image and before-image journaling, do not use the CREATE keyword with both the /AI_JOURNAL and /BI_JOURNAL qualifiers, because that will create two separate journals. When you create a journal that will be used for more than one file or more than one type of journaling (after-image or before-image), you should first use a SET FILE command to create the journal for a single type of journaling and for a single file. After the journal is created, then you can use a single SET FILE command for multiple files and both after-image and before-image journaling. For example, you might use the following sequence of commands:

$ SET FILE/AI_JOURNAL=(FILE=JNL_DISK:,CREATE) [WEEKLY]SALES.DAT
$ SET FILE/BI_JOURNAL=(FILE=JNL_DISK:[WEEKLY]SALES) -
_$INVOICES.DAT,COMMISSIONS.DAT

When after-image and before-image journaling are directed to the same journal, the after-image and before-image information are directed to different record streams within the journal.

If you attempt to recover more than one file marked for both after-image and recovery unit journaling, different rules apply depending on whether you use the /UNTIL qualifier with the RECOVER/FORWARD command.

If you do not use the /UNTIL qualifier with the first backup copy that you restore with after-image recovery, restore only those files in the application that are corrupted or lost. However, do not use the /UNTIL qualifier with any of the files that you restore, in order to maintain data consistency among those files.

For example, suppose that the files SALES.DAT, INVENTORY.DAT, and SALARY.DAT are marked for after-image and recovery unit journaling, and that SALES.DAT and INVENTORY.DAT become corrupted. You can then use after-image recovery with the following commands:

$ RECOVER/FORWARD  JNL_DISK:SALES.BCK
$ RECOVER/FORWARD  JNL_DISK:INVENTORY.BCK

Then, after remarking the restored copies for after-image journaling and renaming and backing up the files, you can continue the application without any further processing to SALARY.DAT.

If you do use the /UNTIL qualifier with the first file that you restore, then you must restore every 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.

For example, suppose that in the previous example you wanted to roll the file SALES.BCK forward to 9:15 a.m. on March 10, 1990. You would then have to roll the other two files in the application forward to exactly the same time, as follows:

$ RECOVER/FORWARD/UNTIL=10-MAR-1990:9:15  JNL_DISK:SALES.BCK
$ RECOVER/FORWARD/UNTIL=10-MAR-1990:9:15  JNL_DISK:INVENTORY.BCK
$ RECOVER/FORWARD/UNTIL=10-MAR-1990:9:15  JNL_DISK:SALARY.BCK

You can use multiple after-image journals within a single transaction, but to assure that the recovered files are consistent, you must recover the files using the after-image journals in their entirety.

The recovered files can be inconsistent if you use the /UNTIL qualifier with the RECOVER command, because the times given for the journal entries may themselves be inconsistent, for either of the following reasons:

If you use before-image recovery for more than one file marked for both before-image and recovery unit journaling, the following rules apply:

Example

For example, consider an application that uses the files SALES.DAT, INVENTORY.DAT, and SALARY.DAT. If you want to roll the file SALES.DAT back to 9:15 a.m., on March 10, 1990, use the following series of commands:

$ RECOVER/BACKWARD/UNTIL=10-MAR-1990:9:15  WORK_DISK:SALES.DAT
$ RECOVER/BACKWARD/UNTIL=10-MAR-1990:9:15  WORK_DISK:INVENTORY.DAT
$ RECOVER/BACKWARD/UNTIL=10-MAR-1990:9:15  WORK_DISK:SALARY.DAT

You can use multiple before-image journals within a single transaction, but to assure that the recovered files are consistent, you must recover the files using the after-image journals in their entirety.

The recovered files can be inconsistent if you use the /UNTIL qualifier with the RECOVER command, because the times given for the journal entries may themselves be inconsistent, for either of the following reasons:

After-image and before-image journals can use many blocks of disk storage space. Store journals on disk only if they are required to safeguard your data. Archive old journals by backing them up onto magnetic tape and deleting them from the journal disk.

Create a new after-image journal when the disk volume containing the journal is nearly full. Depending on the rate of growth of the after-image journal, you may need to create a new journal twice a day, daily, weekly, or monthly.

To create a new after-image journal, do the following:

After creating a new after-image journal, decide whether you will perform a full backup of the data file.

A full backup of a data file can be performed without creating a new after-image journal. This can occur if you forget to issue the SET FILE command before performing the backup, or if someone performs a full backup of the data file without knowing that the file is marked for after-image journaling. The data file cannot be open for updating during the backup operation.

After the backup completes, the after-image journal is still valid. To recover the data file, apply the after-image journal to any full backup performed since the after-image journal was created.

Create a new before-image journal when the disk volume containing the journal is nearly full. Depending on the rate of growth of the before-image journal, you may need to create a new journal twice a day, daily, weekly, or monthly.

To create a new before-image journal, do the following:

You need not coordinate before-image journaling with backups of the data file.

Recovery unit journaling creates a directory called [SYSJNL] and stores all recovery unit journals in this directory. Normally, recovery unit journals are deleted automatically at image rundown time. Therefore, the system manager does not usually need to maintain recovery unit journals in the [SYSJNL] directory. If the SET FILE/RU_ACTIVE=0 command is used for a data file, however, the associated recovery unit journals for active transactions are not deleted from the [SYSJNL] directory.

Use the following procedure to determine which recovery unit journals in the [SYSJNL] directory are no longer needed and can be deleted.

A volume label is the only device-independent identifier for an OpenVMS volume or volume set. RMS Journaling uses a volume label plus a file ID as the forward pointer from a data file to its journals. Physical device names are not used, because you would be unable to use journals on a disk that was moved or copied from one physical device to another.

For RMS to obtain the device name from the volume label, it is necessary that an executive-mode logical name with the concealed and terminal attributes, DISK$volume_label, be defined for the device on which the volume is mounted, where volume_label represents the label for the particular volume. The Mount utility automatically creates such a logical name when you use it to mount a volume with the /SYSTEM or /CLUSTER qualifier, even if you also specify a logical name for the device. To use the /SYSTEM qualifier, you must have the SYSNAM (system logical name) or the SYSPRV (system privilege) privilege.

Example

For example, the executive-mode logical name DISK$FINANCE_DISK is created if you mount the disk with any of the following MOUNT commands:

$ MOUNT/SYSTEM DBA0: FINANCE_DISK
$ MOUNT/SYSTEM DBA0: FINANCE_DISK DISK1
$ MOUNT/CLUSTER DBA0: FINANCE_DISK
$ MOUNT/CLUSTER DBA0: FINANCE_DISK DISK1

For volumes mounted privately or with the /GROUP qualifier, the Mount utility creates the executive-mode logical name (with the concealed and terminal attributes) DISK$volume_label only as a job logical name. To create journals or to access files marked for journaling on a privately mounted volume, you must explicitly define the logical name DISK$volume_label, using the /SYSTEM and /EXECUTIVE_MODE qualifiers, as in the following example:

$ DEFINE/EXECUTIVE_MODE/TRANSLATION_ATTRIBUTES=(CONCEALED,TERMINAL)
_Log name: DISK$FINANCE_DISK
_Equ name: DBA0:

You should also be aware that using RMS Journaling can increase the use of virtual memory for some processes running journaling applications. If system performance seems to be affected by journaling, adjust your system parameters accordingly. See the Guide to OpenVMS Performance Management for information on this topic.

The RMS Recovery utility (RECOVER/RMS_FILE) restores RMS files if they have been 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).

Rolling an RMS file forward from a backup copy of the data file is called after-image recovery. Rolling the data file back to a previous state is called before-image recovery.

The qualifiers that you use with the RECOVER/RMS_FILE command determine the type of recovery that is applied to your file. You must use either the /FORWARD qualifier (to specify after-image recovery) or the /BACKWARD qualifier (to specify before-image recovery), but you cannot use both. The qualifier /RMS_FILE is the default for the RECOVER command; therefore, you need not include it. Output is always directed to SYS$OUTPUT.

No specific privileges are required to use the RMS Recovery utility. For afterimage recovery, you must have:

For before-image recovery, you must have:

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

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 names with commas.

To recover a file using after-image journaling, specify the backup copy of the file. To recover a file using before-image journaling, specify the original file.

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

/BACKWARD

Rolls a file back to a previous state. Use the /BACKWARD qualifier to recover a file using a before-image journal.

To specify a date and time to which the file is to be rolled back, 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.

When the recovery operation is complete, the RMS Recovery utility displays the time of the last record it 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, changes made within incomplete transactions are automatically undone as part of the before-image recovery operation, and the time of the last record processed would be the time when the first record was changed within one of the incomplete transactions.

/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=blocks

Specifies the number of blocks that RMS recovery reads for each I/O from the before-image journal. This qualifier is similar in concept to the multiblock count field (RAB$B_MBC) in RMS. The parameter can take values from 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 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[=uic]

Selects only those files whose 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 OpenVMS User’s Manual.

/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 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 the /BACKWARD or the /FORWARD qualifier.

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

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

The redoing 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 as many RECOVER/FORWARD commands as there are journals. The RMS Recovery utility uses the correct journal (unless it has been moved or restored from a backup copy, in which case you must use the /JOURNAL qualifier) and 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 remark the restored file for after-image journaling before it can be used for further processing using after-image journaling. Remarking the file for after-image journaling sets the journaling enabled bit in the file header, which was automatically turned off by the Backup utility when the backup copy was made. Immediately after remarking the restored file for after-image journaling, you should make a backup copy of it.

/JOURNAL=journal-filespec

Specifies the journal that is to be used for recovery operations. By default, the RMS Recovery utility uses the journal with the file specification that was specified when the 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. 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 Chapter 3, Section 3.6.7 (for after-image recovery) or Chapter 4, Section 4.5.7 (for before-image recovery).

/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 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 changed. 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[=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. To indicate the time attribute to be used as the basis for selection, specify one of the following qualifiers with /SINCE: /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.

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

/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 User’s Manual for more information about specifying absolute or delta time. The /UNTIL qualifier functions as follows:

The SET FILE/AI_JOURNAL command marks one or more RMS files for afterimage journaling. You can specify certain characteristics of the journal with this command, including its file specification, whether it is to be created, its initial size, and an extension quantity.

The SET FILE/NOAI_JOURNAL command unmarks a file for after-image journaling.

SET FILE/[NO]AI_JOURNAL\=(FILE=journal-filespec[,...]) filespec[,...]

filespec[,...]

Identifies the file to be marked for after-image journaling. If you specify more than one file, separate the file specifications with commas. Wildcard characters (* and %) are allowed. The file specification cannot include a node name, because the SET FILE command is not valid for network access.

/LOG

/NOLOG (default)

Controls whether the SET FILE command displays the file specification and the type of journaling that has been set. By default, this information is not displayed.

You must use the SET FILE/NOAI_JOURNAL command before you can delete a file that has been marked for after-image journaling.

Note

If the after-image journal has been corrupted, or if backup operations have replaced the journal with another file that is not a journal, the command SET FILE/NOAI_JOURNAL fails with the message:

SET-F-IVJFILE, invalid journal ’file_spec’

The following table explains how to correct the problem.

Four keywords are used as parameters to the SET FILE/AI_JOURNAL command: ALLOCATION, [NO]CREATE, EXTENSION, and FILE. You must always use the FILE keyword; you can also use any, all, or none of the other three keywords.

Use an equal sign ( = ) immediately after the SET FILE/AI_JOURNAL command to use a keyword. If you use more than one keyword, enclose the list in parentheses and separate the items in the list with commas.

ALLOCATION=n

Specifies the initial size, in blocks, of the journal. The ALLOCATION keyword is meaningful only when the CREATE keyword is also used.

The default allocation is 0 blocks.

CREATE

NOCREATE (default)

Specifies that a new journal is to be created. If no journal exists, using this keyword creates a new one. If a journal with the file name specified by the FILE keyword already exists, using the CREATE keyword creates a new version of the journal. The files named in this SET FILE command use the new journal, but any other files that used the previous version of the journal will continue to do so.

If you specify an existing journal without the CREATE keyword, the SET FILE command issues the following error message:

FLK---file locked by another user

If a journal does not exist, and you do not specify the CREATE keyword, a journal is not automatically created and an error message is displayed.

EXTENSION=n

Specifies an extension quantity, in blocks, for the journal. You can specify a value from 0 to 65,535.

The EXTENSION keyword is meaningful only when you use the CREATE keyword. If the file is extended, the value that you specify is used. If you do not use the EXTENSION keyword when you create a journal, RMS calculates its own EXTENSION value for the journal.

FILE=journal-filespec

Specifies the journal where all modifications to the named file will be recorded. The FILE keyword is required when you use the SET FILE/AI_JOURNAL command.

By default, any portions of the file specification that you omit will be the same as the file that is to be journaled, but with the file type .RMS$JOURNAL. For example, if you issue the following command, then, by default, the file specification for the after-image journal is JOURNAL_ DISK:PAYROLL.RMS$JOURNAL:

$ SET FILE/AI_JOURNAL=(FILE=JOURNAL_DISK:) FINANCE_DISK:PAYROLL.DAT

If the file that you specify with the FILE keyword does not exist, and you do not specify the CREATE keyword, a journal is not automatically created and an error message is displayed.

The SET FILE/BI_JOURNAL command marks one or more RMS files for before-image journaling. You can specify certain characteristics of the journal with this command, including its file specification, whether it is to be created, its initial size, and an extension quantity.

The SET FILE/NOBI_JOURNAL command unmarks a file for before-image journaling.

SET FILE/[NO]BI_JOURNAL\[=(keyword[,...])] filespec[,...]

filespec[,...]

Identifies the file to be marked for before-image journaling. If you specify more than one file, separate the file specifications with commas. Wildcard characters (* and %) are allowed. The file specification cannot include a node name, because the SET FILE command is not valid for network access.

/LOG

/NOLOG (default)

Controls whether the SET FILE command displays the file specification and the type of journaling that has been set. By default, this information is not displayed.

You must use the SET FILE/NOBI_JOURNAL command before you can delete a file that has been marked for before-image journaling.

Note

If the before-image journal has been corrupted, or if backup operations have replaced the journal with another file that is not a journal, the command SET FILE/NOBI_JOURNAL fails with the message:

SET-F-IVJFILE, invalid journal ’file_spec’

The following table explains how to correct the problem.

Four keywords are used as optional parameters to the SET FILE/BI_JOURNAL command: ALLOCATION, [NO]CREATE, EXTENSION, and FILE. You can use any, all, or none of these keywords.

Use an equal sign ( = ) immediately after the SET FILE/BI_JOURNAL command to use a keyword. If you use more than one keyword, enclose the list in parentheses and separate the items in the list with commas.

ALLOCATION=n

Specifies the initial size, in blocks, of the journal. The ALLOCATION keyword is meaningful only when the CREATE keyword is also used.

The default allocation is 0 blocks.

CREATE

NOCREATE (default)

Specifies that a new journal is to be created. If a journal with the same file name already exists, using the CREATE keyword creates a new version of the journal. The data files named in this SET FILE command use the new journal, but any other files that used the previous version of the journal will continue to do so.

If you specify an existing journal without the CREATE keyword, the SET FILE command issues the following error message:

FLK---file locked by another user

If a journal does not exist, and you do not specify the CREATE keyword, a journal is not automatically created and an error message is displayed.

EXTENSION=n

Specifies an extension quantity, in blocks, for the journal. You can specify a value from 0 to 65,535.

The EXTENSION keyword is meaningful only when you use the CREATE keyword. If the file is extended, the value that you specify is used. If you do not use the EXTENSION keyword when you create a journal, RMS calculates its own EXTENSION value for the journal.

FILE=journal-filespec

Specifies the journal where all before-image journal entries for the named file will be recorded.

By default, any portions of the file specification that you omit will be the same as the file that is to be journaled, but with the file type .RMS$JOURNAL. For example, if you issue the following command, then, by default, the file specification for the before-image journal is FINANCE_DISK:PAYROLL.RMS$JOURNAL:

$ SET FILE/BI_JOURNAL FINANCE_DISK:PAYROLL.DAT

Use the FILE keyword if you want to override the default file specification for the journal.

The FILE keyword is optional with the SET FILE/BI_JOURNAL command.

The SET FILE/RU_ACTIVE command specifies a recoverable facility to control active recovery units for a file.

When a file has active recovery units and RMS Journaling cannot determine the outcome of the recovery units (for example, if the recovery unit journal is unavailable), the file cannot be opened or deleted. The presence of active recovery units prevents you from unmarking (or marking) a file for any journaling type. However, with the SET FILE/RU_FACILITY/RU_ACTIVE command, you can clear the recoverable facility that controls active recovery units for the file.

You can determine the recoverable facility that controls active recovery units (if any) for the file by entering the DCL command DIRECTORY/FULL or DUMP/HEADER. You can use the ANALYZE/RMS_FILE/RU_JOURNAL command to determine the state of any active recovery units.

SET FILE/[NO]RU_ACTIVE\=ru-facility filespec[,...]

ru-facility

Specifies a recoverable facility. The value can be an integer from 0 to 255, or it can be the name of a Digital recoverable facility.

Facility numbers 1 to 127 are reserved by Digital; facility numbers 128 to 255 are available for user-written recoverable facilities. Currently, the only recoverable facility defined by Digital is 1 (RMS). Specifying the number 1 is equivalent to using the text RMS.

The number 0 corresponds to no recoverable facility and is equivalent to using the qualifier /NORU_ACTIVE.

filespec[,...]

Specifies the file that is to be modified. If you specify more than one file, separate the file specifications with commas. Wildcard characters (* and %) are allowed. The file specification cannot include a node name, because the SET FILE command is not valid for network access.

$ SET FILE/RU_FACILITY=1/RU_ACTIVE=0 FINANCE_DISK:[PAYROLL]WEEKLY.DAT

If the file WEEKLY.DAT is unavailable due to active recovery units and an unavailable recovery unit journal, you can use this command to gain access to the file. In this example, the recoverable facility is defined as RMS by the /RU_FACILITY=1 qualifier. The RU_ACTIVE attribute that indicates active RMS recovery units for the file WEEKLY.DAT is cleared by the /RU_ ACTIVE=0 qualifier.

The SET FILE/RU_FACILITY command specifies the recoverable facility that currently controls active recovery units on a file.

When a file has active recovery units and RMS Journaling cannot determine the outcome of the recovery units (for example, if the recovery unit journal is unavailable), the file cannot be opened or deleted. The presence of active recovery units prevents you from unmarking (or marking) a file for any journaling type. However, with the SET FILE/RU_FACILITY/RU_ACTIVE command, you can clear the recoverable facility that controls active recovery units for the file.

You can determine the recoverable facility that controls active recovery units (if any) for the file by entering the DCL command DIRECTORY/FULL or DUMP/HEADER. You can use the ANALYZE/RMS_FILE/RU_JOURNAL command to determine the state of any active recovery units.

SET FILE/RU_FACILITY\=ru-facility filespec[,...]

ru-facility

Specifies a recoverable facility. The value can be an integer from 0 to 255, or it can be the name of a Digital recoverable facility.

Facility numbers 1 to 127 are reserved by Digital; facility numbers 128 to 255 are available for user-written recoverable facilities. Currently, the only recoverable facility defined by Digital is 1 (RMS). Specifying the number 1 is equivalent to using the text RMS.

The number 0 corresponds to no recoverable facility.

The recoverable facility that you specify for the /RU_FACILITY qualifier is used only to open the file; it does not actually modify any file attributes.

filespec[,...]

Specifies the file that is to be modified. If you specify more than one file, separate the file specifications with commas. Wildcard characters (* and %) are allowed. The file specification cannot include a node name, because the SET FILE command is not valid for network access.

The SET FILE/RU_JOURNAL command marks an RMS file for recovery unit journaling. You can also use this command to specify the default volume on which recovery unit journals will be created for this file.

The SET FILE/NORU_JOURNAL command unmarks a file for recovery unit journaling.

SET FILE/[NO]RU_JOURNAL\[=volume-name] filespec[,...]

volume-name

Specifies the volume on which the recovery unit journals will be located, using one of the following keywords:

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

filespec[,...]

Specifies the file that is to be marked for recovery unit journaling. If you specify more than one file, separate the file specifications with commas. Wildcard characters (* and %) are allowed. The file specification cannot include a node name, because the SET FILE command is not valid for network access.

You must use the SET FILE/NORU_JOURNAL command before you can delete a file that has been marked for recovery unit journaling.

The journaling XAB (XABJNL) contains journaling-specific information for a file. It is an output-only XAB, which is filled in when the file is opened or displayed ($OPEN or $DISPLAY). The XABJNL for the data file has a field that points to the FAB for the journal associated with the data file; that FAB also contains information for the journal.

The following macros are defined for XABJNL:

The journaling XAB contains the following fields:

The individual XABJNL fields are described in the following sections. For simplicity, the field names are shortened; for example, XAB$B_JNL_TYPE is listed as B_JNL_TYPE.

The journaling type field specifies the type of journaling for which you request information. It can contain the string XAB$C_AI, XAB$C_BI, or XAB$C_RU_ DEFAULT. When the $OPEN or the $DISPLAY service is called, RMS uses this field to determine the type of journaling being requested, in order to return the appropriate information.

This is a required, input-only field.

The journal file access block (FAB) address field points to a FAB that describes the journal associated with the data file. It applies only to XABJNL XABs that have an after-image or before-image journal type.

On $OPEN and $DISPLAY services, the journal FAB, NAM, and XAB blocks are filled in with information about the specified journal. Because the only information stored in the journal access control element (ACE) is the volume name and the file ID of the journal, you will only be able to get the device name and file ID by using the journal FAB and NAM blocks.

This is an optional, input-only field.

The journaling flags field receives information for two flags that are specific to journaling, the journaling-disabled flag and the backup-done flag. It applies only to XABJNL XABs that have an after-image or before-image journal type.

If the XAB$V_JOURNAL_DISABLED flag is set, then journaling cannot be applied to the file. This flag is set by BACKUP on the backup copies of files marked for journaling to prevent the backup copy from being modified. If this flag is set for a data file marked for after-image or before-image journaling, then RMS does not allow the data file to be opened for write access.

If the XAB$V_BACKUP_DONE flag is set, it means that a BACKUP/RECORD operation has been done since the last time the file was opened by RMS for write access. This also tells RMS to write a ‘‘backup done’’ entry in the journal. The setting of this bit is synchronized with the updating of the XAB$L_BACKUP_ SEQNO longword, which is used to provide ‘‘backup-done’’ entries in the journal. If the RMS Recovery utility is used to restore data, then the backup-done entries are used to avoid redoing updates that are already reflected in the backup copy of the data file.

These bits are output-only parameters for the $OPEN and $DISPLAY services.

The length of volume name buffer field contains a value corresponding to the size of the user buffer that is available for receiving the name of the volume label for a journal. For XABJNL XABs with an after-image or before-image journal type, the value is for the volume (corresponding to the executive-mode, systemwide logical name DISK$volume_label) where the journal is located. For an RU_DEFAULT XABJNL (specified by the XAB$B_JNL_TYPE field), this field contains information on the default volume name where a recovery unit journal would be created. Note that the volume where a recovery unit journal ultimately resides is dependent on several factors, and that a file may be journalled to a recovery unit journal on a volume other than the one specified at the time the file was marked for recovery unit journaling.

This is an optional, input-only field.

The journal volume name address field contains the address of the buffer that is to receive the volume name string for the volume where the journal is to be located. For XABJNL XABs with an after-image or before-image journal type, the value returned is for the volume where the journal is located; for an RU_DEFAULT XABJNL (specified by the XAB$B_JNL_TYPE field), this field contains the default volume name where a recovery unit journal is created.

This is an optional, input-only field.

The returned length of volume name field receives the actual length of the volume name. For XABJNL XABs with an after-image or before-image journal type, the value returned is for the volume where the journal is located. For an RU_DEFAULT XABJNL (specified by the XAB$B_JNL_TYPE field), the value returned is for the default volume name where a recovery unit journal is created.

This is an output-only field returned by calls to the $OPEN or the $DISPLAY service.

The journal creation date field receives the expected creation date of the journal; it is retrieved from the data file being journaled, and not the journal itself. RMS Journaling uses this field to verify that the correct journal is being opened.

This field is used only for XABJNL XABs with an after-image or before-image type; it is an output-only field, used with the $OPEN or the $DISPLAY service.

The journal index field receives a value that uniquely identifies a journal stream within a journal; this value is automatically assigned when the file is marked for journaling.

This is an output-only field returned on calls to the $OPEN or the $DISPLAY service.

The backup sequence number field receives the sequence number associated with the most recent backup-done entry that is written to the journal.

This is an output-only field returned on calls to the $OPEN or the $DISPLAY service.

The Recovery utility time stamp field receives the date and time stamp of the last journal entry that was processed by the Recovery utility. It provides a check to verify that the file will not be rolled forward to a time earlier than a previous RECOVER/FORWARD operation.

This is an output-only field.

The recovery unit XAB (XABRU—pronounced "zab-ru") is used to designate a specific recovery unit for use by a particular file operation or stream.

For record operations, RMS operations are associated with recovery units on a stream basis.

If a XABRU is present when a $CONNECT call is issued and a valid recovery unit handle argument (ru_handle) is specified in the XABRU, the stream is joined to the recovery unit specified by the ru_handle argument. Any further record operations on that stream will take place as part of the specified recovery unit.

The following macros are defined for XABRU:

The XABRU contains the following fields:

The individual XABRU fields are described in the following sections.

The recovery unit handle field contains the recovery unit handle returned by the $START_RU service.

If a XABRU is specified in the FAB at the time of an $OPEN call, and this field contains any value other than 0, then the specified recovery unit handle identifies the default recovery unit for all record streams subsequently connected to this FAB. If a XABRU is specified in the record access block (RAB) at the time of a $CONNECT call, and this field contains any value other than 0, then the record stream attempts to join the recovery unit specified by the recovery unit handle.

If a XABRU is specified in both the FAB and the RAB, then the XABRU specified in the RAB takes precedence. (That is, the record stream joins the recovery unit identified by the recovery unit handle specified in the XABRU in the RAB.) If there is no XABRU in either the FAB or the RAB, then the stream joins the default recovery unit (that is, the most recently started recovery unit).

This is an optional, input-only field.

The recovery unit handle joined field receives the recovery unit handle to which the record stream was joined. This is an output-only field, and it is filled in only for a XABRU specified in the RAB if a record stream joins a recovery unit when the $CONNECT service is called. This field is ignored for XABRU XABs specified in the FAB.

The recovery unit flags field is used to specify recovery unit information. The XAB$W_RU_FLAGS field has only one bit that can be set: the XAB$M_NOJOIN bit. When this bit is set during the execution of the RMS services $OPEN or $CONNECT, the record stream does not join any recovery unit.

If a XABRU is specified in the FAB at the time of an $OPEN call, and the XAB$M_NOJOIN bit is set, then no record streams associated with the file join any recovery unit, unless specifically overridden when the call to $CONNECT is made. If a XABRU is specified in the RAB at the time of a $CONNECT call, and the XAB$M_NOJOIN is set, then the record stream does not join any recovery unit.

If a record stream does not join any recovery unit, and the file is marked for recovery unit journaling, only RMS operations that do not modify the contents of the file can be used. Any attempt to modify the file results in the error message "NRU, operation prohibited outside recovery-unit."

If there is no XABRU specified in either the FAB or the RAB, then the record stream attempts to join the default recovery unit (that is, the most recently started recovery unit).

This is an optional, input-only field.

A set-mode XAB$_RUJVOLNAM item list entry specifies a volume name that RMS uses to create a recovery unit journal. A sense-mode XAB$_RUJVOLNAM item list entry returns to the caller the name of the volume where the recovery unit journal is located.

When an RMS record service associates a stream with a transaction, and this is the first stream in the process to associate with that transaction, then RMS checks to see if a set-mode XAB$_RUJVOLNAM item list entry is specified with the caller’s RAB. If one is found, then the volume name specified by the item list entry is prefixed with the string DISK$ and the resultant string is used to determine the required location of the recovery unit journal.

Note that the XAB$_RUJVOLNAM item list entry overrides both the default recovery unit journal placement and any setting specified by using the SET FILE/RU_JOURNAL=LABEL command.

The fields of a set-mode XAB$_RUJVOLNAM item list entry are defined as follows:

The fields of a sense-mode XAB$_RUJVOLNAM item list entry are defined as follows:

The following usage restrictions apply to the XAB$_RUJVOLNAM item list entry:

A set-mode XAB$_TID item list entry selects a specific TID for association with a stream regardless of the process default transaction. A sense-mode XAB$_TID item list entry returns to the caller the TID of the transaction with which a stream has been associated.

The fields of a set-mode XAB$_TID item list entry are defined as follows:

The fields of a sense-mode XAB$_TID item list entry are defined as follows:

The following usage restrictions apply to the XAB$_TID item list entry: