| |
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:
-
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.
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 |
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.
Documented below are the differences we are aware of between the
HP3000 TurboIMAGE intrinsic calls and the IMAGE3K implementation.
General
-
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.
-
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.
-
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.
-
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
-
In addition to ' ' (space) and ';' (semicolon) a NUL character
is also accepted as a delimiter/terminating character.
-
Data base, data set and item names are not case sensitive.
-
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.
-
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.
-
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.
-
Eloquence does not use hashing. So there are no secondaries
in master sets.
-
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.
-
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.
-
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.
-
Item level security is not implemented. All items are considered
writable.
-
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 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
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.
|
-
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.
-
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
-
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
-
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 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.
-
Synonym chain information is always zero
-
Synonym chain information is always zero
-
Synonym chain information is always zero
-
Additional mode 2 is available which has the same effect as
if CIUPDATE is set.
-
Synonym chain information is always zero
-
Mode 8 is the same as mode 7
-
Additional modes 15,16 are available
-
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.
-
Writes to stderr
-
Rough approximation yet
-
Transactions are not database specific but affect all databases
-
No restrictions on database modes, provided database id is not
verified
-
Nested transactions are allowed
-
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
-
Transactions are not database specific but affect all databases
-
Provided database id is not verified
-
Text is ignored
-
Nested transactions are allowed
|
|
