[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS Programming Concepts Manual


Previous Contents Index


Chapter 14
Using the Distributed Transaction Manager

This chapter describes how to use the distributed transaction manager. It shows you how to use DECdtm services to bind together operations on several databases or files into a single transaction. To use DECdtm services, the resource managers taking part in the transaction must support DECdtm. DEC Rdb for OpenVMS Alpha, DEC Rdb for OpenVMS VAX, DEC DBMS for OpenVMS Alpha, DEC DBMS for OpenVMS VAX, and OpenVMS RMS Journaling support DECdtm.

This chapter is divided into the following sections:

Section 14.1 gives an introduction to DECdtm services.

Section 14.2 discusses how to call DECdtm services.

Section 14.3 gives an example that shows how to use DECdtm services.

14.1 Introduction to DECdtm Services

A transaction performs operations on resources. Examples of resources are databases and files. A transaction often needs to use more than one resource on one or more nodes. This type of transaction is called a distributed transaction.

Maintaining the integrity and consistency of the resources used by a distributed transaction can be complex. To help with this, DECdtm manages distributed transactions and reduces the amount of coding required in your applications.

DECdtm uses an optimized version of the standard two-phase commit protocol. This ensures that transactions are atomic. If a transaction is atomic, either all the transaction operations take effect (the transaction is committed), or none of the operations take effect (the transaction is aborted).

The two-phase commit protocol makes sure that all the operations can take effect before the transaction is committed. If any operation cannot take effect, for example if a network link is lost, then the transaction is aborted, and none of the operations take effect.

14.1.1 Sample Atomic Transaction

Edward Jessup, an employee of a computer company in Italy, is transferring to a subsidiary of the company in Japan. An application must remove his personal information from an Italian DBMS database and add them to a Japanese Rdb database. Both of these operations must happen, otherwise Edward may either end up "in limbo" (the application might remove him from the Italian database but then lose a network link while trying to add him to the Japanese database), or find that he is in both databases at the same time. Either way, the two databases would be out of step.

If the application used DECdtm to execute both operations as an atomic transaction, then this error could never happen; DECdtm would automatically detect the network link failure and abort the transaction. Neither of the databases would be updated, and the application could then try again.

14.1.2 Transaction Participants

A DECdtm transaction involves the following participants:

Figure 14-1 shows the participants in the distributed transaction discussed in Section 14.1.1. The application is on node ITALY.

Figure 14-1 Participants in a Distributed Transaction


14.1.3 DECdtm System Services

The DECdtm system services are:

These are all synchronous system service calls. There are also asynchronous versions (SYS$START_TRANS, SYS$END_TRANS, and SYS$ABORT_TRANS). For a full description of all the DECdtm system services, see the OpenVMS System Services Reference Manual.

14.1.4 Default Transactions

Some resource managers (such as OpenVMS RMS Journaling) support the concept of default transactions. This means that the application does not need to specify the transaction identifier when executing transaction operations. The resource manager checks whether the calling process has a default transaction; if it has, the resource manager assumes that the operation is part of the default transaction.

14.2 Calling DECdtm System Services

An application using the DECdtm system services follows these steps:

  1. Calls SYS$START_TRANSW. This starts a new transaction and returns the transaction identifier.
  2. Instructs the resource managers to perform the required operations on their resources.
  3. Ends the transaction in one of two ways:

14.3 Using DECdtm Services: An Example

The following is a sample Fortran application that uses DECdtm system services. It can be found in SYS$EXAMPLES:DECDTM$EXAMPLE1.

The application opens two files, sets a counter, then enters a loop to perform the following steps:

The application repeats these steps until either an error occurs or the user requests an interrupt. Because DECdtm services are used, the two files will always be in step with each other. If DECdtm services were not used, one file could have been updated while the other was not. This would result in the files' being out of step.

This example contains numbered callouts, which are explained after the program listing.


C 
C This program assumes that the files DECDTM$EXAMPLE1.FILE_1 and 
C DECDTM$EXAMPLE1.FILE_2 are created and marked for recovery unit 
C journaling using the command file SYS$EXAMPLES:DECDTM$EXAMPLE1.COM 
C 
C To run this example, enter the following: 
C   $ FORTRAN SYS$EXAMPLES:DECDTM$EXAMPLE1 
C   $ LINK DECDTM$EXAMPLE1 
C   $ @SYS$EXAMPLES:DECDTM$EXAMPLE1 
C   $ RUN DECDTM$EXAMPLE1 
C 
C SYS$EXAMPLES also contains an example C application, DECDTM$EXAMPLE2.C 
C The C application performs the same operations as this Fortran example. 
C  
        IMPLICIT    NONE 
 
        INCLUDE     '($SSDEF)' 
        INCLUDE     '($FORIOSDEF)' 
 
        CHARACTER*12 STRING 
        INTEGER*2   IOSB(4) 
        INTEGER*4   STATUS,COUNT,TID(4) 
        INTEGER*4   SYS$START_TRANSW,SYS$END_TRANSW,SYS$ABORT_TRANSW 
        EXTERNAL    SYS$START_TRANSW,SYS$END_TRANSW,SYS$ABORT_TRANSW 
        EXTERNAL    JOURNAL_OPEN 
C 
C Open the two files 
C 
(1)        OPEN (UNIT = 10, FILE = 'DECDTM$EXAMPLE1.FILE_1', STATUS = 'OLD', 
        1     ACCESS = 'DIRECT', RECL = 3, USEROPEN = JOURNAL_OPEN) 
        OPEN (UNIT = 11, FILE = 'DECDTM$EXAMPLE1.FILE_2', STATUS = 'OLD', 
        1     ACCESS = 'DIRECT', RECL = 3, USEROPEN = JOURNAL_OPEN) 
 
        COUNT = 0 
 
        TYPE *, 'Running DECdtm example program' 
        TYPE *, 'Press CTRL-Y to interrupt' 
C 
C Loop forever, updating both files under transaction control 
C 
        DO WHILE (.TRUE.) 
C 
C Update the count and convert it to ASCII 
C 
(2)          COUNT = COUNT + 1 
          ENCODE (12,8000,STRING) COUNT 
8000      FORMAT (I12) 
C 
C Start the transaction 
C 
(3)          STATUS = SYS$START_TRANSW (%VAL(1),,IOSB,,,TID) 
          IF (STATUS .NE. SS$_NORMAL .OR. IOSB(1) .NE. SS$_NORMAL) GO TO 9040 
C 
C Update the record in each file 
C 
(4)          WRITE (UNIT = 10, REC = 1, ERR = 9000, IOSTAT = STATUS) STRING 
          WRITE (UNIT = 11, REC = 1, ERR = 9010, IOSTAT = STATUS) STRING 
C 
C Attempt to commit the transaction 
C 
(5)          STATUS = SYS$END_TRANSW (%VAL(1),,IOSB,,,TID) 
          IF (STATUS .NE. SS$_NORMAL .OR. IOSB(1) .NE. SS$_NORMAL) GO TO 9050 
 
        END DO 
C 
C Errors that should cause the transaction to abort 
C 
(6)
9000    TYPE *, 'Failed to update DECDTM$EXAMPLE1.FILE_1' 
        GO TO 9020 
 
9010    TYPE *, 'Failed to update DECDTM$EXAMPLE1.FILE_2' 
9020    STATUS = SYS$ABORT_TRANSW (%VAL(1),,IOSB,,,TID) 
        IF (STATUS .NE. SS$_NORMAL .OR. IOSB(1) .NE. SS$_NORMAL) GO TO 9060 
        STOP 
C 
C Errors from DECdtm system services 
C 
9040    TYPE *, 'Unable to start a transaction' 
        GO TO 9070 
9050    TYPE *, 'Failed to commit the transaction' 
        GO TO 9070 
9060    TYPE *, 'Failed to abort the transaction' 
9070    TYPE *, 'Status = ', STATUS, ' IOSB = ', IOSB(1) 
        END 
C 
C Switch off TRUNCATE access and PUT with truncate on OPEN for RU Journaling 
C 
        INTEGER FUNCTION JOURNAL_OPEN (FAB, RAB, LUN) 
 
        INCLUDE '($FABDEF)' 
        INCLUDE '($RABDEF)' 
        INCLUDE '($SYSSRVNAM)' 
 
        RECORD  /FABDEF/ FAB, /RABDEF/ RAB 
 
        FAB.FAB$B_FAC = FAB.FAB$B_FAC .AND. .NOT. FAB$M_TRN 
        RAB.RAB$L_ROP = RAB.RAB$L_ROP .AND. .NOT. RAB$M_TPT 
 
        JOURNAL_OPEN = SYS$OPEN (FAB) 
        IF (.NOT. JOURNAL_OPEN) RETURN 
        JOURNAL_OPEN = SYS$CONNECT (RAB) 
 
        RETURN 
        END 
 

  1. The application opens DECDTM$EXAMPLE1.FILE1 and DECDTM$EXAMPLE1.FILE2 for writing. It then zeroes the variable COUNT and enters an infinite loop.
  2. The application increments the count by one and converts it to an ASCII string.
  3. The application calls SYS$START_TRANSW to start a transaction. The application checks the immediate return status and service completion status to see whether they signify an error.
  4. The application attempts to write the string to the two files. If it cannot, the application aborts the transaction. Because the files are OpenVMS RMS journaled files, the default transaction is assumed.
  5. The application calls SYS$END_TRANSW to attempt to commit the transaction. It checks the immediate return status and service completion status to see whether they signify an error. If they do, the application reports the error and exits. If there are no errors, the transaction is committed and the application continues with the loop.
  6. If either of the two files could not be updated, the application calls SYS$ABORT_TRANSW to abort the transaction. It checks the immediate return status and service completion status to see whether they signify an error. If they do, the application reports the error and exits.


Chapter 15
Condition-Handling Routines and Services

This chapter describes the OpenVMS Condition Handling facility. It contains the following sections:

Section 15.1 gives an overview of run-time errors.

Section 15.2 gives an overview of the OpenVMS Condition Handling facility, presenting condition-handling terminology and functionality.

Section 15.3 describes VAX system and Alpha system exceptions, arithmetic exceptions, and unaligned access traps on Alpha systems.

Section 15.4 describes how run-time library routines handle exceptions.

Section 15.5 describes the condition value field and the testing and modifying of values.

Section 15.6 describes the exception dispatcher.

Section 15.7 describes the argument list that is passed to a condition handler.

Section 15.8 describes signaling.

Section 15.9 describes types of condition handlers.

Section 15.10 describes types of actions performed by condition handlers.

Section 15.11 describes messages and how to use them.

Section 15.12 describes how to write a condition handler.

Section 15.13 describes how to debug a condition handler.

Section 15.14 describes several run-time library routines that can be established as condition handlers.

Section 15.15 describes how to establish, write, and debug an exit handler.

15.1 Overview of Run-Time Errors

Run-time errors are hardware- or software-detected events, usually errors, that alter normal program execution. Examples of run-time errors are as follows:

When an error occurs, the operating system either returns a condition code or value identifying the error to your program or signals the condition code. If the operating system signals the condition code, typically an error message is displayed, and program execution continues or terminates, depending on the severity of the error. See Section 15.5 for details about condition values.

When unexpected errors occur, your program should display a message identifying the error and then either continue or stop, depending on the severity of the error. If you know that certain run-time errors might occur, you should provide special actions in your program to handle those errors.

Both an error message and its associated condition code identify an error by the name of the facility that generated it and an abbreviation of the message text. Therefore, if your program displays an error message, you can identify the condition code that was signaled. For example, if your program displays the following error message, you know that the condition code SS$_NOPRIV was signaled:


%SYSTEM-F-NOPRIV, no privilege for attempted operation

15.2 Overview of the OpenVMS Condition Handling Facility

The operating system provides a set of signaling and condition-handling routines and related system services to handle exception conditions. This set of services is called the OpenVMS Condition Handling facility (CHF). The OpenVMS Condition Handling Facility is a part of the common run-time environment of OpenVMS, which includes run-time library (RTL) routines and other components of the operating system.

The OpenVMS Condition Handling facility provides a single, unified method to enable condition handlers, signal conditions, print error messages, change the error behavior from the system default, and enable or disable detection of certain hardware errors. The RTL and all layered products of the operating sytem use the CHF for condition handling.

See the OpenVMS Calling Standard for a detailed description of OpenVMS condition handling.

15.2.1 Condition-Handling Terminology

This section defines terms used to describe condition handling.

exception

An event detected by the hardware or software that changes the normal flow of instruction execution. An exception is a synchronous event caused by the execution of an instruction and often means something generated by hardware. When an exception occurs, the processor transfers control by forcing a change in the flow of control from that explicitly indicated in the currently executing process.

Some exceptions are relevant primarily to the current process and normally invoke software in the context of the current process. An integer overflow exception detected by the hardware is an example of an event that is reported to the process. Other exceptions, such as page faults, are handled by the operating system and are transparent to the user.

An exception may also be signaled by a routine (software signaling) by calling the RTL routines LIB$SIGNAL or LIB$STOP.

condition

An informational state that exists when an exception occurs. Condition is a more general term than exception; a condition implies either a hardware exception or a software-raised condition. Often, the term condition is preferred because the term exception implies an error. Section 15.3.1 and Section 15.3.1.1 further define the differences between exceptions and conditions.

condition handling

When a condition is detected during the execution of a routine, a signal can be raised by the routine. The routine is then permitted to respond to the condition. The routine's response is called handling the condition.

On VAX systems, an address of 0 in the first longword of a procedure call frame or in an exception vector indicates that a condition handler does not exist for that call frame or vector.

On Alpha systems, the handler valid flag bit in the procedure descriptor is cleared to indicate that a condition handler does not exist.

The condition handlers are themselves routines; they have their own call frames. Because they are routines, condition handlers can have condition handlers of their own. This allows condition handlers to field exceptions that might occur within themselves in a modular fashion.

On VAX systems, a routine can enable a condition handler by placing the address of the condition handler in the first longword of its stack frame.

On Alpha systems, the association of a handler with a procedure is static and must be specified at the time a procedure is compiled (or assembled). Some languages that lack their own exception-handling syntax, however, may support emulation of dynamic specified handlers by means of built-in routines.

If you determine that a program needs to be informed of particular exceptions so it can take corrective action, you can write and specify a condition handler. This condition handler, which receives control when any exception occurs, can test for specific exceptions.

If an exception occurs and you have not specified a condition handler, the default condition handler established by the operating system is given control. If the exception is a fatal error, the default condition handler issues a descriptive message and causes the image that incurred the exception to exit.

To declare or enable a condition handler, use the following system services:

Parallel mechanisms exist for uniform dispatching of hardware and software exception conditions. Exceptions that are detected and signaled by hardware transfer control to an exception service routine in the executive. Software-detected exception conditions are generated by calling the run-time library routines LIB$SIGNAL or LIB$STOP. Hardware- and software-detected exceptions eventually execute the same exception dispatching code. Therefore, a condition handler may handle an exception condition generated by hardware or by software identically.

The Set Exception Vector (SYS$SETEXV) system service allows you to specify addresses for a primary exception handler, a secondary exception handler, and a last-chance exception handler. You can specify handlers for each access mode. The primary exception vector is reserved for the debugger. In general, you should avoid using these vectored handlers unless absolutely necessary. If you use a vectored handler, it must be prepared for all exceptions occurring in that access mode.

15.2.2 Functions of the Condition Handling Facility

The OpenVMS Condition Handling facility and the related run-time library routines and system services perform the following functions:


Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
5841PRO_038.HTML