Eloquence  Eloquence B.07.00 Release Notes

Eloquence B.07.00 - TurboIMAGE compatibility

TurboIMAGE compatibility

This document covers the Eloquence TurboIMAGE compatibility extension and the TurboIMAGE database intrinsic calls.

[ Main document | Back ]

Contents:


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 HP Eloqunece 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 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 ACU Cobol

There are two options to use Eloquence from ACU Cobol. 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 ACU Cobol.

  • ACU Cobol version 5.2.1 on HP-UX (PA-RISC) may need the ACU patch ecn1767 to load shared libraries.

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 is specified with the linker.

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 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 MF Cobol (image3kc requires calling convention 0, image3k requires calling convention 74).


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.


Database Intrinsics

The Eloquence TurboIMAGE compatibility extension provides all TurboIMAGE intrinsics. Due to differences in the underlying implementation some details may differ from TurboIMAGE. For each TurboIMAGE intrinsic call a short description is provided along with notes which describe possible Eloquence specific behavior or limitations.

List of database calls.

Additional database documentation: Related documentation:
  • HP3000 TurboIMAGE documentation 30391-90012, revision E0701
    an on-line version is available at at http://docs.hp.com ( HTML PDF ).

General Remarks

This section provides some general overview which applies to all database calls.
  1. The Eloquence database implements transaction nesting and transaction isolation. So nesting of dynamic transactions is allowed and modified information is not exposed to concurrent sessions until the transaction is committed. A concurrent read access outside the transaction context returns the unmodified information.

  2. Database "intrinsics" might return different status values in case of "unusual" situations. While all common status values are converted to TurboIMAGE conventions, Eloquence status values differ from TurboIMAGE and not all can be translated. If you discover a problem please send us a message so we can investigate the situation and improve the status translation.

  3. In case of a status error, status elements 6 .. 10 are different from TurboIMAGE. They include additional Eloquence specific information.

    Element Contents
    6 Native Eloquence function id.
    7 Native Eloquence status code.
    8-9 Native Eloquence secondary status code.
    10 Native Eloquence mode

  4. In addition to ' ' (space) and ';' (semicolon) a NUL character is also accepted as a delimiter/terminating character.

  5. Database, data set and item names are not case sensitive.

  6. The Eloquence database procedures may provide additional modes and functionality (eg. Index access, locking modes). Additional Eloquence functionality has been made available in a non-conflicting manner so aware applications can make use of additional functionality.

  7. Eloquence does not enforce locking. It's optional and there are no special requirements depending on data set types or transactions. The Eloquence database handles concurrency internally through transactions. So you are free to use locking according to the requirement of your application. Instead of checking if a write access is covered by a lock Eloquence checks if a concurrent lock has been granted. In this case a write attempt will return with a database status.

  8. Eloquence does not use hashing. So there are no secondaries in master sets.

  9. The Eloquence schema processor is able to process the TurboIMAGE schema syntax (you need to specify the -T commandline option).

    The item types J and R are not supported natively and are only visible to the TurboIMAGE emulation.

    • The 'R' item type is supported in TurboIMAGE compatibility only, values are expected to be encoded in IEEE format. Native Eloquence considers this an 'E' type.
    • The 'J' item type is supported in TurboIMAGE compatibility only. Native Eloquence considers this an 'I' type.

  10. The Eloquence security system differes from the traditional IMAGE model. A user name and password is required to connect to a database. Unless specified a default user ("public") is used.
    A user name and password can be specified either by using the Eloquence specific DBLOGON call or providing a user name and password with DBOPEN.

  11. Item level security is not implemented. All items are considered writable.

  12. Data set and item numbers passed as a qualifier conflict with single character data set or item names on little endian machines (Intel) when a NUL character is used as a separator. When specifying single character data set or item name you must use a separator other than a NUL character.

  13. Static transactions are currently not supported with Eloquence and DBBEGIN, DBEND and DBMEMO have no effect. Eloquence relies on dynamic transactions internally. A future version of Eloquence may add support for static transactions for use with forward recovery or auditing purposes.

DBOPEN

Initiates access to the database and establishes the user class number and access mode for all subsequent database access. DBOPEN is used in conjunction with DBCLOSE to establish and terminate access to a database. 

DBOPEN(base,password,mode,status)
base
is the name of an integer array containing a string of ASCII characters. The string must consist of two blanks followed by a left-justified database name and terminated by a semicolon, a space or a NUL character, for example, " orders;". Please refer to the section on Database Names for detailed information.

If the database is successfully opened, the two blanks are replaced with a value called the base ID. The base ID uniquely identifies this access path between the database and the process calling DBOPEN. In all subsequent accesses to the database, the first halfword of base must be this base ID; therefore, the array should not be modified. The base ID contains a number that distinguishes between the 63 access paths allowed for each process for accessing a given database.

password
is the name of an integer array containing a left-justified string of ASCII characters consisting of an optional password followed by an optional user identifier.

The following constructs are valid for the password and user identifier (a _ represents a blank): 

   password [{_;}[/USERIDENT{_;}]]
   
   [/USERIDENT]{_;}          Provides user name and empty password
   ;[/USERIDENT{_;}]         Same
   password[/USERIDENT]{_;}  Specifies user name and password
The password or the user identifier string must be terminated by a semicolon, space or NUL character. Since Eloquence does not assume a fixed length, a termination character should alsways be present.

Unless the password and the user identifier string is present, the password argument is ignored. Please refer to the section on Database Security and Authorisation for detailed information.

mode
is an integer between 1 and 9, inclusive. See discussion below for a summary.

status
is the name of an array of 10 halfwords in which the database returns status information about the procedure. If the procedure executes successfully, the status array contents are:
Element Contents
1 If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2 User id as defined by the server. Id 1 specfies the default dba user and 2 the default public user.
3-4 Zero
5-10 Information about the current procedure call and its results.

DBOPEN modes

  • TurboIMAGE/XL supports the following DBOPEN modes:
    • Mode 1: modify DB, lock enforced, allow concurrent modify/read - 1,5
    • Mode 2: update DB, allow concurrent update/read - 2,6
    • Mode 3: modify DB, exclusively
    • Mode 4: modify DB, allow concurrent read - 6
    • Mode 5: read DB, allow concurrent modify/read - 1,5
    • Mode 6: read DB, allow concurrent read/modify - 6/2, 6/4, 6/8
    • Mode 7: read DB, exclusively
    • Mode 8: read DB, allow concurrent read - 6/8

  • Eloquence natively supports the following DBOPEN modes:
    • Mode 1: modify DB, allow concurrent read/modify
    • Mode 3: modify DB, exclusively
    • Mode 8: read DB, allow concurrent read
    • Mode 9: read DB, allow concurrent read/modify

  • The Eloquence TurboIMAGE compatibility option supports all DBOPEN modes:
    • Modes 1, 3, 8 are equivalent
    • Modes 2, 4 are mapped to mode 1
    • Modes 5, 6 are mapped to mode 9
    • Mode 7 is mapped to mode 8
    • Mode 9 is available in addition

Notes:

  • The Database name is not limited to 8 characters and must follow the Eloquence conventions.
    The database name must either be separated by a NUL character, a semicolon or a space character. Since Eloquence database names are not limited to a fixed length a terminating character must be present.
    Please refer to the section on Database Names for detailed information.

  • Remote database handling is different (the server instance is encoded with the database name).

  • Eloquence uses a different access control scheme than TurboIMAGE. The Eloquence database maintains users with passwords. The user name and password can either be specified with the DBOPEN password argument or the Eloquence specific DBLOGON call can be used. It no user name is specified a default user ("public") is used. Status element 2 returns the user id which is different from the user class returned by TurboIMAGE.
    Please refer to the section on Database Security and Authorisation for detailed information.

  • If a user name is present in the password argument (the optional "identifier") it is used as authorisation information with the database server. If only a password is present the password argument is ignored and the default user ("public") is used which is the Eloquence equivalent to user class 0.

  • Eloquence does not implement "Creator Access". Instead an adminstrative access group ("dba") is added to each database which by default is associated with the default adminstrative user ("dba"). The dba group does not grant access to the database contents but can only be used to maintain the database. The dbutil utility program can be used to grant additional access rights to the dba group.

  • Eloquence users and passwords are not limited to 8 characters. However due to the design of the TurboIMAGE API the IMAGE3K library is unable to reliably determine the bounds of the password and user argument unless a termination character is present (either space or semicolon) or a NUL character is used to terminate the password argument. It is recommended that the password and the optional identifier are terminated with a space or semicolon character.

  • Only modes 1, 3, 5, 8 are fully compatible. All other modes are mapped and usually do not impose concurrency restrictions.
    • Mode 6 allows concurrent modification
    • Mode 9 is available in addition

  • Access to database is denied unless at least read access for a single data set is granted to the user. This is different than TurboIMAGE which assigns user class 0 if an invalid password is used or no access rights are granted with a password.

  • A status -104 is returned by DBOPEN if the separate IMAGE3K license key has not been installed on the database server.

DBCLOSE

Terminates access to a database or a data set, or rewinds a data set. DBCLOSE is used in conjunction with DBOPEN to establish and terminate access to a database. 

DBCLOSE(base,dset,mode,status)
base
is the name of an array used as the base parameter when opening the database. The first element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.)

dset
is the name of an array containing the left-justified name of the data set to be closed, or is an integer referencing the data set by number if mode equals 2 or 3. If mode equals 1, this parameter is ignored. The data set name can be up to 16 characters long. If shorter, it must be terminated by a semicolon, a space or NUL character.

mode
is an integer equal to 1, 2, or 3 indicating the type of termination desired.

status
is the name of an array of 10 halfwords in which the database returns status information about the procedure. If the procedure executes successfully, the status array contents are:
Element Contents
1 If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2-4 Unchanged from previous procedure call using this array.
5-10 Information about the current procedure call and its results.

Notes:

  • Mode 2 is the same as mode 3.
  • Mode 1 does not abort a dynamic transaction. Eloquence transactions are not database specific so this cannot be enforced. Eventually we should abort/roll-back an eventually pending dynamic transaction on a DBCLOSE.

DBCONTROL

DBCONTROL(base,qualifier,mode,status)
base
is the name of an array used as the base parameter when opening the database. The first element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.)

qualifier
used only for certain DBCONTROL modes.

mode
must be an integer equal to 1, 2, 5, 6, 7, 9, 10, 13, 14, 15, 16, 18, 19 or 20.

status
is the name of an array of 10 halfwords in which the database returns status information about the procedure. If the procedure executes successfully, the status array contents are:
Element Contents
1 If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2-4 Unchanged from previous procedure call using this array.
5-10 Information about the current procedure call and its results.

DBCONTROL modes

Mode Description
1 Turn on the deferred output option (AUTODEFER). This mode is accepted but has no effect with Eloquence.
2 Turn off the deferred output option (AUTODEFER). This mode is accepted but has no effect with Eloquence.
5 Enable the critical item update option (CIUPDATE). Mode 5 enables the CIUPDATE option for the current DBOPEN until either a DBCONTROL mode 6 call disables the option or the database is closed. With Eloquence CIUPDATE is allowed but disabled by default.
6 Disable the critical item update option (CIUPDATE). Mode 6 disables the CIUPDATE option for the current DBOPEN until either a DBCONTROL mode 5 call enables the option or the database is closed. With Eloquence CIUPDATE is allowed (but not enabled) by default.
7 Allow the database to be included in the dynamic multiple database transaction (DMDBX) and enable the database for deadlock detection. This mode is accepted but has no effect with Eloquence.
9 Enable the HWMPUT option of DBPUT for the current DBOPEN. This mode is invalid with Eloquence, the application has no control over record placement. Assuming the application requesting this mode expects a specific behavior this mode will result in a status error.
10 Disable the HWMPUT option of DBPUT for the current DBOPEN. This mode is invalid with Eloquence, the application has no control over record placement. Assuming the application requesting this mode expects a specific behavior this mode will result in a status error.
13 Allow a privileged mode caller to perform B-Tree related tasks such as adding, dropping, rebuilding, releasing, or securing a B-Tree index file. Exclusive database access is required to add, drop, or rebuild a B-Tree index. Qualifier has a structured record containing dataset information and directives. This mode is not supported with Eloquence.
14 Allow a privileged mode caller to set BTREEMODE1 option to ON or OFF and set wildcard character for the database (permanent). This mode is not supported with Eloquence.
15 Enable B-Tree wildcard search for DBFIND mode 1, X and U types, for the master data set's key item and its corresponding search items in details, if the key item has a B-Tree index. In other words, turn on the BTREEMODE1 flag for the current database open. The first byte of the qualifier is examined. If it is null or blank, then the current wildcard character is not changed. If it is in the ASCII range (33...126), then the wildcard character is changed to that value for the current DBOPEN. If the qualifier is any other value, DBCONTROL returns an error.
Affects only the current database open. It needs to be done once per database and remains activated until the database is closed or the application terminates. This mode allows you to perform B-Tree searches on ASCII types without making application changes. This mode is currently not supported with Eloquence.
16 Disable B-Tree wildcard search for DBFIND mode 1 regardless of the existence of a B-Tree index. That is, turn off the BTREEMODE1 flag for the current database open. The qualifier is ignored, and BTREEMODE 1 is turned off. Affects the current database open only. It needs to be done once per database and remains activated until the database is closed or the application terminates. This mode is currently not supported with Eloquence.
18 Enables the XM to return a warning when the dynamic transaction exceeds the 28MB threshold. This mode is accepted but has no effect with Eloquence.
19 Disables the XM to return a warning when the dynamic transaction exceeds the 28MB threshold. This mode is accepted but has no effect with Eloquence.
20 Allows the program to overwrite the DBUTIL 'OLDINFOLIMITS' setting. DBINFO mode 103 returns data items in a database; DBINFO mode 203 returns data sets in a database; DBINFO mode 204 returns all data sets with an item and DBINFO mode 301 returns paths for a specific data set. If a user program allocates arrays to store the data returned from above DBINFO calls and the size of the arrays are defined by the old TurboIMAGE item/set limit. Then a database with new item/set limit may cause the program to abort.
This mode is accepted but has no effect with Eloquence. Eloquence expects an application which assumes specific database limits to the database limits using DBINFO mode 406.

Notes:

  • AUTODEFER (mode 1, 2) is accepted but has no effect

  • HWPUT (mode 9, 10) is not accepted and results in status -31. The application has no control over record placement. Assuming the application requesting this mode expects a specific behavior this mode will result in a status error.

  • CIUPDATE is always considered allowed (but disabled by default)

  • betreemode1 is considered enabled by default

  • Modes 1, 2, 7, 18, 19, 20 are accepted but have no effect with Eloquence.

  • Modes 9, 10, 13, 14 are not supported with Eloquence and result in status -31.

  • Database open mode and transaction status is not checked

DBINFO

Provides information about the database being accessed. The information returned is restricted by the user class number established when the database is opened; any data items, data sets or paths of the database which are inaccessible to that user class are considered to be non-existent. 
DBINFO(base,qualifier,mode,status,buffer)
base
is the name of an array used as the base parameter when opening the database. The first element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.)

qualifier
is the name of an array containing a data set/data item name or an integer referencing a data item/data set, depending on the value of the mode parameter. This parameter form is identical to the dset and item parameters for DBFIND, and the dset and list parameters for DBPUT.

mode
is an integer indicating the type of information desired.
Please refer to the document on DBINFO modes for detailed information on valid DBINFO modes, qualifiers and buffer.

status
is the name of an array of 10 halfwords in which the database returns status information about the procedure. If the procedure executes successfully, the status array contents are:
Element Contents
1 If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2 Length of information in buffer array (in halfwords).
3-4 Unchanged from previous procedure call using this array.
5-10 Information about the current procedure call and its results.

buffer
is the name of an array in which the requested information is returned. The contents of the buffer array vary according to the mode parameter used.

Please refer to the document on DBINFO modes for detailed information on valid DBINFO modes, qualifiers and buffer.


DBLOCK

Applies a logical lock to a database, one or more data sets, or one or more data entries. 
DBLOCK(base,qualifier,mode,status)
base
is the name of an array used as the base parameter when opening the database. The first element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.)

qualifier
The qualifier argument depends on the mode:
  • Modes 1,2,11,12: Ignored
  • Modes 3,4,13,14: An integer variable referencing the data set number or the name of an array containing a data set name. Could also be "@" when applying a database lock.
  • Modes 5,6,15,16: The name of the array containing the lock descriptors.

mode
contains an integer indicating the type of locking desired. Valid modes are 1 to 6 and 11 to 16.

status
is the name of an array of 10 halfwords in which the database returns status information about the procedure. If the procedure executes successfully, the status array contents are:
Element Contents
1 If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2 The number of lock descriptors that were successfully applied in the DBLOCK request. For successful locks in modes 1 through 4 and 11 through 14 this will be 1.
3 Zero. TurboIMAGE used to return additional information for a return status 20 which is not available with Eloquence: If the return status is 20, this element contains 0 if the database is locked, 1 if the data set or entries are locked.
4 Unchanged from previous procedure call using this array.
5-10 Information about the current procedure call and its results.

DBLOCK modes:

Lock
Mode		 Lock
Level		 Locking Type Description
1 Base Unconditional DBLOCK applies an unconditional lock to the entire database, returning to the calling program only after the lock is successful (or if an error occurs). The qualifier parameter is ignored.
2 Base Conditional DBLOCK applies a conditional lock to the entire database and returns immediately. A return status of zero indicates success. A non-zero return status indicates the reason for failure.
3 Set Unconditional DBLOCK applies an unconditional lock to a data set. The qualifier parameter must specify the name of an array containing the left-justified name of the data set or the name of an integer referencing the data set number. The data set name can be 16 characters long or, if shorter, terminated by a semicolon or blank.
The data set need not be accessible for read or write access to the user requesting the lock.
4 Set Conditional DBLOCK applies a conditional lock of the same type as mode 3. It always returns to the calling program immediately. A return status of zero indicates success and a non-zero return status indicates a reason for failure.
5 Entry Unconditional DBLOCK applies unconditional locks to the data entries specified by lock descriptors. The qualifier parameter must specify the name of an array containing the lock descriptors. It returns only when all the locks have been acquired.
6 Entry Conditional DBLOCK applies conditional locks of the same type as mode 5. If multiple lock descriptors are specified and DBLOCK encounters a lock descriptor that it cannot apply, it returns. All locks that have been applied until that point are released.
Modes 1 through 6 request a write lock. Modes 11 through 16 are identical but request a read lock. A write lock does block any concurrent read or write lock. A read lock blocks concurrent write locks but allows current read locks.

Notes:

  • With the Eloquence database, locking is optional. DBLOCK is not enforced to allow read or write access.

  • Multiple locks are allowed. Details are subject to the server configuration (eloqdb6.cfg):
    • AllowSecondaryBlockingLock needs to be set to 1 to allow secondary blocking ("Unconditional") locks. For historic reasons they are not enabled by default.

      If set, secondary blocking locks are allowed. Normally, secondary locks in a blocking (odd) mode will fail with database status -135 ("Second lock is not allowed in modes 1,3,5,11,13 and 15.") instead of blocking. Enabling this setting could result in a deadlock detected by the database when programs use an incompatible lock strategy.

    • LockConflictingItems needs to be set to 1 to allow DBLOCK to assume different items locking an entry do not conflict. By default this is set to 0.

      If set, predicate locks with conflicting items are granted, however any write attempt to data where another process owns a lock will result in a status error -12. By default Eloquence does not allow a predicate lock with a conflicting item, because this could lead to a situation where two processes own a lock on an overlapping subset of data.

    We recommend to set AllowSecondaryBlockingLock = 1 and LockConflictingItems = 0 in the server configuration.

  • Subsequent "unconditional" locks will return a database status when they would cause a deadlock. However a deadlock condition is never returned for a program only using a single lock or only conditional locks.

  • A compound lock descriptor is applied atomically. There is no need to DBUNLOCK in case of a failed lock request.

  • Additional modes 11-16 are available for read locking.

  • In mode 3,4,13,14 passing "@" as the qualifier is currently not supported.

  • Due to a bug in the IMAGE3K library, status element 2 currently returns zero instead of the number of lock descriptors. However, since Eloquence applies lock descriptors atomically, a zero status indicates all lock descriptors are granted and a a failure indicates no lock descriptor was accepted.

  • With TurboIMAGE status element 3 indicates for a return status 20 if the database is locked (0) or if the data set or entries are locked (1). With Eloquence this is always zero.

DBUNLOCK

Relinquishes the locks acquired by all previous calls to DBLOCK. If the calling process has the same database opened multiple times, only those locks put into effect for the specified access path are unlocked. 
DBUNLOCK(base,qualifier,mode,status)
base
is the name of an array used as the base parameter when opening the database. The first element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.)

qualifier
The qualifier argument depends on the mode:
  • Modes 1 (2,11,12): Ignored
  • Modes 3 (4,13,14): An integer variable referencing the data set number or the name of an array containing a data set name. Could also be "@", when releasing a database lock.
  • Modes 5 (6,15,16): The name of the array containing the lock descriptors.

mode
contains an integer indicating the type of unlock desired. Valid modes are 1, 3, 5, 11, 13 and 15. Modes 2, 4, 6, 12, 14 and 16 are also accepted as an alias.

status
is the name of an array of 10 halfwords in which the database returns status information about the procedure. If the procedure executes successfully, the status array contents are:
Element Contents
1 If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2 Zero. TurboIMAGE used to return the number of lock descriptors that were released.
3-4 Reserved for internal use.
5-10 Information about the current procedure call and its results.

DBUNLOCK modes other than mode 1 are specific to Eloquence. It allows to selectively release a lock if called with the same mode and qualifier as DBLOCK.

Notes:

  • DBUNLOCK is allowed during dynamic transactions. However the lock will not be released until the transaction ends.
  • With Eloquence status element 2 is always zero. TurboIMAGE used to returrn the number of released locks.
  • Modes other than mode 1 are specific to Eloquence.

DBPUT

Adds new entries to a manual master or detail data set. The database must be opened in write mode. 
DBPUT(base,dset,mode,status,list,buffer)
base
is the name of an array used as the base parameter when opening the database. The first element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.)

dset
is the name of an array containing the left-justified name of the data set to which the entry is to be added, or is an integer referencing the data set by number. The data set name can be up to 16 characters long. If shorter, it must be terminated by a semicolon, a space or the NUL character.

mode
must be an integer equal to 1.

status
is the name of an array of 10 halfwords in which the database returns status information about the procedure. If the procedure executes successfully, the status array contents are:

list
is the name of an array containing an ordered set of data item identifiers; names or numbers. The new entry contains values supplied in the buffer array for data items in the list array. Search or sort items defined for the entry must be included in the list array. Fields of unreferenced items are filled with binary zeros.

The list array can contain a left-justified set of data item names, separated by commas and terminated by a semicolon or blank; no embedded blanks are allowed, and no name can appear more than once. For example: 

 ACCOUNT,LAST-NAME,CITY,STATE;
When referencing by number, the first halfword of the list array is an integer n that is followed by n single positive integers identifying unique data item numbers. Example: 4 1 10 3 16 lists for the four data item numbers 1, 10, 3, and 16.

The list specifies data items for which values are supplied in the buffer array, and is saved internally by TurboIMAGE as the current list for the data set. The current list is unchanged until a different list is specified in a subsequent call to DBGET, DBPUT, or DBUPDATE for the same access path and data set.

Some special list constructs are allowed. List processing involves some overhead which can be shortened in subsequent calls by using the asterisk construct to specify that the current list is to be used. Be sure a current list exists before using the asterisk construct, or a null list is assumed.

buffer
is the name of an array containing data item values to be added. The values must be in the same order as their data item identifiers in the list array.
Element Contents
1 If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2 Length of logical entry in buffer array (in halfwords).
3-4 Word record number of new entry (32 bit).
5-6 Word count of number of entries in chain (32 bit). If detail data set, chain is current chain of new entry.
7-8 If detail, word record number of predecessor on current detail chain (32 bit).
9-10 If detail, word record number of successor on current detail chain (32 bit).

Special List Parameter Constructs:

Construct list Array Contents Purpose
Empty 0; or 0_ or _ (0 must be ASCII) Request no data transfer.
Empty Numeric 0 (n, length of data item identifier list, is zero) Request no data transfer.
Asterisk *; or *_ Request procedure to use previous list and apply it to same data set. If "*" is used to define the list in the first call to DBGET and DBPUT it is treated as a zero.
At-sign @; or @_ Request procedure to use all data items of the data set in the order of their occurrence in the entry.
Note: _ indicates a space character.

Notes:

  • With the Eloquence database, locking is optional. A write attempt which is covered by a concurrent DBLOCK returns status -12.
  • Synonym chain information (for master data set) is always zero.

DBDELETE

Deletes the current entry from a manual master or detail data set. The database must be opened in write mode. 
DBDELETE(base,dset,mode,status)
base
is the name of an array used as the base parameter when opening the database. The first element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.)

dset
is the name of an array containing the left-justified name of the data set to which the entry is to be added, or is an integer referencing the data set by number. The data set name can be up to 16 characters long. If shorter, it must be terminated by a semicolon, a space or the NUL character.

mode
must be an integer equal to 1.

status
is the name of an array of 10 halfwords in which the database returns status information about the procedure. If the procedure executes successfully, the status array contents are:
Element Contents
1 If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2 Zero.
3-4 Word record number of new entry (32 bit).
5-6 Word count of number of entries in chain (32 bit). If detail data set, chain is current chain of entry.
7-8 If detail, word record number of predecessor on current detail chain (32 bit).
9-10 If detail, word record number of successor on current detail chain (32 bit).

Notes:

  • With the Eloquence database, locking is optional. A write attempt which is covered by a concurrent DBLOCK returns status -12.

  • Synonym chain information (for master data set) is always zero.

  • Status elements 3-10 were left unchanged by TurboIMAGE for detail data sets but are modified by Eloquence.

DBUPDATE

Modifies values of data items in the entry residing at the current record address of a specified data set. The database must be opened in write mode. The update is always carried out correctly against the latest version of the data, regardless of modifications made by other users.

You can use DBUPDATE to modify the values of detail data set search and sort items if permitted by the critical item update (CIUPDATE) option settings or using mode 2. This includes master data set key item values if no detail is connected. 

DBUPDATE(base,dset,mode,status,list,buffer)
base
is the name of an array used as the base parameter when opening the database. The first element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.)

dset
is the name of an array containing the left-justified name of the data set to which the entry is to be added, or is an integer referencing the data set by number. The data set name can be up to 16 characters long. If shorter, it must be terminated by a semicolon, a space or the NUL character.

mode
must be an integer equal to 1 or 2.

status
is the name of an array of 10 halfwords in which the database returns status information about the procedure. If the procedure executes successfully, the status array contents are:

list
is the name of an array containing an ordered set of data item identifiers, either names or numbers. Values supplied in the buffer array replace the values of data items occupying the same relative position in the list array. The user class established when the database is opened must allow at least read access to all the items included in the list array.

The list array can contain a left-justified set of data item names, separated by commas and terminated by a semicolon or a blank. No embedded blanks are allowed and no name can appear more than once.

When referencing by number, the first element of the list array is an integer n followed by n unique data item numbers (one-halfword positive integers).

The list not only specifies the data items to be updated immediately but is saved internally as the current list for this data set. The current list is unchanged until a different list is specified in a subsequent call to DBGET, DBPUT, or DBUPDATE for the same access path and data set.

Some special list constructs are allowed. These are described in Special List Parameter Constructs with the DBPUT procedure. List processing involves some overhead which can be shortened in subsequent calls by using the asterisk construct to specify that the current list is to be used.

buffer
is the name of an array containing data item values to be added. The values must be in the same order as their data item identifiers in the list array. The number of halfwords for each value must correspond to the number of halfwords required by its type multiplied by the sub-item count. Search and sort item values can be included in this update list if their values will not change unless mode 2 is used or the CIUPDATE flag is set.
Element Contents
1 If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2 Length of logical entry in buffer array (in halfwords).
3-4 Word record number of new entry (32 bit).
5-6 Word count of number of entries in chain (32 bit). If detail data set, chain is current chain of new entry.
7-8 If detail, word record number of predecessor on current detail chain (32 bit).
9-10 If detail, word record number of successor on current detail chain (32 bit).

Notes:

  • With the Eloquence database, locking is optional. A write attempt which is covered by a concurrent DBLOCK returns status -12.

  • Synonym chain information (for master data set) is always zero.

  • Additional mode 2 is available which has the same effect as if CIUPDATE is set.

DBGET

DBGET(base,dset,mode,status,list,buffer,argument)
base
is the name of an array used as the base parameter when opening the database. The first element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.)

dset
is the name of an array containing the left-justified name of the data set to which the entry is to be added, or is an integer referencing the data set by number. The data set name can be up to 16 characters long. If shorter, it must be terminated by a semicolon, a space or the NUL character.

mode
contains an integer between 1 and 8, inclusive, which indicates the reading method. The methods are:
Mode Method
1 Re-read. Read the entry at the internally maintained current record number (argument parameter is ignored).
2 Serial Read. Read the first entry whose record number is greater than the internally maintained current number (argument parameter is ignored).
3 Backward Serial Read. Read the first entry whose record number is less than the internally maintained current number (argument parameter is ignored).
4 Directed Read. Read the entry, if it exists, at the record number specified in the argument parameter (argument is treated as a 32-bit record number).
5 Chained Read or Next Qualified Entry Read. Read the next entry in the current chain, or read the next qualified entry for a B-Tree DBFIND. This is the entry referenced by the internally maintained forward pointer (argument parameter is ignored). Super-chains are traversed for detail data sets.
6 Backward Chained Read. Read the previous entry in the current chain, or the previous qualified entry for a B-Tree DBFIND. This is the entry referenced by the internally maintained backward pointer (argument parameter is ignored). Super-chains are traversed for detail data sets.
7 Calculated Read. (Master data sets only.) Read the entry with a key item value that matches the value specified in argument. The entry is in the master data set specified by dset.
8 Primary Calculated Read. (Master data sets only.) Read the entry occupying the primary address of a synonym chain using the key item value specified in argument to locate the entry. The key item value returned is always that of the primary entry and might not match the value specified in argument. (Refer to chapter 10 for synonym chain description.)
With Eloquence this is identical to mode 7.

status
is the name of an array of 10 halfwords in which the database returns status information about the procedure. If the procedure executes successfully, the status array contents are:

list
is the name of an array containing an ordered set of data item identifiers, either names or numbers. Values supplied in the buffer array replace the values of data items occupying the same relative position in the list array. The user class established when the database is opened must allow at least read access to all the items included in the list array.

The list array can contain a left-justified set of data item names, separated by commas and terminated by a semicolon or a blank. No embedded blanks are allowed and no name can appear more than once.

When referencing by number, the first element of the list array is an integer n followed by n unique data item numbers (one-halfword positive integers).

The list not only specifies the data items to be updated immediately but is saved internally as the current list for this data set. The current list is unchanged until a different list is specified in a subsequent call to DBGET, DBPUT, or DBUPDATE for the same access path and data set.

Some special list constructs are allowed. These are described in Special List Parameter Constructs with the DBPUT procedure. List processing involves some overhead which can be shortened in subsequent calls by using the asterisk construct to specify that the current list is to be used.

buffer
is the name of an array containing data item values to be added. The values must be in the same order as their data item identifiers in the list array. The number of halfwords for each value must correspond to the number of halfwords required by its type multiplied by the sub-item count.
Element Contents
1 If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2 Length of logical entry in buffer array (in halfwords).
3-4 Word record number of new entry (32 bit).
5-6 Word count of number of entries in chain (32 bit). If detail data set, chain is current chain of new entry.
7-8 If detail, word record number of predecessor on current detail chain (32 bit).
9-10 If detail, word record number of successor on current detail chain (32 bit).

Notes:

  • Synonym chain information (for master data set) is always zero.
  • Mode 8 is the same as mode 7
  • Additional modes 15 and 16 are available


DBFIND

Locates related master set key item entry that matches the specified search item value and sets up pointers to the first and last entries of a detail data set chain in preparation for chained access to the data entries which are members of the chain. The path is determined and the chain pointers are located on the basis of a specified search item and its value. With the TPI modes, index access is supported. 

DBFIND(base,dset,mode,status,item,argument)
base
is the name of an array used as the base parameter when opening the database. The first element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.)

dset
is the name of an array containing the left-justified name of the data set to which the entry is to be added, or is an integer referencing the data set by number. The data set name can be up to 16 characters long. If shorter, it must be terminated by a semicolon, a space or the NUL character.

mode
must be an integer equal to 1 or 10. Please refer to the TPI Support documentation for additional DBFIND modes.

status
is the name of an array of 10 halfwords in which the database returns status information about the procedure. If the procedure executes successfully, the status array contents are:
Element Contents
1 If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2 Zero.
3-4 Word record number set to zero (32 bit).
5-6 Word count of number of entries in chain or qualifier (32 bit). For modes 21 and 24 2^31-1 is returned.
7-8 If detail, word record number of predecessor on current detail chain (32 bit). For modes 21 and 24 2^31-1 is returned.
9-10 If detail, word record number of successor on current detail chain (32 bit). For modes 21 and 24 2^31-1 is returned.

item
is the name of an array containing a left-justified name of the detail data set search item or is an integer referencing the search item number that defines the path containing the desired chain. The specified search item defines the path to which the chain belongs. For a B-Tree DBFIND on a master, it is the key item name or a number. The name can be up to 16 characters long. If shorter, it must be terminated by a semicolon, a space or the NUL character.

argument
contains a value for the key item to be used in calculated access to locate the desired chain head in the master data set. This is referred to as a simple argument.

Notes:

  • As of Eloqauence B.07.00, DBFIND modes 1,4,21 and 24 are implemented but can currently not be used with search items. They may be used with an Eloquence index item.

  • Eloquence supports the TPI modes for database access. Please refer to the TPI Support documentation for additional DBFIND modes.

DBERROR

Moves a message, as an ASCII character string, to a buffer specified by the calling program. The message interprets the contents of the status array as set by a call to a database procedure. 
DBERROR(status,buffer,length)
status
is the name of the array used as the status parameter in the database procedure call about which information is requested.

buffer
is the name of an array in the calling program's data area, at least 36 halfwords (72 bytes) long, in which the message is returned.

length
is a short, 16-bit integer variable which is set by DBERROR to the positive byte length of the message placed in the buffer array. The length will never exceed 72 characters.

Notes:

  • Messages differ from TurboIMAGE.

DBEXPLAIN

Prints a multiline message to stderr which describes a database procedure call and explains the call's results as recorded in the calling program's status array. 
DBEXPLAIN(status)
status
is the name of the array used as the status parameter in the database procedure call about which information is requested.
Notes:

  • Writes to stderr
  • Messages differ from TurboIMAGE.

DBXBEGIN

Designates the beginning of a transaction or sub-transaction. DBXBEGIN is used in conjunction with DBXEND to begin and end a dynamic transaction. 
DBXBEGIN(base|baseidlist,text,mode,status,textlen)
base
is the name of an array used as the base parameter when opening the database. The first element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.)

Currently ignored. Eloquence transactions are not database specific but include all databases modified in a transaction.

baseidlist
is the name of the integer array containing the base IDs of the databases which are involved in a DMDBX. Use baseidlist when calling DBXBEGIN mode 3 (DMDBX). The layout of this array is shown here (each element is a halfword or two bytes):
Element Contents
1-2 Application program must set these two halfwords to binary 0s before calling DBXBEGIN. After returning to the calling program, these two halfwords contain the transaction ID. Use this same baseidlist with the corresponding DBXEND or DBXUNDO intrinsics.
3 Number of base IDs involved in the DMDBX. This must be a number between 1 and 15 inclusive.
4-n Base IDs of the databases involved in the DMDBX. Each base ID occupies one half-word or 2 bytes and it is the first halfword of the base parameter used to call database procedures.

Currently ignored. Eloquence transactions are not database specific but include all databases modified in a transaction.

text
is the name of an array up to 256 halfwords long that contains user ASCII or binary data to be written to the log file as part of the transaction log.

mode
is an integer indicating the transaction type:
  • Mode 1: Indicates a dynamic transaction which spans only one database.
  • Mode 3: Indicates a dynamic transaction spanning multiple databases.
The mode parameter has no effect with Eloquence.

status
is the name of an array of 10 halfwords in which the database returns status information about the procedure. If the procedure executes successfully, the status array contents are:
Element Contents
1 If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2 Transaction nesting level.
3-4 Unchanged.
5-10 Information about the current procedure call and its results.

textlen
is an integer equal to the number of halfwords to be logged from the text parameter, or is a negative integer equal to the number of bytes. Length can be zero.

Notes:

  • Transactions are not database specific but affect all databases. Consequently, no check is made for a valid database id or database id list and no check is made for dbopen mode restrictions.

  • In mode 3 the baseidlist argument is not updated.

  • Nested transactions are allowed

  • Element 2 of the status error was unchanged with TurboIMAGE. Eloquence returns the transaction nesting level.
  • TurboIMAGE/XL in addition supports the DBXBEGIN mode 4 which is used by SQL. This is not supported with Eloquence.

DBXEND

Designates the end of a transaction or subtransaction ("commit"). DBXEND is used in conjunction with DBXBEGIN to begin and end a dynamic transaction. 
DBXEND(base|baseidlist,text,mode,status,textlen)
base
is the name of an array used as the base parameter when opening the database. The first element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.)

Currently ignored. Eloquence transactions are not database specific but include all databases modified in a transaction.

baseidlist
is the name of the integer array containing the base IDs of the databases which are involved in the DMDBX. Use the same baseidlist used with DBXBEGIN when calling DBXEND mode 3 to end the DMDBX. The layout of this array is same as in DBXBEGIN, except that the transaction ID is already set in the first two halfwords by DBXBEGIN.

Currently ignored. Eloquence transactions are not database specific but include all databases modified in a transaction.

text
is the name of an array up to 256 halfwords long that contains user ASCII or binary data to be written to the log file as part of the transaction log.

mode
must be a halfword equal to 1, 2 or 3 or 5.
  • Mode 1: End of dynamic transaction spanning one database.
  • Mode 2: End of dynamic transaction spanning one database, started with DBXBEGIN mode 1, and write contents of the transaction management (XM) logging buffer in memory to disk. If logging is enabled, the contents of the logging buffer in memory will also be written to disk.
  • Mode 3: Indicates the end of a DMDBX started with DBXBEGIN mode 3. If user logging is enabled for the databases, mode 3 generates multiple entries in the log file, one for each database in the DMDBX, in order to mark the end of a dynamic transaction.
  • Mode 5: Commit top level transaction. If nested transactions are used this will commit all pending operations.
Modes 1,2 and 3 are handled identical with Eloquence.

status
is the name of an array of 10 halfwords in which the database returns status information about the procedure. If the procedure executes successfully, the status array contents are:
Element Contents
1 If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2 Transaction nesting level.
3-4 Unchanged.
5-10 Information about the current procedure call and its results.

textlen
is an integer equal to the number of halfwords to be logged from the text parameter, or is a negative integer equal to the number of bytes. Length can be zero.

Notes:

  • Transactions are not database specific but affect all databases. Consequently, no check is made for a valid database id or database id list and no distinction is made between a single database and multiple databases (DBMX).

  • Modes 1,2 and 3 are mapped to Eloquence mode 1

  • Mode 5 is mapped to Eloquence mode 2

  • Text is ignored

  • Nested transactions are allowed. If used, DBXEND most be called the same number of times as DBXBEGIN or mode 5 with DBXEND must be used.

  • Element 2 of the status error was unchanged with TurboIMAGE. Eloquence returns the transaction nesting level.

  • TurboIMAGE/XL in addition supports the DBXEND mode 4 which is used by SQL. This is not supported with Eloquence.

DBXUNDO

Rolls-back the active sequence of database procedure calls which are considered a dynamic transaction. 
DBXUNDO(base|baseidlist,text,mode,status,textlen)
base
is the name of an array used as the base parameter when opening the database. The first element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.)

Currently ignored. Eloquence transactions are not database specific but include all databases modified in a transaction.

baseidlist
Name of the integer array containing the base IDs of the databases which are involved in the DMDBX. Use the same baseidlist parameter of DBXBEGIN mode 3, when calling DBXUNDO to roll-back a DMDBX.

Currently ignored. Eloquence transactions are not database specific but include all databases modified in a transaction.

text
is the name of an array up to 256 halfwords long that contains user ASCII or binary data to be written to the log file as part of the transaction log.

mode
must be a halfword equal to 1,3 or 5.
  • Mode 1: Dynamically roll-back DBPUT, DBDELETE, and DBUPDATE intrinsics which completed successfully since the matching DBXBEGIN mode 1 call.
  • Mode 3: Dynamically roll-back DBPUT, DBDELETE, and DBUPDATE intrinsics which completed successfully inside the DMDBX to their respective databases since the matching DBXBEGIN mode 3 call. If user logging is enabled for the databases, mode 3 generates multiple entries in the log file, one for each database, in order to mark the roll-back of the dynamic transaction.
  • Mode 5: Roll-back top level transaction. If nested transactions are used this will roll-back any pending transaction.
Modes 1 and 2 are handled identical with Eloquence.

status
is the name of an array of 10 halfwords in which the database returns status information about the procedure. If the procedure executes successfully, the status array contents are:
Element Contents
1 If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2 Transaction nesting level.
3-4 Unchanged.
5-10 Information about the current procedure call and its results.

textlen
is an integer equal to the number of halfwords to be logged from the text parameter, or is a negative integer equal to the number of bytes. Length can be zero.

Notes:

  • Transactions are not database specific but affect all databases. Consequently, no check is made for a valid database id or database id list and no distinction is made between a single database and multiple databases (DBMX).

  • Modes 1 and 3 are mapped to Eloquence mode 1

  • Mode 5 is mapped to Eloquence mode 3

  • Text is ignored
  • Nested transactions are allowed. If used, DBXUNDO most be called the same number of times as DBXBEGIN or mode 5 with DBXUNDO must be used.

  • Element 2 of the status error was unchanged with TurboIMAGE. Eloquence returns the transaction nesting level.

  • TurboIMAGE/XL in addition supports the DBXUNDO mode 4 which is used by SQL. This is not supported with Eloquence.

DBBEGIN

Designates the beginning of a sequence of database procedure calls regarded as a static or multiple database transaction (based on the mode) for the purposes of logging and recovery. The text parameter can be used to log user information to the log file. DBBEGIN is used in conjunction with DBEND to begin and end a static or multiple database transaction.

Static transactions are currently not supported with Eloquence and DBBEGIN has no effect. Eloquence relies on dynamic transactions internally. A future version of Eloquence may add support for static transactions for use with forward recovery or auditing purposes. 

DBBEGIN(base|baseidlist,text,mode,status,textlen)
base
is the name of the array used as the base parameter when opening the database. The first element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.) Use base when calling DBBEGIN mode 1 (static transaction).

The base argument is ignored with Eloquence.

baseidlist
is the name of the integer array containing the base IDs of the databases which are involved in a multiple database transaction. Use baseidlist when calling DBBEGIN mode 3 or 4 (multiple database transaction). The layout of this array is shown here (each element is a halfword or two bytes):
Element Contents
1-2 The application program must set these two halfwords to binary 0s before calling DBBEGIN. After returning to the calling program, these two halfwords contain the transaction ID. This ID can be used in order to end the transaction by calling DBEND.
3 The number of base IDs involved in the multiple database transaction. This must be a number between 1 and 15, inclusive.
4-n Base IDs of the databases involved in the transaction. Base ID is the first halfword of the base parameter used to call database procedures.

The baselist argument is ignored with Eloquence.

text
is the name of an array up to 256 halfwords long that contains user ASCII or binary data to be written to the log file as part of the transaction log.

mode
is an integer indicating the transaction type:
  • Mode 1: Indicates a static transaction.
  • Mode 3: Indicates a multiple database transaction with one log record per database. If user logging is enabled for the databases, mode 3 generates multiple entries in the log file in order to mark multiple database transactions.
  • Mode 4: Indicates a multiple database transaction. If user logging is enabled for the databases, mode 4 generates one entry in the log file in order to mark multiple database transactions.
The mode parameter has no effect with Eloquence.

status
is the name of an array of 10 halfwords in which the database returns status information about the procedure. If the procedure executes successfully, the status array contents are:
Element Contents
1 If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2-4 Unchanged.
5-10 Information about the current procedure call and its results.

textlen
is an integer equal to the number of halfwords to be logged from the text parameter, or is a negative integer equal to the number of bytes. Length can be zero.

Notes:

  • Static transactions are not supported and DBBEGIN has no effect besides verfying the arguments.

DBEND

Designates the end of a sequence of database procedure calls regarded as a static or multiple database transaction (based on the mode) for the purposes of logging and recovery. The text parameter can be used to log user information to the log file. DBEND isused in conjunction with DBBEGIN to begin and end a static or multiple database transaction.

Static transactions are currently not supported with Eloquence and DBEND has no effect. Eloquence relies on dynamic transactions internally. A future version of Eloquence may add support for static transactions for use with forward recovery or auditing purposes. 

DBEND(base|baseidlist|transid ,text,mode,status,textlen)
base
is the name of the array used as the base parameter when opening the database. The first element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.) Use with DBEND mode 1 or 2.

The base argument is ignored with Eloquence.

baseidlist
is the name of an integer array containing the list of base IDs which are involved in a multiple database transaction. Use with DBEND mode 3 or 4, and set the first two halfwords to binary zeroes. The layout of this array is shown here (each element is a halfword, or two bytes):
Element Contents
1-2 Must be set to binary zeroes.
3 The number of base IDs involved in the multiple database transaction. This must be a number between 1 and 15, inclusive.
4-n Base IDs of the databases involved in the transaction. Base ID is the first halfword of the base parameter used to call database procedures.

The baselist argument is ignored with Eloquence.

transid
is the name of the integer array containing the two-halfword transaction ID. The transaction ID was returned by DBBEGIN mode 3 or 4. Use with DBEND mode 3 or 4, and do not set the first two halfwords to binary zeroes.

The transid argument is ignored with Eloquence.

text
is the name of an array up to 256 halfwords long that contains user ASCII or binary data to be written to the log file as part of the transaction log.

mode
must be an integer equal to 1, 2, 3, or 4.
  • Mode 1: End of static transaction.
  • Mode 2: Write contents of the logging buffer in memory to disk, and end the static transaction.
  • Mode 3: End of multiple database transaction. If user logging is enabled for the databases, mode 3 generates multiple entries in the log file in order to mark multiple database transactions.
  • Mode 4: Write contents of the logging buffer in memory to disk, and end the multiple database transaction. If user logging is enabled for the databases, mode 4 generates one entry in the log file in order to mark multiple database transactions.
The mode parameter has no effect with Eloquence.

status
is the name of an array of 10 halfwords in which the database returns status information about the procedure. If the procedure executes successfully, the status array contents are:
Element Contents
1 If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2-4 Unchanged.
5-10 Information about the current procedure call and its results.

textlen
is an integer equal to the number of halfwords to be logged from the text parameter, or is a negative integer equal to the number of bytes. Length can be zero.

Notes:

  • Static transactions are not supported and DBEND has no effect besides verfying the arguments.

DBMEMO

Used to log user data (ASCII or binary) to the log file.

Static transactions are currently not supported with Eloquence and DBMEMO has no effect. Eloquence relies on dynamic transactions internally. A future version of Eloquence may add support for static transactions for use with forward recovery or auditing purposes. 

DBMEMO(base,text,mode,status,textlen)
base
is the name of the array used as the base parameter when opening the database. The first element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.)

The base argument is ignored with Eloquence.

text
is an array of up to 512 bytes that contains user data (ASCII or binary) to be written to the log file as part of the DBMEMO log record.

mode
must be an integer equal to 1.

status
is the name of an array of 10 halfwords in which the database returns status information about the procedure. If the procedure executes successfully, the status array contents are:
Element Contents
1 If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2-4 Unchanged.
5-10 Information about the current procedure call and its results.

textlen
is an integer equal to the number of halfwords to be logged from the text parameter, or is a negative integer equal to the number of bytes. Length can be zero.

Notes:

  • Static transactions are not supported and DBMEMO has no effect besides verfying the arguments.

DBLOGON

A user name and password is required to connect to a database. Unless specified by either DBLOGON or DBOPEN a default user ("public") is used. DBLOGON saves the identity for usage with a subsequent DBOPEN. 

DBLOGON(user,password,status)
user
is an array of up to 128 bytes that contains the user name. It must be terminated by either a semicolon, a space a NUL character.

password
is an array of up to 128 bytes that contains the password associated with the user. It must be terminated by either a semicolon, a space a NUL character.

status
is the name of an array of 10 halfwords in which the database returns status information about the procedure. If the procedure executes successfully, the status array contents are:
Element Contents
1 If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2-4 Unchanged.
5-10 Information about the current procedure call and its results.

Discussion:

DBLOGON does not verify the arguments but merely saves the information for usage by a subsequent DBOPEN. DBLOGON is called impliceitely by specifying a user name and password with the DBOPEN password parameter. To reset a previously established identity (to force using the default user name), call DBLOGON with an empty string for the user name.

Notes:

  • Eloquence specific.
© Copyright 2002-2003 Marxmeier Software AG. All rights reserved.
Revision: 2003-03-19