HP OpenVMS Systems Documentation

Order Number: AA--JG41C--TE

This manual describes the use of RMS Journaling for OpenVMS.

Revision/Update Information: This manual supersedes the RMS Journaling for OpenVMS Manual, Version 5.5.

Operating System and Version: OpenVMS VAX Version 6.0 or later
OpenVMS AXP Version 1.5 or later

Software Version: RMS Journaling for OpenVMS VAX, Version 6.0
RMS Journaling for OpenVMS AXP, Version 1.5

Digital Equipment Corporation/Maynard, Massachusetts

The information in this document is subject to change without notice and should be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document.

The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license.

No responsibility is assumed for the use or reliability of software on equipment that is not supplied by Digital Equipment Corporation or its affiliated companies.

© Digital Equipment Corporation 1993. All rights reserved.

The postpaid Reader's Comments forms at the end of this document request your critical evaluation to assist in preparing future documentation.

The following are trademarks of Digital Equipment Corporation: AXP, Bookreader, DEC C, DEC COBOL, DECdtm, DEC Rdb, DECwindows, Digital, OpenVMS, OpenVMS RMS, VAX, VAXcluster, VAX DBMS, VAX DOCUMENT, VAX MACRO, VMS, VMScluster, the AXP logo, and the DIGITAL logo.

The following is a third-party trademark:

PostScript is a registered trademark of Adobe Systems Incorporated.

All other trademarks and registered trademarks are the property of their respective holders.

ZK4454

This document was prepared using VAX DOCUMENT, Version V3.2n.

Introduction

This manual describes RMS Journaling for OpenVMS and how to use it. It also includes information about other OpenVMS components that support RMS Journaling.

Who should use this manual

This manual is intended for application programmers and designers who want to use RMS Journaling in their applications and system managers who have RMS Journaling installed on their systems.

How this manual is organized

This manual has nine chapters and four appendixes:

• Chapter 1 introduces you to RMS Journaling; it provides an overview of the three types of journaling.
• Chapter 2 describes how to get information on the journaling status of a file.
• Chapter 3 describes how to use after-image journaling.
• Chapter 4 describes how to use before-image journaling.
• Chapter 5 describes how to use recovery unit journaling.
• Chapter 6 describes issues for combining different types of journaling.
• Chapter 7 discusses system management considerations for systems on which RMS Journaling is used.
• Chapter 8 contains reference information about the RECOVER/RMS_FILE and SET FILE commands.
• Chapter 9 contains reference information about RMS blocks and fields specific to RMS Journaling.
• Appendix A summarizes the support for RMS services under the three types of journaling.
• Appendix B describes the obsolete recovery unit services.
• Appendix C contains three implementations of a sample application program showing the use of DECdtm transaction services, written in DEC C (two versions) and DEC COBOL.
• Appendix D describes limitations on recovery unit recovery on systems running versions of RMS Journaling earlier than Version 5.4.

Associated documents

Use this manual with the OpenVMS documentation set and the documentation for your programming language and application development tools. In addition:

Conventions used in this manual

In this manual, every use of OpenVMS means both the OpenVMS AXP operating system and the OpenVMS VAX operating system.

The following conventions are also used in this manual:

RMS Journaling is a tool that helps to protect your data from being lost or becoming inconsistent.

1.1.2 Files and RMS Journaling

Journaling is applied on a file-by-file basis, not on an application basis.

You can use RMS Journaling for any RMS (Record Management Services) file that is updated. You can use any of the journaling types with sequential, relative, or Prolog 3 indexed file organizations.

You cannot use RMS Journaling for:

• File operations that do not use RMS services
• RMS files that are rewritten with a new version number (such as text files that are modified by a text editor) rather than updated in place

The following topics are covered in this chapter:

To use journaling for a file, you must mark the file for journaling with the DCL command SET FILE. The SET FILE command allows you to mark a file for one, two, or all three journaling types.

1.3 Journaling Types

There are three types of RMS Journaling: after-image, before-image, and recovery unit. All three types allow the re-creation of a previous state of a data file by using information kept in a separate file called a journal. Each journaling type protects against a different kind of problem, as summarized in the following table.

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

There are several ways to get the current journaling status of a file.

The following topics are covered in this chapter:

The RMS services $OPEN and $DISPLAY provide the current journaling characteristics of a file from within an application. Both of these services set the FAB$B_JOURNAL field in the file access block (FAB) to indicate whether the file is a journal or whether it is marked for after-image, before-image, or recovery unit journaling. For information on using these RMS services, see the OpenVMS Record Management Services Reference Manual.

For more information on the FAB$B_JOURNAL field, see Chapter 9.

2.3 Using the ANALYZE/RMS_FILE Command

The ANALYZE/RMS_FILE command provides journaling information about a file, including information about the state of recovery units.

The following example shows the partial output for this command for a file that is marked for both after-image and before-image journaling:

$ ANALYZE/RMS_FILE [PAYROLL]WEEKLY.DAT

Check RMS File Integrity              15-JUN-1990 08:08:27.80   Page 1
FINANCE_DISK:[PAYROLL]WEEKLY.DAT;1


FILE HEADER
                                  .
                                  .
                                  .
    Journaling Enabled:  After-Image, Before-Image


RMS FILE ATTRIBUTES
                                  .
                                  .
                                  .

    After-Image Journaling
            Journal Name: JOURNAL_DISK:[FINANCE]PAYROLL.RMS$JOURNAL;1 (1)
            Journal Creation Date: 10-JUN-1990 12:05:33.95
            Journal Stream Index: 1 (2)
    Before-Image Journaling
            Journal Name: JOURNAL_DISK:[FINANCE]PAYROLL.RMS$JOURNAL;1 (1)
            Journal Creation Date: 10-JUN-1990 12:05:33.95
            Journal Stream Index: 2 (2)



The analysis uncovered NO errors.

This example shows that after-image journaling and before-image journaling are using the same journal ((1)). Note that after-image journaling and before-image journaling use different record stream identifiers ((2)), allowing RMS Journaling to distinguish the updates that are journaled.

2.3.2 Using the /RU_JOURNAL qualifier

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.

2.3.3 Example

Suppose that a system crash occurred during execution of an application that used files marked for recovery unit journaling, and that you are unable to open the file CHECKING.DAT. The following example shows the output of the ANALYZE/RMS_FILE/RU_JOURNAL command for the file CHECKING.DAT:

$ 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  (1)

        Journal Spec: DISK$WORK:[SYSJNL]RMS$79400083.RMS$JOURNAL;1  (2)
        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:  (3)

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

        Recovery Unit State:  Started  (5)

The analysis uncovered NO errors.

The following table explains the numbered items in the example.

2.3.4 Recovery unit states

You can use the DIRECTORY/FULL command to:

• Determine if a file is marked for one or more types of journaling
• Identify the journals for after-image and before-image journaling

$ DIRECTORY/FULL SALES.DAT

Directory DISK1:[FINANCE]

SALES.DAT;1                   File ID:  (332,10,0)
Size:          265/265        Owner:    [335,310]
Created:  27-MAR-1990 10:15   Revised:  12-APR-1990 07:30 (9)
Expires:   <None specified>   Backup:   13-APR-1990 00:16
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:[FINANCE]NEW_SALES.RMS$JOURNAL;1
BI journal:    JOURNAL_DISK:[FINANCE]SALES.RMS$JOURNAL;1
File protection:    System:RWED, Owner:RWED, Group:RE, World:

Total of 1 file, 265/265 blocks.

The Journaling Enabled field can include the following items:

The next two fields, AI journal and BI journal, list the respective journals for SALES.DAT. These fields are displayed only when a file is marked for after-image or before-image journaling.

2.4.2 Example: remote files

If you use the DIRECTORY/FULL command for a remote network file, the long-term journals are not identified, as in the following example:

$ DIRECTORY/FULL BOSTON::DISK1:[FINANCE]SALES.DAT

Directory BOSTON::DISK1:[FINANCE]

SALES.DAT;1                   File ID:  (332,10,0)
Size:          265/265        Owner:    [335,310]
Created:  27-MAR-1990 10:15   Revised:  12-APR-1990 07:30 (9)
Expires:   <None specified>   Backup:   13-APR-1990 00:16
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:         Not available
BI journal:         Not available
File protection:    System:RWED, Owner:RWED, Group:RE, World:

Total of 1 file, 265/265 blocks.

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.

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