.
contact contact

Eloquence TurboIMAGE compatibility extension

 
.
  A.06.31 Release Notes
Eloquence TurboIMAGE compatibility extension (IMAGE3K) is an optional Eloquence component which implements a HP3000 TurboIMAGE compatible interface for the HP Eloqunce database. While not 100% compatible it is close so applications originating on the HP3000 can be ported to the Eloquence database with no or only minor changes.

In addition to the TurboIMAGE intrinsic calls the Eloquence database offers enhanced capabilities:

  • Fully 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.
  • Additional locking capabilities
  • Additional database utilities including database restructuring (not yet available for A.06.xx).
  • Cross platform (HP-UX, Linux, Windows).
  • Dynamic, multi-level transactions, full transaction isolation (uncommitted changes are not visible to other processes).
  • New security subsystem.

The Eloquence IMAGE3K library is an optional component and requires a separate license key. Please use our Feedback Form on the Eloquence web site or send an email notice to the Eloquence Support if you would like to evaluate the Eloquence TurboIMAGE compatibility extension.

Your feedback is appreciated. Please send comments, bug reports or questions to the Eloquence Team (send an email message to feedback@marxmeier.com or use our Feedback Form on the Eloquence web site.)

Content of this document:


Changes to previous version

  • Integration into the A.06.31 product and update of the release notes document.

  • The schema processor has been changed to improve handling of foreign TurboIMAGE types and save the item type specified in the schema file for later usage by DBINFO.

  • Fixed translation of some DBGET status codes. DBGET mode 3 (reading backwards) now returns status 10 if at the beginning of the data set. DBGET mode 6 (reading chain backwards) now returns status 14 if at the beginning of the chain.

  • Fixed DBINFO
    • mode 101: item number are returned negative as item write access is always available
    • mode 102: return original item type saved by schema
    • mode 102: word 11 returns Eloquence item format number
    • mode 502: CIUPDATE is allowed (element 1)

  • DBOPEN can use the password argument to authorize to the database server.


Installation

You should have Eloquence A.06.31 installed. In addition we recommend to install the latest patch for the eloqdb6 database server.

A list of Eloquence patches for the version A.06.31 is available at
http://eloquence.marxmeier.com/support/A06/patch-A0631.html

The IMAGE3K library has been included with the Eloquence A.06.31 product release. On the HP-UX and Linux platform it is installed automatically. To install the IMAKE3K library on Windows you need to download the eq63_client_image3k.cab cabinet file. Choose a customized Eloquence installation and enable the IMAGE3K component to be installed.

You need a separate license key on the database server in order to use the IMAGE3K library. If no license key is installed DBOPEN fails with status -104.

Platform File
HP-UX /opt/eloquence6/include/image3k.h
/opt/eloquence6/lib/libimage3k.sl
Linux /opt/eloquence6/include/image3k.h
/opt/eloquence6/lib/libimage3k.so
Windows \Program files\Hewlett-Packard\HP-Eloquence\include\image3k.h
\Program files\Hewlett-Packard\HP-Eloquence\lib\image3k.def
\Program files\Hewlett-Packard\HP-Eloquence\lib\image3k.lib
\WINNT\SYSTEM32\image3k.dll


Compiling/Linking

When compiling programs against the IMAGE3K API, it is strongly 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 program:

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

When not compiling for MPE the image3k.h file is included. Example programs (written in 'C') using the IMAGE3K API are available for your reference.

You need to link against the libimage3k.sl (HP-UX), image3k.so (Linux) or image3k.lib (Windows) library which implements the IMAGE3K API and the libeqdb.sl (HP-UX) libeqdb.so (Linux) or eloqdb32.lib (Windows) library which implements the Eloquence database client API.

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" 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 platform. When the database server is using a different platform (eg. Client on Windows, Server on HP-UX) all values and strings are converted by the Eloquence database.


Limitations / Remarks

Documented below are the differences we are aware of between the HP3000 TurboIMAGE intrinsic calls and the IMAGE3K implementation.

General

  1. User mode logging (aka. static transactions)

    User mode logging is not supported. Since the Eloquence database internally uses "dynamic transactions" the TurboIMAGE static transactions do not make sense. User specific logging of transactions is not available with the Eloquence database. If user mode logging is required (due to software compatibility requirements) it should either be implemented in the software or could be added to the IMAGE3K API layer.

    As a consequence DBBEGIN, DBEND and DBMEMO do next to nothing besides validating the arguments. In addition any restrictions related to "static" transactions are not enforced.

  2. The Eloquence database implements transaction nesting and transaction isolation. So nesting of dynamic transactions is allowed and modified information are only visible outside the transaction context if the transaction is commited. A concurrent read access outside the transaction context returns the unmodified information.

  3. 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.

  4. In case of a status error, status elements 5 .. 9 are different from TurboIMAGE. They include additional Eloquence specific information.
       status[5]   = native Eloquence function id
       status[6]   = native status
       status[7,8] = native ext. status.
       status[9]   = native mode
    

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

  6. Data base, data set and item names are not case sensitive.

  7. Some database "intrinsics" 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 (for example use indexing instead of KSAM).

    Please refer to the Eloquence database manual for more information.

  8. 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 accordig to the requirement of your application. However a concurrent lock will cause a write access to return with a database status.

  9. Item lists are not supported. A item list argument must be '@;', '@ ' '*;' or '* '. Item lists will be fully supported with the upcoming A.07.00 release.

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

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

    Currently only data types I1,I2,X,E2,E4,R2,R4 are supported natively. All other types are mapped to existing data types. See discussion in the schema section of this document for further details.

    The Eloquence A.07.00 database will provide native support for the TurboIMAGE data types.

  12. A limit of 199 data sets per database applies. This is not really a limit of the database but some database tools (eg. dbcreate, dberase) currently rely on this limitations.

  13. The Eloquence security system differes from the traditionsl IMAGE model. A user name and password can be specified in the DBOPEN password parameter. Otherwise the default user "public" is used.

    As an alternative we have added the DBAUTH function call which can be used to specify user and password information instead of the default user for subsequent DBOPENs. This call is experimental and may change in subsequent versions.

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

  15. 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.


The schema processor

The Eloquence schema processor is able to process the TurboIMAGE schema syntax. In order to enable TurboIMAGE compatibility you need to specify the -T command line option. The -W command line option allows to specify a line width other than 72 (0 = off). Otherwise any character beyound the column 72 is ignored. This may be required to remove line numbers if the file has been saved with line numbers.

Please note, that the Eloquence schema processor does not require (but accepts) $CONTROL directives. Almost all settings can be specified from the command line. The -n (equivalent to "NOROOT") takes precendent over any $CONTROL directive.

  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
   -l         - output source listing
   -n         - no root file, only check syntax
   -t         - output set table
   -T         - TurboIMAGE compatibility mode
   -W width   - Limit line length to given width

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


Supported data types

Eloquence currently does not support all TurboIMAGE data types natively. Data types not handled natively are mapped to either similar or the binary data type.

I[n] Integer, n = number of halfwords
I1 mapped to type I, I2 mapped to type D
I4 mapped to B8
Sizes other than 1,2 and 4 are not supported
J[n] same as I[n]
K[n] Unsigned integer, n = number of halfwords
handled like I[n]
E[n] IEEE floating point, n = number of halfwords
E2 mapped to type S, E4 mapped to type L
Sizes other than 2 and 4 are not supported
R[n] HP 3000 floating point number (Real)
same as E[n]
Pn Packed decimal, n = number of nibbles
mapped to B[n/2]
Xn n byte string
mapped to X
Un Upper case string
mapped to X
Z[n] Zoned decimal, n = number of digits
mapped to B

For mapped data types the HP3K DBINFO mode 102 does return the original type specified in the schema file. The Eloquence A.07.00 database will provide native support for the TurboIMAGE data types.

Impact:
I4 Since I4 is mapped as a binary type, access in index order will return values in the wrong order for negative values. If server and client run on different architectures, the byte order is not adapted depending on architecture.
K[n] Eloquence currently does not support unsigned data types natively and signed types are used. As a consequence, when Kn is used as an index, index order is wrong if Eloquence does assume anegative value.
K4 Same as I4
Pn Eloquence does currently not support packed decimals natively. If Pn is used to define an index the order is likely wrong.
Un Upper case strings are handled like regular strings. It is the responsibility of the application to ensure valid values are written to the database and provided as search arguments.
Z[n] Ordering of negative numbers in index operations is wrong.


DBOPEN

  • The Database name is not limited to 6 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.

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

  • Eloquence A.06.xx uses an enhanced access control scheme which is different from traditional IMAGE. The Eloquence database maintains users with passwords. Each user may be member of one or more groups which define the access rights to the data sets. Unless a user is specified the default user ("public") is used to access the database. As a side effect the user class returned in status[2] is different.

  • If a user name is present in the password argument (the optional "identifier") it is used as authorization 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 content 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 no separate IMAGE3K license key has been installed on the data base server.

DBCLOSE

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

DBCONTROL

  • AUTODEFER (mode 1, 2) is accepted but has no effect
  • HWPUT (mode 9, 10) is not accepted and results in status -31. If HWPUT were simply ignored, it could cause applications to fail due to unexpected re-use of deleted records.
  • CIUPDATE is always considered allowed (but disabled by default)
  • Database open mode and transaction status is not checked

DBINFO

  • mode 101,103,104 always return negative item numbers
  • mode 202,205: no blocking factor is present (returned as 0)
  • mode 204,205: capacity is dynamic and reflects the maximum number of records in the data set.
  • mode 205: additional capacity values are 0
  • mode 205: dynamic expansion flag is always 1
  • mode 301: sort item is not returned
  • mode 401-404 are a rough approximations yet
  • mode 502: CIUPDATE is always allowed
  • mode 901: Language ID is always 0
  • mode 801-804 are equivalent to Eloquence mode 501-504

DBLOCK

  • Multiple locks are allowed.
  • Subsequent "unconditional" locks will return a database status when they cause a deadlock.
  • 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.

DBUNLOCK

  • DBUNLOCK is allowed during dynamic transactions.
  • Currently, only mode 1 unlock is supported. In the future, additional Eloquence unlock modes will be supported to allow selective unlocks.

DBPUT

  • Synonym chain information is always zero

DBDELETE

  • Synonym chain information is always zero

DBUPDATE

  • Synonym chain information is always zero
  • Additional mode 2 is available which has the same effect as if CIUPDATE is set.

DBGET

  • Synonym chain information is always zero
  • Mode 8 is the same as mode 7
  • Additional modes 15,16 are available

DBFIND

  • Additional modes 2,3,4 and 5 are available, however for all modes besides mode 1 the argument must be provided in an Eloquence compatible manner. This is subject to change.

DBERROR

  • Rough approximation yet

DBEXPLAIN

  • Writes to stderr
  • Rough approximation yet

DBXBEGIN

  • Transactions are not database specific but affect all databases
  • No restrictions on database modes, provided database id is not verified
  • Nested transactions are allowed

DBXEND

  • Transactions are not database specific but affect all databases
  • Provided database id is not verified
  • mode 2 is the same as mode 1
  • Text is ignored
  • Nested transactions are allowed

DBXUNDO

  • Transactions are not database specific but affect all databases
  • Provided database id is not verified
  • Text is ignored
  • Nested transactions are allowed


 
 
.
 
 
  Privacy | Webmaster | Terms of use | Impressum Revision:  2002-11-18  
  Copyright © 1995-2002 Marxmeier Software AG