C Prototype

Arguments

addres

Routine to receive control when a change mode trap or a compatibility
mode fault occurs. The addres argument is the
exception handling code in the address space of the calling process.

If you specify the addres argument as 0, $DCLCMH
clears the previously declared handler.

prvhnd

OpenVMS usage:

address

type:

longword (unsigned)

access:

write only

mechanism:

by reference

Address of a previously declared handler. The prvhnd
argument is the address of a longword containing the address of the
previously declared handler.

type

OpenVMS usage:

longword_unsigned

type:

longword (unsigned)

access:

read only

mechanism:

by value

Handler type indicator. The type argument is a
longword value. The value 0 (the default) indicates that a change mode
handler is to be declared for the access mode at which the request is
issued; the value 1 specifies that a compatibility mode handler is to
be declared.

Description

On Alpha and I64 systems, the Declare Change Mode or Compatibility Mode
Handler service calls the change mode handler as a normal procedure
(that is, with a standard procedure call). The change mode handler must
exit by performing a standard procedure return to the change mode
dispatcher.

Arguments (for example, the change mode code) passed between the
routine that issued the change mode instruction and the change mode
handler are strictly by agreement between the two procedures.

The following MACRO code example shows a subroutine calling Change Mode
to User. The example is written for Alpha and I64 users porting from
VAX systems.

CHG_MD: .CALL_ENTRY
CHMU
RET

Call this subroutine from any program that requires a Change Mode to
User instruction to be invoked.

On VAX systems, the $DCLCMH service specifies the address of a routine
to receive control when (1) a Change Mode to User or Change Mode to
Supervisor instruction trap occurs, or (2) a compatibility mode fault
occurs. A change mode handler provides users with a dispatching
mechanism similar to that used for system service calls. It allows a
routine that executes in supervisor mode to be called from user mode.
You declare the change mode handler from supervisor mode; then when the
process executing in user mode issues a Change Mode to Supervisor
instruction, the change mode handler receives control and executes in
supervisor mode.

The top longword of the stack contains the zero-extended change mode
code. The change mode handler must exit by removing the change mode
code from the stack and issuing an REI instruction.

The operating system uses compatibility mode handlers to bypass normal
condition handling procedures when an image executing in compatibility
mode causes a compatibility mode exception. Before transferring control
to the compatibility mode handler, the system saves the compatibility
exception code, the registers R0 through R6, and the PC and PSL in a
10-longword array starting at the location CTL$AL_CMCNTX. Before the
compatibility mode handler exits, it must restore the saved registers
R0 through R6, push the saved PC and PSL onto the stack, and exit by
issuing an REI instruction.

Declares an exit handling routine that receives control when an image
exits.

Format

SYS$DCLEXH desblk

C Prototype

int sys$dclexh (void *desblk);

Argument

desblk

OpenVMS usage:

exit_handler_block

type:

longword (unsigned)

access:

write

mechanism:

by reference

Exit handler control block. The desblk argument is the
address of this control block. This control block, which describes the
exit handler, is depicted in the following diagram:

Description

The Declare Exit Handler service declares an exit handler routine that
receives control when an image exits. Image exit normally occurs when
the image currently executing in a process returns control to the
operating system. Image exit might also occur when you call the Exit
($EXIT) or Force Exit ($FORCEX) service. Process exit handlers are not
invoked when a process is deleted (such as using a $DELPRC call, for
example).

Exit handlers are described by exit control blocks. The operating
system maintains a separate list of these control blocks for user,
supervisor, and executive modes, and the $DCLEXH service adds the
description of an exit handler to the front of one of these lists. The
actual list to which the exit control block is added is determined by
the access mode of the $DCLEXH caller.

At image exit, the image context, the image stack pointers, and the
validity of any variables allocated on the stack are all indeterminate.
Accordingly, the exit handler control block and any variables accessed
by each exit handler must all be declared using non-volatile semantics.
Examples of such non-volatile declarations include the BASIC and Fortran
COMMON
construct, and the C
static
storage class.

The declared exit handlers are called from the least-privileged
processor mode to the most-privileged mode, and the exit handler(s) for
each processor mode are called in the reverse order from which they
were originally declared. Each exit handler is executed only once; it
must be explicitly redeclared by the application if it is to be
executed again.

The exit handler routine is called as a normal procedure with the
argument list specified in the third through nth longwords of
the exit control block. The first argument is always the address of a
user-allocated longword to receive the system status code indicating
the reason for the exit; the system always fills in the referenced
longword before calling the exit handler. Accordingly, the exit handler
routine receives a pointer to the status code as its first argument.
Application programmers can append zero or more additional
application-specific longword arguments for use within the exit handler
routine, with the total number of arguments controlled by the value
specified in the argument count field.

You can call this service only from user, supervisor, and executive
modes.

Following is a BASIC programming example for this service. To view a C
example, see the HP OpenVMS Programming Concepts Manual.

Arguments

efn

Number of the event flag that is set when the service completes. If
this argument is omitted, event flag 0 is used.

flags

OpenVMS usage:

mask_longword

type:

longword (unsigned)

access:

read only

mechanism:

by value

Flags specifying options for the service. The flags
argument is a longword bit mask in which each bit corresponds to an
option flag. The $DDTMDEF macro defines symbolic names for these option
flags, described in Table SYS-23. All undefined bits must be 0. If this
argument is omitted, no flags are used.

Specifies successful synchronous completion by returning SS$_SYNCH.
When SS$_SYNCH is returned, the AST routine is not called, the event
flag is not set, and the I/O status block is not filled in.

DDTM$M_VOLATILE

Set this flag for the new RMI to be volatile. With this flag set, the
DECdtm transaction manager will not log information about any RM
participants associated with the new RMI. Resource managers that never
perform recovery should set this flag.

If this flag is clear, the new RMI is not volatile. The DECdtm
transaction manager will log the following information about each RM
participant associated with the new RMI:

The name of the RM participant.

The identifier (TID) of the transaction in which it is
participating.

If this flag is clear and a recoverable failure occurs, such as a
system crash, the resource manager can use the $GETDTI system service
to query the transaction log to determine the outcome of the
transactions in which it was participating before the failure occurred.

iosb

OpenVMS usage:

io_status_block

type:

quadword (unsigned)

access:

write only

mechanism:

by reference

The I/O status block in which the completion status of the service is
returned as a condition value. See the Condition Values Returned
section.

The following diagram shows the structure of the I/O status block:

astadr

OpenVMS usage:

ast_procedure

type:

procedure entry mask

access:

call without stack unwinding

mechanism:

by reference

The AST routine that is executed when the service completes, if
SS$_NORMAL is returned in R0. The astadr argument is
the address of the entry mask of this routine. The routine is executed
in the same access mode as that of the caller of the $DECLARE_RM
service.

astprm

OpenVMS usage:

user_arg

type:

longword (unsigned)

access:

read only

mechanism:

by value

The AST parameter that is passed to the AST routine specified by the
astadr argument.

rm_id

OpenVMS usage:

identifier

type:

longword (unsigned)

access:

write only

mechanism:

by reference

Longword in which the identifier (RM_ID) of the new RMI is returned.
This identifier is unique within the calling process at any time.

event_handler

OpenVMS usage:

ast_procedure

type:

procedure entry mask

access:

call without stack unwinding

mechanism:

by reference

The new RMI's event handler. This routine is called to report an event
to the new RMI or one of its RM participants. The
event_handler argument is the address of the entry
mask of this routine. An event handler must be specified.

This routine is called as an AST delivered by the DECdtm transaction
manager.

The AST is executed in the access mode specified by the
acmode argument. The AST parameter is the address of a
DECdtm event report block that contains an event report.

The DECdtm transaction manager reports events to an RMI and the RM
participants associated with it using ASTs executed in the access mode
specified in the call to $DECLARE_RM that created that RMI.

The DECdtm transaction manager creates an event report block, and
passes its address to the AST routine in the parameter of the AST. Each
event report block contains:

The identifier of the event report.

A code that describes the event.

The identifier (TID) of the transaction.

The name of the RM participant or RMI.

The context of the RM participant or RMI.

Other data that depend on the type of the event.

Table SYS-24 describes the fields in an event report block, in
alphabetical order:

See the $ACK_EVENT service for a list of possible values. Present
only in abort event reports.

DDTM$L_EVENT_TYPE

A code that identifies the event (longword). The following table lists
the possible values:

Symbol

Event

DDTM$K_ABORT

Abort

DDTM$K_COMMIT

Commit

DDTM$K_PREPARE

Prepare

DDTM$K_ONE_PHASE_COMMIT

One-phase commit

DDTM$K_STARTED_DEFAULT

Default transaction started

DDTM$K_STARTED_NONDEFAULT

Nondefault transaction started

DDTM$L_REPORT_ID

Event report identifier (unsigned longword).

DDTM$L_RM_CONTEXT

The context of the RM participant or RMI to which the event report is
being delivered (unsigned longword).

DDTM$Q_PART_NAME

The name of the RM participant or RMI to which the event report is
being delivered (descriptor).

DDTM$Q_TX_CLASS

The transaction class of the transaction (descriptor).

Each event report must be acknowledged by calling $ACK_EVENT,
specifying the identifier of the report. This acknowledgment need not
come from AST context.

The DECdtm transaction manager delivers only one event report at a time
to each RM participant. For example, if a prepare event report has been
delivered to an RM participant, and the transaction is aborted while
the RM participant is doing its prepare processing, then the DECdtm
transaction manager does not deliver an abort event report to that RM
participant until it has acknowledged the prepare event report by a
call to $ACK_EVENT. Note that the DECdtm transaction manager may
deliver multiple reports to an RMI.

After acknowledging the event report, the RMI or RM participant should
no longer access the event report block.

part_name

OpenVMS usage:

char_string

type:

character-coded text string

access:

read only

mechanism:

by descriptor--fixed-length string descriptor

The name of the new RMI. This is:

The default name of its RM participants, used when a call to
$JOIN_RM or $ACK_EVENT that adds one of these RM participants to a
transaction does not specify the name of the new RM participant.
When an RM participant associated with the new RMI is added to a
transaction by a call to $JOIN_RM or $ACK_EVENT that has a zero
part_name argument, then that RM participant inherits
its name from the RMI. The name of that RM participant is the same as
the name of the RMI.

The string passed in the participant name field of Transaction
Started event reports delivered to the new RMI.

This string must be no longer than 32 characters.

If this argument is omitted, the name of the new RMI is the null string.

To ensure smooth operation in a mixed-network environment, refer to the
chapter entitled Managing DECdtm Services in the HP OpenVMS System Manager's Manual, for
information on defining node names.

rm_context

OpenVMS usage:

userarg

type:

longword (unsigned)

access:

read only

mechanism:

by value

The context of the new RMI. This is:

The default context of its RM participants, used when a call to
$JOIN_RM or $ACK_EVENT that adds one of these RM participants to a
transaction does not specify the context of the new RM participant.
When an RM participant associated with the new RMI is added to a
transaction by a call to $JOIN_RM or $ACK_EVENT that has a zero
rm_context argument, then that RM participant inherits
its context from the RMI. The context of that RM participant is the
same as the context of the RMI.

The string passed in the context field of Transaction Started event
reports delivered to the new RMI.

If this argument is omitted, the context of the new RMI is 0.

acmode

OpenVMS usage:

access_mode

type:

longword (unsigned)

access:

read only

mechanism:

by value

The access mode of the new RMI. This is:

The access mode at which the ASTs delivered to its event handler
are to be executed.

The least privileged access mode that the caller must be in to call
$ACK_EVENT to acknowledge an event report delivered to the new RMI or
to its RM participants.

The least privileged access mode that the caller must be in to
delete the new RMI by calling $FORGET_RM.

The least privileged access mode that the caller must be in to call
$JOIN_RM to add a new RM participant associated with the new RMI.

The most privileged access mode of new branches that this RMI is
interested in, if the event_mask argument requests
events of type Transaction Started. The call to $START_TRANS or
$START_BRANCH that adds a new branch to a transaction specifies the
access mode of that transaction within this process. The DECdtm
transaction manager reports a Transaction Started event to the new RMI
only if the access mode of the transaction is the same as or less
privileged than the access mode of the new RMI. For example, if the
access mode of the new RMI is supervisor, it will receive a Transaction
Started event when a branch of the calling process is added to a
transaction only if the access mode of that transaction is user or
supervisor.

The access mode of the new RMI is the least privileged of:

The access mode of the caller.

The access mode specified by the acmode argument.

If this argument is omitted, the access mode of the new RMI is the same
as the access mode of the caller.

tm_log_id

OpenVMS usage:

DECnet_uid

type:

octaword (unsigned)

access:

write only

mechanism:

by reference

The globally unique identifier of the transaction log for the local
node. This identifier is used during resource manager recovery to check
that the correct DECdtm transaction manager log is used. See $GETDTI
for more information.

To ensure smooth operation in a mixed-network environment, refer to the
chapter entitled Managing DECdtm Services in the HP OpenVMS System Manager's Manual, for
information on defining node names.

event_mask

OpenVMS usage:

mask_longword

type:

longword (unsigned)

access:

read only

mechanism:

by value

Requests the types of event to be reported to the new RMI and to its RM
participants. The only type of event that can be reported to the new
RMI is a Transaction Started event (a default or non-default
transaction started event). The following types of event can be
reported to its RM participants: