Database Library Enhancements

Contents:

• TurboIMAGE compatibility library (image3k)
• Database client library (eloqdb)

TurboIMAGE compatibility library (image3k)

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

Database client library (eloqdb)

• The eloqdb database client library was enhanced to upload process information to the database server when a server connection is established. The process information is then output in the session status of the server web status and allows to identify the application.

  The process information includes the user id (not on Windows), the process id and the command line. In addition, if the environment variable EQ_AUDIT_INFO is set its content is also included. The EQ_AUDIT_INFO environment variable allows to include application specific information in the status output.

• The eloqdb database client library was enhanced to check if a process was fork()ed with a database opened. This is unsupported and resulted in undefined behavior with previous library versions.

  Any attempt to access the database in the forked child process will now abort with an internal error like below:

   Assertion failed: 
   initial_process_id == current_process_id
  

  A fork() is valid if no database is currently opened.

• The Eloquence client library was changed to return the sort item in the related detail set when a master set is passed as qualifier (#2300).

  The image3k library internally makes use of the Eloquence DBINFO mode 303 to implement DBINFO mode 301. However the Eloquence DBINFO mode 303 did not return sort item information when a master set was provided as qualifier.