| ODB for Win95/NT An Object-Oriented Database V. 0.1 Mail to: ODB for Win 95 / NT |

# 4.0 Database operations

In this section the ODB-database engine methods in the API are described and exemplified as C++ examples. Throughout the examples a database object named My_DB is used to exemplify the ODB-API.

## 4.1 Database creation

Figure 3. The ODB-database object
The ODB-API contains a C++ class named database see Figure 3. The database object in your application is a particular important object. It is through the database object which all accesses to the ODB-database and all calls to the database engine go.

The database object contains the database name, an ODB-type named Usertypes, an object identifier (OID) generator and a string table.

The name of the database object is assigned to it at creation or when the database is loaded from file. The type Usertypes is the root of the user defined type tree. This type can not be given user defined properties and objects can not be created from it. Thus, if a type is created without a specified supertype the type named Usertypes will become its supertype by default.

The string table is a character string repository. All strings used in the database are stored in this table. This facilitates fast look-up of string valued properties. There are som cases where the application must access the string table but in most cases ODB handles this for the application.

The OID generator generates OIDs for all new objects or types in the database. The OID can not be changed by the application and the application must never reference object by their OID's as the OIDs of the objects may change when the database is loaded again.

If your application only needs one database this database is declared in your application as:

    database My_DB("DBName");

This statement declares the object My_DB to be an ODB-database object with name DBname. All applications using ODB must have a database object. There is no limit set by ODBto the number of databases a single application can use.

If several databases are required in the application these can be created dynamically by using the C++ new-operator as:

    new database("OneMoreDB");

The database can be saved and restored from file as:

    database My_DB;

    My_DB.load_database("Db1.odb");

    My.DB.save_database("Db1.odb");

In above statements the database object My_DB is first loaded and then saved with file name Db1.odb.

## 4.2 Type creation

An ODB-type serve as a template for object creation. Properties and indexes are defined on types. A type can be declared as a subtype to any other type previously defined. If no supertype is declared then the new type will become subtype to the type named Usertypes in the database object. ODB-types are instances of the system type named type, see Figure 2.

An ODB-type inherits all properties defined to its supertype. Any indexes defined to the supertype will also be defined to the new type. Types are created by the ODB-database object as:

    My_DB.create_type("Person");

    My_DB.create_type("Employee","Person");

Here a type named Person is first created. A supertype has not been specified thus the type named Person will be a subtype of the type Usertypes in the database object My_DB. In the next example a type named Employee is created as a subtype to the type named Person.

If several databases are active in some application there may be types eith identical names in the different databases. Since references to types go through the database object there is never any ambiguity when referencing types by their names.

The return value from the create_type-statement is a reference to the new type or the NULL-reference if the type creation failed. The following example declares a type reference that can be bound to the return value from the create_type statement:

    ODB_TYPE My_NewType;

    My_NewType=My_DB.create_type("Person");

The return value need to be assigned a reference. The type is inserted in the type hierarchy of the database and can be referenced by its name whenever required.

## 4.3 Property Creation

Properties are defined to types and for the objects of that type the properties can be given values. Properties are typed where the following types together with their identifiers are supported:

Type | Type tag Integer | _INT_
Real | _REAL_
Charstring | _CHAR_
Object reference | _OBJECT_
Collection of Integer | _INT_COLLECTION_
Collection of Real | _REAL_COLLECTION_
Collection of Charstring | _CHAR_COLLECTION_
Collection of object reference. | _OBJECT_COLLECTION_

To create an integer valued property named salary to the type named employee in the database My_DB we write:

    My_DB.add_property("Employee","Salary",_INT_);

Analogously, an object valued property named Boss is created as:

    My_DB.add_property("Employee","Boss",_OBJECT_);

The return value is either less than or greater than zero if the operation failed or succeeded, respectively.

The add_property-statement can be executed any time and all subtypes to the target type that may exist will also be given the property. All instances to the types which has been given a new property will also be given the property. The value however will be undefined and it is up to the application that the value is not referenced prior to being assigned a value.

## 4.4 Object creation

Objects are created as instances to a particular type. When objects are created these are given all the properties defined to the type. The values of the properties are undefined and must be assigned values prior to being referenced.

To create an instances of the type named Person in the database My_DB we write:

    My_DB.create_instance("Person");

The return value is a reference to the newly created object or the NULL reference. To declare a variable which can be assigned the result of the create_instance operation we write:

    ODB_REF My_NewObj;

    My_NewObj=My_DB.create_instance("Person");

The return value may be discarded but then there is a problem in referencing the object at a later stage. Perhaps the best procedure is to create an object and keep a reference to it. This reference can then be used when the properties of the objects are assigned values. When values are assigned to its properties the reference may be discarded and the object can at a later stage be referenced through its attribute values. This is easily done through the query interface described later in this manual.

## 4.5 Object modification

Object modification means changing the values of its properties. This is done by using sending the message set_propertyvalue to the database object as:

    My_DB.setproperty_value(My_NewObj,"Salary",(ODB_INT)53200);

Where My_NewObj is an ODB-object declared and created e.g as:

    ODB_REF My_NewObj;

    My_NewObj=My_DB.create_instance("Employee");

The object is given the value 53200 for the property named Salary. Note that constants may require type casting for disambiguation purposes. In this example the constant 53200 is casted to the type ODB_INT. The result from the database method setproperty_value is greater than or less than zero if the operation was successful or failed, respectively.

When property values are modified all indexes are automatically updated to consider the new value for the property.

## 4.6 Index creation

To make retrievals through some property fast, indexes can be created. For example if a frequent search in the database is on a particular attribute e.g. Salary then an index should be created on that attribute to facilitate fast access to the objects with a particular value for the attribute named Salary.

Indexes are created from the database object through the create_index method. The following example creates an index on the Salary property of the type Employee .

    My_DB.create_index("Employee","Salary");

Note that if an index is created to some attribute of a particular type the index will also be created to that attribute in all subtypes. In above example any subtype to Employee will get an index on the salary property. It does not matter if the index is created before or after the subtypes are created. It does not matter if instances to the types the index is created over has been created. All existing instances will be entered into the index structures automatically by ODB.

## 4.7 Type deletion

Types can be deleted from the database dynamically. This is a particularly costly operation. When a type is deleted so are the subtypes to the type as well as all objects that are instances to the type or to any subtype of the type. Hence, A type deletion is a recursively applied down the type tree rooted at the specified type to delete.

Types are deleted by the database object by sending the delete_type message. The result of the operation is either greater than or less than zero if the operation was successful or failed, respectively. To delete the type Person from the database My_DB we write:

    My_DB.delete_type("Person");

This will delete the type named Person, all instances of that type and then recursively delete all subtypes to the Person type. This operation can be costly to perform when there are a lot of objects and types that has to be deleted and their memory freed.

Note especially that any references maintained by the application to types or objects which have been deleted must be reset by the application. Dereferncing such a reference is an undefined operation.

## 4.8 Property deletion

Single properties can be deleted from types. When a property is deleted from some type it is deleted from all subtypes as well.

When a property is deleted from a type the property is also deleted from all object that are instances to that type, i.e. the extent of the type.

Properties are deleted from types by sending the delete_property message to the database object. To delete the property named Salary from the type named Employee in the database My_DB we write:

    My_DB.delete_propery("Employee","Salary");

Note that if the property that is to be deleted is inherited to the specified type that property can not be deleted as that would leave the database schema in an inconsistent state. To properly delete a property it must be deleted from the most general type it is defined for. (A supertype is more general than its subtypes)

This is because the object-oriented model states that any operation op applicable to a type t is also applicable to all subtypes of the type t. Hence, deleting an inherited property would violate this constraint.

## 4.9 Delete Object

Objects may be deleted. When an object is deleted the system automatically deletes all references to that object from other objects in the database. Any references kept by the application to the deleted object must be reset by the application itself.

Objects are deleted by sending the delete_object message to the database. When deleting an object the database object must be provided a handle to the object that are subject of deletion.

A handle can be obtained through the query interface or other methods that returns object handles.

To exemplify, consider the following example where a handle obj is declared. This handle is then assigned an object through the getobjectwithoid method. This object is then deleted by the database object:

    //Declare object handle,

    //database and an integer

    ODB_REF obj;

    database My_DB("ExDB");

    ODB_INT i=0;

    My_DB.create_type("Person");

    //Create 500 objects

    while(i++ < 500) My_DB.create_object("Person");

    //Assign an object to the handle, We can be

    //quite certan there is an object with OID 415 now

    obj=My_DB.getobjectwithoid("Person", 415);

    //Delete the object

    //If there were no object with OID=415

    //then obj==NULL but that is all handeled

    //by ODB

    My_DB.delete_object(obj);

Any other object that reference the deleted object through some attribute will now have that attribute value set to NULL. Note that in this example the object handle obj is outside the control of ODB and must not be used by the application after the deletion. This is up to the application programmer to see to.

## 4.10 Delete index

Indexes may be deleted by sending the drop_index message to the database object. In the following example the index over Salary for type Employee in database My_DB is deleted:

    My_DB.drop_index("Employee","Salary");

The result is greater or less than zero if the operation was successful or failed respectively.

| ODB for Win95 / NT An Object-Oriented Database V. 0.1 Mail to ODB for Win 95 / NT |