Starts a new transaction.

    Format

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

                       ,[tid] ,[timout] ,[acmode] ,[tx_class]]

    C Prototype

      int sys$start_trans  (unsigned int efn, unsigned int flags,

                           struct _iosb *iosb,...);

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

    Table SYS-27 $START_TRANS Option Flags

    Flag                Description

    DDTM$M_NONDEFAULT   Set this flag if you do not want the new
                        transaction to be the default transaction of
                        the calling process. An error is returned if
                        this flag is set and the tid argument is zero
                        or omitted.

                        If this flag is clear, the new transaction
                        becomes the default transaction of the
                        calling process. An error is returned if
                        this flag is clear and the calling process
                        already has a default transaction.

    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.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    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
    AST routine that is executed when the service completes if SS$_
    NORMAL is returned in R0. The astadr argument is the address of
    this routine. This routine is executed in the same access mode of
    the caller of the $START_TRANS service.

 astprm

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

 tid

    OpenVMS usage:trans_id
    type:         octaword (unsigned)
    access:       write only
    mechanism:    by reference
    Address of an octaword in which the service returns the
    identifier (TID) of the new transaction.

    No other call to $START_TRANS on any node ever returns the same
    TID value.

    The default value of this argument is zero. An error is returned
    if the DDTM$M_NONDEFAULT flag is set and this argument is either
    omitted or zero.

 timout

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference
    Timeout for the new transaction. This is the time at which the
    DECdtm transaction manager is to abort the transaction if the
    transaction has not already committed.

    A positive time value specifies an absolute time. The absolute
    value of a negative time specifies an offset (delta time) from
    the current time.

    The transaction is aborted at the next timer interval if you
    specify either a zero time value or any time in the past. If this
    argument is omitted, the new transaction has no timeout.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    An access mode of the new branch of the new transaction.

    An access mode is maintained for each transaction per process.
    All branches in a transaction in a process have the same access
    mode. Subsequent operations do not alter it. The access mode of a
    branch is the least privileged mode in which a successful call to
    $END_TRANS may be made.

    Note that the transaction may be aborted by a call to $ABORT_
    TRANS from any access mode.

    The access mode of the branch is the least privileged of the
    following:

    o  The access mode of the caller

    o  The access mode specified by the acmode argument

    If the acmode argument is omitted, the access mode of the new
    branch is the same as that 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 new
    transaction on the local node. This string is passed in the event
    reports delivered to RMIs and RM participants on the local node.

    This string must be no longer than 31 characters. If this
    argument is omitted or the string is of length zero, the new
    transaction has no transaction class on the local node. In this
    case, the class of the transaction on the local node can be
    specified by a subsequent call to $START_BRANCH on that node.