 |
HP OpenVMS System Services Reference Manual
$ABORT_TRANSW
Ends a transaction by aborting it.
$ABORT_TRANSW always waits for the request to complete before returning
to the caller. Other than this, it is identical to $ABORT_TRANS.
Do not call $ABORT_TRANSW from AST level, or from an access mode that
is more privileged than the DECdtm calls made by any resource manager
participant in the transaction. If you do, the $ABORT_TRANSW service
will wait indefinitely.
Format
SYS$ABORT_TRANSW [efn] ,[flags] ,iosb [,[astadr] ,[astprm] ,[tid]
,[reason] ,[bid]]
C Prototype
int sys$abort_transw (unsigned int efn, unsigned int flags, struct
_iosb *iosb,...);
$ACK_EVENT
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,...);
Arguments
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Reserved to HP. 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-4 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-5 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:
- Completed the commit processing for its transaction operations.
- 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$_REMEMBER
|
The RM participant requires that the DECdtm 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-6 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$_PREPARED
|
Yes
|
RM participant decided not to accept the 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-7 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$_PREPARED
|
Yes
|
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. 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-8 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-9 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 Table SYS-10. The default value for this argument is
DDTM$_VETOED.
Table SYS-10 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_BRANCH
|
Transaction aborted because it had an unauthorized branch.
|
|
DDTM$_PART_SERIAL
|
Transaction aborted because a resource manager serialization check
failed.
|
|
DDTM$_PART_TIMEOUT
|
Transaction aborted because a resource manager timeout expired.
|
|
DDTM$_SEG_FAIL
|
Transaction aborted because a process or image terminated.
|
|
DDTM$_SERIALIZATION
|
Transaction aborted because a 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 HP.
afttime
| OpenVMS usage: |
utc_date_time |
| type: |
octaword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Reserved to HP.
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 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 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 HP.
Description
The $ACK_EVENT system service:
- Acknowledges an event report delivered by the DECdtm transaction
manager to an RM participant or RMI in the calling process.
Every
event report delivered by the DECdtm transaction manager to an RM
participant or RMI must be acknowledged by a call to $ACK_EVENT
specifying the identifier of the event report. This acknowledgment need
not come from AST context. The caller of $ACK_EVENT must be in the same
access mode as, or a more privileged access mode than, that in which
the event handler AST was delivered.
The DECdtm transaction manager
may deliver multiple event reports to an RMI, but delivers only one
event report at a time to an 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.
After acknowledging
the event report, the RMI or RM participant should no longer access the
event report block.
- Adds a new RM participant to a transaction, if the event being
acknowledged is of type Transaction Started and the value of the
report_reply argument is SS$_NORMAL.
Note that the
new RM participant cannot be the coordinator of the transaction.
- Removes an RM participant from a transaction if the event being
acknowledged is one of the events listed in the following table and the
report_reply argument is as listed in this table:
| Event |
report_reply |
|
Abort
|
SS$_FORGET
|
|
Commit
|
SS$_FORGET or SS$_REMEMBER
|
|
Prepare
|
SS$_FORGET or SS$_VETO
|
|
One-phase commit
|
SS$_NORMAL or SS$_VETO
|
Required Privileges
None
Required Quotas
None
Related Services
$ABORT_TRANS, $ABORT_TRANSW, $ADD_BRANCH, $ADD_BRANCHW, $CREATE_UID,
$DECLARE_RM, $DECLARE_RMW, $END_BRANCH, $END_BRANCHW, $END_TRANS,
$END_TRANSW, $FORGET_RM, $FORGET_RMW, $GETDTI, $GETDTIW,
$GET_DEFAULT_TRANS, $JOIN_RM, $JOIN_RMW, $SETDTI, $SETDTIW,
$SET_DEFAULT_TRANS, $SET_DEFAULT_TRANSW, $START_BRANCH, $START_BRANCHW,
$START_TRANS, $START_TRANSW, $TRANS_EVENT, $TRANS_EVENTW
Condition Values Returned
|
SS$_NORMAL
|
The request was successful.
|
|
SS$_ACCVIO
|
An argument was not accessible to the caller.
|
|
SS$_BADPARAM
|
Either the options flags were invalid, or the reply passed in the
report_reply argument was invalid for the type of
event being acknowledged.
|
|
SS$_BADREASON
|
The abort reason code passed in the
reason argument was invalid.
|
|
SS$_EXASTLM
|
The process AST limit (ASTLM) was exceeded.
|
|
SS$_ILLEFC
|
The event flag number was invalid.
|
|
SS$_INSFARGS
|
A required argument was missing.
|
|
SS$_INSFMEM
|
There was insufficient system dynamic memory for the operation.
|
|
SS$_INVBUFLEN
|
The string passed in the
part_name argument was too long.
|
|
SS$_NOSUCHREPORT
|
Either an event report with the specified report identifier had not
been delivered to any RM participant or RMI in the calling process, or
that event report had already been acknowledged.
|
|
SS$_WRONGACMODE
|
The caller was in a less privileged access mode than that of the RMI
whose event handler was used to deliver the event report that is being
acknowledged by this call to $ACK_EVENT.
|
|
