Document revision date: 19 July 1999

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:

• Application: Defines the operations that the transaction will perform.
• Resource manager: Performs the operations on the resources. A resource manager must support DECdtm. Examples of those that do are Rdb, DBMS, and OpenVMS RMS Journaling.
• Transaction manager: Coordinates the actions of the resource managers on its node. Transaction managers are provided by DECdtm.

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

The DECdtm system services are:

• SYS$START_TRANSW: Starts a new transaction and returns the transaction identifier.
• SYS$END_TRANSW: Ends a transaction by attempting to commit it. Returns the outcome of the transaction (either commit or abort).
• SYS$ABORT_TRANSW: Aborts a transaction.

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:
   • Commit: To attempt to perform, or commit, the transaction, the application calls SYS$END_TRANSW. This checks whether all the participants can commit their operations. If any participant cannot commit an operation, the transaction is aborted.
     When SYS$END_TRANSW returns, the application finds out the outcome of the transaction by reading the completion status in the I/O status block.
   • Abort: To abort the transaction, the application calls SYS$ABORT_TRANSW. Typically, an application aborts a transaction if a resource manager returns an error or if the user enters invalid information during the transaction.

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:

• Increments the counter by 1
• Calls SYS$START_TRANSW to start a new transaction
• Writes the counter value to the two files
• Either calls SYS$END_TRANSW to attempt to commit the transaction, or calls SYS$ABORT_TRANSW to abort the transaction

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.

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:

• System errors---for example, specifying an invalid argument to a system-defined procedure
• Language-specific errors---for example, in Fortran, a data type conversion error during an I/O operation
• Application-specific errors---for example, attempting to use invalid data

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:

• Set Exception Vector (SYS$SETEXV)
• Set System Service Failure Exception Mode (SYS$SETSFM)
• Unwind from Condition Handler Frame (SYS$UNWIND)
• Declare Change Mode or Compatibility Mode Handler (SYS$DCLCMH)

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:

• Establish and call condition-handler routines
  You can establish condition handlers to receive control in the event of an exception in one of the following ways:
  • On VAX systems, by specifying the address of a condition handler in the first longword of a procedure call frame.
    On Alpha systems, the method for establishing a dynamic (that is, nonvectored) condition handler is specified by the language.
  • By establishing exception handlers with the Set Exception Vector (SYS$SETEXV) system service.
  
  The first of these methods is the preferred way to specify a condition handler for a particular image. The use of dynamic handlers is also the most efficient way in terms of declaration. Vectored handlers should be used for special purposes, such as writing debuggers.
  The VAX MACRO programmer can use the following single-move address instruction to place the address of the condition handler in the longword pointed to by the current frame pointer (FP):

  MOVAB HANDLER,(FP)

  
  You can associate a condition handler for the currently executing routine by specifying an address pointing to the handler, either in the routine's stack frame on VAX systems or in one of the exception vectors. (The MACRO-32 compiler for OpenVMS Alpha systems generates the appropriate Alpha code from this VAX instruction to establish a dynamic condition handler.)
  On VAX systems, the high-level language programmer can call the common run-time library routine LIB$ESTABLISH (see the OpenVMS RTL Library (LIB$) Manual), using the name of the handler as an argument. LIB$ESTABLISH returns as a function value the address of the former handler established for the routine or 0 if no handler existed.
  On VAX systems, the new condition handler remains in effect for your routine until you call LIB$REVERT or control returns to the caller of the caller of LIB$ESTABLISH. Once this happens, you must call LIB$ESTABLISH again if the same (or a new) condition handler is to be associated with the caller of LIB$ESTABLISH.
  On VAX systems, some languages provide access to condition handling as part of the language. The ON ERROR GOTO statement in BASIC and the ON statement in PL/I can be used to define condition handlers. If you are using a language that does provide access to condition handling, use its language mechanism rather than LIB$ESTABLISH. Each procedure can declare a condition handler.
  When the routine signals an exception, the OpenVMS Condition Handling facility calls the condition handler associated with the routine. See Section 15.8 for more information about exception vectors. Figure 15-5 shows a sample stack scan for a condition handler.
  The following DEC Fortran program segment establishes the condition handler ERRLOG. Because the condition handler is used as an actual argument, it must be declared in an EXTERNAL statement.

  INTEGER*4 OLD_HANDLER EXTERNAL ERRLOG . . . OLD_HANDLER = LIB$ESTABLISH (ERRLOG)

  
  As its function value, LIB$ESTABLISH returns the address of the previous handler. If only part of a program unit requires a special condition handler, you can reestablish the original handler by invoking LIB$ESTABLISH and specifying the saved handler address as follows:

  CALL LIB$ESTABLISH (OLD_HANDLER)

  
  The run-time library provides several condition handlers and routines that a condition handler can call. These routines take care of several common exception conditions. Section 15.14 describes these routines.
  On Alpha systems, LIB$ESTABLISH and LIB$REVERT are not supported, though a high-level language may support them for compatibility. (Table 15-4 lists other run-time library routines supported and not supported on Alpha systems.)

• On VAX systems, remove an established condition-handler routine
  On VAX systems using LIB$REVERT, you can remove a condition handler from a routine's stack frame by setting the frame's handler address to 0. If your high-level language provides condition-handling statements, you should use them rather than LIB$REVERT.
• On VAX systems, enable or disable the detection of arithmetic hardware exceptions
  On VAX systems, using run-time library routines, you can enable or disable the signaling of floating point underflow, integer overflow, and decimal overflow, which are detected by the VAX hardware.
• Signal a condition
  When the hardware detects an exception, such as an integer overflow, a signal is raised at that instruction. A routine may also raise a signal by calling LIB$SIGNAL or LIB$STOP. Signals raised by LIB$SIGNAL allow the condition handler either to terminate or to resume the normal flow of the routine. Signals raised by LIB$STOP require termination of the operation that raises the condition. The condition handler will not be allowed to continue from the point of call to LIB$STOP.
• Display an informational message
  The system establishes default condition handlers before it calls the main program. Because these default condition handlers provide access to the system's standard error messages, the standard method for displaying a message is by signaling the severity of the condition: informational, warning, or error. See Section 15.5 for the definition of the severity field of a condition vector. The system default condition handlers resume execution of the instruction after displaying the messages associated with the signal. If the condition value indicates a severe condition, then the image exits after the message is displayed.
• Display a stack traceback on errors
  The default operations of the LINK and RUN commands provide a system-supplied handler (the traceback handler) to print a symbolic stack traceback. The traceback shows the state of the routine stack at the point where the condition occurred. The traceback information is displayed along with the messages associated with the signaled condition.
• Compile customer-defined messages
  The Message utility allows you to define your own exception conditions and the associated messages. Message source files contain the condition values and their associated messages. See Section 15.11.3 for a complete description of how to define your own messages.
• Unwind the stack
  A condition handler can cause a signal to be dismissed and the stack to be unwound to the establisher or caller of the establisher of the condition handler when it returns control to the OpenVMS Condition Handling facility (CHF). During the unwinding operation, the CHF scans the stack. If a condition handler is associated with a frame, the system calls that handler before removing the frame. Calling the condition handlers during the unwind allows a routine to perform cleanup operations specific to a particular application, such as recovering from noncontinuable errors or deallocating resources that were allocated by the routine (such as virtual memory, event flags, and so forth). See Section 15.12.3 for a description of the SYS$UNWIND system service.
• Log error messages to a file
  The Put Message (SYS$PUTMSG) system service permits any user-written handler to include a message in a listing file. Such message logging can be separate from the default messages the user receives. See Section 15.11 for a detailed description of the SYS$PUTMSG system service.

	privacy and legal statement
5841PRO_038.HTML