Oracle Rdb uses the database handle to identify the particular
    database that is referenced by a database request. Note that the
    database handle should not be thought of as a program variable.
    The database handle provides context to any statement that uses
    the database handle. When your program accesses a single database
    you do not have to include database handles or scopes in the
    DATABASE statement. Unlike transaction handles and request
    handles, database handles do not have to be declared in your
    programs. The RDML preprocessor automatically generates the data
    declaration for the database handle.

    The database handle is used in several RDML statements and
    clauses to identify a database:

    o  DATABASE

    o  FINISH

    o  READY

    o  relation-clause of the record selection expression

    o  DEFINE_TYPE or DECLARE_VARIABLE (synonyms)

    o  BASED ON clause

    Oracle Rdb lets you have more than one database active at a given
    time. You can use the database handle to distinguish among these
    different databases in RDML statements.

    Both the default and named database handle are declared as GLOBAL by
    default.

1  –  More

    The example program shown here illustrates a problem with RDML. It is
    written in VAX C, and although the precompilation is clean, the C
    compiler gives errors at the READY statement. This problem occurs only
    when the READY statement contains a database handle that is incorrectly
    specified as a variable rather than specified in a DATABASE statement.

    This program works if a database handle specified in one of the database
    statements is used in the READY statement, whether the READY statement
    is used in a function or in a main module.

    #include stdio
    DATABASE first_db = FILENAME 'the_first';
    DATABASE second_db = FILENAME 'the_second';
    main()
    {
    one_ready(first_db);
    one_ready(second_db);
    printf("%d\n",first_db);
    printf("%d\n",second_db);
    START_TRANSACTION READ_WRITE;
    COMMIT;
    }
    one_ready(the_handle)
    unsigned long the_handle;
    {
    READY the_handle ON ERROR printf("an error\n"); END_ERROR;
    return(the_handle);
    }

    The READY statement, as documented in the V3.0, V3.1, and V4.0 Oracle
    Rdb RDML Reference Manual, states that the database handle (or multiple
    database handles) used in the READY statement must be specified in a
    DATABASE statement.  Oracle does not support user-specified database
    handles in RDML; database handles are automatically declared and used
    in RDML as a result of their specification in a DATABASE statement
    (which is really a declaration). This program attempts to use a
    database handle that is declared explicitly (as opposed to being
    specified in a DATABASE statement), and RDML therefore does not
    recognize it as a database handle. Because a READY statement by itself
    is valid, RDML simply recognizes that the READY statement syntax has
    terminated at that point, and so it fails to detect the ON ERROR clause
    later in the same line.  (It assumes that the rest of the line was host
    language syntax.)

    To enable RDML to recognize your database handle, associate a unique
    number with each database handle, and use it to identify which database
    handle to use. The example shown here is a possible approach:

    #include <stdio.h>

    DATABASE first_db = FILENAME 'PERSONNEL';
    DATABASE second_db = FILENAME 'PERSONNEL';

    main()
    {
    one_ready(1);
    one_ready(2);
    printf("%d\n", first_db);
    printf("%d\n", second_db);
    START_TRANSACTION READ_WRITE;
    COMMIT;
    }

    one_ready(int which_handle)
    {
    switch (which_handle)
       {
        case 1:
           READY first_db ON ERROR printf("an error\n"); END_ERROR;
           break;
        case 2:
           READY second_db ON ERROR printf("an error\n"); END_ERROR;
           break;
       }
    }

2  –  Examples

    The following program segments demonstrate how to use a database
    handle in a READY statement. These segments declare a COMPILETIME
    database and ready it. Because a RUNTIME database is not
    explicitly declared, the programs use the COMPILETIME database
    at runtime also.

2.1  –  C Example

    #include <stdio.h>
    DATABASE PERS = FILENAME "PERSONNEL";

    main ()
    {
    READY PERS;
    START_TRANSACTION READ_ONLY;

    /* perform some database actions */

    COMMIT;
    FINISH PERS;
    }

2.2  –  Pascal Example

    program dbhandle (input,output);
    DATABASE PERS = FILENAME 'PERSONNEL';

    begin
    READY PERS;
    START_TRANSACTION READ_ONLY;

    {* perform some actions on the database *}

    COMMIT;
    FINISH PERS;
    end.

3  –  Format

  (B)0db-handle =

  qqqqq> host-variable qqqqq>

3.1  –  Format arguments

    host-variable          A valid alphanumeric host language
                           variable.