Getting started with the Eloquence A.06.00 database

2 Introduction

Getting started with the Eloquence A.06.00 database

This section intends to provide a quick start to the new database. While this document is a bit UNIX centristic, it applies to the Windows NT platform as well.

The examples below assume, that the data base server is running on a system called "server" and is listening on port number 8800. If the server is running on the local system, you could simply omit the host name. If the server is listening on the port mapped to the eloqdb service, you can omit the port number as well. Of course, you could also use a service name instead of the port number.

Create a data base environment

Login to your server system. The server system must have been configured before. The configuration is described more detailed in the Installation and Configuration manual.

On Windows NT, the data base server must have been registered with the Windows NT Service control manager.
The TCP service name eloqdb should have been mapped to a port number (unless you intend to use the port number directly).
Create a new user account and group for use with the data base server (not required on Windows NT)

Create a server configuration

First you need to create a server configuration file. You can either use the template file in /opt/eloquence6/newconfig/config/eloqdb6.cfg or start from the scratch. Since most configuration items are optional and provide a reasonable default it's actually easy to start with an empty file.

# eloqdb6.cfg
[Server]
Service=8800
UID = eloq
GID = eloq
LogFile = /tmp/eloqdb6.log

[Volumes]

Short description of the configuration settings:

On Windows NT the UID and GID entries are not supported.
On UNIX, you should create a separate uid/group for use with the Eloquence data base. All data base volume files are owned by the "data base user". For testing purposes it is also possible to use your own user/group.
Service = 8800

By providing a port number we are not required to create the configuration in /etc/services and we do not desturb any other running eloqdb6 server. Of course, the port number must not already be in use.

LogFile = /tmp/eloqdb6.log

All server log messages will be written into the file /tmp/eloqdb6.log. You should use an absolute path here, because the current directory of the server could be a different than you expect. If you omit this entry the server log is written to the syslog (UNIX) or the Event Log (Windows NT) by default.

[Volumes]

This section is initially empty and will be filled in by the dbvolcreate and dbvolextend utilities.

Create the server root volume

dbvolcreate is used to create a new volume set. You need a config file with an empty [volumes] section.

dbvolcreate -v -c eloqdb6.cfg /path/volume01.vol

This creates the root volume /path/volume01.vol with the default size (~2.5 MB) and adds the volume path to the volume section of the config file. The config file could even be empty during volume creation, but it must exist.

Additional dbvolcreate options.

   -s sz    initial volume size in MB
   -e sz    chunks the volume is extended by (MB)
   -m sz    max volume size (MB)

Create the log volume

Next you need to create a log volume. The server refuses to start without one. The dbvolextend utility is used to create additional volumes.

dbvolextend -v -c eloqdb6.cfg -t log /path/volume02.vol

This will create the log volume and append it in the volume section of the config file. Additional dbvolextend options.

   -s sz    initial volume size in MB
   -e sz    chunks the volume is extended by (MB)
   -m sz    max volume size (MB)

The log volume will need at least enough space to hold all commited transactions between two check points. So starting a huge dbimport with a large CheckpointFreq setting may cause the log volume to grow and use a huge amount of disk space.

Start the server

Next start the server. Logging into a file with mode "*1" is probably a good idea in the beginning. This example will set the log mode on the commandline but it can also be defined in the config file (see eloqdb6.cfg).

On UNIX:

eloqdb6 -d"*1" -c eloqdb6.cfg

On Windows NT:

You normally start the data base server from the Windows NT control panel. You could also start the data base server from the commandline by specifying the -standalone option. However this is only considered a debug tracking option and should not be used regulary.

eloqdb6 -standalone -d"*1" -c eloqdb6.cfg

If the server comes up, you sucessfully created a db environment. Else have a look at the log file (/tmp/eloqdb6.log in this example).

If you kill the server (please no -9 or you will have stuck IPC resources) or if the server did crash due to a problem, all committed but not yet completed transactions are recovered automatically.

Create a data base

Since we now should have the server up and running, all remaining actions follow the client/server model. So you should now login to your client system.

The new data base server does no longer use ROOT files. Instead it includes a special data base (the system catalog) which is used to hold the data base structure. Actually, there are several catalogs: One which is used to hold server global information and a seperate one for each data base. You can use the dbdumpcat utility to have a look into the server catalogs. The new data base provides its own authorization scheme and list of users.

The server has two predefined users, "dba" and "public" which are created when the database environment is generated. By default the user dba has administrative capabilities (for example it can create a new data base) but is not allowed to access any data. The user "public" by default has no administrative capabilities but is allowed to access the data base contents. The user "public" is also used as a default user whenever a data base is opened without providing authorization information to the server (please refer to the DBLOGON statement more information).

The dbutil utility can be used to create additional users and to maintain the access rights.

Create a data base

The new schema utility transmits the data base structure from a SCHEMA file to the data base server:

schema -u dba -h server -s 8800 db.txt

This will create the data base catalog on the specified server. The server name can be omitted if the server is running on the local system. Specifying a service name or port number can be omitted if the server is using the default eloqdb service.

The -u dba is required. It will identify you as user dba to the server. All commandline tools use $LOGNAME as the default user. After the schema succeeded, you should be on known grounds. dbcreate and dbimport should work as expected.

dbcreate -u dba server:8800/db
dbimport -vs db.exp -u public server:8800/db

Please note, that the -u public argument is required. It will identify you as user public to the server. All commandline tools use $LOGNAME as the default user.

Eloquence Database Manual - 19 DEC 2002