New Functionality and enhancements

Contents:

• Overview

• Database limits
• Description of new item types

• Environment variables
  • Database name
  • Authorization

• Database utilities
  • Default user authorization
  • Schema processor
  • Other database utilities

• Database API functions
  • DBOPEN status codes
  • DBFIND mode 6 and 7
  • DBINFO mode 303
  • DBINFO mode 505

• DBUTIL utility
  • Command line usage
  • Database structural maintenance
  • Interactive usage
  • Dbutil script syntax

• Forward-logging
  • Introduction
  • Recovering from abnormal server termination
  • Forward-log configuration
  • Forward-log management
  • The dbrecover utility

Overview

• Performance enhancements

  The B.07.00 database server reduces the number of write requests to the transaction log volume by bundling them to a single request whenever possible. This can result in significantly better write performance compared to the A.06.31 eloqdb6. During write operations such as DBPUT or DBUPDATE the performance gains can be up to 25%.

• Improved reliability in case of abnormal server termination

  An improved log volume format ensures data integrity should the server terminate abnormally. Assuming the data and log volumes have not been corrupted (eg. by a disk failure or an operating system problem) the volumes will be successfully recovered during the next server startup. More ...

• Forward logging functionality

  The forward logging functionality provides additional protection against system failure and speeds up recovery in case of a fatal problem. Forward logging retains a log of all changes since the last backup. In case of a system failure those changes may be re-applied to the last backup, thus ensuring that no data is lost and database integrity is maintained. More ...

• Increased database (schema) limits

  The database limits have been modified to follow or extend the current TurboIMAGE limits. More ...

• Native support of TurboIMAGE item types

  The items types supported by TurboIMAGE on the HP3000 are now supported. More ...

• Default database server and user can be specified in the environment

  The EQ_DBSERVER, EQ_DBUSER and EQ_DBPASSWORD environment variables can be used to specify the default database server, user and password. More ...

• New DBFIND mode 6 and 7

  The DBFIND modes 6 and 7 have been added. For now they are only used internally with the TurboIMAGE compatibility API. More ...

• New DBINFO mode 303

  The DBINFO mode 303 has been added to return sort item along with the path information. This supplements DBINFO mode 301 which does not support sort items. More ...

• New DBINFO mode 505

  The DBINFO mode 505 has been added and returns a list of all data sets which contain a specific index item. More ...

• Improved dbutil utility

  The dbutil utility has been changed substantially. It provides an interactive user interface to allow easy management of database security options and database properties. The dbutil scripting abilities have been improved to support database structural maintenance and other adminitrative operations. More ...

Database limits

Resource	Limit
Data items / database	2048
Data sets / database	500
Paths / data set, detail / master	16 / 64
Item length	4096 bytes
Entry length	5120 bytes
Media length	8000 bytes
B-tree index key size	256 bytes

The database utilities have been modified to support the new limitations. Previous Eloquence versions will refuse to open a database which exceeds internal limits.

Description of new item types

I - signed integer

Type I supports now arbitrary sizes. For example I32 (I16 in TurboIMAGE compatibility mode) specifies a 256 bit signed integer. Please note that the item size must have an even number of bytes.

K - unsigned integer

Type K supports arbitrary sizes. For example K64 (K32 in TurboIMAGE compatibility mode) specifies a 512 bit unsigned integer. Please note that the item size must have an even number of bytes.

U - upper case string

This is identical to type X (string) but content is automatically changed to upper case.

P - packed decimal

Type P supports packed decimal values (fixed comma, no exponent). Each digit occupies a nibble (4 bit, half byte) with the last nibble specifying the sign. Item size is specified in bytes (half bytes in TurboIMAGE compatibility mode), for example a P2 indicates a two byte item (P4 in TurboIMAGE compatibility mode). Please note that the item size must have an even number of bytes.

Nibble packed BCD format. The last nibble indicates the sign or is an indicator for an unsigned value.

sign	meaning
0xc	positive value
0xd	negative value
0xf	unsigned value

Z - zoned decimal

Type Z supports decimal values (fixed comma, no exponent). Each digit occupies a byte with the last byte specifying the sign in addition to the digit. Item size is specified in bytes, for example a Z4 indicates a four byte item. Please note that the item size must have an even number of bytes.

The last character in a zoned format indicates the sign in addition to the digit value. Unsigned values don't use a sign so the last character is a digit.

digit	positive	negative
0	{	}
1	A	J
2	B	K
3	C	L
4	D	M
5	E	N
6	F	O
7	G	P
8	H	Q
9	I	R

Environment Variables

Env.Variable	Description
EQ_DBSERVER	Specifies the host and port to connect by default. Previous Eloquence versions connected to localhost:eloqdb unless specified otherwise.
EQ_DBUSER	Specifies the default user to connect the database server. Previous Eloquence versions used the login id of the operating system as the default database user. If the user starts with file: it is considered a reference to a file where the first line holds the user id and the second line the password. See below for a detailed description.
EQ_DBPASSWORD	Specifies the default password used to connect the database server. Previous Eloquence versions used no password as the default. If the password starts with file: it is considered a reference to a file holding the password. See below for a detailed description.
EQ_DBAPI_LOGFLAGS	Specifies the logging flags used with the Eloquence database client library. This is intended to allow logging of database operations with custom applications.
EQ_DBAPI_LOGFILE	Specifies the log file to be used with EQ_DBAPI_LOGFLAGS. the default is stderr.

The Eloquence client side API and all database tools have been modified to support the EQ_DBSERVER, EQ_DBUSER and EQ_DBPASSWORD environment variables.

The example below describes how to use a the user name "mike" with a password in the file $HOME/eqdb_pswd as the default authorization information. The default database server to contact is set to lxsrv:8302.

   $ export EQ_DBSERVER=lxsrv:8302
   $ export EQ_DBUSER=mike
   $ export EQ_DBPASSWORD=file:$HOME/db_pswd

Database Name

Eloquence databases do not reside in the file system but are managed by a server process. Consequently, a database name no longer refers to a location in the file system but specifies the database server instance and the database on that server.

The database name consists of the following elements:

 [[host][:service]/]database

• The host name or IP address on which the database server resides. The default is the local system (localhost or IP address 127.0.0.1).

• The service name or port number which is used by the server process on that machine. The default is defined by the service name eloqdb which defaults to port 8102 during installation.

• The database name. If the host name or service is specified it is separated with a slash from the database name.

The examples below specify the database SAMPLEDB on the local system, using the default database server instance:

  localhost:eloqdb/SAMPLEDB
  :eloqdb/SAMPLEDB
  SAMPLEDB

 [host][:service]

• The host name or IP address on which the database server resides. The default is the local system (localhost or IP address 127.0.0.1).

• The service name or port number which is used by the server process on that machine. The default is defined by the service name eloqdb which defaults to port 8102 during installation.

If the EQ_DBSERVER environment variable is set to lxsrv:8302 then a DBOPEN will default to connect the database server running on host lxsrv at the port number 8302.

Authorization

Eloquence requires to use the DBLOGON call to provide authorization information when connecting to a database. By default Eloquence will use the user "public". For administrative tasks (such as schema) Eloquence defaults to the user "dba".

In order to authorize with the Eloquence database server the DBLOGON call is used. Once a user and password has been specified it is saved and used with subsequent DBOPEN.

The user name or password can be a reference to a file which holds the actual user name and/or password.

• If the user name starts with file: it is expected to be a reference to a file. The first line is used as the user name and if present a second line is used as the password.

• If the password starts with file: is is expected to be a reference to a file. The first line of that file is used as the user password.

The environment variables EQ_DBUSER and EQ_DBPASSWORD can be used to specify the default user and password.

For example:

If the environment variable EQ_DBUSER is set to "mike" and the EQ_DBPASSWORD variable is set to "file:/home/mike/db_pswd" and the file db_pswd holds the string "secret" the user name "mike" and the password "secret" are used by default to access the database.