ADABAS D on Linux - HowTo

Introduction

ADABAS D is a high-performance database, which efficiently and easily utilizes system resources and is portable across several UNIX, Linux, Windows 95 and NT platforms. By combining ease of administration with high performance, ADABAS D is an ideal database system for workgroup and business-critical applications in client-server environments.

Although ADABAS D is capable to handle gigabytes of data, Software AG provides free versions (Personal Edition) on Windows 95/NT and Linux, limited to a data volume of 24 MegaByte and 3 concurrent user sessions. This Personal Edition will be called PE in this HowTo document for short.

There are two unlimited versions of ADABAS D available for Linux called ADABAS D Workgroup Edition (Entry) for 10 concurrent user sessions and ADABAS D Workgroup Edition (Business) for an unlimited number of users.
This Linux Workgroup Edition will be abbreviated as LE in this document.

This HowTo tells you everything you should know to install either the Personal Edition (PE) or Workgroup Edition (LE) on a Linux System.

If you find something important missing or if you know some hints making life easier with Adabas D on Linux, send an email to the author (address see below), who will probably insert your notes into this paper.

Here is an overview of the following sections.

The first chapter Requirements describes the minimal equipment of your computer and the environment you should create on your system before installing Adabas D.

Then chapter Installation will describe the installation process and tries to give you some clues, what to do in the unlikely case it fails.

After this, chapter Using the RDBMS tries to give some hints, what to do with the ready-installed database server, e.g. administration of the server, building an application, using the tools...

Finally, chapter Trouble shooting gives some hints what to do, if anything doesn't work the way it should.

Requirements

• You must have a CD-ROM player and the ability to mount the filesystem of the CD.
• You should create a special database user and database group
• The environment of all users who want to use Adabas D must have set the environment variables DBROOT and PATH appropriately.
• The upper limit of the size of a shared memory segment must be high enough (not a problem for Linux 2.0 or greater).

CD-ROM

You can do the mount as an ordinary user if there is a line in /etc/fstab for your CD-ROM device with the user option. Note that turning on the user option automatically sets noexec. So be sure to explicitly add the exec option for your CR-ROM device or use the -o exec option as command line argument, to allow execution of programs from this file system.

Database user

For a single user desktop system it is sufficient to use the normal user account and group you always login in. Nevertheless it is recommended that you create a user adabas and a group database (these names aren't fixed, but used everywhere throughout this HowTo). Since you must be able to login using this account, you should give it a login shell and DBROOT (see below) as home directory.

Later on during installation you have to enter the name of the user and group into the installation program, which will set the ownership of all installed files to this user. (You could as well change the user and group owner later using chown, but that's is not the preferred method)

DBROOT

This directory will become the root directory of your Adabas D database; we will call it DBROOT from now on. For examples in this HowTo we will use /usr/local/adabas as DBROOT.

To use the database, you must have set the environment variable DBROOT pointing to this directory. You can add the following line to the file /etc/profile:
DBROOT=/usr/local/adabas; export DBROOT
Then for all users this variable is set automatically. If you don't want to fiddle with /etc files, you can add this line to the file .profile in the homedirectory of every user using Adabas D respectively.

PATH

Shared memory

For a Linux System prior to 2.0 it is defined in /usr/src/linux/include/linux/shm.h and its value is 0x400000. Since Adabas needs a litte more even for a system with only five users and normal-sized caches, you have to increase this limit.

For newer Linux Systems (2.0 or later) it is defined in /usr/src/linux/include/asm/shmparam.h and its value is 0x1000000. A properly configured database for five users will hardly need more than 16MB, so you can live with this default. But be aware of the fact that you still have to adjust some parameters during the installation of an own new database, since the default values require more than 16MB (see section Creating your own database).

If you have to increase the constant, edit the include file and look for a row that starts with #define SHMMAX. Replace the number by e.g. 0x1000000.

Creating a new Linux kernel depends on the distribution you use. If you are booting with LILO, a call of make zlilo is all you need. Otherwise a call of make zImage will create a compressed kernel and you have to install it manually after this.

Installation

For installation you should be logged in as the database user (in our examples adabas). If you are logged in as a different user, you should become the database user by means of the su command. If you are sitting in front of an X display, you have to allow other accounts to connect to your X server by typing the following command before issuing the su:
xhost +myHostName

The installation with a graphical interface can be started by
/cdrom/install&
First you should select the packages to install; the default choice (the database software itself and the preconfigured example database MYDB) is a good point to start with. Then click through the five points in order.

Note that there is a small inconvenience in the file selection dialogs, you will get into in the first two points. They allow only a selection of files (and not directories), so that you can't push the Okay button if your DBROOT directory is still empty (and probably it is!). You can avoid this by calling install with two parameters (source dir and DBROOT) like this:
/cdrom/install /cdrom $DBROOT&

If for any reason no X display is available, you have to issue the following commands instead:
/cdrom/install.lnx
x_install

Creating your own database

If you don't want to install the preconfigured database MYDB or if you want to create another database, you can do this with the DBA tool xcontrol.

There are three parameters you must adjust, since the default values are of little value for the average Linux box.

• DATA_CACHE_PAGES: The default of 5000 pages is probably overconfigured for a desktop system. The data cache will reside in shared memory and 5000 pages are 20MB. The limit for shared memory (SHMMAX) in an unmodified Linux kernel is 4MB or 16MB (see also section Shared memory), so you have to decrease this value or rebuild your Linux kernel.

You can shrink it down to a value of 200, but if you have enough RAM and SHMMAX is big enough, a value between 1000 and 2000 seems to be better (more cache is always better!).
• OPMSG1: Since there is virtually no linux system with the device /dev/syscon, you better fill in the name of an existing device or file here (like /dev/null or /dev/console).
• MAXUSERTASKS: This parameter determines the maximum number of simultanious client connections to the database server. Its value has influence on many other internal buffer and cache sizes, so you better follow the advice, given in the help text of this parameter:

Don't overconfigure this parameter.
For the PE it is limited to max. 3 anyway. For a one user system 3 or 4 users should be enough.
You better decrease the default of 50 for the LE unless you really want to work with that many connections. And if the limit is really too low, you can increase it anytime.

Using the RDBMS

State of a database server

offline

The database kernel is not running at all; no resources are occupied. An application trying to connect will answer database not running

cold

The database kernel is running, but will not respond to the normal SQL commands; only some maintenance commands are allowed (notably RESTART). An application trying to open a normal user connection will get the error -8000 (database must be restarted).

warm

The database kernel is running, and will respond to the normal SQL commands.

start.sh:

    #!/bin/sh
    x_start MYDB
    xutil -d MYDB -u control,control restart

    #!/bin/sh
    xutil -d MYDB -u control,control shutdown
    x_stop MYDB

    #!/usr/local/adabas/bin/adabastclsh
    exec x_start MYDB
    set l [adalogon control,control -serverdb MYDB -service utility]
    adautil   $l restart
    adalogoff $l

    #!/usr/local/adabas/bin/adabastclsh
    set l [adalogon control,control -serverdb MYDB -service utility]
    adautil   $l shutdown
    adalogoff $l
    exec x_stop MYDB

The following is an init script for use with the S.u.S.E boot concept (starting with version 4.4.3). You can put the following lines into a file /sbin/init.d/adabas and make soft links to e.g. /sbin/init.d/rc3.d/S25adabas and /sbin/init.d/rc3.d/K15adabas. Then the database kernel will get automatically started and stopped when you switch into or out of runlevel 3.

#! /bin/sh

. /etc/rc.config

[ -z "$DBROOT" -o -z "$DBUSER" -o  -z "$DBNAME" -o -z "$DBCONTROL" ] && exit

export DBROOT DBUSER DBNAME DBCONTROL

case "$1" in
    start)
        echo "Starting Adabas D."
        su $DBUSER -c $DBROOT/bin/adabastclsh << 'EndOfScript'

# ------------- BEGIN StartScript BEGIN -----------------
if [catch {exec $env(DBROOT)/bin/x_start $env(DBNAME)} msg] {
    puts $msg
    exit
}
if [catch {adalogon $env(DBCONTROL)  -serverdb $env(DBNAME) -service utility} l] {
    puts $l
    exit
}
if [catch {adautil $l restart} msg] {
    puts $msg
    exit
}
adalogoff $l
# --------------  END  StartScript  END  ----------------

EndOfScript
;;
    stop)
        echo -n "Shutting down Adabas D:"
        su $DBUSER -c $DBROOT/bin/adabastclsh << 'EndOfScript'
    
# -------------- BEGIN StopScript  BEGIN ----------------
if [catch {adalogon $env(DBCONTROL)  -serverdb $env(DBNAME) -service utility} l] {
    puts "\n$l"
    exit
}
catch {adautil $l shutdown}
adalogoff $l

if [catch {exec $env(DBROOT)/bin/x_stop $env(DBNAME)} msg] {
    puts "\n$msg"
    exit
}
puts " stopped."
# --------------  END  StopScript   END  ----------------

EndOfScript
;;

      *)
            echo "Usage: $0 {start|stop}"
            exit 1
esac

#
# Adabas D on Linux (Software AG)
#
# If you want to start Adabas D, the relational database system,
# automatically on system reboot, give values to DBROOT, DBNAME
# DBUSER and DBCONTROL.
#
# DBROOT: The top directory of the Adabas D installation.
#
DBROOT=/usr/local/adabas
#
# DBNAME: The name of the database you want to start at
#         system boottime.
#
DBNAME=MYDB
#
# DBUSER: The name of the unix account, to whom all the
#         Adabas files belong.
#
DBUSER=adabas
#
# DBCONTROL: The connect string of the adabas control user in the
#            form <name>,<password> or ,<userkey>.
#            Example for MYDB: control,control
#
DBCONTROL=control,control
#

The User file

• The system DBA (data base administrator), the only user who can create other users with DBA access. In the preconfigured MYDB the user/password combination is superdba,admin.
• The control user, who can call the administration tools xcontrol, x_param, xutil and panel. In MYDB it is control,control.
• The domain user, who owns all the system tables and views. There should be no need to connect as domain user; in MYDB it is domain,domain.

My user file contains the following entries:
Userkey DEFAULT for krischan,geheim
Userkey c for control,control
Userkey demo for demo,demo
Userkey sys for superdba,admin

Having this file I can call the tools with the -U option as shown in the following examples. Note, that the last two examples are actually the same thing.

    panel   -Uc
    xquery  -Usys
    fotos   -Udemo
    tkquery -UDEFAULT
    tkquery

Embedded SQL in C (for Web Applications, too)

sqlinit: DBROOT must be set !!!

SetEnv DBROOT /usr/local/adabas

ODBC

Tcl

Trouble shooting

The program install doesn't execute

The graphical install program hangs while extracting the archives

The problem occurs with the first edition of the PE, if your tar program gives the date of a file in the form yyyy-mm-dd and not separated by blanks. This seems to be the case in newer Caldera systems. There is no workaround; you have to use install.lnx and x_install (see chapter Installation).

Cannot read param file...

In every case step 4 of the installation process (call of the postinstallation script x_install) wasn't finished properly. This is a hard to notice when working with the graphical setup, since the xterm closes immediately after termination of the installation script, so that an error message is visible only a very short time.

To fix this problem, first make sure, that there exists a /usr/spool directory. Since the normal path of the spool directory is /var/spool on most Linus systems, you can create a soft link at /usr/spool pointing to /var/spool. Finally call $DBROOT/bin/x_install as superuser.

Cannot create rundirectory 0

• Cannot create rundirectory 0
• Run-directory 0 is missing
• Run-directory (null) is missing
• -20022 Invalid value entered: 3

The program which investigates one configuration parameter ($DBROOT/pgm/getparam) simply returns 0, if it can't find or read this file. But you can't create a directory 0...

The bottom line is that you should call the administration tools only as the user who was mentioned to x_install during installation (see also section Database user).

You can call tools non administration tools like tkquery or xquery as every user, just be sure to set DBROOT and to modify PATH by adding :$DBROOT/bin.

If there appears a warning like the following (even if the mentioned directory exists and gives permissions to read/write):
sql22_msg: cannot create directory 'dbroot/wrk/unix-account': ERRNO 13
you can ignore it or change the permissions of both dbroot/wrk and dbroot/wrk/unix-account.

sqlinit: cannot find user name for uid xxx!

If your account is registered in the yellow pages of the NIS service, you will get the same error. Currently there seems to be no tested workaround other than to insert your account into the local /etc/passwd.

Perhaps it may work to add lines like the following into /etc/nsswitch.conf to avoid the second problem. Since I have no NIS on my local network, I can't test it. But I'm looking forward a mail of someone, who can.

passwd: files nisplus nis
shadow: files nisplus nis
group:  files nisplus nis

Cannot open /dev/syscon

To avoid this message, enter /dev/null as OPMSG1, in the Install Serverdb or Configuration/Alter Parameters/Kernel dialog.

The kernel dies while starting.

Under some circumstances no correct kernel diagnose file would be written; this seems to be the case only, if you create a new database with xcontrol (the recommended way). In this case you have to leave xcontrol and start the database kernel manually from the shell prompt by entering x_start .

There are three critical sections, where the start up of the database kernel may be aborted. Here we will describe them in the order, they appear.

• sql41_create_shm: shmget error, Invalid argument

The first limit to get by is the limit of shared memory. The database kernel reports near line 8 of the knldiag the amount, it requests from the Linux kernel. This line may look like this:
... creating shared section size 4911104
If the requested amount of shared memory is available, some more lines are written giving pointers to start and end of the memory segment. If your shared memory has a limit that is smaller than the wanted segment size, there is a line complaining about an invalid argument. See section Shared memory for a description, how to increase your limit.
• shareddynpool too small in xparam

If there is a line in knldiag complaining about a too small value of shareddynpool, most probably something went wrong with x_param during the configuration of the new database.
When you create a new database with xcontrol and choose the Stepwise option, a screen with some values for e.g. SHMMAX should appear after the installation of the parameters. If instead a nearly blank screen will be displayed, x_param didn't finish its work. Although xcontrol gives you the option to continue, you should cancel the installation, since the database kernel will refuse to start anyway with a line in knldiag saying something like:
WARNING: shareddynpool too small in XPARAM.
As it seems this error only occurs when xcontrol was started in in a shell with a huge environment (i.e. there are lots of environment variables with long values). To prevent this error inspect your environment by means of the unix command env and unset some environment variables with e.g. unset TERMCAP.
• area for task-stack-allocation is STACK

If there is a line like the one above in knldiag directly befor the kernel dies with an signal 11 (segmentation violation), then the stack usage of your database kernel is bigger than the stack limit.
When the line above is printed into the knldiag file, the database kernel is testing for every of its separate processes, whether the maximal procedure stack usage fits onto the stack. He does this by calling repeatedly a procedure until the procedure stack grows to the wanted size. If there is a limitation of the stack size of one process, the Linux kernel send a segmentation violation signal.
The stack limit for a non root unix account is 8 MB (defined in /usr/src/linux/include/linux/sched.h). You can increase this value and install a new kernel. But there is a more elegant way to work around this limit.
There is a hidden parameter in the database configuration, which tells the database kernel, where it should create the area for the procedure stack. The default value for this is STACK; this is what the line above says, too. You can switch it to DATA, then the procedure stack is created on the data heap. The data segment of one process is typically unlimited and if there is not enough space on the heap, no signal is send by the Linux kernel. Instead a null pointer is returned, which can be handled more gracefully by the database kernel.
You can switch the parameter at the unix prompt with:
$DBROOT/pgm/putparam TASK_STACK_AREA DATA

Clients connect only to hosts listed in /etc/hosts

The reason for this behaviour is a missing file /etc/nsswitch.conf, where you can configure the used nameservices. This file must contain at least the follwoing line, so that the Adabas D runtime system uses name services.

hosts:  files nisplus nis dns

unknown service 'sql30' (see /etc/services)

To avoid this error, be sure to give no -n option, don't put a hostname into the -d option and leave the server node entry in the user file empty.

If you really need to connect to a server on a different host, you have to upgrade to the LE.

-20035 Remote SQL Server could not be started

Since xcontrol uses the ps command with system V style parameters, it cannot correctly determine, if the Remote SQL server is running. To prevent this error, set the environment variable PS_PERSONALITY to POSIX before starting xcontrol. This can be done on the command line of a bourne shell like the following.

PS_PERSONALITY=POSIX xcontrol -d MYDB -u demo,demo

The GUI tools terminate with an error

• The DISPLAY variable is not or incorrectly set; set the environment variable DISPLAY to contain the name of your computer followed by :0.
• The access to the display isn't granted. Use the xhost program to allow access from your computer.
• The PATH variable must contain $DBROOT/bin (see section PATH). It isn't sufficient to call the tools with an absolute path name without setting the PATH, since they internally call an interpreter program located in $DBROOT/bin.

Error -8000 while loading system tables

Bug reports

Everything concerning Adabas D on Linux itself should be posted to comp.databases.adabas if of general enough nature. Note that both (PE and LE) are not directly supported by Software AG. Should you encounter serious problems, please see http://www.sag.de/linux1.htm to order support and upgrade service at the Linux reseller of your choice.

Have fun, Krischan

Christian Krone
krischan@cs.tu-berlin.de