Library /sys$common/syshlp/helplib.hlb  —  System Services, $DECLARE RM, Arguments
 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Number of the event flag that is set when the service completes.
    If this argument is omitted, event flag 0 is used.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    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 $DECLARE_RM Option Flags. All undefined bits
    must be 0. If this argument is omitted, no flags are used.

    Table SYS-11 $DECLARE_RM Option Flags

    Flag Name      Description

    DDTM$M_SYNC    Specifies successful synchronous completion 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.
    DDTM$M_        Set this flag for the new RMI to be volatile.
    VOLATILE       With this flag set, the DECdtm transaction manager
                   will not log information about any RM participants
                   associated with the new RMI. Resource managers
                   that never perform recovery should set this flag.

                   If this flag is clear, the new RMI is not
                   volatile. The DECdtm transaction manager will
                   log the following information about each RM
                   participant associated with the new RMI:

                   o  The name of the RM participant.

                   o  The identifier (TID) of the transaction in
                      which it is participating.

                   If this flag is clear and a recoverable failure
                   occurs, such as a system crash, the resource
                   manager can use the $GETDTI system service to
                   query the transaction log to determine the outcome
                   of the transactions in which it was participating
                   before the failure occurred.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    The I/O status block in which the completion status of the
    service is returned as a condition value.

    Refer to the HP OpenVMS System Services Reference Manual to view
    the I/O status block diagram.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure entry mask
    access:       call without stack unwinding
    mechanism:    by reference
    The 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 same access mode as that of the caller of the $DECLARE_RM
    service.

 astprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The AST parameter that is passed to the AST routine specified by
    the astadr argument.

 rm_id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Longword in which the identifier (RM_ID) of the new RMI is
    returned. This identifier is unique within the calling process
    at any time.

 event_handler

    OpenVMS usage:ast_procedure
    type:         procedure entry mask
    access:       call without stack unwinding
    mechanism:    by reference
    The new RMI's event handler. This routine is called to report
    an event to the new RMI or one of its RM participants. The
    event_handler argument is the address of the entry mask of this
    routine. An event handler must be specified.

    This routine is called as an AST delivered by the DECdtm
    transaction manager.

    The AST is executed in the access mode specified by the acmode
    argument. The AST parameter is the address of a DECdtm event
    report block that contains an event report.

    The DECdtm transaction manager reports events to an RMI and the
    RM participants associated with it using ASTs executed in the
    access mode specified in the call to $DECLARE_RM that created
    that RMI.

    The DECdtm transaction manager creates an event report block,
    and passes its address to the AST routine in the parameter of the
    AST. Each event report block contains:

    o  The identifier of the event report.

    o  A code that describes the event.

    o  The identifier (TID) of the transaction.

    o  The name of the RM participant or RMI.

    o  The context of the RM participant or RMI.

    o  Other data that depend on the type of the event.

    Fields in an Event Report Block describes the fields in an event
    report block, in alphabetical order:

    Table SYS-12 Fields in an Event Report Block

    Symbol             Description

    DDTM$A_TID_PTR     Address of the identifier (TID) of the
                       transaction.
    DDTM$L_ABORT_      Abort reason code (longword).
    REASON
                       See the $ACK_EVENT service for a list of
                       possible values. Present only in abort event
                       reports.
    DDTM$L_EVENT_TYPE  A code that identifies the event (longword).
                       The following table lists the possible values:
                       Symbol             Event

                       DDTM$K_ABORT       Abort
                       DDTM$K_COMMIT      Commit
                       DDTM$K_PREPARE     Prepare
                       DDTM$K_ONE_PHASE_  One-phase commit
                       COMMIT
                       DDTM$K_STARTED_    Default transaction started
                       DEFAULT
                       DDTM$K_STARTED_    Nondefault transaction
                       NONDEFAULT         started

    DDTM$L_REPORT_ID   Event report identifier (unsigned longword).
    DDTM$L_RM_CONTEXT  The context of the RM participant or RMI to
                       which the event report is being delivered
                       (unsigned longword).
    DDTM$Q_PART_NAME   The name of the RM participant or RMI to
                       which the event report is being delivered
                       (descriptor).
    DDTM$Q_TX_CLASS    The transaction class of the transaction
                       (descriptor).

    Each event report must be acknowledged by calling $ACK_EVENT,
    specifying the identifier of the report. This acknowledgment need
    not come from AST context.

    The DECdtm transaction manager delivers only one event report
    at a time to each 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.
    Note that the DECdtm transaction manager may deliver multiple
    reports to an RMI.

    After acknowledging the event report, the RMI or RM participant
    should no longer access the event report block.

 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 RMI. This is:

    o  The default name of its RM participants, used when a call to
       $JOIN_RM or $ACK_EVENT that adds one of these RM participants
       to a transaction does not specify the name of the new RM
       participant.

       When an RM participant associated with the new RMI is added to
       a transaction by a call to $JOIN_RM or $ACK_EVENT that has a
       zero part_name argument, then that RM participant inherits its
       name from the RMI. The name of that RM participant is the same
       as the name of the RMI.

    o  The string passed in the participant name field of Transaction
       Started event reports delivered to the new RMI.

    This string must be no longer than 32 characters.

    If this argument is omitted, the name of the new RMI is the null
    string.

    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 of the new RMI. This is:

    o  The default context of its RM participants, used when a
       call to $JOIN_RM or $ACK_EVENT that adds one of these RM
       participants to a transaction does not specify the context
       of the new RM participant.

       When an RM participant associated with the new RMI is added
       to a transaction by a call to $JOIN_RM or $ACK_EVENT that has
       a zero rm_context argument, then that RM participant inherits
       its context from the RMI. The context of that RM participant
       is the same as the context of the RMI.

    o  The string passed in the context field of Transaction Started
       event reports delivered to the new RMI.

    If this argument is omitted, the context of the new RMI is 0.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The access mode of the new RMI. This is:

    o  The access mode at which the ASTs delivered to its event
       handler are to be executed.

    o  The least privileged access mode that the caller must be in
       to call $ACK_EVENT to acknowledge an event report delivered to
       the new RMI or to its RM participants.

    o  The least privileged access mode that the caller must be in to
       delete the new RMI by calling $FORGET_RM.

    o  The least privileged access mode that the caller must be in to
       call $JOIN_RM to add a new RM participant associated with the
       new RMI.

    o  The most privileged access mode of new branches that this RMI
       is interested in, if the event_mask argument requests events
       of type Transaction Started.

       The call to $START_TRANS or $START_BRANCH that adds a new
       branch to a transaction specifies the access mode of that
       transaction within this process. The DECdtm transaction
       manager reports a Transaction Started event to the new RMI
       only if the access mode of the transaction is the same as or
       less privileged than the access mode of the new RMI.

       For example, if the access mode of the new RMI is supervisor,
       it will receive a Transaction Started event when a branch
       of the calling process is added to a transaction only if the
       access mode of that transaction is user or supervisor.

    The access mode of the new RMI is the least privileged of:

    o  The access mode of the caller.

    o  The access mode specified by the acmode argument.

    If this argument is omitted, the access mode of the new RMI is
    the same as the access mode of the caller.

 tm_log_id

    OpenVMS usage:DECnet_uid
    type:         octaword (unsigned)
    access:       write only
    mechanism:    by reference
    The globally unique identifier of the transaction log for the
    local node. This identifier is used during resource manager
    recovery to check that the correct DECdtm transaction manager
    log is used. See $GETDTI for more information.

    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.

 event_mask

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Requests the types of event to be reported to the new RMI and to
    its RM participants. The only type of event that can be reported
    to the new RMI is a Transaction Started event (a default or non-
    default transaction started event). The following types of event
    can be reported to its RM participants:

    o  Abort events

    o  Commit events

    o  One-phase commit events

    o  Prepare events

    The event_mask argument is a longword bit mask that is the
    logical OR of each bit set, where each bit corresponds to an
    event. The $DDTMDEF module defines a symbolic name for each flag
    bit. $DECLARE_RM Event Selection Flags describes the flags. All
    undefined bits must be 0.

    If this argument is omitted, the following events are requested:

    o  Abort events

    o  Commit events

    o  One-phase commit events

    o  Prepare events

    Table SYS-13 $DECLARE_RM Event Selection Flags

    Flag Name      Description

    DDTM$M_EV_     Specifies that abort events are to be reported
    ABORT          to the RM participants associated with the new
                   RMI. If this flag is set, when an abort event
                   occurs for a transaction, the DECdtm transaction
                   manager delivers an abort event report to each RM
                   participant in the transaction that is associated
                   with the new RMI.
    DDTM$M_EV_     Specifies that commit events are to be reported to
    COMMIT         the RM participants associated with the new RMI.

                   If this flag is set, when the DECdtm transaction
                   manager decides that the outcome of a transaction
                   is commit, it delivers a commit event report to
                   each RM participant in the transaction that is
                   associated with the new RMI.
    DDTM$M_EV_     Specifies that prepare events are to be reported
    PREPARE        to the RM participants associated with the new
                   RMI.

                   If this flag is set, when the DECdtm transaction
                   manager initiates the commit protocol (in response
                   to a call to $END_TRANS) to determine the outcome
                   of a transaction, it reports a prepare event to
                   each RM participant in the transaction that is
                   associated with the new RMI.

                   The acknowledgment of a prepare event is a vote on
                   the outcome of the transaction. See $ACK_EVENT for
                   more information.
    DDTM$M_EV_     Specifies that events of type Transaction Started
    TRANS_START    are to be reported to the new RMI. Events of type
                   Transaction Started are:

                   o  Default transaction started events.

                   o  Non-default transaction-started events.

                   If this flag is set, the DECdtm transaction
                   manager will report one of these events to the
                   new RMI whenever a new branch in the calling
                   process is added to a transaction, provided that
                   the access mode of the new branch is not more
                   privileged than the access mode of the new RMI.
                   The acknowledgment of that event report may add
                   a new RM participant associated with the new RMI
                   to that transaction. See the description of the
                   acmode argument for a discussion of access modes.
Close Help