|
The Eloqunce image3k library provides the TurboIMAGE interface for
the Eloquence database.
The B.08.30 image3k library comes with the following enhancements:
Support for big endian byte order
Traditionally the CPU internals or the operating system define the
order in which information is stored in memory. Either big endian
or little endian order is used.
For example, HP-UX uses a big endian byte order while Linux typically
uses a little endian byte order.
Languages such as Cobol or Java also come with a preference for a
specific byte order to provide a consistent platform regardless
of the actual hardware. For historical reasons both default to the
big endian byte order.
Applications may need adaptions when moving to a platform with a
different byte order.
In most cases the compiler will take care of this. However, this
would affect all data and may result in inconsistencies when sharing
binary data with additional sources.
To support moving of applications from a big endian platform the
Eloquence image3k library was enhanced to support the big endian
byte order on little endian platforms. This allows to move Cobol
applications using TurboIMAGE database calls without any concern
for the byte order to the Linux or Windows platform.
The application byte order may be specified with the EQ3K_OPTIONS
environment variable or using DBCONTROL mode 1000
in the application.
EQ3K_OPTIONS="BYTEORDER=COBOL"
This indicates to the image3k library to assume the big endian byte order
when called from the application process.
Support for multi-threaded applications
The Eloquence database client libraries (eqdb, image3k and ftc)
support multiple threads.
Eloquence by default assumes a thread model that is easy and safe to
use and does not impose overhead.
By default databases are not shared among threads and each thread is
required to open its databases.
With IMAGE database calls it is not sufficient to simply protect
against concurrent calls by multiple threads. Database calls typically
depend on a context that needs to be protected against concurrent
modification as well. Examples include the current record, current path,
chain, FTS results, database transactions or database locks.
More complex threading models are equally supported. Additional
DBCONTROL modes allow managing the association of database context
and threads.
A database context (including any databases opened in this contect)
may be released and is then available for use by another thread.
This allows for ownership of database a contexts for the duration of
a transaction rather than individual calls.
The DBCONTROL modes below may be used by threads to manage the
image3k library:
- 1001 - current database session id
-
Returns the session id of the current database context or zero if no
database context is associated.
The database and qualifier arguments are ignored.
A 32 bit session id is returned in status element 3 and 4.
- 1002 - release database session
-
Disassociates the current database context from the thread and makes
it available for request by another thread.
The database and qualifier arguments are ignored.
- 1003 - request database session
-
The qualifier argument may be used to pass a database session id to
request a specific database context (pointing to a 32 bit session id).
A zero session id (or NULL qualifier) will attach any available
database session.
The database argument is ignored.
A 32 bit session id is returned in status element 3 and 4.
-
A session id of -1 indicates the thread is already associated with a
database context. A thread may only be attacted to a single database
context.
-
A zero session id indicates the requested session was not
available. If no session id was requested then no database
session is available. If necessary an additional database context
may be started by opening a database.
-
Otherwise the id of the associated session is returned (as in
mode 1001).
Changing the database context associated with a thread also affects
the fts and eqdb libraries.
For Eloquence versions before B.08.30 separate experimental thread
safe libraries were available. Only supported a limited thread model
was supported and managing threads was not supported.
As of B.08.30 the default libraries are thread safe.
DBCONTROL modes and image3k options
The DBCONTROL call supports additional modes to allow specifying
image3k options and manage threads.
DBCONTROL(base,qualifier,mode,status)
- 1000 - set image3k option
-
DBCONTROL mode 1000 may be used to set an option in the
image3k library. The qualifier argument specifies an option string
terminated by a semicolon or a NUL character.
Please refer to the image3k option section below for a list of supported
options.
A status -21 is returned for an invalid qualifier argument.
The database argument is ignored.
The DBCONTROL mode -6141 is recognized in addition
to allow calling DBCONTROL mode 1000 in either big endian or
little endian byte order.
- 1001 - current database session id
-
DBCONTROL mode 1001 returns the database session id of the
current database context or zero if no database context is associated.
The database and qualifier arguments are ignored.
The database session id is a 32 bit integer value returned in status
elements 3 and 4.
- 1002 - release database session
-
DBCONTROL mode 1002 disassociates the current database
context from the thread and makes it available for request by other
threads. The database and qualifier arguments are ignored.
- 1003 - request database session
-
DBCONTROL mode 1003 requests a database context to be
associated with the thread. The qualifier argument may specify
a session id (pointer to a 32 bit integer value).
A zero session id (or NULL qualifier) will attach any available
database session.
The database argument is ignored.
The database session id is returned in status elements 3 and 4.
-
A session id of -1 indicates another session id is already
associated with a thread. Only a single database context may be
attached to a thread.
-
A zero session id indicates the requested session was not
available. If no session id was requested then no database
session is available. If necessary an additional database
context may be started by opening a database.
-
Otherwise the id of the associated session is returned (as in
mode 1001).
- 1020 - byte order
-
DBCONTROL mode 1020 returns the current image3k byte
order. The database and qualifier arguments are ignored.
The Status element 2 returns a nonzero flag if the image3k
library expects calls in a different byte order.
This is set if the BE or BE2 option is active.
The status element 3 returns a bit encoded value:
- Bit zero (1) is set if database content of integer (or alike)
items are returned or expected in a different byte order.
This indicates the BE, BE2, BEDATA
or BEDATA2 option is active.
- Bit one (2) is set if the option BE2 or BEDATA2
is active.
The DBCONTROL mode -1020 is also recognized in addition
to allow calling DBCONTROL mode 1020 in either big endian or
little endian byte order.
- 1021 - character set
-
DBCONTROL mode 1021 obtains the assumed character set
encoding.
A value of 0 indicates a HPROMAN8 character set, a value of 1
indicates a ISO88591 characters set encoding. A value of -1 may
be returned if the option CHARSET=IGNORE is set until the database
server is connected.
image3k options
The image3k library options are specified with DBCONTROL mode 1000
or using the EQ3K_OPTIONS environment variable.
The following options are supported:
- BYTEORDER=arg
The BYTEORDER option may be used to specify the byte order
assumed by the image3k library.
The option value NATIVE or DEFAULT specifies the
native byte order of the system. This is the default used by the
image3k library.
For little endian systems such as Linux or Windows the option
values COBOL, BE, BE2, BEDATA
and BEDATA2 are supported in addition.
- NATIVE or DEFAULT
-
Specifies to use the byte order associated with the hardware or
operating system. This is the default.
- COBOL or BE
-
The image3k library assumes big endian mode and expects any call
parameters in big endian oder. Any information returned such as
status codes or DBINFO results use the big endian order.
Any database content of integer or similar item types (I/J/K item type)
use big endian encoding. Any floating point types (W item type) use
the (native) little endian encoding. This follows Cobol conventions
that defaults to big endian byte order for COMP data types but the
native format for IEEE floating point types.
- BE2
-
This mode is identical to the BE mode but in addition
affects IEEE floating point types to use the big endian order.
- BEDATA
-
This mode does not switch the image3k library calls to
big endian mode. Any call parameter and call results use the
native byte order.
However, any database content of integer (or alike) types use the
big endian byte order.
- BEDATA2
-
This mode is identical to the BEDATA mode but in addition
affects IEEE floating point types to use the big endian order.
- CHARSET=arg
The CHARSET option may be used to specify the image3k
character set assumed by the image3k library.
Supported character set encodings include DEFAULT,
HPROMAN8, ISO88591 and IGNORE.
By default the database client library uses the HP-ROMAN8 character
set encoding on HP-UX and ISO-8859-1 on other platforms. Any string
values are converted on the fly as necessary if the client and server
assume a differen character set encoding.
The IGNORE option value may be specified to ignore any
character set encoding and not modify any string data.
EQ3K_OPTIONS environment variable
The EQ3K_OPTIONS environment variable may be used to specify
a list of image3k options, separated by a semicolon.
Specifying EQ3K_OPTIONS is equivalent to calling DBCONTROL
mode 1000 with the option as an argument.
For example:
EQ3K_OPTIONS="BYTEORDER=COBOL;CHARSET=ISO88591"
This specifies the Cobol byte order and ISO-8859-1 character set encoding.
|
