Creates a new Resource Manager instance (RMI) in the calling
process.
Format
SYS$DECLARE_RM [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,rm_id
,event_handler ,[part_name] [,[rm_context]
,[acmode] ,[tm_log_id] ,[event_mask]]
C Prototype
int sys$declare_rm unsigned int efn, unsigned int
flags, struct _iosb *iosb, void
(*astadr)(__unknown_params), int
astprm, unsigned int *rm_id, void
(*event_handler)(__unknown_params),... ;
1 – Arguments
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
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 $DECLARE_RM Option Flags. All undefined bits
must be 0. If this argument is omitted, no flags are used.
Table SYS-11 $DECLARE_RM Option Flags
Flag Name Description
DDTM$M_SYNC 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_ Set this flag for the new RMI to be volatile.
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:
o The name of the RM participant.
o 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.
Refer to the VSI OpenVMS System Services Reference Manual to view
the I/O status block diagram.
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:
o The identifier of the event report.
o A code that describes the event.
o The identifier (TID) of the transaction.
o The name of the RM participant or RMI.
o The context of the RM participant or RMI.
o Other data that depend on the type of the event.
Fields in an Event Report Block describes the fields in an event
report block, in alphabetical order:
Table SYS-12 Fields in an Event Report Block
Symbol Description
DDTM$A_TID_PTR Address of the identifier (TID) of the
transaction.
DDTM$L_ABORT_ Abort reason code (longword).
REASON
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_ One-phase commit
COMMIT
DDTM$K_STARTED_ Default transaction started
DEFAULT
DDTM$K_STARTED_ Nondefault transaction
NONDEFAULT 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:
o 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.
o 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
VSI 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:
o 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.
o 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:
o The access mode at which the ASTs delivered to its event
handler are to be executed.
o 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.
o The least privileged access mode that the caller must be in to
delete the new RMI by calling $FORGET_RM.
o 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.
o 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:
o The access mode of the caller.
o 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
VSI 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:
o Abort events
o Commit events
o One-phase commit events
o Prepare events
The event_mask argument is a longword bit mask that is the
logical OR of each bit set, where each bit corresponds to an
event. The $DDTMDEF module defines a symbolic name for each flag
bit. $DECLARE_RM Event Selection Flags describes the flags. All
undefined bits must be 0.
If this argument is omitted, the following events are requested:
o Abort events
o Commit events
o One-phase commit events
o Prepare events
Table SYS-13 $DECLARE_RM Event Selection Flags
Flag Name Description
DDTM$M_EV_ Specifies that abort events are to be reported
ABORT to the RM participants associated with the new
RMI. If this flag is set, when an abort event
occurs for a transaction, the DECdtm transaction
manager delivers an abort event report to each RM
participant in the transaction that is associated
with the new RMI.
DDTM$M_EV_ Specifies that commit events are to be reported to
COMMIT the RM participants associated with the new RMI.
If this flag is set, when the DECdtm transaction
manager decides that the outcome of a transaction
is commit, it delivers a commit event report to
each RM participant in the transaction that is
associated with the new RMI.
DDTM$M_EV_ Specifies that prepare events are to be reported
PREPARE to the RM participants associated with the new
RMI.
If this flag is set, when the DECdtm transaction
manager initiates the commit protocol (in response
to a call to $END_TRANS) to determine the outcome
of a transaction, it reports a prepare event to
each RM participant in the transaction that is
associated with the new RMI.
The acknowledgment of a prepare event is a vote on
the outcome of the transaction. See $ACK_EVENT for
more information.
DDTM$M_EV_ Specifies that events of type Transaction Started
TRANS_START are to be reported to the new RMI. Events of type
Transaction Started are:
o Default transaction started events.
o Non-default transaction-started events.
If this flag is set, the DECdtm transaction
manager will report one of these events to the
new RMI whenever a new branch in the calling
process is added to a transaction, provided that
the access mode of the new branch is not more
privileged than the access mode of the new RMI.
The acknowledgment of that event report may add
a new RM participant associated with the new RMI
to that transaction. See the description of the
acmode argument for a discussion of access modes.