Initiates a group of statements that Rdb/VMS executes as a unit.  A
 transaction ends with a COMMIT or ROLLBACK statement.  If you end the
 transaction with the COMMIT statement, all the statements within the
 transaction execute.  If you end the transaction with ROLLBACK, none
 of the statements takes effect.

 If an application starts a distributed transaction by explicitly
 calling the DEC/dtm system service SYS$START_TRANS, it must complete
 the transaction by calling the DEC/dtm SYS$END_TRANS or
 SYS$ABORT_TRANS system service.


 Examples:

      Read-only --  START_TRANSACTION READ_ONLY

      Read/write -- START_TRANSACTION READ_WRITE RESERVING -
                       JOB_HISTORY FOR PROTECTED WRITE, -
                       SALARY_HISTORY FOR EXCLUSIVE WRITE -
                     WAIT -
                     EVALUATING JOB_CODE_EXISTS AT VERB_TIME

      Batch-update - START_TRANSACTION BATCH_UPDATE

Additional information available:

MoreMultiple Database AccessFormatExamples

 If you have invoked a database, you have the necessary privileges to
 use the START_TRANSACTION statement.

 If you issue a data manipulation statement without issuing
 START_TRANSACTION first, Rdb/VMS automatically starts a transaction
 for you, using the READ_ONLY option.  Thus, you can perform simple
 data retrieval without starting a transaction explicitly.

 If you issue a data manipulation statement, such as GET or PRINT, and
 then try to use START_TRANSACTION, you may get an error message
 warning you that a transaction is already in progress.  To solve this
 problem, always issue an explicit START_TRANSACTION statement when
 you plan to perform more than one operation.

 You must have the DISTRIBTRAN database access right to a database to
 run a two-phase commit transaction on that database.

 You can use different share and access modes in the START_TRANSACTION
 statement when you intend to access more than one database in your
 application.  To use this feature, you must specify a database handle
 for each database you invoke.  For example, your application can
 access any relation in one database using the read-only transaction
 to check certain data values while it updates relations in another
 database using the read/write transaction.

 Note that any START_TRANSACTION statements already contained in your
 application programs will continue to execute normally.

 Because the read-only transaction uses a snapshot version of the
 database, you might encounter inconsistencies in the data your
 application retrieves.  Therefore, if your program accesses one
 database using read-only, another transaction using read/write might
 update a relation in the database file itself.  The data your program
 reads from the snapshot file represents a before-image of the record
 the other program is updating.  If you require absolute data
 consistency for certain update applications, you should specify the
 read/write transaction mode for both databases and permit others to
 read one of the databases by including the SHARED READ reserving
 option.  In this way, you maintain data consistency during updates
 while permitting concurrent data retrieval from the database your
 program reads.

 Before you can use the multiple database feature of the
 START_TRANSACTION statement, you must issue an INVOKE statement for
 each database you intend to access.  The INVOKE statement must
 include a database handle.  For example, the following INVOKE
 statements identify two databases required by an update application.

 &RDB&  INVOKE DATABASE DB1 = FILENAME 'PERSONAL$DISK:PERSONNEL'
 &RDB&  INVOKE DATABASE DB2 = FILENAME 'PERSONAL$DISK:BENEFITS'

 Because the program only needs to read the EMPLOYEES relation of the
 PERSONNEL database (DB1), but needs to change values in two
 relations, TUITION and STATUS of the BENEFITS dtabase (DB2), the
 update program might contain the following START_TRANSACTION
 statement:

 &RDB&  START_TRANSACTION
 &RDB&   ON DB1 USING
 &RDB&    (READ_ONLY
 &RDB&       RESERVING EMPLOYEES FOR SHARED READ) AND
 &RDB&   ON DB2 USING
 &RDB&    (READ_WRITE
 &RDB&       RESERVING TUITION FOR SHARED WRITE
 &RDB&                 STATUS  FOR SHARED WRITE)

 If you refer to more than one Rdb/VMS database for actual update
 operations within one transaction, use a distributed transaction.

 For complete information on distributed transactions, see the VAX
 Rdb/VMS Guide to Distributed Transactions.

 STARTTRANSACTION ─┬────────────────────>──────────────────┬─┐
                    └─> ( ──> 
T
R
A
N
S
A
C
T
I
O
N
H
A
N
D
L
E var ──> ) ─┘ │
  ┌───────────────────────────────<───────────────────────────┘
  └┬────────────────>────────────────┬─┬───────>────────┬─┐
   └─> distributed-transaction-flag ─┘ ├─> tx-options ──┤ │
                                       └─> on-clause ───┘ │
  ┌───────────────────────────────────────────────────────┘
  └──┬────────>───────┬──>
     └──> on-error ───┘

Additional information available:

TRANSACTION_HANDLE

distributed-transaction-flagtx-optionson-clauseon-error

 A keyword followed by a host language variable.  A transaction handle
 identifies each instance of a database attach.  If you do not declare
 the transaction handle explicitly, Rdb/VMS attaches an internal
 identifier to the transaction.

 If you specify a transaction handle on a START_TRANSACTION statement,
 you must also specify the transaction handle on any COMMIT, FOR,
 ROLLBACK, START_STREAM, and STORE statements that relate to the
 transaction.

 You can specify this clause only once within a single
 START_TRANSACTION statement.

 In Callable RDO, use !VAL as a marker for host language variables.

 Normally, you do not need to use this argument.  The ability to
 declare a transaction handle is provided for compatibility with other
 database products and future releases of Rdb/VMS.

 Do not use this argument in interactive RDO.

 distributed-transaction-flag =

 ─> 
D
I
S
T
R
I
B
U
T
E
D
T
R
A
N
S
A
C
T
I
O
N ─┬───────────────────>───────────────┬─>
                             └> 
D
I
S
T
R
I
B
U
T
E
D
T
I
D distributed-tid ─┘

Additional information available:

DISTRIBUTED_TRANSACTIONDISTRIBUTED_TID

 A distributed transaction is a transaction that uses more than one
 database handle.  Examples of a distributed transaction include:


  o  a transaction that attaches more than once to a single Rdb/VMS
     database

  o  a transaction that attaches to two or more Rdb/VMS databases

  o  a transaction that attaches to more than one database management
     system (an Rdb/VMS database and a VAX DBMS database, for example)


 Distributed transactions are managed by the DECdtm services.  DECdtm
 services assigns a unique distributed transaction identifier
 (distributed TID) to each distributed transaction when the
 distributed transaction is started.

 Use the DISTRIBUTED_TRANSACTION keyword by itself (without the
 DISTRIBUTED_TID distributed-tid clause) when you want to start a
 distributed transaction.

 For complete information on distributed transactions, see the VAX
 Rdb/VMS Guide to Distributed Transactions.

 A keyword followed by a host language variable (distributed-tid) in
 application programs.  When you want the transaction you are starting
 to join a distributed transaction, use this clause to specify the
 distributed TID of the distributed transaction that you want your
 transaction to join.

 The distributed-tid is a host language variable.  You use the
 distributed-tid variable to hold the value of the distributed TID
 that DECdtm services generates and returns to the application.
 DECdtm services uses the distributed TID to distinguish the databases
 involved in a particular distributed transaction.

 Note that if you want to start a distributed transaction, you should
 use only the DISTRIBUTED_TRANSACTION clause.  However, if you want
 your application to start a transaction that will join a distributed
 transaction, then you must use both the DISTRIBUTED_TRANSACTION
 clause and the DISTRIBUTED_TID distributed-tid clause.

 Your application must explicitly call the SYS$START_TRANS system
 service and you must specify the DISTRIBUTED_TID distributed-tid
 clause if you want the transaction you are starting to join a
 distributed transaction.  The distributed-tid variable is an octaword
 (16 bytes) that you should declare and initialize to zero at the
 beginning of your application.

 Do not use the DISTRIBUTED_TID clause in interactive RDO.  It is
 valid only in RDBPRE and Callable RDO.

 For complete information on distributed transactions, see the VAX
 Rdb/VMS Guide to Distributed Transactions.

 tx-options =

 ─┬──> 
B
A
T
C
H
U
P
D
A
T
E ───────────>────────────────────────────────────┬>
  └┬──────────────────┬─┬──────>──────┬─┬──────────────────┬─┐      │
   ├─> 
R
E
A
D
O
N
L
Y    ──┤ ├─> 
W
A
I
T ─────┤ ├──> 
C
O
N
C
U
R
R
E
N
C
Y ──┤ │      │
   └─> 
R
E
A
D
W
R
I
T
E   ──┘ └─> 
N
O
W
A
I
T ───┘ └──> 
C
O
N
S
I
S
T
E
N
C
Y ──┘ │      │
  ┌────────────────────────────<─────────────────────────────┘      │
  └┬─────────────────>───────────────────────┬─┐                    │
   └─> 
E
V
A
L
U
A
T
I
N
G ─┬─> evaluating-clause ──┬─┘ │                    │
                   └──────── , <───────────┘   │                    │
  ┌─────────────────────────<──────────────────┘                    │
  └┬─────────────────────────────>─────────────────────────────────┬┘
   └─> 
R
E
S
E
R
V
I
N
G ─┬─> reserving-clause ─┬─┬───────────>───────────┬┘
                  └──────── , <─────────┘ ├─> 
W
I
T
H 
A
U
T
O
L
O
C
K
I
N
G ──┤
                                          └─> 
W
I
T
H 
N
O
A
U
T
O
L
O
C
K
I
N
G ┘

Additional information available:

BATCH_UPDATEREAD_ONLYREAD_WRITEWAIT_NOWAIT
CONSISTENCY_CONCURRENCYAUTO_LOCKING

evaluating-clausereserving-clause

 Before you begin a batch-update transaction in your programs, you
 should create a backup copy of the database.

 You can reduce overhead in large, initial load operations by using
 the BATCH_UPDATE option.  To speed update operations, Rdb/VMS does
 not write to the process' recovery-unit journal (RUJ) file in the
 batch-update transaction.  Therefore, you cannot explicitly roll back
 a batch-update transaction with a ROLLBACK statement.  If Rdb/VMS
 attempts to perform an automatic rollback due to any error (for
 example, a constraint condition is violated) that you do not trap in
 your program, the transaction fails and your database is permanently
 corrupted (because no RUJ file exists).  You must then re-create the
 database from the backup copy you created prior to starting the
 batch-update transaction.  After you have corrected the error
 condition, you can restart the program from the beginning.

 For critical information on the hazards of batch-update transactions,
 read the START TRANSACTION statement's section on batch-update
 transactions in the VAX Rdb/VMS RDO and RMU Reference Manual.

 If you start a read-only transaction, you can retrieve a snapshot of
 the database at the moment the transaction started.  Other users can
 update records in the relation you are using, but your transaction
 retrieves the records as they existed at the time the transaction
 started.  Any changes that other users make and commit during the
 transaction are invisible to you.  A read-only transaction lets you
 read data without incurring the overhead of record locking.  You
 cannot modify, store, or erase records or execute data definition
 statements in a read-only transaction.

 Signals that you want to use the locking mechanisms of Rdb/VMS to get
 consistency in data retrieval and update.  Use a read/write
 transaction mode when you need to:

  o  Store, modify, or erase data
  o  Retrieve data that is guaranteed to be correct at the moment of
     retrieval
  o  Use Rdb/VMS data definition statements

 Determines what your transaction does when it encounters a locked
 record:

  o  If you specify WAIT, the transaction waits for others to complete
     and then proceeds.  WAIT is the default.
  o  If you specify NOWAIT, your transaction returns an error message
     when it encounters a locked record.

 The extent to which the database protects the consistency of your
 data.  In Rdb/VMS, this distinction is not meaningful.  Rdb/VMS
 always guarantees degree 3 consistency.  Degree 3 consistency means
 that the database system guarantees that data you have read will not
 be changed by another user before you issue a COMMIT statement.

 In other database systems that you might want to access using the
 remote feature of Rdb/VMS, this option specifies the degree to which
 you want to control the consistency of the database.  In such
 systems, the CONCURRENCY option sacrifices some consistency
 protection for improved performance with many users.

 The default for Rdb/VMS is CONSISTENCY.

 This feature is provided for compatibility with other Digital
 Equipment Corporation database products.  If you use the CONCURRENCY
 option, you may be able to transport your programs to another system
 that takes advantage of that option and achieve improved performance.

 evaluating-clause =

 ─┬────────────────┬──> constraint ──> 
A
T ──┬─> 
V
E
R
B
T
I
M
E ───┬─>
  └─> db-handle . ─┘                        └─> 
C
O
M
M
I
T
T
I
M
E ─┘

Additional information available:

Options

   VERB_TIME     When the data manipulation statement is issued
   (default)

   COMMIT_TIME   When the COMMIT statement executes

   db-handle     A database handle (for multiple databases)

 reserving-clause =

 ──┬─┬────────>────────────┬─┬─> relation-name ──┬─┬───┐
   │ └─> db-handle ──> . ──┘ └─> view-name ──────┘ │   │
   └────────────────── , <─────────────────────────┘   │
                                                       │
   ┌─────────────────────<─────────────────────────────┘
   └─> 
F
O
R ───┬────────>─────────┬────┬──> 
R
E
A
D ───┬───>
              ├──> 
E
X
C
L
U
S
I
V
E ────┤    └──> 
W
R
I
T
E ──┘
              ├──> 
P
R
O
T
E
C
T
E
D ────┤
              └──> 
S
H
A
R
E
D ───────┘

Additional information available:

MoreOptions

 The list of relations to be locked during the transaction.  In
 general, include all the relations your transaction will access.  If
 you specify the AUTO LOCKING clause, constraints and triggers defined
 on the reserved relations will be able to access additional relations
 that do not appear in the list of reserved relations.

 Note that if you use the RESERVING clause without the AUTO LOCKING
 clause, you can access only those relations that you have explicitly
 reserved.

    Option       Access Constraints

  SHARED        Other users can work with the same relations as you.
                Depending on the option they choose, they can have
                read-only or read and write access to the relations.

  PROTECTED     Other users can read the relations you are using.
                They cannot have WRITE access.

  EXCLUSIVE     Other users cannot read records from the relations
                included in your transaction.  If another user refers
                to the same relation in a START_TRANSACTION statement,
                Rdb/VMS denies access to that user.

  READ          You will only read data from the relations.

  WRITE         You will store, modify, or erase data in the
                relations.

 An optional clause that can be specified with the RESERVING clause.
 When you specify the WITH AUTO_LOCKING clause, Rdb/VMS automatically
 locks any relations referenced from constraints and triggers defined
 on the reserved relations when the referenced relations are accessed
 from the constraints or triggers.  If one of these referenced
 relations is also a reserved relation, the explicitly specified lock
 mode must not conflict with the lock mode required by the constraint
 or trigger that references the relation.

 The default is WITH AUTO_LOCKING.  Specify the WITH NOAUTO_LOCKING
 clause if you do not want to use the auto-locking option.

 on-clause =

 ─┬─> 
O
N ─┬─> db-handle ─┬─> 
U
S
I
N
G ─> ( ─┬─> tx-options ─┬─> ) ─┬─>
  │       └───── , <─────┘               └─> 
D
E
F
A
U
L
T
S ───┘      │
  └───────────────────────── 
A
N
D <──────────────────────────────┘

Additional information available:

db-handletx-options

 A host language variable used to refer to the database.

 For more information on transaction options, select the subtopic
 tx-options of the START_TRANSACTION Format subtopic.

 The ON ERROR clause.  Specifies host language statement(s) to be
 performed if an error occurs during the START_TRANSACTION operation.

 Example 1

 Ready a relation with defaults:

 START_TRANSACTION READ_WRITE

 This statement allows access to all the relations in the current
 database so that all users can modify records.  It is equivalent to
 readying all the relations for the SHARED WRITE reserving option.


 Example 2

 Start a read-only transaction:

 START_TRANSACTION READ_ONLY

 This statement lets you read data from the database but not store or
 modify data.  When you retrieve data, you see the state of the
 records as they existed at the time of the START_TRANSACTION
 statement.  You do not see any updates to the database made after
 that time.


 Example 3

 Start a transaction with locked relations:

 The following statement lets you specify the intended action for each
 relation in the transaction.

 START_TRANSACTION READ_WRITE RESERVING
       EMPLOYEES FOR PROTECTED WRITE,
       JOBS, SALARY_HISTORY FOR SHARED READ

 Assume that this transaction updates the EMPLOYEES relation based on
 values found in two other relations, JOBS and SALARY_HISTORY:

  o  The transaction must update EMPLOYEES, so EMPLOYEES is readied
     for the PROTECTED WRITE option.
  o  The program will only read values from JOBS and SALARY_HISTORY,
     so there is no need for PROTECTED or WRITE access.  However, you
     do intend to update records in the transaction, so the read-only
     transaction mode is not appropriate.


 Example 4

 In the following example, the user [SQL,HALSTON] receives the READ,
 WRITE, MODIFY, and ERASE rights.  HALSTON also gets the DISTRIBTRAN
 right, which allows HALSTON to run the two-phase commit protocol on
 the current database.

 RDO> DEFINE PROTECTION FOR DATABASE
 cont> POSITION 2
 cont> IDENTIFIER [SQL,HALSTON]
 cont> ACCESS "READ+WRITE+MODIFY+ERASE+DISTRIBTRAN".
 RDO>
 RDO> SHOW PROTECTION FOR DATABASE
     (IDENTIFIER=[SQL,RICK],ACCESS=READ+WRITE+MODIFY+ERASE+SHOW+DEFINE+
       CHANGE+DELETE+CONTROL+OPERATOR+ADMINISTRATOR+REFERENCES+SECURITY+
       DISTRIBTRAN)
     (IDENTIFIER=[SQL,HALSTON],ACCESS=READ+WRITE+MODIFY+ERASE+DISTRIBTRAN)
     (IDENTIFIER=[*,*],ACCESS=NONE)