The DDL Declare Statement

The declare statement is used to specify three different entities: the database name, a user-defined “Object Identifier” or oid, and an automatic object identifier or auto_oid:

 
    declare database dbname;
     
    declare oid  structname [expected-number-of-entries];
     
    declare auto_oid[expected-number-of-entries];
     

Database declaration

All schema definitions must contain a database declaration to specify the name of the database. The DDL compiler creates implementation file names based on the dbname passed to the declare statement. For example the following declaration:

 
    declare database simpledb;
     

will cause the DDL compiler to produce files simpledb.h and simpledb.c.

OID declaration

The declare statement is also used to identify a unique object identifier with the expected number of objects that will be stored with an oid. The expected-number-of-entries is used by the runtime to calculate the initial hash table size for the index.

Once the oid structure is declared, classes with this unique identifier can then be declared (see the class statement). The runtime maintains an internal index referencing all objects of such classes. Objects can reference each other by oid using the ref data type. The oid is a user-defined structure, even if the oid has a single field. Each oid value must be unique for the entire database.

Only one database and one oid declaration is allowed within a database schema. For example:

 
    struct Id {
        uint4 id;
        uint4 time_in;
    };
    declare database	market;
    declare oid 	Id[20000];
     

Structures that represent oid have a limitation in that their elements must be of a fixed size. For instance, the following is illegal and will generate a compiler error:

 
    struct StrId {
    string str;
    int2   num;
    };
    declare oid StrId[20000];
     

But the following definition is perfectly okay:

 
    struct StrId {
        char<32> str;
        int2     num;
    };
    declare oid StrId[20000];
     

AUTO_OID declaration

The auto_oid declaration is necessary for eXtremeDB High Availability databases and can be useful for databases that might participate in Binary Schema Evolution (BSE). Like the oid, an auto_oid declaration specifies the number of expected objects in the database:

     
    declare auto_oid[10000];
     

However, where the oid is a user-defined structure and must be inserted or updated explicitly by the application, the auto_oid is an 8-byte unique identifier generated by the runtime and inserted automatically when database objects are created. This auto_oid is a global object identifier used by the runtime during BSE load operations and to perform synchronization in eXtremeDB High Availability applications. (Note that the internal format of the auto_oid is not published and there are no interface functions to create or modify an auto_oid directly.)

Note: The “number of expected objects” specified in the oid and auto_oid declaration need not be precise. This estimate simply initializes the hash table used for the internal hash index associated with them and this table size will be increased automatically by the runtime if necessary.

List declaration

Each list declaration will create an additional dynamic structure, which will consume resources similar to those taken by a tree index. The list declaration is useful when:

• objects of a class have to be accessed sequentially
• the application does not require any particular order in which objects are accessed
• there is no suitable index for the class