Contents

• Changes to previous version
• Known Problems & Limitations

Changes to previous version

• On HP-UX, Eloquence libraries are no longer installed in the Eloquence lib directory. A subdirectory has been introduced which separates different library versions.

  The following conventions apply:

  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)

This section keeps track of all user visible changes relative to previous versions.

B.07.10 Release:

• The image3k library was enhanced to provide additional context information if a status code is returned.
  • The DBEXPLAIN output was modified to include the database and the referenced set and item if called immediately after a failed database call. The output is truncated to 79 characters.

     DBINFO MODE 205 ON customers OF sample
     DBFIND MODE 21 ON customers.custno OF sample
    

  • The DBCALL call was modified to return the database and the referenced set and item if called immediately after a failed database call. The output is truncated to 72 characters for MPE compatibility.

• The DBOPEN call has been enhanced to check for an environment variable that matches the database name. This environment variable may be used to replace the database name. This mechanism may be used to provide a replacement to MPE file equations with the image3k library.

  To be effective the environment variable needs to start with the prefix "EQ3K__" followed by the upshifted database name. Any dot characters (.) in the database name are replaced by underscore characters (_).

  For example:

   Database Name   Environment Variable
   --------------- ---------------------
   Sample          EQ3K__SAMPLE
   sample.test     EQ3K__SAMPLE_TEST
  

• The EQ3K_MINCAPACITY environment variable may be used to specify a minimum value for capacity returned by DBINFO calls mode 202 and 205.

• The image3k library on HP-UX was modified to accept an TPI item offset of 5000. While the HP-UX version of the image3k library uses 10000 as a mininum value for a TPI item number to ensure full compatibility with MPE checking for an offset of 5000 in addition provides full compatibility to the Windows and Linux versions.

• The change in image3k patch PE70-0406020 to support an offset of 10000 for TPI items caused an ambiguity on little endian platforms (Linux and Windows). On these platforms the image3k library could no longer distinguish if an item number or name was passed. This could result in status -52 returned from DBFIND. To solve this abiguity and still support the concept to have a mininum value for a TPI item number we have changed the offset for TPI item numbers from 10000 to 5000 on Linux and Windows.

  Any application that relies on TPI items having numbers above 10000 needs to be changed to use an offset of 5000 on little endian platforms. The HP-UX version of the image3k currently retains an offset of 10000 for TPI item numbers for full backwards compatibility.

• The TPI related DBINFO modes have been modified to accept and return item numbers greater than 10000 in case an item is a TPI item. This is specified in the TPI documentation and solves potential compatibility issues in case applications specifically check for this item number range. Eloquence simply adds 10000 to the index item number.

• DBOPEN has been corrected to return status -1 if the database could not be opened. In previous image3k versions could return status -11 if the database did not exist.

• DBLOCK returns a status code 26 in case a deadlock situation was detected. With previous image3k versions DBLOCK returned a status code -35. Status code 26 is specified by the TurboIMAGE documentation.

  Please note that other intrisic calls that modifiy the database could still return status -35 in case a deadlock situation is encounted.

• DBINFO modes 811 and 812 have been modified to accept IMAGE data items in addition to index items. Previous versions only accepted index items and returned a status when a data item was specified.

• Added support for HP Fortran 90 using the +ppu compile option in HP-UX. When the +ppu compile option is used, an underline character is added to all external symbols (e.g. dbget becomes dbget_).

• Added support for the DBMAINT intrinsic call. The DBMAINT call is undocumented on MPE and may be used to create or erase a database. The Eloquence implementation in addition supports purging of a database.

  The DBMAINT arguments are similar to DBOPEN:

   DBMAINT (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;"

  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{_;}]]
  

  The examples below specify an user name and an empty password

   [/USERIDENT]{_;}
   ;[/USERIDENT{_;}]
  

  The example below specifies an user name and a password

   password[/USERIDENT]{_;}
  

  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 always be present.

  Unless both the password and the user identifier string are present, the password argument is ignored.

  mode

  is an integer equal to 1, 2, or 4 indicating the type of operation requested.

   1 - create the database
   2 - erase the database.
   4 - purge the database (Eloquence specific)
  

  status

  is the name of an array of 10 halfwords in which the database returns status information about the procedure.

  DBMAINT requires exclusive access to the database and affects all sets of a database. The Eloquence dbcreate, dberase and dbpurge utility programs allow to specify a list of data sets in addition.

  Eloquence either requires that the user has administrative access to the database (eg. it is member of the "dba" group) or has the erase privilege (in case of mode 4).

• DBFIND TPI modes may also be used to access search items (equivalent to the TurboIMAGE btree modes).

• DBLOCK modes 3/4/13/14 have been modified to support the "@" qualifier to specify an effective database lock. This is supported by TurboIMAGE but was not possible with Eloquence.

• DBUNLOCK did not support the extended Eloquence modes to allow selective unlock. DBUNLOCK has been modified to follow the Eloquence documentation.

• A compatibility problem with TPI DBFIND mode 1 and 21 with numeric values has been fixed. DBFIND mode 1/21 was handling numeric arguments on an index incorrectly.

  DBFIND was expecting that numeric values are passed as text and converted it to the binary representation. However the TPI documentation defines that numeric values should be passed as a binary value. DBFIND mode 1/21 on indexes has been changed to follow the TPI documentation.

  The HP3K_TPI_COMPAT property may be used to enable the previous behavior. If the bit 1 in the HP3K_TPI_COMPAT property value is set (+2) then a numeric argument may be passed as text if the argument either starts with an operator (==, <=, >=), a positive or the negative sign. Otherwise a binary value is assumed. As this may cause ambiguities, the default is that numeric values must be passed as a binary value.

  Setting this property can be done with the dbutil utility either interactively or using the following script:

   --- snip ---
   database "<database_name>";
   create property "HP3K_TPI_COMPAT"
    value "2";
   --- snip ---
  

• The encoding of the status array has been modified in case an Eloquence call fails. In case a nonzero status is returned the status array is used as below:

   Element Description
   ------- ------------------------------------
    1      IMAGE status code
    2 - 4  unchanged
    5      zero
    6      IMAGE intrinsic ID
    7      Eloquence status code
    8      Eloquence extended status code
    9      IMAGE mode
    10     Encoded Eloquence call ID and mode
           (Format: 6 bit id, 10 bit mode)
  

• DBLOCK could return wrong status codes. A wrong status code was returned instead of status -128 and -126.

• The IMAGE3K library has been modified to consistently return status -105 in case a memory allocation failed.

• The Eloquence DBFIND mode 1/21 index handling has been enhanced with the option to handle TPI and TurboIMAGE btree search arguments more similar (#2032).

  TurboIMAGE btree indexes and TPI indexes use slightly different conventions in the DBFIND mode 1/21 search argument. With TurboIMAGE btree indexes the wildcard character can be configured through DBCONTROL or dbutil. For TPI indexes a "@" character is used. TPI also considers a space character before the "@" wildcard to be special.

  The IMAGE btree functions are currently not enabled in Eloquence and Eloquence indexes are used used as a replacement. However Eloquence indexes follow the TPI conventions which could cause problems with applications relying on the IMAGE btree behavior. As Eloquence allows to use all TurboIMAGE DBFIND modes, independendly of the index type, this option allows DBFIND mode 1/21 calls to work more closely.

  The HP3K_TPI_COMPAT database property can be used to cause Eloquence indexes to follow the TurboIMAGE btree behavior more closely. If HP3K_TPI_COMPAT is set to nonzero it causes TPI indexes to use the current IMAGE btree wildcard character and not handle trailing spaces as a special case. The default value is zero which implements the previous behavior. Setting this property can be done with the dbutil utility either interactively or using the following script:

   --- snip ---
   database "<database_name>";
   create property "HP3K_TPI_COMPAT"
    value "1";
   --- snip ---
  

  This property is currently not available in the dbutil TurboIMAGE property dialog.

• DBCONTROL mode 5 and 6 return status -82 is CIUPDATE is DISALLOWED.

• Implemented the undocumented DBVERSION intrinsic. The DBVERSION intrinsic result follows the MPE format and returns the following NUL terminated string:

   MPE/iX:     "HP30391 C.1005"
   Eloquence : "IMAGE3K B.0700.12"
  

• Mode 0 has been added to all database calls. On MPE this may used to obtain version information about a TurboIMAGE intrinsic call (eg. QUERY/3000 version command). Eloquence returns status -31 (invalid mode) but status elements 2 to 4 return the Eloquence image3k library version (w/o the patch level, for example B.07.00). It is recommended to use DBINFO mode 801 (or DBVERSION) to obtain the TurboIMAGE version.

B.07.00 Release:

• Fixed a problem with the DBFIND mode 1 call to enable usage with master sets and search items when btreemode1 is set. Please note that this feature is currently not enabled on the server side.

• Changed image3k library version code to B.07.00.07

B.07.00 RC2:

• DBXUNDO mode 3 resulted in status -31

• Alignment requirements for the database argument were removed.
  The database argument was previously required to be 16-bit aligned. This is consistent with the HP3000. However some compilers may not align the base variable properly if it is defined as a string. The image3k library has been changed to no longer require specific alignment for the database argument (#1683).

• Changed image3k library version code to B.07.00.06

B.07.00 pre-release 9 (X2309):

• XBEGIN mode 3 resulted in status -31

• Fixed a problem in the Eloquence client side library related to search items other than first. You need the Eloquence database client library X.23.09.01 or above for this to work correctly.

• Added Linux glibc2.2 build.

• The product code returned by DBINFO mode 801 has been changed from HP Eloquence to Eloquence.

• Changed library version code to A.07.00.02

B.07.00 pre-release 8 (X2308):

• The image3k library revision id was changed to "A.07.00.01".

• Documented use of for database properties to define the image3k library defaults. Database properties allow persistent configuration settings for a database and have been previously undocumented.
  Database properties can be defined with the dbutil utility using the SET command.

• DBINFO 501 (subsystem access) return value is defined with the HP3K_SUBSYSTEM property.

• DBINFO mode 833 returned status -21 for a master set if the set name was specified.

• DBINFO mode 833 returned the wrong item offset. Instead of returning the offset into the item the offset into the key buffer was returned (#1382, fixed with version X.23.07.03).

B.07.00 pre-release 7 (X2307):

• A compatibility problem with DBGET mode 4 was fixed. It is now valid to pass the record number argument from an element of the status array (eg. a previous DBFIND status). Previously, the status array was initialized before the arguments were evaluated.

• An internal buffer could overflow during item list verification and result in an application abort.

• Fixed DBCONTROL. Status element 1 could be uninitialized on success.

• Fixed a compatibility problem with TPI DBFIND modes 1 and 21. The argument parsing now only matches match the first index segment (or any leading string segments).

• DBCONTROL modes 15 and 16 are now supported to control btreemode1 mode and wildcard.

• Added initial support for btreemode1 in DBFIND (modes 1, 4, 21 and 24). Modes 4 and 24 can also be used for index access as an alternative to the TPI modes.

• Fixed a build problem with the image3k shared library. The path to the libeqdb shared library is now embedded.

• Fixed DBINFO compatibility problems:
  • Mode 209: A detail set is allowed as an argument
  • modes 403, 406, 833: Fixed an endian problem with
  • Mode 502: Fixed wrong status 1 returned instead of 0

• Initial support for IMAGE indexes (btreemode1) has been added. The schema processor understands the /INDEXED if specified in the schema file and DBINFO and DBFIND have been modified accordingly. As of this pre-release, support on the server side is not completed.

• DBINFO mode 113 and 209 now support btreemode1 of returned by the database server rather then returning static values.

• Initial support has been added to allow persistent configuration of database settings, such as the default CIUPDATE flag and the default CIUPDATE flag setting.

• DBINFO mode 502 has been modified to returns the default setting of the CIUPDATE flag.

• DBINFO mode 113 returns the initial and current settings for btreemode1 and the wildcard to be used with DBFIND modes 1 and 21.

• DBINFO mode 901 does no longer return a static value but the language id returned can be configured with the database (not yet available).

• Preliminary support for search items in manual master sets which are not the first item in the entry has been added. Previous Eloquence versions required that the first item in a manual master set was used as the search item while TurboIMAGE allows to use a different search item.
  Currently, this option must be enabled explicitely by specifying the -x command line option to the schema processor, otherwise an error message is issued by schema (#1230).

• DBUPDATE modes 1 does no longer allow to change sort items unless the CIUPDATE flag is set. Previously, updating of sort items was allowed in mode 1 but the sort order was not maintained.

• The image3k library verifies the binary compatibility of the unterlying libeqdb library. In case an incompatibility is detected, DBOPEN fails with status -91. This verification is not possible with libeqdb versions before B.07.00 PR#7 and incompatible libraries versions will result in an application abort.

• DBLOCK status element 2 returns the number of lock descriptors that were successfully applied in the DBLOCK request. For DBLOCK modes 1 through 4 and 11 through 14 this will be 1. With Eloquence predicate locks are processed atomically and either succeed or a database status is returned. The number of lock descriptors is always idendential to the argument.

• DBINFO mode 406 returns the database name (without any connection information) truncated to 28 characters. Previous versions returned the first 28 characters from the database name passed to DBOPEN.

• DBUNLOCK status elements 2-4 are set to zero. The number of released lock descriptors in status element 2 is not available.

B.07.00 pre-release 6 (X2306):

• The EQ_DBSERVER, EQ_DBUSER and EQ_DBPASSWORD environment variables can be used to specify the default data base server, user and password. Please refer to the sections on Data Base Names and Authorisation for a description.

• The DBLOGON call has been added to allow providing authorisation information as an alternative to specify the data base password and identity with DBOPEN.

• DBXUNDO returns the current transaction nesting level in status element 2. A new mode 5 has been added which allows to roll-back all levels of transactions (in case of nested transactions). This is equivalent to Eloquence DBROLLBACK mode 3.

• DBXEND returns the current transaction nesting level in status element 2. A new mode 5 has been added which allows to commit all levels of transactions (in case of nested transactions). This is equivalent to Eloquence DBCOMMIT mode 2.

• DBINFO modes 403 and 406 have been added.

• The Database identifier gets replaced with spaces on a successfull DBCLOSE mode 1.

• Database identifiers returned by DBOPEN start with 1 instead of 0. Previous versions returned 0 as database identifier for the first database opened which could cause problems if applications rely on a nonzero value.

• The list argument no longer relies on specific alignment if a string argument is passed. Any argument passed which is not 16 bit aligned is considered a string argument and not a binary list of items. Previous B.07.00 pre-releases always required 16 bit alignment.

• DBOPEN mode 7 is mapped to Eloquence DBOPEN mode 8 which allows concurrent read-only access but prohibits any concurrent read-write access. Previously mode 7 was mapped to Eloquence DBOPEN mode 9 which allows concurrent modification.

• DBINFO returned negative item numbers even if the database was opened in read-only mode (such as with mode 101, 103 or 104). DBINFO now returns positive item numbers when the database is opened in read-only mode.

• DBINFO returned negative data set numbers even if the database was opened in read-only mode (such as with mode 201, 203 or 204). DBINFO now returns positive data set numbers when the database is opened in read-only mode.

• DBINFO mode 403 returns the Eloquence transaction identifier in element 8-9 and the current transaction nesting level in element 14.

• DBINFO mode 406 returns the current schema version and the number of data items, index items and data sets of a database.

• Minor corrections with some DBINFO returns. The new documentation section on DBINFO modes provides a detailed overview and implementation notes on DBINFO.

• The prototype for the DBERROR function has been fixed in the image3k header file. In the previous version the text length was marked a const pointer, which was not appropriate.

• A DBFIND on a search item could result in a crash if an index item with the same name as the search item existed but was not used with the specified data set.

B.07.00 pre-release 4 (X2304):

• DBINFO returned the size of P type items in bytes instead of digits (half-bytes).

• The static image3k library is additionally provided for applications which do not allow dynamic linking. We however do not recommend to link your programs statically as this will require re-linking in case of a bug fix or new version.

B.07.00 pre-release 3 (X2303):

• Item lists are supported (DBGET, DBPUT and DBUPDATE).

• Index items can have the same name as a data item.

• Support for the TurboIMAGE TPI functionality has been added.

• New database limits are supported.

• Upper case entry points for the TurboIMAGE intrinsics have been created in addition to the lower case ones. This makes it possible to use upper case image calls from languages other than C or C++.

• DBINFO mode 801 has been added which allows to identify the version of the TurboIMAGE compatibility library. See below for additonal documentation.

• DBINFO modes 701, 702, 703, 704, 705 have been added. These DBINFO modes implement the equivalent of the HP Eloqunence DBINFO modes 501 to 505.

B.07.00 pre-release 1 (X2301):

• DBINFO mode 202 and 205 returned the entry size in bytes instead of 16 bit words.

Known Problems & Limitations

There are currently no known problems with Eloquence B.07.10.