Adds a new branch to a transaction.

    Format

      SYS$START_BRANCH  [efn] ,[flags] ,iosb ,[astadr] ,[astprm]

                        ,tid ,tm_name ,bid [,[timout], [acmode],

                        [tx_class]]

    C Prototype

      int sys$start_branch  (unsigned int efn, unsigned int

                            flags, struct _iosb *iosb, void

                            (*astadr)(__unknown_params), int astprm,

                            unsigned int tid [4], void *tm_name,

                            unsigned int bid [4],...);

1  –  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 $START_BRANCH Option Flags. All undefined
    bits must be 0. If this argument is omitted, no flags are used.

    Table SYS-26 $START_BRANCH Option Flags

    Flag Name          Description

    DDTM$M_BRANCH_     Specifies that the new branch is
    UNSYNCHED          unsynchronized.

                       If this flag is clear, the new branch is
                       synchronized.
    DDTM$M_NONDEFAULT  Set this flag if you do not want the
                       transaction to be the default transaction
                       of the calling process. If this flag is
                       clear, the transaction becomes the default
                       transaction of the calling process.

                       An error is returned if this flag is clear
                       and the calling process has an current default
                       transaction.
    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.

 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.

    To view the I/O status block diagram, see the VSI OpenVMS System
    Services Reference Manual.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure entry mask
    access:       call without stack unwinding
    mechanism:    by reference
    The AST routine 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 $START_BRANCH
    service.

 astprm

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

 tid

    OpenVMS usage:trans_id
    type:         octaword (unsigned)
    access:       read only
    mechanism:    by reference
    The identifier (TID) of the transaction to which the new branch
    will be added.

 tm_name

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    The name of the node on which the call was made to $ADD_BRANCH
    that authorized the new branch to be added to the transaction.
    Note that this cannot be a cluster alias.

    To ensure smooth operation in a mixed-network environment,
    refer to the chapter entitled Managing DECdtm Services in the
    VSI OpenVMS System Manager's Manual, for information on defining
    node names.

 bid

    OpenVMS usage:branch_id
    type:         octaword (unsigned)
    access:       read only
    mechanism:    by reference
    The identifier (BID) of the new branch that is to be added to the
    transaction.

    An BID value of zero is invalid.

 timout

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Reserved to VSI.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    The access mode of the new branch in this process. This is the
    least privileged mode that a caller must be in to remove this
    branch from the transaction by calling $END_BRANCH. Note that it
    can be removed from the transaction by calling $ABORT_TRANS from
    any access mode.

    This argument only influences the access mode of the first branch
    in this process. Subsequent branches have the same access mode
    as the first. The access mode of the new branch is the least
    privileged of:

    o  The access mode of the caller.

    o  The access mode specified by the acmode argument.

    Note that if a branch already exists in this process, then
    neither the access mode of the caller nor the access mode
    specified by the acmode argument may be less privileged than
    that branch.

    The default value of this argument is the access mode of the
    caller.

 tx_class

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    A string that specifies the transaction class for the transaction
    on the local node if the transaction does not already have a
    transaction class on the local node. This string is passed in the
    event reports delivered to Resource Manager identifiers (RMIs)
    and Resource Manager (RM) participants on the local node.

    This argument is ignored if the transaction already has a
    transaction class on the local node.

    This string must be no longer than 31 characters.