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
[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 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).
- 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, 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.
|
