Declarative Objectivity (DO) Language : Getting Started With DO : A Quick Tour
1 
A Quick Tour
In this chapter, you will:
Create a new federated database.
Start the interactive DO runner.
Add class descriptions to the federated database schema.
Create objects and perform queries.
Modify and delete objects.
Delete the federated database.
Creating a Federated Database
With Objectivity/DB, you typically distribute related data in many individual databases (.DBs), which are members of a single federated database. A federated database uses a running lock server to manage concurrent access by multiple users.
To create the federated database:
1. Create a data directory within your project directory—for example, myProject/data.
2. Open a command prompt in the data directory and use an administrative tool to verify that the lock server is running on your host machine:
objy CheckLs
If necessary, start the lock server:
objy StartLockServer
3. In the same command prompt, use an administrative tool to create a federated database named quickTour:
objy CreateFd -fdName quickTour
4. Examine the files created in the data directory.
quickTour.boot is the boot file for the new federated database. Applications interact with a federated database by accessing its boot file.
quickTour.fdb is the system database file. It maintains the global catalog of databases, the schema, indexes, and other internal information. Later, as objects are added to the federated database, additional database files will be created in the same location.
Now you are ready to use DO to interact with the federated database.
Starting an Interactive DO Runner Session
You start the DO runner in interactive mode by executing the DO command from the command line, providing a single option that identifies the boot file for the federated database to be accessed.
To start the DO runner for the newly created federated database:
1. In the data directory, enter the following command:
objy DO -bootFile quickTour.boot
2. (Optional) Just for practice, exit and restart the DO runner:
DO> /EXIT
objy DO -bootFile quickTour.boot
For a list of keyboard shortcuts and commands you can use in interactive mode, see DO in Objectivity/DB Administration.
Adding Class Descriptions
Before adding objects to a federated database, you need to create class descriptions for those objects. Taken together, such descriptions make up the federated database’s schema. The schema enhances query performance by ensuring that data is stored as well-formed objects of platform-independent types.
Let’s add a class description for a Person class to our federated database. We want the class to have six attributes, including an integer attribute, a date attribute, and four string attributes. (For complete information about available attribute types and how to specify them, see Attribute Structures.)
To create a class description with DO, you execute an UPDATE SCHEMA statement that includes a nested CREATE CLASS clause:
1. Copy the following multi-line UPDATE SCHEMA statement from the UPDATE keyword on the first line, through the semicolon on the last line:
UPDATE SCHEMA
{
  CREATE CLASS Person
  {
    firstName:     String,
    lastName:      String,
    personCode:    String,
    birthdate:     Date,
    sex:           String
  }
};
 
2. Paste the copied statement at your DO> command prompt.
3. Press Enter to submit the statement.
4. Notice the result. The statement returns Done if successful.
Note: Whitespace and line breaks are ignored by the DO runner. Pressing Enter in interactive mode executes a statement only if it ends with a semicolon; otherwise, another line break is added.
Creating Objects
Now that the Person class description is available, you can create objects of that class. You create an object by executing a CREATE statement that specifies the class and attribute values. Any omitted attributes are given default values.
To create a couple of Person objects:
1. Create a Person object with all default attribute values:
CREATE Person{};
2. Notice the result. The statement returns the unique object identifier (OID) that has been assigned to the new object within the federated database:
__identifier__:3-3-1-4
3. Create a Person object with the supplied firstName and lastName attribute values:
CREATE Person{firstName: 'James', lastName: 'Bond'};
4. Once again, notice the new object’s OID:
__identifier__:3-3-1-5
Note: The DO runner displays results one window screen at a time. If the DO runner pauses during output and displays a colon (:) prompt, simply press Enter to continue.
Querying for Objects
You can query for all objects of a given class, or you can include a WHERE clause to narrow your search based on attribute values.
To query for the Person objects created in the previous exercise:
1. Find all Person objects and display their attribute values:
SELECT * FROM Person;
2. Examine the results. In particular, notice that the attributes you omitted during object creation have default values such as null:
{
  Person
  {
     __identifier__:3-3-1-4,
    firstName:null,
    lastName:null,
    personCode: null,
    birthdate:0001-01-01,
    sex:null
  },
  Person
  {
    __identifier__:3-3-1-5,
    firstName:'James',
    lastName:'Bond',
    personCode: null,
    birthdate:0001-01-01,
    sex:null
  }
}
3. Now find just the person whose first name is James:
SELECT * FROM Person WHERE firstName='James';
4. Notice the smaller result set:
  Person
  {
    __identifier__:3-3-1-5,
    firstName:'James',
    lastName:'Bond',
    personCode: null,
    birthdate:0001-01-01,
    sex:null
  }
}
5. Now find the person whose first name is James, and retrieve only the first name and last name:
SELECT firstName, lastName FROM Person WHERE firstName='James';
6. Notice the returned subset, or projection, from the found object:
  Person_Projection
  {
    __identifier__:3-3-1-5,
    firstName:'James',
    lastName:'Bond'
  }
}
SQL vs. DO Statement Styles
The queries shown in the previous exercise use SQL-style statements, with the SELECT keyword at the beginning of the statement.
SELECT * FROM Person;
SELECT * FROM Person WHERE firstName='James';
SELECT firstName, lastName FROM Person WHERE firstName='James';
DO also supports an alternative statement style that starts with the FROM clause, and uses RETURN instead of SELECT. This style is used in the documentation because RETURN more clearly expresses the statement’s result, which is to return retrieved objects or values.
Try these DO-style statements:
FROM Person RETURN *;
FROM Person WHERE firstName='James' RETURN *;
FROM Person WHERE firstName='James' RETURN firstName, lastName;
Modifying Objects
You can modify existing objects by executing an UPDATE statement. An UPDATE statement includes:
An optional WHERE clause that limits, or qualifies, the objects to be modified.
An action clause that indicates the kind of modification to make. For example, you use a SET clause to provide a new value for an attribute.
To set an attribute of a Person object:
1. Find the person object whose last name is Bond, and change the code name to the supplied value:
UPDATE Person WHERE lastName='Bond' SET personCode TO '007' RETURN personCode;
2. Examine the results to confirm your change:
{
  Person_Projection
  {
    __identifier__:3-3-1-5,
    personCode:'007'
  }
}
Note: If the data set had multiple Person objects with the same qualifying lastName, this UPDATE statement would set the personCode attribute in each one.
Deleting Objects
You can delete existing objects from the federated database by executing a DELETE statement. You normally include a WHERE clause to limit the objects to be deleted.
Delete the person whose code name is 007:
DELETE Person WHERE personCode = '007';
Note: If the data set had multiple Person objects with the same qualifying firstName, then this DELETE statement would delete all of them.
Deleting a Federated Database
At this point, the quick tour is over, and you can delete the entire federated database.
1. Exit the DO runner:
DO> /EXIT
2. From a command prompt in the data directory, use an administrative tool to delete the federated database named quickTour:
objy DeleteFd -bootfile quickTour.boot