HP Eloquence A.06.31 Release Notes

HP Eloquence TurboIMAGE compatibility extension

HP Eloquence TurboIMAGE compatibility extension (IMAGE3K) is an optional HP 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 HP Eloquence database with no or only minor changes.

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

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

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

Content of this document:


Changes to previous version


Installation

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

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

The IMAGE3K library has been included with the HP 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 HP 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 -114.

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

HP 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 HP 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 HP Eloquence database internally uses "dynamic transactions" the TurboIMAGE static transactions do not make sense. User specific logging of transactions is not available with the HP 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 HP 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, HP 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 HP Eloquence specific information.
       status[5]   = native HP 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 HP 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 HP Eloquence database manual for more information.

  8. HP Eloquence does not enforce locking. It's optional and there are no special requirements depending on data set types or transactions. The HP 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. HP Eloquence does not use hashing. So there are no secondaries in master sets.

  11. The HP 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 HP 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 HP 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 HP 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 HP 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

HP 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 HP 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] HP 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 HP Eloquence does assume anegative value.
K4 Same as I4
Pn HP 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

DBCLOSE

DBCONTROL

DBINFO

DBLOCK

DBUNLOCK

DBPUT

DBDELETE

DBUPDATE

DBGET

DBFIND

DBERROR

DBEXPLAIN

DBXBEGIN

DBXEND

DBXUNDO


© Copyright 2001 Hewlett-Packard GmbH. All rights reserved.
© Copyright 1999-2001 Marxmeier Software AG. All rights reserved.
Revision: 2001-07-05