.
Eloquence B.07.10 contact contact

Documentation / TurboIMAGE compatibility

Eloquence TurboIMAGE compatibility

 
.
  This document covers the Eloquence TurboIMAGE compatibility extension.

Contents

Reference documentation

Getting started

Version history


Introduction to Eloquence

The Eloquence TurboIMAGE compatibility extension is an optional Eloquence component which provides a HP e3000 TurboIMAGE compatible programming interface ("intrinsics") for the Eloquence database. While not 100% compatible it is close so applications originating on the HP e3000 can be ported to the Eloquence database with no or only minor changes.

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

The Eloquence database is a client/server based architecture. All database access is performed by the database server on behalf of the application.
The Eloquence TurboIMAGE compatibility extension is a library of functions that translates the TurboIMAGE intrinsic calls into the native Eloquence API. This does not impose a performance impact.
  -----------------    -----------------
  |               |    |               |
  |  Application  |    |  Application  |
  |               |    |               |
  |---------------|    |---------------|
  |  EQ DB API    |    |  IMAGE3K API  |
  -----------------    |---------------|
          ^            |  EQ DB API    |
          |            -----------------
          |                   ^       
          |                   | 
          v                   v
    ----------------------------------
    |                                |
    |  Eloquence database server     |
    |                                |
    ----------------------------------
The IMAGE3K functions translate the TurboIMAGE calls into the Eloquence calls. An application using the IMAGE3K option calls the image3k library functions which then calls the Eloquence client side API.

Database Names

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 database name is no longer restricted to 6 characters and can include dots and hyphen characters in addition to letters and digits.

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

localhost:eloqdb/SAMPLEDB
:eloqdb/SAMPLEDB
SAMPLEDB
The environment variable EQ_DBSERVER can be used to specify the default database server. The syntax is as below:
[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.
For example:
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.
This is effective for all database utilities.

Database Security and Authorisation

The Eloquence database server maintains its own user list. In order to connect to the Eloquence database server a user name and password is required. Two predefined users, "dba" and "public" are created by default.

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.
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.
This makes sure the password is not exposed to other users which can use the ps utility to obtain the command line of executing processes or may have access to environment variables (on Linux through the /proc file system).

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.
This is effective for all database utilities.

Compiling/Linking

When compiling programs against the IMAGE3K API, it is recommended (but not required) to include the file image3k.h. This will provide the IMAGE prototypes to the compiler.

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.

The archive hp3ksrc.tar.Z includes the source code of the Eloquence migration utilities which can be compiled on the HP e3000 and with Eloquence. The following Makefile can be used to compile the example programs and link with the Eloquence database.
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)
Notes:
  • 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

There are two options to use Eloquence from Acucobol. Either the Eloquence image3k library is loaded dynamically by the application or the image3k library is linked to the runcbl cobol runtime. The notes below describe how to load the Eloquence image3k library dynamically.
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

With MF Cobol, the Eloquence image3k library is linked to the application. This makes the TurboIMAGE intrinsics available. The image3k library needs to be specified when linking the executable.

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

The Eloquence schema processor is compatible with TurboIMAGE schema files. In order to enable TurboIMAGE compatibility you need to specify the -T command line option.
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 -T option implies the -W72 option which causes characters beyond column 72 to be ignored by default. This will ignore any editor line numbers if the file has been saved with line numbers. The -W command line option allows to specify a line width other than 72 (0 = off).

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
dbschema is a small script file which is installed with Eloquence and simply calls the schema processor with the -T option.
#!/bin/sh
# dbschema - default to TurboIMAGE compatible schema processor

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


Database Properties

Database properties can be used to define the image3k default behavior. Database properties are defined with the dbutil utility (interactively or with the dbutil scripting capabilities).

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.


 
 
 
  Privacy | Webmaster | Terms of use | Impressum Revision: 2007-03-29  
  Copyright © 1995-2024 Marxmeier Software AG