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.

 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 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 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)

 Note that referring to more than one Rdb/VMS database for actual
 update operations within one transaction is not recommended.  That
 is, attempting to update multiple databases using a single
 START_TRANSACTION statement is not advisable; for instance, the
 transaction COMMIT may succeed for the first database in which you
 performed updates, but could then fail if the disk device holding the
 second database (in which you also performed updates) is damaged by a
 system failure.  This could leave your application in an inconsistent
 state.

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

Additional information available:

TRANSACTION_HANDLE

on-erroron-clausetx-options

 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.

 You can put parentheses around the host language variable name.

 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.

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

 on-clause =

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

Additional information available:

db-handle

 A host language variable used to refer to the database.

 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:

READ_ONLYREAD_WRITEBATCH_UPDATEWAIT_NOWAIT
AUTO_LOCKING

evaluating-clausereserving-clause

 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

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

 Use a batch-update transaction to perform large volume updates or
 loads of the database.  Batch-update mode locks all relations in the
 database.  It does not use the RUJ file to preserve the integrity of
 the database.  If you issue a ROLLBACK statement after a batch-update
 transaction, the database will be corrupt.

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

 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.

 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 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.

 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.