Contents

• Introduction to Eloquence
  • Eloquence TurboIMAGE compatibility
  • Database Names
  • Database Security and Authorisation
  • Compiling/Linking
  • Using Eloquence with Acucobol
  • Using Eloquence with MF Cobol

• The schema processor
• Database properties

Reference documentation

• Database intrinsics
• TPI support
• DBINFO modes

Getting started

• TurboIMAGE database migration

Version history

• Changes to previous version
• Known Problems & Limitations

Introduction to Eloquence

Some visible differences are:

• Integrated indexing capabilities.
• We no longer use hashing. So there are no "migrating secondaries" and no set level locking is required in order to add or delete an entry from a master set.
• Capacity is no longer relevant. The Eloquence database grows dynamically when required (including master data sets).
• Additional locking capabilities.
• Additional database utilities including database restructuring.
• Multiplatform (HP-UX, Windows NT/2000/XP, Linux).
• Network transparent.
• Dynamic, nested transactions, transaction isolation (uncommitted changes are not visible to other processes).
• Deadlock detection and recovery.
• On-line backup and forward recovery.
• New, more flexible security subsystem.
• The Eloquence database does not reside in the file system but uses volume files which reside in the file system as a container for the data and structural information.
• Eloquence does not use a ROOT file. Structural information is kept in the database (in the database catalog).

Eloquence TurboIMAGE compatibility

  -----------------    -----------------
  |               |    |               |
  |  Application  |    |  Application  |
  |               |    |               |
  |---------------|    |---------------|
  |  EQ DB API    |    |  IMAGE3K API  |
  -----------------    |---------------|
          ^            |  EQ DB API    |
          |            -----------------
          |                   ^       
          |                   | 
          v                   v
    ----------------------------------
    |                                |
    |  Eloquence database server     |
    |                                |
    ----------------------------------

Database Names

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.

Database Security and Authorisation

For each database access groups define the access rights. This is the equivalent of the TurboIMAGE user classes which can be defined in the PASSWORDS: section in the schema file. The schema processor creates two default groups "public" and "dba". The group "dba" provides the right to erase a data set and the group "public" has the access rights defined for user class 0. Other groups are created and provide the access rights defined in the schema file.

Users can be associated with up to eight access groups and get the summary rights associated with the access groups. Unless associated with a security group, no access to the database is possible. By default, the schema processor associates the user "dba" with the group "dba" and the user "public" with the access group "public" and all other access groups defined in the schema file. This can be changed with the dbutil utility.

Eloquence requires to use the DBLOGON call to provide authorisation information when connecting to a database. By default Eloquence will use the user "public" which is the equivalent to the UCL 0 with TurboIMAGE. For administative tasks (such as schema) Eloquence utilities default to the user "dba".

Authorisation information can be provided in different ways:

• You can explicitely use the DBLOGON call to specify a user name and password which is then used with a subsequent DBOPEN.

• With the TurboIMAGE compatibility API you can use the DBOPEN password argument to specify a user and password. This will result in an implicit call to DBLOGON.

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.

Compiling/Linking

The following change should be considered in a portable 'C' program which can be used on the HP e3000 and with Eloquence:

#if defined(_MPEXL_SOURCE)
#pragma intrinsic DBOPEN
...
#pragma intrinsic DBEXPLAIN
#else
#include "image3k.h"
#endif

This causes include file image3k.h to be used when not compiling for MPE.

The program needs to be linked against the Eloquence image3k library which implements the TurboIMAGE intrinsics. The library name depends on the platform: libimage3k.sl (HP-UX), libimage3k.so (Linux) or image3k.lib (Windows).
The Eloquence image3k library has a dependency on the Eloquence database client library which is loaded automatically at runtime (libeqdb.sl on HP-UX, libeqdb.so on Linux, eloqdb32.dll on Windows). It is not necessary to explicitly link against the Eloquence database client API library.

The IMAGE3K library uses the native calling convention of the operating system. On the Windows platform the 'C' calling convention (cdecl) is used. When calling it from a language other than 'C' (for instance COBOL) please make sure to specify the correct calling convention.

The IMAGE3K library uses the native byte order to encode integer or floating point values. This is "big endian" on HP-UX and "little endian" on Linux and Windows. When calling the IMAGE3K library you may need to specify arguments as "call by reference" and "native byte order" to get the correct results if the programming environment internally uses a different encoding.

Eloquence by default uses the HP-ROMAN8 character set on the HP-UX platform and the ISO-8859-1 character set encoding on the Windows and Linux platforms. When the database server is using a different platform (eg. Client on Windows, Server on HP-UX) all values and strings are converted on the fly by the Eloquence database library.

Depending on the platform, the Eloquence libraries and 'C' header files are installed in different locations:

• HP-UX:
  

  The various Eloquence library versions are located in subdirectories in /opt/eloquence6/lib to support multiple library versions:

  pa11_32	PA-RISC 1.1 compatible libraries (32 bit)
  pa20_32	PA-RISC 2.0 libraries (32 bit)
  pa20_64	PA-RISC 2.0 libraries (64 bit)
  hpux32	IA64 32 bit libraries (Itanium)
  hpux64	IA64 64 bit libraries (Itanium)

  The 'C' header files are installed in the /opt/eloquence6/include directory.

• Linux:
  

  The Eloquence libraries are located in the /opt/eloquence6/lib directory and the 'C' header files are installed in the /opt/eloquence6/include directory.

• Windows:
  

  The shared libraries (.dll, used at runtime) are installed in the Windows system directory, e.g. C:\Windows\System32. This ensures the Windows dynamic linker is able to locate them without specifying a path.
  The stub libraries (.lib, used to link against) and 'C' header files are installed in the Eloquence lib and include installation subdirectories, e.g. C:\Programs\Eloquence\lib and C:\Programs\Eloquence\include.

Example programs (written in 'C') using the TurboIMAGE API are available for your reference.

• FTP protocol
  ftp://ftp.marxmeier.com/eloq/B0710/mpe/migration

• HTTP protocol
  http://eloquence.marxmeier.com/download/B0710/mpe/migration/

CFLAGS = -O -D_POSIX_SOURCE -I/opt/eloquence6/include
LIB = -L/opt/eloquence6/lib -limage3k
all: hp3kinfo hp3kexport
hp3kinfo: hp3kinfo.c
        $(CC) -o $@ $(CFLAGS) hp3kinfo.c $(LIB)
hp3kexport: hp3kexport.c
        $(CC) -o $@ $(CFLAGS) hp3kexport.c $(LIB)

• The leading spaces in the makefile must be tab characters.

• On HP-UX, the required library version subdirectory must be specified in the library path, e.g. -L /opt/eloquence6/lib/pa20_32 for the 32 bit PA-RISC 2.0 libraries.

Using Eloquence with Acucobol

HP-UX

1. Add the following line to the etc/cblconfig configuration file:

   SHARED-LIBRARY-EXTENSION .sl
   

2. Load the libimage3k.sl from within your program (once per application). This makes the TurboIMAGE intrinsics available:

   CALL "/opt/eloquence6/lib/pa11_32/libimage3k.sl".
   

   On HP-UX on the Itanium architecture the 64 bit library must be loaded instead:

   CALL "/opt/eloquence6/lib/hpux64/libimage3k.sl".
   

Linux

1. Load the libimage3k.sl from within your program(once per application). This makes the TurboIMAGE intrinsics available:

   CALL "/opt/eloquence6/lib/libimage3k.so".
   

2. On Linux and Windows (little-endian) you should consider to use the -D5 compile option.

Windows

1. load the image3kc.dll from within your program(once per application). This makes the TurboIMAGE intrinsics available:

   CALL "image3kc.dll".
   

2. On Linux and Windows (little-endian) you should consider to use the -D5 compile option.

Notes:

• On little endian architectures (Intel) the COMP-5 type must be used with the Eloquence image3k library (rather than COMP). The Eloquence library uses the native byte order of the underlying system while the cobol COMP data type uses the big endian byte order for all systems, independendly of the underlying architecture. The -D5 compiler option maps all COMP data types to COMP-5. Subsequent Eloquence versions will likely allow to remove this requirement.

• On Windows the image3k.dll and image3kc.dll are available. The image3k.dll uses the stdcall (aka. "pascal") calling convention which is standard on Windows. The image3kc.dll (note the additional 'C') uses the cdecl calling convention as an alternative which is assumed by default by Acucobol.

Using Eloquence with MF Cobol

Notes:

• On little endian architectures (Intel) the COMP-5 type must be used with the Eloquence image3k library (rather than COMP). The Eloquence library uses the native byte order of the underlying system while the cobol COMP data type uses the big endian byte order for all systems, independendly of the underlying architecture. The following compiler directive maps all COMP data types to COMP-5:

  MAKESYN "COMP-5" = "COMP"
  

  Subsequent Eloquence versions may provide an option to remove this requirement.

• On Windows the image3k.dll and image3kc.dll are available. The image3k.dll uses the stdcall (aka. "pascal") calling convention which is standard on Windows. The image3kc.dll (note the additional 'C') uses the cdecl calling convention as an alternative which is assumed by default by MF Cobol (image3kc requires calling convention 0, image3k requires calling convention 74).

• For compatibility with 'Z' item format you also need to set the SIGN "EBCDIC" MF compiler directive to specify the sign is at the end (same format as TurboIMAGE). The MF default assumes the sign is at the beginning.

The schema processor

usage: schema [options] schema_file
options:
 -u user    - set user name
 -p pswd    - set password
 -h host    - host to contact
 -s service - service name or or port number
 -b name    - specify database name
 -l         - output source listing           (LIST)
 -n         - no root file, only check syntax (NOROOT)
 -t         - output set table                (TABLE)
 -e cnt     - Abort after cnt error messages  (ERRORS=)
 -T         - HP3000 TurboImage compatibility mode
 -W width   - Limit line length to width
 -L         - Add line number to source listing

The Eloquence schema processor does not require $CONTROL directives. Most common settings can be specified from the command line. Command line options take precendence over $CONTROL directives.

$CONTROL	Equiv. Option
$CONTROL NOLIST	default
$CONTROL LIST	-l
$CONTROL ROOT	default
$CONTROL NOROOT	-n
$CONTROL TABLE	-t
$CONTROL ERRORS=	-e

The following notes apply to the Eloquence schema processor:

• The /INDEXED option is accepted but has no effect. Currently, Eloquence does not support the TurboIMAGE btree. For indexed access to the database you need to create index items and define an index for the detail data set. IMAGE btree access ("superchains") will be added with a feature patch after the B.07.00 release.

• $CONTROL options are supported but most have no effect since they are specific to TurboIMAGE implementation details which have no equivalent with Eloquence.

• $CONTROL ODDPALLOWED is not supported and P items using an odd number of nibbles are not allowed. Eloquence internally maintains item sizes in bytes and cannot handle sub-item sizes below a byte.

• Item- and data set names are considered case insensitive. The characters valid in an item- or data set name is more limited in Eloquence. If you get a syntax error due to an invalid data set or item name please consider changing to a valid name or send a bug report.

• The data set capacity is not retained. DBINFO modes 202 and 205 return the max. number of records allocated for a data set.

• The schema processor assigns the "public" user to all database access groups which effectively defaults to public access to the database. You can use the dbutil utility to modify the database access rights.

As an alternative to running schema directly, you can also use the dbschema script. Both commands shown below are equivalent.

schema -T schemafile
dbschema schemafile

#!/bin/sh
# dbschema - default to TurboIMAGE compatible schema processor

ELOQUENCE=${ELOQUENCE:-/opt/eloquence6}
exec $ELOQUENCE/bin/schema -T $@

Database Properties

Database properties are stored in the sysdbproperties table of the database catalog. To use database properties with a database, the database must have been created with the B.07.00 database server (PR#7 or above).

Property	Description
HP3K_LANG	This property defines the database language id as returned by DBINFO mode 901. It has no effect on the database operation. The default language id is zero.
HP3K_CIUPDATE	This property defines the default value of the CIUPDATE flag. This value returned by DBINFO mode 502. The default value for the CIUPDATE flag is 1 (ALLOWED).
HP3K_BTREEMODE1	This property defines the default value of the BTREEMODE1 flag. The default value for the BTREEMODE1 flag is 1 (ON).
HP3K_WILDCARD	This property defines the default wildcard character used with BTREEMODE1. The default value is "@".
HP3K_SUBSYSTEM	this property defines the default SUBSYSTEM access as returned by DBINFO mode 501 and was historically used by the TurboIMAGE QUERY application. It has no effect on the database operation. The default SUBSYSTEM access is 3 (RW).

Database properties used by the image3k library can be defined with the SET command of dbutil. The syntax used is similar to TurboIMAGE.

SET LANGUAGE = n;

Set the TurboIMAGE LANGUAGE property to n where n is a numerical value.

Note:

• The value of the LANGUAGE property is returned by DBINFO mode 901.
• This statement sets the HP3K_LANG database property.

SET CIUPDATE = mode;

Set the TurboIMAGE CIUPDATE property to mode where mode is DISALLOWED, ALLOWED or ON.
The default value is ALLOWED.

Note:

• The value of the CIUPDATE property is used by DBUPDATE and returned by DBINFO mode 502.
• This statement sets the HP3K_CIUPDATE database property.

SET BTREEMODE1 = mode;

Set the TurboIMAGE BTREEMODE1 property to mode where mode is ON or OFF.
The default value is ON.

Note:

• The value of the BTREEMODE1 property is used by DBFIND and returned by DBINFO mode 113.
• This statement sets the HP3K_BTREEMODE1 database property.

SET WILDCARD = "c";

Set the TurboIMAGE WILDCARD property to c where c is a valid ASCII character.
The default value is @.

Note:

• The value of the WILDCARD property is used by DBFIND and returned by DBINFO mode 113.
• This statement sets the HP3K_WILDCARD database property.

SET SUBSYSTEM = mode;

Set the TurboIMAGE SUBSYSTEM property to mode where mode is NONE, READ or RW.
The default value is RW.

Note:

• The value of the SUBSYSTEM property is returned by DBINFO mode 501.
• This statement sets the HP3K_SUBSYSTEM database property.