Library /sys$common/syshlp/helplib.hlb  —  System Services, $ACK EVENT, 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-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 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.
Close Help