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, BENEFITS and STATUS, 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)

 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.

 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 database handle.  A host language variable associated with the
 database when the database was invoked.

 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 ───┬─┘
                      └──────── , <───────────┘

Additional information available:

READ_ONLYREAD_WRITEBATCH_UPDATEWAIT_NOWAIT

reserving-clauseevaluating-clause

 If you start a transaction READ_ONLY, 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.  Using a READ_ONLY
 transaction mode 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

 Signals that you want to perform large volume updates or loads of the
 database.  BATCH_UPDATE transaction 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.  Create backup copies of
 the database before you start a BATCH_UPDATE transaction.

 Read the description of BATCH_UPDATE in Chapter 6 (the
 START_TRANSACTION section) of the VAX Rdb/VMS Reference Manual for
 critical information about the hazards of BATCH_UPDATE transactions.

 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.

 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:

Options

    Option       Access Constraints

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

  PROTECTED     Other users can read the relation(s) you are using.
                They cannot have WRITE access.

  EXCLUSIVE     Other users cannot read records from the relation(s)
                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 relation(s).

  WRITE         You will store, modify, or erase data in the
                relation(s).

 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)

 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.