$ABORT_TRANS, or Abort Transaction, is a system service that ends a transaction by aborting it.
The $ABORT_TRANS system service:
- Initiates abort processing for the specified transaction, if it has not already been initiated.
If abort processing has not already been initiated, the DECdtm transaction manager instructs the resource managers to abort (roll back) the transaction operations so that none of those operations ever take effect. It delivers an abort event to each RM participant in the transaction that is associated with an RMI that requested abort events.
- Removes the specified branch from the specified transaction in this process.
Preconditions for the successful completion of $ABORT_TRANS include:
- If the BID is zero, the calling process must have started the transaction.
- If the BID is nonzero, the calling process must contain the specified branch of the specified transaction.
- If the BID is nonzero, the tid argument must not be omitted. If you explicitly pass the BID, you must also explicitly pass the TID.
$ABORT_TRANS may fail for various reasons, including:
- The preconditions were not met.
- There has already been a call to $ABORT_TRANS, $END_TRANS, or $END_BRANCH for the specified branch.
Postconditions on successful completion of $ABORT_TRANS are listed in the following table:
|The transaction is ended.||If DDTM$M_NOWAIT is clear:
|The outcome of the transaction is abort.||None of the operations of the transaction will ever take effect.|
|DECdtm quotas are returned.||If DDTM$M_NOWAIT is clear, all quotas allocated for the transaction by calls on the local node to DECdtm services are now returned.|
|The transaction is not the default transaction of the calling process.||If DDTM$M_NOWAIT is clear, then, if the transaction was the default transaction of the calling process, it is now no longer the default.|
$ABORT_TRANS will not complete successfully (that is, the event flag will not be set, the AST routine will not be called, and the I/O status block will not be filled in) until all branches on the local node have been removed from the transaction.
Thus this call to $ABORT_TRANS cannot complete successfully until every authorized and synchronized branch on the local node has initiated a call to $END_TRANS, $END_BRANCH, or $ABORT_TRANS.
$ABORT_TRANS must deliver notification ASTs to resource managers participating in the transaction. Therefore it will not complete successfully while the calling process is either:
- In an access mode that is more privileged than the DECdtm calls made by any resource manager participating in the transaction. RMS journaling calls DECdtm in executive mode. Oracle Rdb and Oracle CODASYL DBMS call DECdtm in user mode.
- At AST level in the same access mode as the least privileged DECdtm calls made by any resource manager participating in the transaction.
For example, if Oracle Rdb is a participant in the transaction, $ABORT_TRANS will not complete successfully while the calling process is in supervisor, executive, or kernel mode, or while the calling process is at AST level.
Note that successful completion of $ABORT_TRANS is not indefinitely postponed by network failure.
int sys$abort_trans (unsigned int efn, unsigned int flags, struct _iosb *iosb,...);
Number of the event flag that is set when the service completes. If this argument is omitted, event flag 0 is used.
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 the table below. All undefined bits must be 0. If this argument is omitted, no flags are used.
|DDTM$M_NOWAIT||Set this flag to indicate that the service should return to the caller without waiting for final cleanup. Note that $ABORT_TRANSW with the DDTM$M_NOWAIT flag set is not equivalent to $ABORT_TRANS. $ABORT_TRANS returns when the operation has been queued. The former does not return until the operation has been initiated. The latter returns as soon as the operation
has been queued. The full range of status values may be returned from a nowait call.
|DDTM$M_SYNC||Set this flag to specify that successful synchronous completion is to be indicated 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.|
I/O status block in which the following information is returned:
- The completion status of the service, returned as a condition value. See the Condition Values Returned section.
- An abort reason code that gives one reason why the transaction aborted, if the completion status of the service is SS$_NORMAL.
Note that, if there are multiple reasons why the transaction aborted, the abort reason code returned in the I/O status block might not be the same as the abort reason code passed in the reason argument. The DECdtm transaction manager returns one of the reasons in the I/O status block. It may return different reasons to different branches of the transaction.
For example, if the call to $ABORT_TRANS gives DDTM$_ABORTED as the reason and the transaction timeout expires at about the same time as the call to $ABORT_TRANS, then either the DDTM$_TIMEOUT or DDTM$_ABORTED reason code can be returned in the I/O status block.
The $DDTMMSGDEF macro defines symbolic names for abort reason codes, which are defined in the following table:
|DDTM$_ABORTED||The application aborted the transaction without giving a reason.|
|DDTM$_COMM_FAIL||A communications link failed.|
|DDTM$_INTEGRITY||A resource manager integrity constraint check failed.|
|DDTM$_LOG_FAIL||A write operation to the transaction log failed.|
|DDTM$_ORPHAN_BRANCH||An unauthorized branch caused failure.|
|DDTM$_PART_SERIAL||A resource manager serialization check failed.|
|DDTM$_PART_TIMEOUT||The timeout specified by a resource manager expired.|
|DDTM$_SEG_FAIL||A process or image terminated.|
|DDTM$_SERIALIZATION||A DECdtm transaction manager serialization check failed.|
|DDTM$_SYNC_FAIL||The transaction was not globally synchronized; an authorized branch was not added to the transaction.|
|DDTM$_TIMEOUT||The timeout specified on $START_TRANS expired.|
|DDTM$_UNKNOWN||The reason is unknown.|
|DDTM$_VETOED||A resource manager was unable to commit the transaction.|
|Access:||call without stack unwinding|
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 access mode of the caller.
AST parameter that is passed to the AST routine specified by the astadr argument.
Identifier of the transaction to be aborted. If this argument is omitted, $ABORT_TRANS aborts the default transaction of the calling process.
Code that gives the reason why the application is aborting the transaction. The $DDTMMSGDEF macro defines symbolic names for abort reason codes. The codes currently defined are listed in this table.
The default value for this argument is DDTM$_ABORTED.
The identifier (BID) of the branch that is aborting the transaction. The default value of this argument is zero, which is the BID of the branch that started the transaction.
Condition Values Returned
|SS$_NORMAL||If this was returned in R0, the request was successfully queued. If it was returned in the I/O status block, the service completed successfully.|
|SS$_SYNCH||The service completed successfully and synchronously (returned only if the DDTM$M_SYNC flag is set).|
|SS$_ACCVIO||An argument was not accessible by the caller.|
|SS$_BADPARAM||The options flags were invalid or the tid argument was omitted and the bid argument was not zero.|
|SS$_BADREASON||The abort reason code was invalid.|
|SS$_CURTIDCHANGE||The tid argument was omitted and a call to change the default transaction of the calling process was in progress.|
|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$_NOCURTID||An attempt was made to abort the default transaction (the tid argument was omitted), but the calling process did not have a default transaction.|
|SS$_NOLOG||The local node did not have a transaction log.|
|SS$_NOSUCHBID||The calling process did not contain the branch identified by the BID passed in the bid argument (possibly because there has already been a call to $ABORT_TRANS, $END_TRANS, or $END_BRANCH for that branch).
This error is returned only if the bid argument is not zero.
|SS$_NOSUCHID||A transaction with the specified transaction identifier does not exist.|
|SS$_NOTORIGIN||A bid of zero was specified and the calling process did not start the transaction.|
|SS$_TPDISABLED||The TP_SERVER process was not running on the local node.|
|SS$_WRONGSTATE||Commit processing for the transaction had already started. This can occur if bid is zero or the specified branch was unsynchronized.|