Specifies the name of the database to be accessed in a program or by
 RDO.  You must issue an INVOKE DATABASE statement before you can use
 any other statement to reference data in that database.  Using INVOKE
 is equivalent to declaring an external subroutine; it declares the
 database to the program.

 Example:

 RDO>  INVOKE DATABASE FILENAME 'DISK2:[DEPT4]PERSONNEL'

Additional information available:

FormatExamples

 INVOKE DATABASE ───┐
      ┌─────────────┘
      └───┬─────────────────────>────────────────────────┬────┐
          ├───────>─────────┬────────> db-handle ──> typebox (=) ──┘    │
          ├──> 
E
X
T
E
R
N
A
L ────┤                                 │
          ├──> 
G
L
O
B
A
L ──────┤                                 │
          └──> 
L
O
C
A
L ───────┘                                 │
      ┌─────────────────────────<─────────────────────────────┘
      └──┬─────────>─────────┬──┬──> 
P
A
T
H
N
A
M
E ───> path-name ──┬─┐
         └──> 
C
O
M
P
I
L
E
T
I
M
E ───┘  └──> 
F
I
L
E
N
A
M
E ───> file-spec ──┘ │
      ┌──────────────────────────<───────────────────────────────┘
      └──┬─────────────────────────>────────────────────────────┬───┐
         └──> 
R
U
N
T
I
M
E Ftypebox (I)typebox (L)typebox (E)typebox (N)typebox (A)typebox (M)typebox (E) ────┬────> file-spec ────────┬───┘   │
                                   └────> host-variable ────┘       │
      ┌──────────────────────────<──────────────────────────────────┘
      └──┬─────────────────────────>───────────────────────┬──┐
         └──> 
D
B
K
E
Y 
S
C
O
P
E typebox (I)typebox (S) ───┬───> 
C
O
M
M
I
T ──────┬───────┘  │
                                └───> 
F
I
N
I
S
H ──────┘          │
      ┌──────────────────────────<────────────────────────────┘
      └──┬─────────────────────────>───────────────────┬──>
         └──> 
R
E
Q
U
E
S
T
H
A
N
D
L
E 
S
C
O
P
E typebox (I)typebox (S) ─┬─> 
D
E
F
A
U
L
T ──┬─┘
                                       └─> 
F
I
N
I
S
H ───┘

Additional information available:

COMPILETIMERUNTIMEDBKEY_SCOPE_COMMITDBKEY_SCOPE_FINISH
REQUEST_HANDLE_SCOPE_DEFAULTREQUEST_HANDLE_SCOPE_FINISH

db-handlepath-namefile-spechost-variable

 A host language variable that you associate with the name of the
 database.  Use database handles when you are accessing more than one
 database at a time.  Do not declare a host language variable
 explicitly for the database handle.  The Rdb/VMS preprocessors
 declare the variable for you.

 You can make a handle local to the module in which it is declared
 (LOCAL), or global to all modules that declare the database (GLOBAL,
 EXTERNAL).

 The default is GLOBAL.

 A full or relative data dictionary path name, enclosed in quotation
 marks, specifying the source of the database definitions.

 A full or partial VMS file specification, enclosed in quotation
 marks, specifying the source of the database definitions.

 A valid host language variable that equates to a database file
 specification.

 The source of the database definitions when the program is compiled.
 This can be either a data dictionary path name or a VMS file
 specification.  If you specify only the COMPILETIME identifier and
 omit the RUNTIME identifier, Rdb/VMS uses the COMPILETIME identifier
 for both compiling and running the program.

 The source of the database definitions when the program is run.  This
 can be either a VMS file specification or a host language variable.
 If you do not specify this parameter, Rdb/VMS uses the COMPILETIME
 identifier for both compiling and running the program.

 The DBKEY SCOPE clause controls when the database key (dbkey) of an
 erased record may be reused by Rdb/VMS.  When the DBKEY SCOPE is
 COMMIT, Rdb/VMS cannot reuse the dbkey of an erased record to store
 another record until the transaction that erased the original record
 completes (by entering COMMIT).

 The DBKEY SCOPE COMMIT clause specifies that the dbkey of each record
 used is guaranteed to remain consistent only during each transaction.

 ith the DBKEY SCOPE IS FINISH clause, Rdb/VMS cannot reuse the dbkey
 (to store another record) until the user who erased the original
 record detaches from the database (by using the FINISH statement).

 Further, the DBKEY SCOPE FINISH clause specifies that the dbkey of
 each record used is guaranteed not to change until this user detaches
 from the database(usually, with FINISH).

 The REQUEST_HANDLE SCOPE clause is only used by RDBPRE and RDML
 programs, not with RDO.  In a RDBPRE program where an RDO request
 occurs within a higher level language loop, the REQUEST_HANDLE SCOPE
 clause determines whether system or user request handles are set to
 zero in the RDO FINISH statement within the loop.

 The default is DEFAULT, where the values of the request handles are
 not set to zero when the RDO FINISH statement executes.

 The REQUEST_HANDLE SCOPE clause is only used by RDBPRE and RDML
 programs, not with RDO.  In a program where an RDO request occurs
 within a higher level language loop, the REQUEST_HANDLE SCOPE clause
 determines whether system or user request handles are set to zero in
 the RDO FINISH statement within the loop.

 With the REQUEST_HANDLE SCOPE is FINISH clause, the values of the
 request handles are set to zero after the RDO statement FINISH
 executes.

 Example 1

 The following example invokes a database in RDO:

 RDO> INVOKE DATABASE PATHNAME 'DISK1:[DICTIONARY]CORP.MIS.PERSONNEL'

 This example uses the data dictionary definitions in
 DISK1:[DICTIONARY]CORP.MIS.PERSONNEL to invoke the PERSONNEL database
 in RDO.


 Example 2

 The INVOKE DATABASE statement must be part of every program:

 &RDB& INVOKE DATABASE FILENAME 'DISK2:[DEPT3]PERSONNEL'

 This statement declares the database defined by the file
 specification DISK2:[DEPT3]PERSONNEL.  The preprocessor then uses
 this definition when compiling the program, and Rdb/VMS uses the
 database file DISK2:[DEPT3]PERSONNEL.RDB when the program runs.


 Example 3

 The following BASIC example invokes a database using an EXTERNAL
 database handle:

  &RDB& INVOKE DATABASE EXTERNAL
  &RDB&   PERSONNEL = PATHNAME 'DISK1:[DICTIONARY]CORP.MIS.PERSONNEL'

 This example shows a global declaration.  Other modules in the
 program can refer to the database using the handle PERSONNEL; they
 must use the same database handle for the same database.  The program
 does not declare the variable.


  o  GLOBAL and EXTERNAL are synonymous.  These make the database
     handle global to all modules that declare the database.  Rdb/VMS
     creates a PSECT containing one longword using the name supplied
     by the user with the overlay attribute.

  o  The default database scope is GLOBAL.

  o  The preprocessor generates declarations for all database handles.



 Example 4

 The following COBOL example uses the COMPILETIME and RUNTIME options:

    &RDB& INVOKE DATABASE LOCAL PERSONNEL =
    &RDB&    COMPILETIME PATHNAME
    &RDB&      'DISK1:[DICTIONARY]ACCT.PERSONNEL'
    &RDB&    RUNTIME FILENAME
    &RDB&      'USERDISK3:[DEPT3]PERSONNEL'

 This example declares the database using two different sources:

  o  At compile time, the preprocessor uses the database definitions
     in the data dictionary.

  o  At run time, Rdb/VMS uses the definition in file
     USERDISK3:[DEPT3]PERSONNEL.RDB.