IMAGE3K API - 09.09.99 ---------------------- This is a test version of the HP Eloquence IMAGE3K API which emulates the TurboImage API with the HP Eloquence database. The IMAGE3K API is available for testing and evaluation on the HP-UX, Linux and Win32 (Windows NT/95/98) platform. Please note that this version has NOT been tested completely. While the underlying database is stable, the API compliance (compatibility to TurboImage) and the performance are still under investigation. This also has a benefit: If you test this release and encounter a problem we promise you to make a fixed version available immediately (usually within a few hours). You feedback is appreciated. Please send comments, bug reports or questions to eloq-support@msede.com. Installation ============ You should have HP Eloquence A.06.10 installed. In addition we recommend to install the latest patch for the eloqdb6 database server (PE61-9807270 at this time). Installation depends on your operating system: UNIX: Unpack the tar archive into the HP Eloquence directory structure. Please note, that you need to gzip to unpack the archive. cd /opt/eloquence6 gzip -dc /tmp/hp3k-hpux.tar.gz | tar xf - This will install the following files: include/image3k.h lib/libimage3k.sl lib/libeqdb.sl bin/schema WINDOWS: Please use Winzip to unpack the archive. You need to move the files manually. Copy the *.dll files to your windows system32 directory (eg. C:\WINNT\SYSTEM32 on Windows NT). Copy the image3k.h file to the include directory of your HP Eloquence installation. Copy the *.lib and *.def files to the lib directory of your HP Eloquence installation. Copy the *.exe files to the bin directory of your HP Eloquence installation. 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 on 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/image3k.lib library which implements the IMAGE3K API and the libeqdb.sl/eloqdb32.lib which implements the HP Eloquence database client API. Limitations / Remarks ===================== Genral ------ 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 (and forward recovery from a previous backup will be implemented different with the coming A.06.20 release). So DBBEGIN, DBEND and DBMEMO do next to nothing besides validating the arguments. In addition any restrictions concerning "static" transactions are no longer enforced. 2. HP Eloquence supports transaction nesting and transaction isolation. So nesting of dynamic transactions is allowed and dirty (read) access to data modified in a transaction is not visible outside the transaction. 3. All database "intrinsics" might return different status values in case of "unusual" situations. Some status values of HP Eloquence differ from TurboImage and not all are mappable. 4. In case of a status error, status elements 5 .. 9 are different. 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). Our goal is to add additional HP Eloquence functionality in a compatible manner, so HP Eloquence aware applications could use this. 8. HP Eloquence does not enforce locking. It's completely optional. The HP Eloquence database is able to handle concurrency internally through transactions. So you are free to use locking accordig to the requirement of your application. 9. Item lists are not supported. A item list argument must be '@;', '@ ' '*;' or '* ' 10. HP Eloquence does not use hashing. So there are no secondaries in master sets. 11. An experimental version of the HP Eloquence schema processor is included which is able to handle the TurboImage schema syntax (specify the -T commandline switch). While some differences of the HP Eloquence IMAGE kernel do restrict compatibility for now, the schema processor should be able to handle almost all schema files and issue a warning if a feature is not supported (eg. data types or sort items). Currently only data types I1,I2,X,E2,E4 are supported. All other types are mapped to existing data types for now. The following data types are supported: "I[n]" - integer, n = number of halfwords "E[n]" - IEEE floating point, n = number of halfwords "J[n]" - mapped to 'I' "K[n]" - unsigned integer, mapped to 'I' "R[n]" - mapped to 'E' "P[n]" - mapped to 'X' (of same item size) "Xn" - string, n = number of bytes "Un" - UPC string, mapped to 'X' "Z[n]" - zoned decimal, mapped to 'X' The next update of the HP Eloquence database kernel will support these data types. 12. A limit of 99 data sets applies. This is not really a limit of the database but some database tools (eg. dbcreate, dberase) currently rely on this limitations and must be fixed in order to get rid of this limitation. 13. Sort items are not supported yet. They will be supported with an update of the HP Eloquecne database kernel (with the A.06.20 release). 14. HP Eloquence provides an enhanced access control subsystem which is different from the traditionsl IMAGE model. As a side effect, you should call the HP Eloquence specific API function DBLOGON (once) before opening a database. If you do not, a user "public" is assumed. Note: The DBLOGON api call is not yet integrated into the IMAGE3K API so for now all data must be accessible for the user "public". 15. Item level security is ignored. 16. 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. schema ------ This release includes a version of the schema processor which additionally is able to handle the TurboImage 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. 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 width $CONTROL Equiv. Option ---------------- ----------------- $CONTROL NOLIST default $CONTROL LIST -l $CONTROL ROOT default $CONTROL NOROOT -n $CONTROL TABLE -t DBOPEN ------ - Database name is not longer limited to 6 chars and must follow the HP Eloquence conventions. The database name MUST either be separated by a NUL character, a ';' (semicolon) or a space character. Since HP 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) - The pswd argument is ignored with A.06.xx databases. HP Eloquence A.06.xx uses an enhanced access control scheme which is different from traditional IMAGE. As a side effect the user class returned in status[2] is different. Since TurboImage allows specifying the user in addition to the password, this will probably be mapped to DBAUTH in a future release. - Ony modes 1, 3, 5, 8 are fully compatible. All other modes are mapped and usually do not impose concurrency restrictions (yet?). - Mode 6 allows concurrent modification - Mode 9 is available in addition DBCLOSE ------- - Mode 2 is mapped to 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 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 103,104 always return negative item numbers - mode 204,205: no blocking factor - mode 204,205: capacity is dynamic - mode 205: additional capacity values are 0 - mode 205: dynamic expansion flag is always 1 - mode 401-404 are a rough approximation yet - mode 502: CIUPDATE is always allowed - mode 901: Language ID is always 0 - mode 801-804 are equivalent to HP Eloquence mode 501-504 DBLOCK ------ - Multiple locks are allowed. - Subsequent "unconditional" locks will return a database status when they are blocked. - A lock descriptor is applied atmomically. 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, selective unlocks will be supported. DBPUT ----- - Synonym chain information always zero DBDELETE -------- - Synonym chain information always zero DBUPDATE -------- - Synonym chain information always zero - CIUPDATE is emulated through DBDELETE/DBPUT, so the record number is likely to change. DBGET ----- - Synonym chain information always zero - mode 8 is mapped to mode 7 DBFIND ------ - additional modes are available, however for all modes besides mode 1, the argument must be provided in an HP 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 mapped to 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