$ACK EVENT

From VSI OpenVMS Wiki
Jump to: navigation, search

$ACK_EVENT, or Acknowledge Event, is a system service that acknowledges an event reported to a Resource Manager (RM) participant or Resource Manager instance (RMI).

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

Syntax

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 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".

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.

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.

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 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).

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.

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.

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 ransaction. 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 SYS1–10. The default value for this argument is DDTM$_VETOED.

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 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 OpenVMS System Manager's Manual Vol. I, 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.

Required Privileges

None

Required Quotas

None

Condition Values Returned

Value Description
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$_EXASTL 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.

See also

Retrieved from "https://wiki.vmssoftware.com/index.php?title=$ACK_EVENT&oldid=1556"