Acknowledges an event reported to a Resource Manager (RM)
participant or Resource Manager instance (RMI).
Format
SYS$ACK_EVENT [flags] ,report_id ,report_reply [,[reason]
,[beftime] ,[afttime] ,[part_name]
,[rm_context], [timout]]
C Prototype
int sys$ack_event (unsigned int flags, unsigned int report_id,
int report_reply,...);
1 – Arguments
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Reserved to VSI. This argument must be zero.
report_id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by value
The identifier of the event report being acknowledged by this
call to $ACK_EVENT.
report_reply
OpenVMS usage:cond_value
type: longword (unsigned)
access: read only
mechanism: by value
Acknowledgment code appropriate to the event being acknowledged
by this call to $ACK_EVENT. The following tables give the valid
acknowledgment codes for the various events. The title of each
table gives the event, and in brackets, its event code. The event
code is passed in the event report block (see $DECLARE_RM).
Acknowledgment of prepare or one-phase commit events gives a
vote on the outcome of the transaction-either to commit or to
abort. The tables for these events have a column labeled "Vote".
A "yes" vote means that the RM participant wants to commit the
transaction, while a "no" vote means that the RM participant
cannot commit. The transaction will be committed only if all
participants vote "yes".
Table SYS-3 Replies to an Abort Event Report (DDTM$K_ABORT)
report_
reply Description
SS$_FORGET RM participant guarantees that the effects of its
transaction operations will never be detected by any
transaction that commits.
Side effects:
On successful completion of the call to $ACK_EVENT,
the RM participant is removed from the transaction,
and the ASTLM quota consumed by the call to $JOIN_RM
or $ACK_EVENT that added it to the transaction is
returned.
DECdtm also releases any application threads that are
waiting for the transaction to end (necessary but not
sufficient condition). Any call to $END_TRANS, $END_
BRANCH, or $ABORT_TRANS on a node for a transaction
whose outcome is abort is not allowed to complete
until after all abort event reports delivered to RM
participants on that node have been acknowledged.
Table SYS-4 Replies to a Commit Event Report (DDTM$K_COMMIT)
report_
reply Description
SS$_FORGET Allows the DECdtm transaction manager to forget the
RM participant.
The RM participant must not give this reply until it
has either:
o Completed the commit processing for its
transaction operations.
o Safely stored enough information to ensure that
this commit processing will inevitably complete
(for example, logged that the transaction has
committed in a private log).
If the RM participant is associated with a
nonvolatile RMI, then at some point after receiving
this reply, the DECdtm transaction manager will
delete the name of the RM participant from the
transaction database. After SS$_FORGET replies
have been given for all the RM participants in
a transaction, that transaction ceases to be
recoverable (some time after all these replies
are given, the transaction is deleted from the
transaction database). A subsequent call to $GETDTI
can lead the resource manager to wrongly assume that
the transaction had aborted.
If there is a failure after this reply is sent, a
recoverable resource manager must be able to rely
on its own safely stored information to determine if
any of the commit processing associated with the RM
participant needs to be restarted.
Side effects:
On successful completion of the call to $ACK_EVENT,
the RM participant is removed from the transaction,
and the ASTLM quota consumed by the call to $JOIN_RM
or $ACK_EVENT that added it to the transaction is
returned.
DECdtm also releases any application threads that
are waiting for the transaction to end (necessary but
not sufficient condition). Any call to $END_TRANS or
$END_BRANCH on a node for a transaction whose outcome
is commit cannot complete successfully until all
commit event reports delivered to RM participants on
that node have been acknowledged.
SS$_ The RM participant requires that the DECdtm
REMEMBER transaction manager stores its name and the outcome
of the transaction (commit) in the transaction
database. Note that for an RM participant associated
with a volatile RMI, SS$_REMEMBER is treated in the
same way as SS$_FORGET.
Side effects:
On successful completion of the call to $ACK_EVENT,
the RM participant is removed from the transaction,
and the ASTLM quota consumed by the call to $JOIN_RM
or $ACK_EVENT that added it to the transaction is
returned.
DECdtm also releases any application threads that
are waiting for the transaction to end (necessary but
not sufficient condition). Any call to $END_TRANS or
$END_BRANCH on a node for a transaction whose outcome
is commit cannot complete successfully until all
commit event reports delivered to RM participants on
that node have been acknowledged.
Table SYS-5 Replies to a One-phase Commit Event Report (DDTM$K_
ONE_PHASE_COMMIT)
report_
reply Vote Meaning
SS$_NORMAL Yes The RM participant decided to commit the
transaction, and has safely stored enough
information to be able to keep this guarantee
even if there is a recoverable failure, caused,
for example, by a node crash.
The DECdtm transaction manager does not log any
information about the transaction.
Side effects:
On successful completion of the call to $ACK_
EVENT, the RM participant is removed from the
transaction, the transaction is ended, and the
ASTLM quota consumed by the call to $JOIN_RM or
$ACK_EVENT that added the RM participant to the
transaction is returned.
DECdtm also allows the call to $END_TRANS to
complete (necessary and sufficient condition).
SS$_ Yes RM participant decided not to accept the
PREPARED opportunity to decide the outcome of the
transaction. It has performed only prepare
processing for the transaction and requires
full two-phase commit processing. This is
equivalent to voting SS$_PREPARED on a prepare
event.
The RM participant can either commit or
abort the operations of the transaction, and
guarantees that it will abide by the DECdtm
transaction manager's decision on whether the
transaction (and therefore these operations)
are committed or aborted.
A recoverable resource manager must not give
this vote until it has safely stored enough
information to be able to keep this guarantee
even if there is a recoverable failure, caused,
for example, by a node crash.
The DECdtm transaction manager will decide
the outcome of the transaction, then inform
the resource manager of the decision with
a commit or abort event report delivered
to the RM participant (assuming that it is
associated with an RMI that requested these
event reports).
Note that an application or other failure can
cause the DECdtm transaction manager to decide
to abort the transaction.
SS$_VETO No RM participant requires that the transaction
be aborted and guarantees that the effects of
that transaction on its resources will never
be detected by any transaction that commits.
The reason argument gives the reason why the RM
participant is aborting the transaction.
The DECdtm transaction manager does not log any
information about the transaction.
Side effects:
On successful completion of the call to $ACK_
EVENT, the RM participant is removed from the
transaction, the transaction is ended, and the
ASTLM quota consumed by the call to $JOIN_RM or
$ACK_EVENT that added the RM participant to the
transaction is returned.
DECdtm also allows the call to $END_TRANS to
complete (necessary and sufficient condition).
Table SYS-6 Replies to a Prepare Event Report (DDTM$K_PREPARE)
report_
reply Vote Meaning
SS$_FORGET Yes This is called a read-only vote. It is an
optimization that allows an RM participant
to vote "yes" and not receive a commit or abort
event report.
Side effects:
On successful completion of the call to $ACK_
EVENT, the RM participant is removed from the
transaction, and the ASTLM quota consumed by
the call to $JOIN_RM or $ACK_EVENT that added
it to the transaction is returned.
SS$_ Yes The RM participant can either commit or
PREPARED abort the operations of the transaction, and
guarantees that it will abide by the DECdtm
transaction manager's decision on whether the
transaction (and therefore these operations)
are committed or aborted. In other words, the
RM participant guarantees that the behavior
of its resources will never be inconsistent
with that decision, insofar as that behavior is
detected by any transactions that commit.
A recoverable resource manager must not give
this vote until it has safely stored enough
information to be able to keep this guarantee
even if there is a recoverable failure, caused,
for example, by a node crash.
The DECdtm transaction manager will decide
the outcome of the transaction, then inform
the resource manager of the decision with a
commit or abort event report delivered to the
RM participant (assuming that it is associated
with an RMI that requested these event reports)
or, in the event of a failure, using the
resource manager's recovery mechanism.
SS$_VETO No RM participant requires that the transaction
be aborted. The reason argument gives the
reason why the RM participant is aborting the
transaction.
The RM participant guarantees that the effects
of its transaction operations will never be
detected by any transaction that commits.
Side effects:
The DECdtm transaction manager will deliver an
abort event report for the transaction to the
RM participant.
Table SYS-7 Replies to a Default Transaction Started Event Report
(DDTM$K_STARTED_DEFAULT)
report_
reply Description
SS$_NORMAL Adds a new RM participant running in the calling
process to the transaction to which a new branch is
being added. The new RM participant is associated
with the RMI to which the default transaction started
event was reported. The part_name and rm_context
arguments specify the name of the new RM participant
and its context.
Side effects:
The postconditions on successful completion of the
call to $ACK_EVENT are the same as those for $JOIN_
RM.
DECdtm also allows the call to $START_TRANS or
$START_BRANCH that is adding the new branch to
complete (necessary but not sufficient condition).
That call cannot complete successfully until all
default transaction-started event reports delivered
to RMIs in that process have been acknowledged.
SS$_FORGET Acknowledgment of the event report.
Side effects:
DECdtm allows the call to $START_TRANS or $START_
BRANCH that is adding the new branch to complete
(necessary but not sufficient condition).
That call cannot complete successfully until all
default transaction-started event reports delivered
to RMIs in that process have been acknowledged.
Table SYS-8 Replies to a Nondefault Transaction Started Event
Report (DDTM$K_STARTED_NONDEFAULT)
report_
reply Description
SS$_NORMAL Adds a new RM participant running in the calling
process to the transaction to which a new branch is
being added. The new RM participant is associated
with the RMI to which the nondefault transaction
started event was reported. The part_name and rm_
context arguments specify the name of the new RM
participant and its context.
Side effects:
The postconditions on successful completion of the
call to $ACK_EVENT are the same as those for $JOIN_
RM.
DECdtm also allows the call to $START_TRANS or
$START_BRANCH that is adding the new branch to
complete (necessary but not sufficient condition).
That call cannot complete successfully until all
default transaction-started event reports delivered
to RMIs in that process have been acknowledged.
SS$_FORGET Acknowledgment of the event report.
Side effects:
DECdtm allows the call to $START_TRANS or $START_
BRANCH that is adding the new branch to complete
(necessary but not sufficient condition).
That call cannot complete successfully until all
default transaction-started event reports delivered
to RMIs in that process have been acknowledged.
reason
OpenVMS usage:cond_value
type: longword (unsigned)
access: read only
mechanism: by value
A code that gives the reason why the RM participant is aborting
the transaction.
This argument is ignored unless the value in the report_reply
argument is SS$_VETO and the event being acknowledged is a
prepare or one-phase commit event.
The $DDTMMSGDEF macro defines symbolic names for abort reason
codes described in Abort Reason Codes. The default value for this
argument is DDTM$_VETOED.
Table SYS-9 Abort Reason Codes
Symbolic Name Description
DDTM$_ABORTED Application aborted the transaction without
giving a reason.
DDTM$_COMM_FAIL Transaction aborted because a communications
link failed.
DDTM$_INTEGRITY Transaction aborted because a resource manager
integrity constraint check failed.
DDTM$_LOG_FAIL Transaction aborted because an attempt to
write to the transaction log failed.
DDTM$_ORPHAN_ Transaction aborted because it had an
BRANCH unauthorized branch.
DDTM$_PART_SERIAL Transaction aborted because a resource manager
serialization check failed.
DDTM$_PART_ Transaction aborted because a resource manager
TIMEOUT timeout expired.
DDTM$_SEG_FAIL Transaction aborted because a process or image
terminated.
DDTM$_ Transaction aborted because a serialization
SERIALIZATION check failed.
DDTM$_SYNC_FAIL Transaction aborted because a branch had been
authorized for it but had not been added to
it.
DDTM$_TIMEOUT Transaction aborted because its timeout
expired.
DDTM$_UNKNOWN Transaction aborted; reason unknown.
DDTM$_VETOED Transaction aborted because a resource manager
was unable to commit it.
beftime
OpenVMS usage:utc_date_time
type: octaword (unsigned)
access: read only
mechanism: by reference
Reserved to VSI.
afttime
OpenVMS usage:utc_date_time
type: octaword (unsigned)
access: read only
mechanism: by reference
Reserved to VSI.
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 RM participant that is added to the
transaction by this call to $ACK_EVENT. This argument is ignored
unless the event being acknowledged is of type Transaction
Started and the value of the report_reply argument is SS$_NORMAL.
If this argument is omitted (the default) or its value is zero,
the name of the new RM participant is the same of that of the RMI
with which it is associated.
The string passed in this argument must be no longer than 32
characters.
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 associated with the new RM participant. This argument
is ignored unless the value of the report_reply argument is SS$_
NORMAL, and the event being acknowledged is of type Transaction
Started.
The context of the new RM participant is passed in the event
reports subsequently delivered to that RM participant.
The context is used to pass information specific to the new
RM participant from the main line code into the event handler
specified in the call to $DECLARE_RM that created the RMI with
which the new RM participant is associated.
If this argument is omitted (the default) or is zero, the context
associated with the new RM participant is the same of that of the
RMI with which it is associated.
timout
OpenVMS usage:date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
Reserved to VSI.