The eyedboql Tool

eyedboql is a tool that allows you to execute interactively OQL statements. This tool is similar to the Oracle sqlplus and Sybase isql well known tools.

Running eyedboql

The simplest way to run eyedboql is to type eyedboql as follows (assuming that $ is your shell prompt):

$ eyedboql
Welcome to eyedboql.
  Type `\help' to display the command list.
  Type `\copyright' to display the copyright.
?

The string ``? `` is the default prompt for eyedboql.

In an eyedboql session, anything you type is interpreted as an OQL construct (or a part of an OQL construct),
Nevertheless, if the first word of an input line begins with the escape character ``
'', this word is interpreted as an eyedboql internal command. There are about 30 internal commands, but you need to know only of few of them to use eyedboql.

The purpose of the main internal commands is:
- to create or delete databases,
- to open a database,
- to begin, commit or abort a transaction,
- to set the current user and password,
- to execute the contents of a file,
- to display the string representation of an object,
- to display the HTML representation of an object in a WEB browser,
- to change the prompts and the escape character.

Executing Statements

eyedboql allows us to execute OQL statements in an interactive way. For instance, to perform the addition 1+3:

$ eyedboql
Welcome to eyedboql.
  Type `\help' to display the command list.
  Type `\copyright' to display the copyright.
? 1+3;
= 4
?

The string ``= '' preceedes the result atom (if any) of your statement; in the current example, the result atom is the evaluation of the expression statement 1+3;.

Execution Process

Each complete statement typed is sent to the OQL interpreter, A complete statement has a special meaning: it is any sequence of characters:
a. that end with a semi-colon and
b. which parenthesis are balanced and
c. which brakets are balanced and
d. which braces are balanced.

While the statement is not complete, eyedboql prompts the ``second prompt'' (``» '' by default) after each newline.
Once the statement is complete, it is sent to the OQL interpreter, then the atom result is display (if any) after the string ``= '' and the main prompt ``? '' is displayed again.

For instance, the input sequence of characters ``1+newline3newline;'' gives:

? 1+
>> 3
>> ;
= 4

while the input sequence ``{ a := 1+3;newlinec := 2+94;newlined := a+c}'' gives:

? { a := 1+3;
>> c := 2+94;
>> d := a+c}
?

Note that no ``= result atom'' is echoed because a compound statement does not return any atom.

This last example:

? while (true) {
>>   a++;
>>   b++;
>> }
>>
>> ;
?

shows the necessity of typing a semicolon after the while statement although a while statement does not need to end by a semi-colom in the OQL specifications.

Getting Started

By default in an eyedboql session, the database EYEDBDBM is opened in read-only mode. To use another database, one must use either the command line option -db either the
open internal command.

To start to play with eyedboql one needs to know the following five internal commands:

1. 
   open database [rw$\vert$ro] local trsless: opens the database in read-write (rw) or read-only (ro or no option) mode. If local is there, database is opened in a local mode. If trsless is there database is opened in transaction-less mode.
   For instance ``
   open foo rw'' opens the database foo is read-write mode.
2. 
   print [sequence of oids] other options: if a sequence of oids is given: loads the object corresponding to each oid and displays its string representation,
   if no sequence of oids is given: loads the object corresponding to each oid returned by the last statement and displays its string representation.
   For instance, ``select Person;'' will return a bag containing the oid of each Person instance.
   The internal command ``
   print'' typed after that will loads and displays of the corresponding Person instances.
   The other options are one or more space-separated of the followings:

   
   		full		: loads and displays object using the full recursive mode
   
   ctime		: displays the creation time of the object
   
   mtime		: displays the last modification time of the object
   
   contents		:  displays the contents of collections
   
   native		:  displays the native attributes
   
   all		: means ``ctime mtime contents native''
   

   For instance ``
   print full contents'' will load and display the objects and their collection contents in a full recursive mode.
3. 
   commit: commits the current transaction
4. 
   abort: aborts the current transaction
5. 
   quit or ^D: quits the current eyedboql session

Note that a transaction is started automatically before the first complete statement of the sesssion of before the complete statement immediately following
commit or
abort internal command.

Here is a commented example showing the use of these internal commands:

run eyedboql:

$ eyedboql
Welcome to eyedboql.
  Type `\help' to display the command list.
  Type `\copyright' to display the copyright.

open the database person in read-write mode:

? \open person rw

get the first person whose name is "john" and display it:

? john := first(select Person.name = "john");
= 66373.12.4008447:oid
? \print
66373.12.4008447:oid Person = { 
        name = "john";
        age = 32;
        addr Address = { 
                street = "clichy";
                town = "Paris";
                country = NULL;
        };
        cstate = Sir;
        *spouse 66891.12.2738687:oid;
        cars set<Car*> = set { 
                name       = "";
                count      = 4;
                dimension  = 1;
                reference  = true;
                magorder   = 4;
        };
        children array<Person*> = array { 
                name       = "";
                count      = 0;
                range      = [0,0[;
                dimension  = 1;
                reference  = true;
                magorder   = 4;
        };
        x = NULL;
};

change the name of john to "JOHNNY":

? john.name := "JOHNNY";
= "JOHNNY"

retrieve the person whose name is "JOHNNY" and compares it to john using assert : all is fine, no error is raised!

? assert(john = first(select Person.name = "JOHNNY"));

abort the transaction and look for the person whose name is "JOHNNY": no person is returned! this is ok as the transaction was aborted:

? \abort
? select Person.name = "JOHNNY";
= list()

change the name of john to "JOHNNY" again and commit the transaction:

? john.name := "JOHNNY";
= "JOHNNY"
? \commit

then retrieve again the person whose name is "JOHNNY" and compare it to john using assert: all is fine, no error is raised!

? assert(john = first(select Person.name = "JOHNNY"));

quit eyedboql session

? \quit
$

We are going to conclude this section by this important note:
as introduced previously, the current transaction will be committed (resp. aborted) by a
commit (resp.
abort) command.
If you quit eyedboql before committing (resp. aborting) the transaction, it will be automatically aborted, so all your changes will be lost.
This is the default behaviour. This behaviour can be changed by using the
commitonclose internal command.

Command Line Options

The eyedboql command line options are as follows:

		Program Options:

-d <name>, -database=<name> 		  Database name

-r, -read 		   Open database in read mode

-w, -read-write 		   Open database in read/write mode

-s, -strict-read 		  Open database in strict read mode

-l, -local 		       Open database in local mode

-c <command>, -command=<command>		 OQL command to execute

-p, -print 		 Display all the objects loaded

-full 		  Full recursive mode is used to display objects

-commit 		  Commits the current transaction on close

-i, -interact 		  Enter interpreter after executing file or commands

-e, -echo 		  Echo each command

-admin 		  Open database in admin mode

-h, -help 		  Display this message

<file> 		  File(s) to execute



Common Options:

-U <user>|@, -user=<user>|@ 		    User name

-P [<passwd>], -passwd[=<passwd>]		  Password

-host=<host> 		       eyedbd host

-port=<port> 		         eyedbd port

-inet 		       Use the tcp_port variable if port is not set

-dbm=<dbmfile> 		     EYEDBDBM database file

-conf=<conffile> 		    Configuration file

-logdev=<logfile> 		   Output log file

-logmask=<mask> 		   Output log mask

-logdate=on|off 		   Control date display in output log

-logtimer=on|off 		   Control timer display in output log

-logpid=on|off 		   Control pid display in output log

-logprog=on|off 		   Control progname display in output log

-error-policy=<value> 		  Control error policy: status|exception|abort|stop|echo

-trans-def-mag=<magorder> 		   Default transaction magnitude order

-arch 		   Display the client architecture

-v, -version 		   Display the version

-help-eyedb-options 		   Display this message

For instance, to execute the statement ``delete_from(Person)'' on the database person:

$ eyedboql -d person -w -c "delete_from(Person)"
$

To execute the command ``persons := (select Person)'' and then enter the interactive mode of eyedboql:

$ eyedboql -d person -w -c "persons := (select Person)" -i
Welcome to eyedboql.
  Type `\help' to display the command list.
  Type `\copyright' to display the copyright.
?

To execute the file mylib.oql:

$ eyedboql -d person -w mylib.oql