HP OpenVMS Systems Documentation

HP OpenVMS System Services Reference Manual

The new branch should have been previously authorized. Authorization is
provided either by a matching call to $JOIN_RM with the
DDTM$M_COORDINATOR flag set or by a matching call to $ADD_BRANCH. Two
calls, one to $ADD_BRANCH and one to $START_BRANCH or one to $JOIN_RM
and one to $START_BRANCH, are said to be matching when the following
conditions are true:

The same TID values are passed to both calls.

The BID returned by the call to $ADD_BRANCH or $JOIN_RM is the same
as that passed to the call to $START_BRANCH.

The call to $START_BRANCH is made on the node identified by the
tm_name argument passed to the call to $ADD_BRANCH or
on the node on which the call to $JOIN_RM was made.

The call to $ADD_BRANCH or $JOIN_RM is made on the node identified
by the tm_name argument passed to the call to
$START_BRANCH.

$START_BRANCH does not check that there has been a matching call to
$ADD_BRANCH or $JOIN_RM unless the tm_name argument
passed to $START_BRANCH specifies the local node.

Note

The atomicity of the transaction is not guaranteed if there is a call
to $START_BRANCH that does not have a matching call to $ADD_BRANCH or
$JOIN_RM.

Preconditions for the successful completion of $START_BRANCH are:

The local node must have a DECdtm transaction log.

The TP_SERVER process must be running on the local node.

There must not have been a successful call to $START_BRANCH on the
local node that passed the specified BID.

If the tm_name argument specifies the local node,
there must have been a matching call to $ADD_BRANCH or $JOIN_RM on the
local node.

If the DDTM$M_NONDEFAULT flag is clear, the calling process must
not have an unended default transaction.

If this process already contains a branch of this transaction, then
the access mode of the caller must be the same as or more privileged
than the access mode of that branch.

$START_BRANCH may fail because:

Preconditions were not met.

An abort event occurred for the transaction.

A call to $END_TRANS to end the transaction is in progress and it
is too late to add a new branch to the transaction.

The DDTM$M_NONDEFAULT flag was clear and a call to
$SET_DEFAULT_TRANS by the calling process is in progress.

When $START_BRANCH completes successfully:

A new branch running in the calling process has been added to the
transaction.

All Transaction Started events reported to RMIs in the calling
process have been acknowledged.

If the DDTM$M_NONDEFAULT flag was clear, the transaction is the
default transaction of the calling process.

A branch may:

Invoke resource manager operations, explicitly passing the TID.

Invoke resource manager operations without specifying the TID, if
the transaction is the default transaction of the calling process, and
the resource manager supports default transactions.

Call $ADD_BRANCH to authorize another branch to be added to the
transaction.

(The way to invoke a resource manager operation is defined by the
interfaces provided by the resource manager; see the resource manager
documentation.)

A synchronized branch is removed from the transaction by calling
$END_BRANCH, specifying the appropriate BID and TID. An unsynchronized
branch is removed from the transaction by DECdtm during commit or abort
processing.

The branch is also removed from the transaction (and the transaction
aborted):

On termination of the current image or process.

On successful completion of a call to $ABORT_TRANS in the calling
process that passes the appropriate TID and BID.

C Prototype

Arguments

efn

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 Table SYS-57. All undefined bits must be
0. If this argument is omitted, no flags are used.

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. See the Condition Values Returned
section.

The following diagram shows the structure of the I/O status block:

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:

The access mode of the caller

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.

Description

The $START_TRANS system service starts a new transaction whose commit
or abort processing is to be coordinated by the local DECdtm
transaction manager. The service:

Adds a branch running in the calling process to the new
transaction. The identifier (BID) of the new branch is 0.

Sets the default transaction of the calling process to the new
transaction, if the DDTM$M_NONDEFAULT flag is clear and the process
does not have a default transaction.

Delivers an event of type Transaction Started to each RMI in the
calling process that requested Transaction Started events and has an
access mode that is the same as or more privileged than that specified
in this call to $START_TRANS. See the description of the
acmode argument.

The event delivered to all such RMIs is either a default
transaction-started event or a nondefault transaction-started event,
depending on whether the DDTM$M_NONDEFAULT flag is clear or not.

Preconditions for the successful completion of $START_TRANS are:

The local node must have a DECdtm transaction log.

The TP_SERVER process must be running on the local node.

If the DDTM$M_NONDEFAULT flag is clear, the calling process must
not have an unended default transaction.

$START_TRANS may fail for various reasons including:

Preconditions were not met.

The DDTM$M_NONDEFAULT flag was clear and a call to
$SET_DEFAULT_TRANS by the calling process is in progress.

When $START_TRANS completes successfully:

A new transaction has started, with a unique identifier.

The transaction has a single branch, with a BID of 0.

All Transaction Started events reported to RMIs in the calling
process have been acknowledged.

If the DDTM$M_NONDEFAULT flag was clear, the transaction is the
default transaction of the calling process.

A branch may:

Invoke resource manager operations, explicitly passing the TID.

Invoke resource manager operations without specifying the TID, if
the transaction is the default transaction of the calling process, and
the resource manager supports default transactions.

Call $ADD_BRANCH to authorize another branch to be added to the
transaction.

(The way to invoke a resource manager operation is defined by the
interfaces provided by the resource manager. For additional
information, see the resource manager documentation.)

DECdtm cannot commit the transaction until the process calls $END_TRANS.

The transaction is aborted:

On termination of the current image or process.

On successful completion of a call to $ABORT_TRANS in the calling
process, specifying a BID of 0.