2 Getting Started

To get in touch with the Cego database system, we will first take a look to a sample database. Following subsequent steps to create a database, start it up and connect to it using the standard client program cgclt will give a basic understanding of the database system.

This assumes a successful compiliation and installation of the cego database programs. Please see the README file in the distribution for a description of the required steps.

2.1 Building up a tableset using cgmkdb

The easiest way to create a cego tableset is using the cgmkdb utility script in the tools directory. As default, the database is created in the directory /usr/local/cego. Please ensure, that the directory exists and is writable for the creating user.

dude.local > ./cgmkdb mydb Creating xml ... Creating admin user ...... operation ok Creating role ...... operation ok Defining tableset ...... operation ok Creating database user for ...... operation ok Creating tableset ...... operation ok dude.local >

The database mydb has been created with a default tableset tsdef. Now the database can be started with the following command.

dude.local > cego --mode=daemon --dbxml=/usr/local/cego/mydb/mydb.xml --tableset=tsdef Cego daemon up and running ...

This brings up the default tableset tsdef

Sending a Ctrl-C will shutdown the database daemon.

2.2 Building up a tableset manually

To build up a cego database tableset from scratch manually is also pretty easy. The following steps illustrate the way to do so.

Step I - Create an initial database configuration file

A Cego database description is based on an appropriate XML configuration file, which contains all required information about the database. As a first step, we have to create this kind of XML document. For our first sample, we will take the description as described below and save it in a file called cegodb.xml. Later on, we will discuss each of the XML document elements and attributes more detailed.

An initial configuration file is very small and can be created with a normal editor. Of course, you also may cut and paste to xml code listed below

<?xml version="1.0" ?> <!DOCTYPE CEGO_DB_CONFIG> <DATABASE NAME="cegodb" PAGESIZE="4096" ADMINPORT="2000" LOGPORT="3000" DATAPORT="2200"> <MODULE NAME="ALL" LEVEL="NOTICE"></MODULE> </DATABASE>

For our first database sample, we save the XML data to a file cegodb.xml

Please note Some of the parameters should be edited just before creating any tablesets of the database. Later on, these parameters ( database name and pagesize ) should NOT be modified.

Step II - Create a database admin user

For authorization reasons, a database admin user should be created. This user is used later on to connect to the database for further admin actions. To create the database admin user, you have to call the cego program in the following manner

$ cego --mode=adduser --dbxml=cegodb.xml --user=cgadm/cgadm --role=admin

The mode parameter setadminuser invokes cego in the appropriate way to set the admin user. With the parameter --dbxml, a valid configuration file is expected. We use the XML file created in the first step. Username and password are specified with the --user option. The password is stored in a encrypted form in the configuration file. If the user already exists, the password is changed to the given value. Otherwise, a new user entry is created.
If called successful, the configuration file should contain a admin user entry as listed below.

<?xml version="1.0"?> <!DOCTYPE CEGO_DB_CONFIG> <DATABASE NAME="cegodb" PAGESIZE="4096" ADMINPORT="2000" LOGPORT="3000" DATAPORT="2200"> <USER NAME="cgadm" PASSWD="3469c5c767f9cd3dbfa6f84296c992e1"> </USER> </DATABASE>

The configuration file is prepared now to start up the database daemon.

Step III - Start the database daemon

To receive any database admin and client requests, the cego database daemon has to be started up. In a simple way, this is done with

$ cego --mode=daemon --dbxml=cegodb.xml cego daemon up and running ...

At default, the daemon program writes a log file cego.log to the directory, the daemon is started from ( you may change this using the --logfile parameter of the cego program ). You may trace the successful start procedure of the daemon by listing the logfile ( e.g. using tail -f )
Please note : For our first sample, the directory the daemon is started from should be readable and writable for the daemon. Logfile and database files are written to this location. If started successful, the database is ready to receive any connections.

Step IV - Connect to the daemon
Before any database client connections can be served, a valid tableset must be set up. To do this, we first connect to the database using the cgadm admin program.

$ cgadm --server=localhost --port=2000 --user=cgadm/cgadm CGADM >

With the option --server and --port options, valid host and port connection parameters are expected. The admin host port must match with the specified value in the database configuration file.

Step V - Define a tableset

Using the cgadm program, you can define a new tableset now. In a simple way, you just can type

CGADM > define tableset TS1; +-----------+---------------------+---------------------------------------------------+ | ADM | ADM | ADM | | ROLE | HOSTNAME | MSG | +-----------+---------------------+---------------------------------------------------+ | mediator | dude.local | Tableset defined | +-----------+---------------------+---------------------------------------------------+ Admin action successful ok ( 0.010 s )

The new defined tableset should be printed, if all registered tablesets of the database are listed.

CGADM > list tableset; +-----------+----------+-------------+---------------------+---------------------+---------------------+ | TSL | TSL | TSL | TSL | TSL | TSL | | NAME | RUNSTATE | SYNCSTATE | MEDIATOR | PRIMARY | SECONDARY | +-----------+----------+-------------+---------------------+---------------------+---------------------+ | TS1 | DEFINED | SYNCHED | dude.local | dude.local | dude.local | +-----------+----------+-------------+---------------------+---------------------+---------------------+ Admin action finished ok ( 0.037 s )

Step VI - Create the tableset

The new defined tableset can be created now. For this just type

CGADM > create tableset TS1; +-----------+---------------------+---------------------------------------------------+ | ADM | ADM | ADM | | ROLE | HOSTNAME | MSG | +-----------+---------------------+---------------------------------------------------+ | mediator | dude.local | Tableset TS1 created | +-----------+---------------------+---------------------------------------------------+ Admin action successful ok ( 0.092 s )

The run state of the tableset should have changed to state OFFLINE

CGADM > list tableset; +-----------+----------+-------------+---------------------+---------------------+---------------------+ | TSL | TSL | TSL | TSL | TSL | TSL | | NAME | RUNSTATE | SYNCSTATE | MEDIATOR | PRIMARY | SECONDARY | +-----------+----------+-------------+---------------------+---------------------+---------------------+ | TS1 | OFFLINE | SYNCHED | dude.local | dude.local | dude.local | +-----------+----------+-------------+---------------------+---------------------+---------------------+ Admin action finished ok ( 0.001 s )

To store any user data, a datafile should be added to the tableset.

CGADM > add app datafile './data01.dbf' size 300 to TS1; +-----------+---------------------+---------------------------------------------------+ | ADM | ADM | ADM | | ROLE | HOSTNAME | MSG | +-----------+---------------------+---------------------------------------------------+ | mediator | dude.local | Datafile added | +-----------+---------------------+---------------------------------------------------+ Admin action finished ok ( 0.030 s )

The given size of the datafile is given in units of pages. Based on a page size of 4096 bytes ( as specified with the database configuration file ) the new created datafile has a size of about 1.2 MB.

Step VII - Start the tableset

2.3 Using the first tableset

If the first tableset has been set up successful, it can be used as described in the following As another admin action, a database user has to be created by using cgadm. In the following, we create an database user lemke identified with the password lemke.

CGADM > add user lemke identified by 'lemke' to TS1; +-----------+---------------------+---------------------------------------------------+ | ADM | ADM | ADM | | ROLE | HOSTNAME | MSG | +-----------+---------------------+---------------------------------------------------+ | mediator | dude.local | Added user locally | +-----------+---------------------+---------------------------------------------------+ Admin action finished ok ( 0.001 s )

To allow user lemke to perform any database operations, add the role ALL to the user

CGADM > add role ALL to user lemke for TS1; +-----------+---------------------+---------------------------------------------------+ | ADM | ADM | ADM | | ROLE | HOSTNAME | MSG | +-----------+---------------------+---------------------------------------------------+ | mediator | dude.local | Role added | +-----------+---------------------+---------------------------------------------------+ Admin action finished ok ( 0.013 s )

You may use the cgclt program to connect to the cego server. We invoke the client program in interactive mode with the following command

$ cgclt --server=localhost --port=2200 --tableset=TS1 --user=lemke/lemke CGCLT >

Now we can create our first database table using the following sql command

CGCLT > create table mytab ( primary a int not null, b string(30) ); Table mytab created ok ( 0.002 s )

The created table can be checked using the tableinfo command. Since we have specified column a as a primary key, a primary index has been created for the table.

CGCLT > tableinfo mytab; +-------------------------------+----------------+----------------+ | TABLEINFO | TABLEINFO | TABLEINFO | | NAME | TYPE | PAGES | +-------------------------------+----------------+----------------+ | mytab | table | 1 | | mytab_pidx | primary index | 1 | +-------------------------------+----------------+----------------+ ok ( 0.002 s )

To put data into the table, you can use the SQL insert command

CGCLT > insert into mytab values ( 42, 'this is mytext'); Query executed ok ( 0.001 s )

Data can be retrieved using a SQL select command

CGCLT > select * from mytab; +-----------+-------------------------------+ | | | | a | b | +-----------+-------------------------------+ | 42 | this is mytext | +-----------+-------------------------------+ ok ( 0.023 s )

If you have reached this step, you have an up an running cego database system. Please see further sections for a more detailed view about the several features of the database system.