contact contact

A practical aproach to the new Eloquence A.06.00 data base

  Release Notes
Since almost no documentation is available on the new data base yet this document intends to provide a practical aproach to use the new data base. While this document is UNIX centristic, it applies to the 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. If you have not done yet, please configure the server system now. The configuration is described in detail in the Eloquence 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

UID = eloq
GID = eloq
LogFile = /tmp/eloqdb6.log

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 a log volume, because the server will refuse 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 CheckpointFreq=60 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).

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, the 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. By default there are two different users "dba" and "public".

The server has two predefined users, "dba" and "public" which are created when the data base 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 new DBLOGON statement from 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.

Dumping the server catalog

The dbdumpcat utility can be used to have a look at the global server catalog or a data base specific catalog:
dbdumpcat -u public -h server -s 8800
This will dump the global server catalog.
dbumpcat -u public -h server -s 8800 dbname
This will dump the catalog specic to dbname.

Please be aware that you can have any number of data bases in a db environment. Dumping the catalogs might give a better understanding how structural information is handled internally - it's completely different than the old ROOT file aproach.

  Privacy | Webmaster | Terms of use | Impressum Revision:  2002-11-18  
  Copyright © 1995-2002 Marxmeier Software AG