| |
TurboIMAGE compatibility
[ Main document |
Back ]
This document covers the Eloquence TurboIMAGE compatibility extension
and the TurboIMAGE database intrinsic calls.
Contents:
The Eloquence TurboIMAGE compatibility extension is an optional
Eloquence component which provides a HP e3000 TurboIMAGE
compatible programming interface ("intrinsics") for the
HP Eloqunece database. While not 100% compatible it is close so
applications originating on the HP e3000 can be ported to the
Eloquence database with no or only minor changes.
Some visible differences are:
- 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 (including master data sets).
- Additional locking capabilities.
- Additional database utilities including database restructuring.
- Multiplatform (HP-UX, Windows NT/2000/XP, Linux).
- Network transparent.
- Dynamic, nested transactions, transaction isolation (uncommitted
changes are not visible to other processes).
- Deadlock detection and recovery.
- On-line backup and forward recovery.
- New, more flexible security subsystem.
- The Eloquence database does not reside in the file system
but uses volume files which reside in the file system
as a container for the data and structural information.
- Eloquence does not use a ROOT file. Structural information is
kept in the database (in the database catalog).
The Eloquence database is a client/server based architecture.
All database access is performed by the database server on behalf
of the application.
The Eloquence TurboIMAGE compatibility extension is a
library of functions that translates the TurboIMAGE intrinsic calls
into the native Eloquence API. This does not impose a performance
impact.
----------------- -----------------
| | | |
| Application | | Application |
| | | |
|---------------| |---------------|
| EQ DB API | | IMAGE3K API |
----------------- |---------------|
^ | EQ DB API |
| -----------------
| ^
| |
v v
----------------------------------
| |
| Eloquence database server |
| |
----------------------------------
The IMAGE3K functions translate the TurboIMAGE calls into the
Eloquence calls.
An application using the IMAGE3K option calls the image3k library
functions which then calls the Eloquence client side API.
Eloquence databases do not reside in the file system but are
managed by a server process. Consequently, a database name no longer
refers to a location in the file system but specifies the database
server instance and the database on that server.
The database name consists of the following elements:
[[host][:service]/]database
-
The host name or IP address on which the database server
resides. The default is the local system (localhost or IP
address 127.0.0.1).
-
The service name or port number which is used by the server
process on that machine. The default is defined by the service
name eloqdb which defaults to port 8102 during installation.
-
The database name. If the host name or service is specified
it is separated with a slash from the database name.
The database name is no longer restricted to 6 characters and
can include dots and hyphen characters in addition to letters
and digits.
The examples below specify the database SAMPLEDB on the local
system, using the default database server instance:
localhost:eloqdb/SAMPLEDB
:eloqdb/SAMPLEDB
SAMPLEDB
The environment variable EQ_DBSERVER can be used to specify the
default database server. The syntax is as below:
[host][:service]
-
The host name or IP address on which the database server
resides. The default is the local system (localhost or IP
address 127.0.0.1).
-
The service name or port number which is used by the server
process on that machine. The default is defined by the service
name eloqdb which defaults to port 8102 during installation.
For example:
If the EQ_DBSERVER environment variable is set to lxsrv:8302
then a DBOPEN will default to connect the database server
running on host lxsrv at the port number 8302.
This is effective for all database utilities.
The Eloquence database server maintains its own user list.
In order to connect to the Eloquence database server a user
name and password is required.
Two predefined users, "dba" and "public" are created by default.
For each database access groups define the access rights. This
is the equivalent of the TurboIMAGE user classes which can be
defined in the PASSWORDS: section in the schema file.
The schema processor creates two default groups "public" and "dba".
The group "dba" provides the right to erase a data set and the
group "public" has the access rights defined for user class 0.
Other groups are created and provide the access rights defined
in the schema file.
Users can be associated with up to eight access groups and get the
summary rights associated with the access groups. Unless associated
with a security group, no access to the database is possible.
By default, the schema processor associates the user "dba" with the
group "dba" and the user "public" with the access group "public"
and all other access groups defined in the schema file.
This can be changed with the dbutil utility.
Eloquence requires to use the DBLOGON call to provide authorisation
information when connecting to a database. By default Eloquence
will use the user "public" which is the equivalent to the UCL 0
with TurboIMAGE. For administative tasks (such as schema)
Eloquence utilities default to the user "dba".
Authorisation information can be provided in different ways:
-
You can explicitely use the DBLOGON call to specify a user name
and password which is then used with a subsequent DBOPEN.
-
With the TurboIMAGE compatibility API you can use the DBOPEN
password argument to specify a user and password.
This will result in an implicit call to DBLOGON.
Once a user and password has been specified it is saved and
used with subsequent DBOPEN.
The user name or password can be a reference to a file which
holds the actual user name and/or password.
-
If the user name starts with file: it is expected to be a
reference to a file. The first line is used as the user name
and if present a second line is used as the password.
-
If the password starts with file: is is expected to be a
reference to a file. The first line of that file is used as
the user password.
This makes sure the password is not exposed to other users which
can use the ps utility to obtain the command line of executing
processes or may have access to environment variables
(on Linux through the /proc file system).
The environment variables EQ_DBUSER and EQ_DBPASSWORD can be
used to specify the default user and password.
For example:
If the environment variable EQ_DBUSER is set to "mike" and
the EQ_DBPASSWORD variable is set to "file:/home/mike/db_pswd"
and the file db_pswd holds the string "secret" the user name
"mike" and the password "secret" are used by default to access
the database.
This is effective for all database utilities.
When compiling programs against the IMAGE3K API, it is 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 'C' program
which can be used on the HP e3000 and with Eloquence:
#if defined(_MPEXL_SOURCE)
#pragma intrinsic DBOPEN
...
#pragma intrinsic DBEXPLAIN
#else
#include "image3k.h"
#endif
This causes include file image3k.h to be used when not compiling for MPE.
The program needs to be linked against the Eloquence image3k library
which implements the TurboIMAGE intrinsics. The library name depends
on the platform: libimage3k.sl (HP-UX), libimage3k.so (Linux)
or image3k.lib (Windows).
The Eloquence image3k library has a dependency on the Eloquence database
client library which is loaded automatically at runtime
(libeqdb.sl on HP-UX, libeqdb.so on Linux, eloqdb32.dll on Windows).
It is not necessary to explicitly link against the Eloquence database
client API library.
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 byte order" 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 platforms. When the database server is using a different
platform (eg. Client on Windows, Server on HP-UX) all values and
strings are converted on the fly by the Eloquence database library.
Depending on the platform, the Eloquence libraries and 'C' header files
are installed in different locations:
- HP-UX:
The various Eloquence library versions are located in subdirectories
in /opt/eloquence6/lib to support multiple library
versions:
| 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) |
The 'C' header files are installed in the
/opt/eloquence6/include directory.
- Linux:
The Eloquence libraries are located in the /opt/eloquence6/lib
directory and the 'C' header files are installed in the
/opt/eloquence6/include directory.
- Windows:
The shared libraries (.dll, used at runtime) are installed in the Windows
system directory, e.g. C:\Windows\System32. This ensures the
Windows dynamic linker is able to locate them without specifying
a path.
The stub libraries (.lib, used to link against) and 'C' header files are
installed in the Eloquence lib and include
installation subdirectories, e.g. C:\Programs\Eloquence\lib and
C:\Programs\Eloquence\include.
Example programs (written in 'C') using the TurboIMAGE API are
available for your reference.
The archive hp3ksrc.tar includes the source code of the Eloquence
migration utilities which can be compiled on the HP e3000 and
with Eloquence.
The following Makefile can be used to compile the example
programs and link with the Eloquence database.
CFLAGS = -O -D_POSIX_SOURCE -I/opt/eloquence6/include
LIB = -L/opt/eloquence6/lib -limage3k
all: hp3kinfo hp3kexport
hp3kinfo: hp3kinfo.c
$(CC) -o $@ $(CFLAGS) hp3kinfo.c $(LIB)
hp3kexport: hp3kexport.c
$(CC) -o $@ $(CFLAGS) hp3kexport.c $(LIB)
Notes:
- The leading spaces in the makefile must be tab characters.
- On HP-UX, the required library version subdirectory must be
specified in the library path, e.g.
-L /opt/eloquence6/lib/pa20_32 for the 32 bit PA-RISC 2.0
libraries.
Using Eloquence with Acucobol
There are two options to use Eloquence from Acucobol.
Either the Eloquence image3k library is loaded dynamically
by the application or the image3k library is linked to
the runcbl cobol runtime. The notes below describe how to
load the Eloquence image3k library dynamically.
- HP-UX
-
- Add the following line to the etc/cblconfig configuration file:
SHARED-LIBRARY-EXTENSION .sl
- Load the libimage3k.sl from within your program (once per
application). This makes the TurboIMAGE intrinsics available:
CALL "/opt/eloquence6/lib/pa11_32/libimage3k.sl".
On HP-UX on the Itanium architecture the 64 bit library must be
loaded instead:
CALL "/opt/eloquence6/lib/hpux64/libimage3k.sl".
- Linux
-
- Load the libimage3k.sl from within your program(once per
application). This makes the TurboIMAGE intrinsics available:
CALL "/opt/eloquence6/lib/libimage3k.so".
- On Linux and Windows (little-endian) you should consider
to use the -D5 compile option.
- Windows
-
- load the image3kc.dll from within your program(once per
application). This makes the TurboIMAGE intrinsics available:
CALL "image3kc.dll".
- On Linux and Windows (little-endian) you should consider
to use the -D5 compile option.
Notes:
-
On little endian architectures (Intel) the COMP-5 type
must be used with the Eloquence image3k library (rather
than COMP).
The Eloquence library uses the native byte order of the
underlying system while the cobol COMP data type uses the
big endian byte order for all systems, independendly
of the underlying architecture.
The -D5 compiler option maps all COMP data types to COMP-5.
Subsequent Eloquence versions will likely allow to remove this
requirement.
-
On Windows the image3k.dll and image3kc.dll are available.
The image3k.dll uses the stdcall (aka. "pascal") calling convention
which is standard on Windows. The image3kc.dll (note the
additional 'C') uses the cdecl calling convention as an
alternative which is assumed by default by Acucobol.
Using Eloquence with MF Cobol
With MF Cobol, the Eloquence image3k library is linked
to the application. This makes the TurboIMAGE intrinsics
available. The image3k library is specified with the linker.
Notes:
The Eloquence schema processor is compatible with TurboIMAGE
schema files.
In order to enable TurboIMAGE compatibility you need to specify
the -T command line option.
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
-b name - specify database name
-l - output source listing (LIST)
-n - no root file, only check syntax (NOROOT)
-t - output set table (TABLE)
-e cnt - Abort after cnt error messages (ERRORS=)
-T - HP3000 TurboImage compatibility mode
-W width - Limit line length to width
-L - Add line number to source listing
The -T option implies the -W72 option which causes characters
beyond column 72 to be ignored by default. This will ignore any editor
line numbers if the file has been saved with line numbers.
The -W command line option allows to specify a line width other than
72 (0 = off).
The Eloquence schema processor does not require $CONTROL directives.
Most common settings can be specified from the command line.
Command line options take precendence over $CONTROL directives.
| $CONTROL |
Equiv. Option |
| $CONTROL NOLIST |
default |
| $CONTROL LIST |
-l |
| $CONTROL ROOT |
default |
| $CONTROL NOROOT |
-n |
| $CONTROL TABLE |
-t |
| $CONTROL ERRORS= |
-e |
The following notes apply to the Eloquence schema processor:
- The /INDEXED option is accepted but has no effect.
Currently, Eloquence does not support the TurboIMAGE btree.
For indexed access to the database you need to create index
items and define an index for the detail data set.
IMAGE btree access ("superchains") will be added with a
feature patch after the B.07.00 release.
- $CONTROL options are supported but most have no effect since
they are specific to TurboIMAGE implementation details which have
no equivalent with Eloquence.
- $CONTROL ODDPALLOWED is not supported and P items using an odd
number of nibbles are not allowed. Eloquence internally maintains
item sizes in bytes and cannot handle sub-item sizes below a byte.
- Item- and data set names are considered case insensitive.
The characters valid in an item- or data set name is more limited
in Eloquence. If you get a syntax error due to an invalid data
set or item name please consider changing to a valid name or
send a bug report.
- The data set capacity is not retained. DBINFO modes 202 and 205
return the max. number of records allocated for a data set.
- The schema processor assigns the "public" user to all
database access groups which effectively defaults to public access
to the database. You can use the dbutil utility to modify the
database access rights.
As an alternative to running schema directly, you can also use the
dbschema script. Both commands shown below are equivalent.
schema -T schemafile
dbschema schemafile
dbschema is a small script file which is installed with Eloquence
and simply calls the schema processor with the -T option.
#!/bin/sh
# dbschema - default to TurboIMAGE compatible schema processor
ELOQUENCE=${ELOQUENCE:-/opt/eloquence6}
exec $ELOQUENCE/bin/schema -T $@
Database properties can be used to define the image3k default
behavior.
Database properties are defined with the dbutil utility
(interactively or with the dbutil scripting capabilities).
Database properties are stored in the sysdbproperties table
of the database catalog. To use database properties with a
database, the database must have been created with the B.07.00
database server (PR#7 or above).
| Property |
Description |
| HP3K_LANG |
This property defines the database language id as returned
by DBINFO mode 901. It has no effect on the database operation.
The default language id is zero. |
| HP3K_CIUPDATE |
This property defines the default value of the CIUPDATE flag.
This value returned by DBINFO mode 502. The default value
for the CIUPDATE flag is 1 (ALLOWED). |
| HP3K_BTREEMODE1 |
This property defines the default value of the BTREEMODE1 flag.
The default value for the BTREEMODE1 flag is 1 (ON). |
| HP3K_WILDCARD |
This property defines the default wildcard character used with
BTREEMODE1. The default value is "@". |
| HP3K_SUBSYSTEM |
this property defines the default SUBSYSTEM access as returned
by DBINFO mode 501 and was historically used by the
TurboIMAGE QUERY application. It has no effect on the database
operation. The default SUBSYSTEM access is 3 (RW). |
Database properties used by the image3k library can be defined
with the SET command of dbutil. The syntax used is similar to
TurboIMAGE.
- SET LANGUAGE = n;
- Set the TurboIMAGE LANGUAGE property to n
where n is a numerical value.
Note:
- The value of the LANGUAGE property is returned by DBINFO mode 901.
- This statement sets the HP3K_LANG database property.
- SET CIUPDATE = mode;
- Set the TurboIMAGE CIUPDATE property to mode
where mode is DISALLOWED, ALLOWED or ON.
The default value is ALLOWED.
Note:
- The value of the CIUPDATE property is used by DBUPDATE
and returned by DBINFO mode 502.
- This statement sets the HP3K_CIUPDATE database property.
- SET BTREEMODE1 = mode;
- Set the TurboIMAGE BTREEMODE1 property to mode
where mode is ON or OFF.
The default value is ON.
Note:
- The value of the BTREEMODE1 property is used by DBFIND
and returned by DBINFO mode 113.
- This statement sets the HP3K_BTREEMODE1 database property.
- SET WILDCARD = "c";
- Set the TurboIMAGE WILDCARD property to c
where c is a valid ASCII character.
The default value is @.
Note:
- The value of the WILDCARD property is used by DBFIND
and returned by DBINFO mode 113.
- This statement sets the HP3K_WILDCARD database property.
- SET SUBSYSTEM = mode;
- Set the TurboIMAGE SUBSYSTEM property to mode
where mode is NONE, READ or RW.
The default value is RW.
Note:
- The value of the SUBSYSTEM property is returned by DBINFO mode 501.
- This statement sets the HP3K_SUBSYSTEM database property.
The Eloquence TurboIMAGE compatibility extension provides
all TurboIMAGE intrinsics.
Due to differences in the underlying implementation
some details may differ from TurboIMAGE.
For each TurboIMAGE intrinsic call a short description is provided
along with notes which describe possible Eloquence specific
behavior or limitations.
List of database calls.
Additional database documentation:
Related documentation:
- HP3000 TurboIMAGE documentation 30391-90012, revision E0701
an on-line version is available at at http://docs.hp.com (
HTML
PDF ).
This section provides some general overview which applies
to all database calls.
-
The Eloquence database implements transaction nesting and
transaction isolation. So nesting of dynamic transactions is
allowed and modified information is not exposed to concurrent
sessions until the transaction is committed.
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 6 .. 10 are different
from TurboIMAGE. They include additional Eloquence specific
information.
| Element |
Contents |
| 6 |
Native Eloquence function id. |
| 7 |
Native Eloquence status code. |
| 8-9 |
Native Eloquence secondary status code. |
| 10 |
Native Eloquence mode |
-
In addition to ' ' (space) and ';' (semicolon) a NUL character
is also accepted as a delimiter/terminating character.
-
Database, data set and item names are not case sensitive.
-
The Eloquence database procedures may 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.
-
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 according
to the requirement of your application.
Instead of checking if a write access is covered by a lock
Eloquence checks if a concurrent lock has been granted.
In this case a write attempt will return with a database status.
-
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).
The item types J and R are not supported natively and are only
visible to the TurboIMAGE emulation.
- The 'R' item type is supported in TurboIMAGE compatibility
only, values are expected to be encoded in IEEE format.
Native Eloquence considers this an 'E' type.
- The 'J' item type is supported in TurboIMAGE compatibility
only. Native Eloquence considers this an 'I' type.
-
The Eloquence security system differes from the traditional
IMAGE model.
A user name and password is required to connect to a database.
Unless specified a default user ("public") is used.
A user name and password can be specified either by using the
Eloquence specific DBLOGON call or providing a user name
and password with DBOPEN.
-
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.
-
Static transactions are currently not supported with Eloquence
and DBBEGIN, DBEND and DBMEMO have no effect. Eloquence relies
on dynamic transactions internally. A future version of Eloquence
may add support for static transactions for use with forward recovery
or auditing purposes.
Initiates access to the database and establishes the user class number
and access mode for all subsequent database access. DBOPEN is used in
conjunction with DBCLOSE to establish and terminate access to a database.
DBOPEN(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;".
Please refer to the section on Database Names
for detailed information.
If the database is successfully opened, the two blanks are
replaced with a value called the base ID. The base ID uniquely
identifies this access path between the database and the
process calling DBOPEN. In all subsequent accesses to the
database, the first halfword of base must be this base ID;
therefore, the array should not be modified. The base ID
contains a number that distinguishes between the 63 access
paths allowed for each process for accessing a given database.
- 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{_;}]]
[/USERIDENT]{_;} Provides user name and empty password
;[/USERIDENT{_;}] Same
password[/USERIDENT]{_;} Specifies user name and password
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 alsways
be present.
Unless the password and the user identifier string is present,
the password argument is ignored.
Please refer to the section on
Database Security and Authorisation
for detailed information.
- mode
-
is an integer between 1 and 9, inclusive. See discussion below for a summary.
- status
-
is the name of an array of 10 halfwords in which the database returns
status information about the procedure. If the procedure executes
successfully, the status array contents are:
| Element |
Contents |
| 1 |
If the procedure succeeds, the return status is 0.
Otherwise it provides a status code to describe the failure.
|
| 2 |
User id as defined by the server.
Id 1 specfies the default dba user and 2 the default
public user.
|
| 3-4 |
Zero
|
| 5-10 |
Information about the current procedure call and its results.
|
DBOPEN modes
- TurboIMAGE/XL supports the following DBOPEN modes:
- Mode 1: modify DB, lock enforced, allow concurrent modify/read - 1,5
- Mode 2: update DB, allow concurrent update/read - 2,6
- Mode 3: modify DB, exclusively
- Mode 4: modify DB, allow concurrent read - 6
- Mode 5: read DB, allow concurrent modify/read - 1,5
- Mode 6: read DB, allow concurrent read/modify - 6/2, 6/4, 6/8
- Mode 7: read DB, exclusively
- Mode 8: read DB, allow concurrent read - 6/8
- Eloquence natively supports the following DBOPEN modes:
- Mode 1: modify DB, allow concurrent read/modify
- Mode 3: modify DB, exclusively
- Mode 8: read DB, allow concurrent read
- Mode 9: read DB, allow concurrent read/modify
- The Eloquence TurboIMAGE compatibility option supports
all DBOPEN modes:
- Modes 1, 3, 8 are equivalent
- Modes 2, 4 are mapped to mode 1
- Modes 5, 6 are mapped to mode 9
- Mode 7 is mapped to mode 8
- Mode 9 is available in addition
Notes:
-
The Database name is not limited to 8 characters and must
follow the Eloquence conventions.
The database name must either be separated by a NUL character,
a semicolon or a space character. Since Eloquence database names
are not limited to a fixed length a terminating character must be present.
Please refer to the section on Database Names
for detailed information.
-
Remote database handling is different (the server instance is encoded
with the database name).
-
Eloquence uses a different access control scheme than TurboIMAGE.
The Eloquence database maintains users with passwords.
The user name and password can either be specified with the
DBOPEN password argument or the Eloquence specific DBLOGON
call can be used. It no user name is specified a default
user ("public") is used.
Status element 2 returns the user id which is different from
the user class returned by TurboIMAGE.
Please refer to the section on
Database Security and Authorisation
for detailed information.
-
If a user name is present in the password argument (the optional
"identifier") it is used as authorisation information with the
database server. If only a password is present the password argument
is ignored and the default user ("public") is used which is the
Eloquence equivalent to user class 0.
-
Eloquence does not implement "Creator Access". Instead an
adminstrative access group ("dba") is added to each database which
by default is associated with the default adminstrative user ("dba").
The dba group does not grant access to the database contents but can
only be used to maintain the database. The dbutil utility program
can be used to grant additional access rights to the dba group.
-
Eloquence users and passwords are not limited to 8 characters.
However due to the design of the TurboIMAGE API the IMAGE3K library
is unable to reliably determine the bounds of the password and
user argument unless a termination character is present (either
space or semicolon) or a NUL character is used to terminate the
password argument. It is recommended that the password and the
optional identifier are terminated with a space or semicolon
character.
-
Only modes 1, 3, 5, 8 are fully compatible. All other modes are
mapped and usually do not impose concurrency restrictions.
- Mode 6 allows concurrent modification
- Mode 9 is available in addition
-
Access to database is denied unless at least read access for a
single data set is granted to the user. This is different than
TurboIMAGE which assigns user class 0 if an invalid password is
used or no access rights are granted with a password.
-
A status -104 is returned by DBOPEN if the separate IMAGE3K license
key has not been installed on the database server.
Terminates access to a database or a data set, or rewinds a data set.
DBCLOSE is used in conjunction with DBOPEN to establish and terminate
access to a database.
DBCLOSE(base,dset,mode,status)
- base
-
is the name of an array used as the base parameter when opening the
database. The first element of the array must contain the base ID
returned by DBOPEN. (Refer to DBOPEN for more information about the
base ID.)
- dset
-
is the name of an array containing the left-justified name of the data
set to be closed, or is an integer referencing the data set by number
if mode equals 2 or 3. If mode equals 1, this parameter is ignored.
The data set name can be up to 16 characters long. If shorter, it must
be terminated by a semicolon, a space or NUL character.
- mode
-
is an integer equal to 1, 2, or 3 indicating the type of termination
desired.
- status
-
is the name of an array of 10 halfwords in which the database returns
status information about the procedure. If the procedure executes
successfully, the status array contents are:
| Element |
Contents |
| 1 |
If the procedure succeeds, the return status is 0.
Otherwise it provides a status code to describe the failure.
|
| 2-4 |
Unchanged from previous procedure call using this array.
|
| 5-10 |
Information about the current procedure call and its results.
|
Notes:
-
Mode 2 is the same as mode 3.
-
Mode 1 does not abort a dynamic transaction. Eloquence
transactions are not database specific so this cannot be
enforced. Eventually we should abort/roll-back an eventually
pending dynamic transaction on a DBCLOSE.
DBCONTROL(base,qualifier,mode,status)
- base
-
is the name of an array used as the base parameter when opening the
database. The first element of the array must contain the base ID
returned by DBOPEN. (Refer to DBOPEN for more information about the
base ID.)
- qualifier
-
used only for certain DBCONTROL modes.
- mode
-
must be an integer equal to 1, 2, 5, 6, 7, 9, 10, 13, 14, 15, 16, 18, 19 or 20.
- status
-
is the name of an array of 10 halfwords in which the database returns
status information about the procedure. If the procedure executes
successfully, the status array contents are:
| Element |
Contents |
| 1 |
If the procedure succeeds, the return status is 0.
Otherwise it provides a status code to describe the failure.
|
| 2-4 |
Unchanged from previous procedure call using this array.
|
| 5-10 |
Information about the current procedure call and its results.
|
DBCONTROL modes
| Mode |
Description |
| 1 |
Turn on the deferred output option (AUTODEFER).
This mode is accepted but has no effect with Eloquence.
|
| 2 |
Turn off the deferred output option (AUTODEFER).
This mode is accepted but has no effect with Eloquence.
|
| 5 |
Enable the critical item update option (CIUPDATE).
Mode 5 enables the CIUPDATE option for the current DBOPEN until either a
DBCONTROL mode 6 call disables the option or the database is closed.
With Eloquence CIUPDATE is allowed but disabled by default.
|
| 6 |
Disable the critical item update option (CIUPDATE).
Mode 6 disables the CIUPDATE option for the current DBOPEN until either a
DBCONTROL mode 5 call enables the option or the database is closed.
With Eloquence CIUPDATE is allowed (but not enabled) by default.
|
| 7 |
Allow the database to be included in the dynamic multiple
database transaction (DMDBX) and enable the database for
deadlock detection.
This mode is accepted but has no effect with Eloquence.
|
| 9 |
Enable the HWMPUT option of DBPUT for the current DBOPEN.
This mode is invalid with Eloquence, the application has
no control over record placement. Assuming the application
requesting this mode expects a specific behavior this mode
will result in a status error.
|
| 10 |
Disable the HWMPUT option of DBPUT for the current DBOPEN.
This mode is invalid with Eloquence, the application has
no control over record placement. Assuming the application
requesting this mode expects a specific behavior this mode
will result in a status error.
|
| 13 |
Allow a privileged mode caller to perform B-Tree related
tasks such as adding, dropping, rebuilding, releasing, or
securing a B-Tree index file. Exclusive database access is
required to add, drop, or rebuild a B-Tree index. Qualifier
has a structured record containing dataset information and
directives.
This mode is not supported with Eloquence.
|
| 14 |
Allow a privileged mode caller to set BTREEMODE1 option to
ON or OFF and set wildcard character for the database (permanent).
This mode is not supported with Eloquence.
|
| 15 |
Enable B-Tree wildcard search for DBFIND mode 1, X and U types,
for the master data set's key item and its corresponding search
items in details, if the key item has a B-Tree index.
In other words, turn on the BTREEMODE1 flag for the current database
open. The first byte of the qualifier is examined. If it is null or
blank, then the current wildcard character is not changed.
If it is in the ASCII range (33...126), then the wildcard character
is changed to that value for the current DBOPEN.
If the qualifier is any other value, DBCONTROL returns an error.
Affects only the current database open. It needs to be done once per
database and remains activated until the database is closed or the
application terminates. This mode allows you to perform B-Tree
searches on ASCII types without making application changes.
This mode is currently not supported with Eloquence.
|
| 16 |
Disable B-Tree wildcard search for DBFIND mode 1
regardless of the existence of a B-Tree index. That is, turn
off the BTREEMODE1 flag for the current database open. The
qualifier is ignored, and BTREEMODE 1 is turned off. Affects
the current database open only. It needs to be done once
per database and remains activated until the database is
closed or the application terminates.
This mode is currently not supported with Eloquence.
|
| 18 |
Enables the XM to return a warning when the dynamic
transaction exceeds the 28MB threshold.
This mode is accepted but has no effect with Eloquence.
|
| 19 |
Disables the XM to return a warning when the dynamic
transaction exceeds the 28MB threshold.
This mode is accepted but has no effect with Eloquence.
|
| 20 |
Allows the program to overwrite the DBUTIL 'OLDINFOLIMITS' setting.
DBINFO mode 103 returns data items in a database; DBINFO mode 203
returns data sets in a database; DBINFO mode 204 returns all data
sets with an item and DBINFO mode 301 returns paths for a specific
data set. If a user program allocates arrays to store the data
returned from above DBINFO calls and the size of the arrays are
defined by the old TurboIMAGE item/set limit.
Then a database with new item/set limit may cause the program to
abort.
This mode is accepted but has no effect with Eloquence.
Eloquence expects an application which assumes specific
database limits to the database limits using DBINFO mode 406.
|
Notes:
-
AUTODEFER (mode 1, 2) is accepted but has no effect
-
HWPUT (mode 9, 10) is not accepted and results in status -31.
The application has
no control over record placement. Assuming the application
requesting this mode expects a specific behavior this mode
will result in a status error.
-
CIUPDATE is always considered allowed (but disabled by default)
-
betreemode1 is considered enabled by default
-
Modes 1, 2, 7, 18, 19, 20 are accepted but have no effect with
Eloquence.
-
Modes 9, 10, 13, 14 are not supported with Eloquence and
result in status -31.
-
Database open mode and transaction status is not checked
Provides information about the database being accessed. The
information returned is restricted by the user class number
established when the database is opened; any data items, data sets
or paths of the database which are inaccessible to that user class are
considered to be non-existent.
DBINFO(base,qualifier,mode,status,buffer)
- base
-
is the name of an array used as the base parameter when opening the
database. The first element of the array must contain the base ID
returned by DBOPEN. (Refer to DBOPEN for more information about the
base ID.)
- qualifier
-
is the name of an array containing a data set/data item name or an integer
referencing a data item/data set, depending on the value of the mode
parameter. This parameter form is identical to the dset and item
parameters for DBFIND, and the dset and list parameters for DBPUT.
- mode
-
is an integer indicating the type of information desired.
Please refer to the document on DBINFO modes
for detailed information on valid DBINFO modes, qualifiers
and buffer.
- status
-
is the name of an array of 10 halfwords in which the database returns
status information about the procedure. If the procedure executes
successfully, the status array contents are:
| Element |
Contents |
| 1 |
If the procedure succeeds, the return status is 0.
Otherwise it provides a status code to describe the failure.
|
| 2 |
Length of information in buffer array (in halfwords).
|
| 3-4 |
Unchanged from previous procedure call using this array.
|
| 5-10 |
Information about the current procedure call and its results.
|
- buffer
-
is the name of an array in which the requested information is
returned. The contents of the buffer array vary according to the
mode parameter used.
Please refer to the document on DBINFO modes
for detailed information on valid DBINFO modes, qualifiers
and buffer.
Applies a logical lock to a database, one or more data sets, or one or
more data entries.
DBLOCK(base,qualifier,mode,status)
- base
-
is the name of an array used as the base parameter when opening the
database. The first element of the array must contain the base ID
returned by DBOPEN. (Refer to DBOPEN for more information about the
base ID.)
- qualifier
-
The qualifier argument depends on the mode:
- Modes 1,2,11,12: Ignored
- Modes 3,4,13,14: An integer variable referencing the data set
number or the name of an array containing a data set name. Could
also be "@" when applying a database lock.
- Modes 5,6,15,16: The name of the array containing the lock
descriptors.
- mode
-
contains an integer indicating the type of locking desired.
Valid modes are 1 to 6 and 11 to 16.
- status
-
is the name of an array of 10 halfwords in which the database returns
status information about the procedure. If the procedure executes
successfully, the status array contents are:
| Element |
Contents |
| 1 |
If the procedure succeeds, the return status is 0.
Otherwise it provides a status code to describe the failure.
|
| 2 |
The number of lock descriptors that were successfully applied in
the DBLOCK request. For successful locks in modes 1 through 4
and 11 through 14 this will be 1.
|
| 3 |
Zero. TurboIMAGE used to return additional information
for a return status 20 which is not available with
Eloquence:
If the return status is 20, this element contains 0 if the
database is locked, 1 if the data set or entries are locked.
|
| 4 |
Unchanged from previous procedure call using this array.
|
| 5-10 |
Information about the current procedure call and its results.
|
DBLOCK modes:
Lock
Mode |
Lock
Level |
Locking Type |
Description |
| 1 |
Base |
Unconditional |
DBLOCK applies an unconditional lock to the
entire database, returning to the calling
program only after the lock is successful (or if
an error occurs). The qualifier parameter is
ignored.
|
| 2 |
Base |
Conditional |
DBLOCK applies a conditional lock to the
entire database and returns immediately. A return
status of zero indicates success. A non-zero
return status indicates the reason for failure.
|
| 3 |
Set |
Unconditional |
DBLOCK applies an unconditional lock to a data
set. The qualifier parameter must specify the
name of an array containing the left-justified
name of the data set or the name of an
integer referencing the data set number. The
data set name can be 16 characters long or, if
shorter, terminated by a semicolon or blank.
The data set need not be accessible for read
or write access to the user requesting the lock.
|
| 4 |
Set |
Conditional |
DBLOCK applies a conditional lock of the same
type as mode 3. It always returns to the calling
program immediately. A return status of zero
indicates success and a non-zero return
status indicates a reason for failure.
|
| 5 |
Entry |
Unconditional |
DBLOCK applies unconditional locks to the data
entries specified by lock descriptors. The
qualifier parameter must specify the name of
an array containing the lock descriptors. It
returns only when all the locks have been
acquired.
|
| 6 |
Entry |
Conditional |
DBLOCK applies conditional locks of the same
type as mode 5. If multiple lock descriptors are
specified and DBLOCK encounters a lock
descriptor that it cannot apply, it returns. All
locks that have been applied until that point
are released.
|
Modes 1 through 6 request a write lock.
Modes 11 through 16 are identical but request a read lock.
A write lock does block any concurrent read or write lock.
A read lock blocks concurrent write locks but allows
current read locks.
Notes:
Relinquishes the locks acquired by all previous calls to DBLOCK.
If the calling process has the same database opened multiple times,
only those locks put into effect for the specified access path are
unlocked.
DBUNLOCK(base,qualifier,mode,status)
- base
-
is the name of an array used as the base parameter when opening the
database. The first element of the array must contain the base ID
returned by DBOPEN. (Refer to DBOPEN for more information about the
base ID.)
- qualifier
-
The qualifier argument depends on the mode:
- Modes 1 (2,11,12): Ignored
- Modes 3 (4,13,14): An integer variable referencing the data set
number or the name of an array containing a data set name. Could
also be "@", when releasing a database lock.
- Modes 5 (6,15,16): The name of the array containing the lock
descriptors.
- mode
-
contains an integer indicating the type of unlock desired.
Valid modes are 1, 3, 5, 11, 13 and 15.
Modes 2, 4, 6, 12, 14 and 16 are also accepted as an alias.
- status
-
is the name of an array of 10 halfwords in which the database returns
status information about the procedure. If the procedure executes
successfully, the status array contents are:
| Element |
Contents |
| 1 |
If the procedure succeeds, the return status is 0.
Otherwise it provides a status code to describe the failure.
|
| 2 |
Zero. TurboIMAGE used to return the number of lock descriptors
that were released.
|
| 3-4 |
Reserved for internal use.
|
| 5-10 |
Information about the current procedure call and its results.
|
DBUNLOCK modes other than mode 1 are specific to Eloquence.
It allows to selectively release a lock if called with the
same mode and qualifier as DBLOCK.
Notes:
-
DBUNLOCK is allowed during dynamic transactions.
However the lock will not be released until the transaction ends.
-
With Eloquence status element 2 is always zero. TurboIMAGE used
to returrn the number of released locks.
-
Modes other than mode 1 are specific to Eloquence.
Adds new entries to a manual master or detail data set. The database
must be opened in write mode.
DBPUT(base,dset,mode,status,list,buffer)
- base
-
is the name of an array used as the base parameter when opening the
database. The first element of the array must contain the base ID
returned by DBOPEN. (Refer to DBOPEN for more information about the
base ID.)
- dset
-
is the name of an array containing the left-justified name of the
data set to which the entry is to be added, or is an integer
referencing the data set by number. The data set name can be up
to 16 characters long. If shorter, it must be terminated by a
semicolon, a space or the NUL character.
- mode
-
must be an integer equal to 1.
- status
-
is the name of an array of 10 halfwords in which the database returns
status information about the procedure. If the procedure executes
successfully, the status array contents are:
| Element |
Contents |
| 1 |
If the procedure succeeds, the return status is 0.
Otherwise it provides a status code to describe the failure.
|
| 2 |
Length of logical entry in buffer array (in halfwords).
|
| 3-4 |
Word record number of new entry (32 bit).
|
| 5-6 |
Word count of number of entries in chain (32 bit).
If detail data set, chain is current chain of new entry.
|
| 7-8 |
If detail, word record number of predecessor on current
detail chain (32 bit).
|
| 9-10 |
If detail, word record number of successor on current
detail chain (32 bit).
|
- list
-
is the name of an array containing an ordered set of data item
identifiers; names or numbers. The new entry contains values
supplied in the buffer array for data items in the list array.
Search or sort items defined for the entry must be included in
the list array. Fields of unreferenced items are filled with
binary zeros.
The list array can contain a left-justified set of data item names,
separated by commas and terminated by a semicolon or blank; no
embedded blanks are allowed, and no name can appear more than once.
For example:
ACCOUNT,LAST-NAME,CITY,STATE;
When referencing by number, the first halfword of the list array is
an integer n that is followed by n single positive integers
identifying unique data item numbers. Example: 4 1 10 3 16 lists for
the four data item numbers 1, 10, 3, and 16.
The list specifies data items for which values are supplied in the
buffer array, and is saved internally by TurboIMAGE as the current list
for the data set. The current list is unchanged until a different list
is specified in a subsequent call to DBGET, DBPUT, or DBUPDATE for
the same access path and data set.
Some special list constructs are allowed. List processing involves
some overhead which can be shortened in subsequent calls by using
the asterisk construct to specify that the current list is to be
used. Be sure a current list exists before using the asterisk construct,
or a null list is assumed.
- buffer
-
is the name of an array containing data item values to be added.
The values must be in the same order as their data item identifiers
in the list array.
Special List Parameter Constructs:
| Construct |
list Array Contents |
Purpose |
| Empty |
0; or 0_ or _ (0 must be ASCII) |
Request no data transfer.
|
| Empty Numeric |
0 (n, length of data item identifier list, is zero) |
Request no data transfer.
|
| Asterisk |
*; or *_ |
Request procedure to use previous list and
apply it to same data set. If "*" is used to
define the list in the first call to DBGET
and DBPUT it is treated as a zero.
|
| At-sign |
@; or @_ |
Request procedure to use all data items of
the data set in the order of their occurrence
in the entry.
|
Note: _ indicates a space character.
Notes:
-
With the Eloquence database, locking is optional.
A write attempt which is covered by a concurrent DBLOCK
returns status -12.
-
Synonym chain information (for master data set) is always zero.
Deletes the current entry from a manual master or detail data set.
The database must be opened in write mode.
DBDELETE(base,dset,mode,status)
- base
-
is the name of an array used as the base parameter when opening the
database. The first element of the array must contain the base ID
returned by DBOPEN. (Refer to DBOPEN for more information about the
base ID.)
- dset
-
is the name of an array containing the left-justified name of the
data set to which the entry is to be added, or is an integer
referencing the data set by number. The data set name can be up
to 16 characters long. If shorter, it must be terminated by a
semicolon, a space or the NUL character.
- mode
-
must be an integer equal to 1.
- status
-
is the name of an array of 10 halfwords in which the database returns
status information about the procedure. If the procedure executes
successfully, the status array contents are:
| Element |
Contents |
| 1 |
If the procedure succeeds, the return status is 0.
Otherwise it provides a status code to describe the failure.
|
| 2 |
Zero.
|
| 3-4 |
Word record number of new entry (32 bit).
|
| 5-6 |
Word count of number of entries in chain (32 bit).
If detail data set, chain is current chain of entry.
|
| 7-8 |
If detail, word record number of predecessor on current
detail chain (32 bit).
|
| 9-10 |
If detail, word record number of successor on current
detail chain (32 bit).
|
Notes:
-
With the Eloquence database, locking is optional.
A write attempt which is covered by a concurrent DBLOCK
returns status -12.
-
Synonym chain information (for master data set) is always zero.
-
Status elements 3-10 were left unchanged by TurboIMAGE for
detail data sets but are modified by Eloquence.
Modifies values of data items in the entry residing at the
current record address of a specified data set.
The database must be opened in write mode.
The update is always carried out correctly against the latest
version of the data, regardless of modifications made by other users.
You can use DBUPDATE to modify the values of detail data set search
and sort items if permitted by the critical item update (CIUPDATE)
option settings or using mode 2.
This includes master data set key item values if no detail is
connected.
DBUPDATE(base,dset,mode,status,list,buffer)
- base
-
is the name of an array used as the base parameter when opening the
database. The first element of the array must contain the base ID
returned by DBOPEN. (Refer to DBOPEN for more information about the
base ID.)
- dset
-
is the name of an array containing the left-justified name of the
data set to which the entry is to be added, or is an integer
referencing the data set by number. The data set name can be up
to 16 characters long. If shorter, it must be terminated by a
semicolon, a space or the NUL character.
- mode
-
must be an integer equal to 1 or 2.
- status
-
is the name of an array of 10 halfwords in which the database returns
status information about the procedure. If the procedure executes
successfully, the status array contents are:
| Element |
Contents |
| 1 |
If the procedure succeeds, the return status is 0.
Otherwise it provides a status code to describe the failure.
|
| 2 |
Length of logical entry in buffer array (in halfwords).
|
| 3-4 |
Word record number of new entry (32 bit).
|
| 5-6 |
Word count of number of entries in chain (32 bit).
If detail data set, chain is current chain of new entry.
|
| 7-8 |
If detail, word record number of predecessor on current
detail chain (32 bit).
|
| 9-10 |
If detail, word record number of successor on current
detail chain (32 bit).
|
- list
-
is the name of an array containing an ordered set of data item identifiers,
either names or numbers. Values supplied in the buffer array replace the
values of data items occupying the same relative position in the list array.
The user class established when the database is opened must allow at
least read access to all the items included in the list array.
The list array can contain a left-justified set of data item names, separated
by commas and terminated by a semicolon or a blank. No embedded
blanks are allowed and no name can appear more than once.
When referencing by number, the first element of the list array is an integer
n followed by n unique data item numbers (one-halfword positive integers).
The list not only specifies the data items to be updated immediately but
is saved internally as the current list for this data set.
The current list is unchanged until a different list is specified in a
subsequent call to DBGET, DBPUT, or DBUPDATE for the same access path
and data set.
Some special list constructs are allowed.
These are described in Special List Parameter Constructs with the
DBPUT procedure.
List processing involves
some overhead which can be shortened in subsequent calls by using
the asterisk construct to specify that the current list is to be
used.
- buffer
-
is the name of an array containing data item values to be added.
The values must be in the same order as their data item identifiers
in the list array.
The number of halfwords for each value must correspond to the number of
halfwords required by its type multiplied by the sub-item count.
Search and sort item values can be included in this update list if
their values will not change unless mode 2 is used or the
CIUPDATE flag is set.
Notes:
-
With the Eloquence database, locking is optional.
A write attempt which is covered by a concurrent DBLOCK
returns status -12.
-
Synonym chain information (for master data set) is always zero.
-
Additional mode 2 is available which has the same effect as
if CIUPDATE is set.
DBGET(base,dset,mode,status,list,buffer,argument)
- base
-
is the name of an array used as the base parameter when opening the
database. The first element of the array must contain the base ID
returned by DBOPEN. (Refer to DBOPEN for more information about the
base ID.)
- dset
-
is the name of an array containing the left-justified name of the
data set to which the entry is to be added, or is an integer
referencing the data set by number. The data set name can be up
to 16 characters long. If shorter, it must be terminated by a
semicolon, a space or the NUL character.
- mode
-
contains an integer between 1 and 8, inclusive, which indicates the
reading method. The methods are:
| Mode |
Method |
| 1 |
Re-read. Read the entry at the internally maintained
current record number (argument parameter is ignored).
|
| 2 |
Serial Read. Read the first entry whose record number is
greater than the internally maintained current number
(argument parameter is ignored).
|
| 3 |
Backward Serial Read. Read the first entry whose record
number is less than the internally maintained current
number (argument parameter is ignored).
|
| 4 |
Directed Read. Read the entry, if it exists, at the record
number specified in the argument parameter (argument is
treated as a 32-bit record number).
|
| 5 |
Chained Read or Next Qualified Entry Read. Read the
next entry in the current chain, or read the next qualified
entry for a B-Tree DBFIND. This is the entry referenced by
the internally maintained forward pointer (argument
parameter is ignored). Super-chains are traversed for detail
data sets.
|
| 6 |
Backward Chained Read. Read the previous entry in the
current chain, or the previous qualified entry for a B-Tree DBFIND.
This is the entry referenced by the internally maintained backward
pointer (argument parameter is ignored). Super-chains are
traversed for detail data sets.
|
| 7 |
Calculated Read. (Master data sets only.) Read the entry
with a key item value that matches the value specified in
argument. The entry is in the master data set specified by
dset.
|
| 8 |
Primary Calculated Read. (Master data sets only.) Read
the entry occupying the primary address of a synonym
chain using the key item value specified in argument to
locate the entry. The key item value returned is always that
of the primary entry and might not match the value
specified in argument. (Refer to chapter 10 for synonym
chain description.)
With Eloquence this is identical to mode 7.
|
- status
-
is the name of an array of 10 halfwords in which the database returns
status information about the procedure. If the procedure executes
successfully, the status array contents are:
| Element |
Contents |
| 1 |
If the procedure succeeds, the return status is 0.
Otherwise it provides a status code to describe the failure.
|
| 2 |
Length of logical entry in buffer array (in halfwords).
|
| 3-4 |
Word record number of new entry (32 bit).
|
| 5-6 |
Word count of number of entries in chain (32 bit).
If detail data set, chain is current chain of new entry.
|
| 7-8 |
If detail, word record number of predecessor on current
detail chain (32 bit).
|
| 9-10 |
If detail, word record number of successor on current
detail chain (32 bit).
|
- list
-
is the name of an array containing an ordered set of data item identifiers,
either names or numbers. Values supplied in the buffer array replace the
values of data items occupying the same relative position in the list array.
The user class established when the database is opened must allow at
least read access to all the items included in the list array.
The list array can contain a left-justified set of data item names, separated
by commas and terminated by a semicolon or a blank. No embedded
blanks are allowed and no name can appear more than once.
When referencing by number, the first element of the list array is an integer
n followed by n unique data item numbers (one-halfword positive integers).
The list not only specifies the data items to be updated immediately but
is saved internally as the current list for this data set.
The current list is unchanged until a different list is specified in a
subsequent call to DBGET, DBPUT, or DBUPDATE for the same access path
and data set.
Some special list constructs are allowed.
These are described in Special List Parameter Constructs with the
DBPUT procedure.
List processing involves
some overhead which can be shortened in subsequent calls by using
the asterisk construct to specify that the current list is to be
used.
- buffer
-
is the name of an array containing data item values to be added.
The values must be in the same order as their data item identifiers
in the list array.
The number of halfwords for each value must correspond to the number of
halfwords required by its type multiplied by the sub-item count.
Notes:
-
Synonym chain information (for master data set) is always zero.
-
Mode 8 is the same as mode 7
-
Additional modes 15 and 16 are available
Locates related master set key item
entry that matches the specified search item value and sets up
pointers to the first and last entries of a detail data set chain in
preparation for chained access to the data entries which are members
of the chain. The path is determined and the chain pointers are
located on the basis of a specified search item and its value.
With the TPI modes, index access is supported.
DBFIND(base,dset,mode,status,item,argument)
- base
-
is the name of an array used as the base parameter when opening the
database. The first element of the array must contain the base ID
returned by DBOPEN. (Refer to DBOPEN for more information about the
base ID.)
- dset
-
is the name of an array containing the left-justified name of the
data set to which the entry is to be added, or is an integer
referencing the data set by number. The data set name can be up
to 16 characters long. If shorter, it must be terminated by a
semicolon, a space or the NUL character.
- mode
-
must be an integer equal to 1 or 10.
Please refer to the TPI Support
documentation for additional DBFIND modes.
- status
-
is the name of an array of 10 halfwords in which the database returns
status information about the procedure. If the procedure executes
successfully, the status array contents are:
| Element |
Contents |
| 1 |
If the procedure succeeds, the return status is 0.
Otherwise it provides a status code to describe the failure.
|
| 2 |
Zero.
|
| 3-4 |
Word record number set to zero (32 bit).
|
| 5-6 |
Word count of number of entries in chain or qualifier (32 bit).
For modes 21 and 24 2^31-1 is returned.
|
| 7-8 |
If detail, word record number of predecessor on current
detail chain (32 bit).
For modes 21 and 24 2^31-1 is returned.
|
| 9-10 |
If detail, word record number of successor on current
detail chain (32 bit).
For modes 21 and 24 2^31-1 is returned.
|
- item
-
is the name of an array containing a left-justified name of the detail data
set search item or is an integer referencing the search item number that
defines the path containing the desired chain. The specified search item
defines the path to which the chain belongs. For a B-Tree DBFIND on a
master, it is the key item name or a number. The name can be up to 16
characters long. If shorter, it must be terminated by a semicolon,
a space or the NUL character.
- argument
-
contains a value for the key item to be used in calculated access to locate
the desired chain head in the master data set. This is referred to as a
simple argument.
Notes:
-
As of Eloqauence B.07.00, DBFIND modes 1,4,21 and 24 are implemented but can
currently not be used with search items. They may be used with an
Eloquence index item.
-
Eloquence supports the TPI modes for database access.
Please refer to the TPI Support
documentation for additional DBFIND modes.
Moves a message, as an ASCII character string, to a buffer
specified by the calling program. The message interprets the
contents of the status array as set by a call to a
database procedure.
DBERROR(status,buffer,length)
- status
-
is the name of the array used as the status parameter in the
database procedure call about which information is requested.
- buffer
-
is the name of an array in the calling program's data area, at least 36
halfwords (72 bytes) long, in which the message is returned.
- length
-
is a short, 16-bit integer variable which is set by DBERROR to the positive
byte length of the message placed in the buffer array. The length will never
exceed 72 characters.
Notes:
-
Messages differ from TurboIMAGE.
Prints a multiline message to stderr which describes a database
procedure call and explains the call's results as recorded in the
calling program's status array.
DBEXPLAIN(status)
- status
-
is the name of the array used as the status parameter in the
database procedure call about which information is requested.
Notes:
-
Writes to stderr
-
Messages differ from TurboIMAGE.
Designates the beginning of a transaction or sub-transaction.
DBXBEGIN is used in conjunction with DBXEND to begin and end a
dynamic transaction.
DBXBEGIN(base|baseidlist,text,mode,status,textlen)
- base
-
is the name of an array used as the base parameter when opening the
database. The first element of the array must contain the base ID
returned by DBOPEN. (Refer to DBOPEN for more information about the
base ID.)
Currently ignored. Eloquence transactions are not database
specific but include all databases modified in a transaction.
- baseidlist
-
is the name of the integer array containing the base IDs of the databases
which are involved in a DMDBX. Use baseidlist when calling DBXBEGIN mode
3 (DMDBX). The layout of this array is shown here (each element is a
halfword or two bytes):
| Element |
Contents |
| 1-2 |
Application program must set these two halfwords to binary
0s before calling DBXBEGIN. After returning to the calling
program, these two halfwords contain the transaction ID.
Use this same baseidlist with the corresponding DBXEND or
DBXUNDO intrinsics.
|
| 3 |
Number of base IDs involved in the DMDBX. This must be a
number between 1 and 15 inclusive.
|
| 4-n |
Base IDs of the databases involved in the DMDBX. Each
base ID occupies one half-word or 2 bytes and it is the first
halfword of the base parameter used to call
database procedures.
|
Currently ignored. Eloquence transactions are not database
specific but include all databases modified in a transaction.
- text
-
is the name of an array up to 256 halfwords long that contains user ASCII
or binary data to be written to the log file as part of the transaction log.
- mode
-
is an integer indicating the transaction type:
- Mode 1: Indicates a dynamic transaction which spans only one
database.
- Mode 3: Indicates a dynamic transaction spanning multiple
databases.
The mode parameter has no effect with Eloquence.
- status
-
is the name of an array of 10 halfwords in which the database returns
status information about the procedure. If the procedure executes
successfully, the status array contents are:
| Element |
Contents |
| 1 |
If the procedure succeeds, the return status is 0.
Otherwise it provides a status code to describe the failure.
|
| 2 |
Transaction nesting level.
|
| 3-4 |
Unchanged.
|
| 5-10 |
Information about the current procedure call and its results.
|
- textlen
-
is an integer equal to the number of halfwords to be logged from the text
parameter, or is a negative integer equal to the number of bytes. Length
can be zero.
Notes:
-
Transactions are not database specific but affect all databases.
Consequently, no check is made for a valid database id or
database id list and no check is made for dbopen mode restrictions.
-
In mode 3 the baseidlist argument is not updated.
-
Nested transactions are allowed
-
Element 2 of the status error was unchanged with TurboIMAGE.
Eloquence returns the transaction nesting level.
-
TurboIMAGE/XL in addition supports the DBXBEGIN mode 4 which is
used by SQL. This is not supported with Eloquence.
Designates the end of a transaction or subtransaction ("commit").
DBXEND is used in conjunction with DBXBEGIN to begin and end a
dynamic transaction.
DBXEND(base|baseidlist,text,mode,status,textlen)
- base
-
is the name of an array used as the base parameter when opening the
database. The first element of the array must contain the base ID
returned by DBOPEN. (Refer to DBOPEN for more information about the
base ID.)
Currently ignored. Eloquence transactions are not database
specific but include all databases modified in a transaction.
- baseidlist
-
is the name of the integer array containing the base IDs of the databases
which are involved in the DMDBX. Use the same baseidlist used with
DBXBEGIN when calling DBXEND mode 3 to end the DMDBX. The layout of
this array is same as in DBXBEGIN, except that the transaction ID is already
set in the first two halfwords by DBXBEGIN.
Currently ignored. Eloquence transactions are not database
specific but include all databases modified in a transaction.
- text
-
is the name of an array up to 256 halfwords long that contains user ASCII
or binary data to be written to the log file as part of the transaction log.
- mode
-
must be a halfword equal to 1, 2 or 3 or 5.
- Mode 1: End of dynamic transaction spanning one database.
- Mode 2: End of dynamic transaction spanning one database, started
with DBXBEGIN mode 1, and write contents of the
transaction management (XM) logging buffer in memory to
disk. If logging is enabled, the contents of the logging buffer
in memory will also be written to disk.
- Mode 3: Indicates the end of a DMDBX started with DBXBEGIN mode
3. If user logging is enabled for the databases, mode 3
generates multiple entries in the log file, one for each
database in the DMDBX, in order to mark the end of a
dynamic transaction.
- Mode 5: Commit top level transaction. If nested transactions
are used this will commit all pending operations.
Modes 1,2 and 3 are handled identical with Eloquence.
- status
-
is the name of an array of 10 halfwords in which the database returns
status information about the procedure. If the procedure executes
successfully, the status array contents are:
| Element |
Contents |
| 1 |
If the procedure succeeds, the return status is 0.
Otherwise it provides a status code to describe the failure.
|
| 2 |
Transaction nesting level.
|
| 3-4 |
Unchanged.
|
| 5-10 |
Information about the current procedure call and its results.
|
- textlen
-
is an integer equal to the number of halfwords to be logged from the text
parameter, or is a negative integer equal to the number of bytes. Length
can be zero.
Notes:
-
Transactions are not database specific but affect all databases.
Consequently, no check is made for a valid database id or
database id list and no distinction is made between a single
database and multiple databases (DBMX).
-
Modes 1,2 and 3 are mapped to Eloquence mode 1
-
Mode 5 is mapped to Eloquence mode 2
-
Text is ignored
-
Nested transactions are allowed. If used, DBXEND most be called
the same number of times as DBXBEGIN or mode 5 with DBXEND
must be used.
-
Element 2 of the status error was unchanged with TurboIMAGE.
Eloquence returns the transaction nesting level.
-
TurboIMAGE/XL in addition supports the DBXEND mode 4 which is
used by SQL. This is not supported with Eloquence.
Rolls-back the active sequence of database procedure calls which
are considered a dynamic transaction.
DBXUNDO(base|baseidlist,text,mode,status,textlen)
- base
-
is the name of an array used as the base parameter when opening the
database. The first element of the array must contain the base ID
returned by DBOPEN. (Refer to DBOPEN for more information about the
base ID.)
Currently ignored. Eloquence transactions are not database
specific but include all databases modified in a transaction.
- baseidlist
-
Name of the integer array containing the base IDs of the databases which
are involved in the DMDBX. Use the same baseidlist parameter of DBXBEGIN
mode 3, when calling DBXUNDO to roll-back a DMDBX.
Currently ignored. Eloquence transactions are not database
specific but include all databases modified in a transaction.
- text
-
is the name of an array up to 256 halfwords long that contains user ASCII
or binary data to be written to the log file as part of the transaction log.
- mode
-
must be a halfword equal to 1,3 or 5.
- Mode 1: Dynamically roll-back DBPUT, DBDELETE, and DBUPDATE
intrinsics which completed successfully since the matching
DBXBEGIN mode 1 call.
- Mode 3: Dynamically roll-back DBPUT, DBDELETE, and DBUPDATE
intrinsics which completed successfully inside the DMDBX to
their respective databases since the matching DBXBEGIN
mode 3 call. If user logging is enabled for the databases,
mode 3 generates multiple entries in the log file, one for
each database, in order to mark the roll-back of the
dynamic transaction.
- Mode 5: Roll-back top level transaction. If nested transactions
are used this will roll-back any pending transaction.
Modes 1 and 2 are handled identical with Eloquence.
- status
-
is the name of an array of 10 halfwords in which the database returns
status information about the procedure. If the procedure executes
successfully, the status array contents are:
| Element |
Contents |
| 1 |
If the procedure succeeds, the return status is 0.
Otherwise it provides a status code to describe the failure.
|
| 2 |
Transaction nesting level.
|
| 3-4 |
Unchanged.
|
| 5-10 |
Information about the current procedure call and its results.
|
- textlen
-
is an integer equal to the number of halfwords to be logged from the text
parameter, or is a negative integer equal to the number of bytes. Length
can be zero.
Notes:
-
Transactions are not database specific but affect all databases.
Consequently, no check is made for a valid database id or
database id list and no distinction is made between a single
database and multiple databases (DBMX).
-
Modes 1 and 3 are mapped to Eloquence mode 1
-
Mode 5 is mapped to Eloquence mode 3
-
Text is ignored
-
Nested transactions are allowed. If used, DBXUNDO most be called
the same number of times as DBXBEGIN or mode 5 with DBXUNDO
must be used.
-
Element 2 of the status error was unchanged with TurboIMAGE.
Eloquence returns the transaction nesting level.
-
TurboIMAGE/XL in addition supports the DBXUNDO mode 4 which is
used by SQL. This is not supported with Eloquence.
Designates the beginning of a sequence of database procedure calls
regarded as a static or multiple database transaction (based on the
mode) for the purposes of logging and recovery. The text parameter
can be used to log user information to the log file.
DBBEGIN is used in conjunction with DBEND to begin and end a static
or multiple database transaction.
Static transactions are currently not supported with Eloquence
and DBBEGIN has no effect. Eloquence relies on dynamic
transactions internally.
A future version of Eloquence may add support for static
transactions for use with forward recovery or auditing purposes.
DBBEGIN(base|baseidlist,text,mode,status,textlen)
- base
-
is the name of the array used as the base parameter when opening the
database. The first element of the array must contain the base ID returned
by DBOPEN. (Refer to DBOPEN for more information about the base ID.) Use
base when calling DBBEGIN mode 1 (static transaction).
The base argument is ignored with Eloquence.
- baseidlist
-
is the name of the integer array containing the base IDs of the databases
which are involved in a multiple database transaction. Use baseidlist when
calling DBBEGIN mode 3 or 4 (multiple database transaction). The layout of
this array is shown here (each element is a halfword or two bytes):
| Element |
Contents |
| 1-2 |
The application program must set these two halfwords to
binary 0s before calling DBBEGIN. After returning to the
calling program, these two halfwords contain the
transaction ID. This ID can be used in order to end the
transaction by calling DBEND.
|
| 3 |
The number of base IDs involved in the multiple database
transaction. This must be a number between 1 and 15,
inclusive.
|
| 4-n |
Base IDs of the databases involved in the transaction. Base
ID is the first halfword of the base parameter used to call
database procedures.
|
The baselist argument is ignored with Eloquence.
- text
-
is the name of an array up to 256 halfwords long that contains user ASCII
or binary data to be written to the log file as part of the transaction log.
- mode
-
is an integer indicating the transaction type:
- Mode 1: Indicates a static transaction.
- Mode 3: Indicates a multiple database transaction with one log record
per database. If user logging is enabled for the databases,
mode 3 generates multiple entries in the log file in order to
mark multiple database transactions.
- Mode 4: Indicates a multiple database transaction. If user logging is
enabled for the databases, mode 4 generates one entry in
the log file in order to mark multiple database transactions.
The mode parameter has no effect with Eloquence.
- status
-
is the name of an array of 10 halfwords in which the database returns
status information about the procedure. If the procedure executes
successfully, the status array contents are:
| Element |
Contents |
| 1 |
If the procedure succeeds, the return status is 0.
Otherwise it provides a status code to describe the failure.
|
| 2-4 |
Unchanged.
|
| 5-10 |
Information about the current procedure call and its results.
|
- textlen
-
is an integer equal to the number of halfwords to be logged from the text
parameter, or is a negative integer equal to the number of bytes. Length
can be zero.
Notes:
- Static transactions are not supported and DBBEGIN has no
effect besides verfying the arguments.
Designates the end of a sequence of database procedure calls regarded
as a static or multiple database transaction (based on the mode) for
the purposes of logging and recovery. The text parameter can be used
to log user information to the log file. DBEND isused in conjunction
with DBBEGIN to begin and end a static or multiple database transaction.
Static transactions are currently not supported with Eloquence
and DBEND has no effect. Eloquence relies on dynamic
transactions internally.
A future version of Eloquence may add support for static
transactions for use with forward recovery or auditing purposes.
DBEND(base|baseidlist|transid ,text,mode,status,textlen)
- base
-
is the name of the array used as the base parameter when opening the
database. The first element of the array must contain the base ID returned
by DBOPEN. (Refer to DBOPEN for more information about the base ID.) Use
with DBEND mode 1 or 2.
The base argument is ignored with Eloquence.
- baseidlist
-
is the name of an integer array containing the list of base IDs which are
involved in a multiple database transaction. Use with DBEND mode 3 or 4,
and set the first two halfwords to binary zeroes. The layout of this array
is shown here (each element is a halfword, or two bytes):
| Element |
Contents |
| 1-2 |
Must be set to binary zeroes.
|
| 3 |
The number of base IDs involved in the multiple database
transaction. This must be a number between 1 and 15,
inclusive.
|
| 4-n |
Base IDs of the databases involved in the transaction. Base
ID is the first halfword of the base parameter used to call
database procedures.
|
The baselist argument is ignored with Eloquence.
- transid
-
is the name of the integer array containing the two-halfword
transaction ID. The transaction ID was returned by DBBEGIN mode 3 or 4.
Use with DBEND mode 3 or 4, and do not set the first two halfwords to
binary zeroes.
The transid argument is ignored with Eloquence.
- text
-
is the name of an array up to 256 halfwords long that contains user ASCII
or binary data to be written to the log file as part of the transaction log.
- mode
-
must be an integer equal to 1, 2, 3, or 4.
- Mode 1: End of static transaction.
- Mode 2: Write contents of the logging buffer in memory to disk, and
end the static transaction.
- Mode 3: End of multiple database transaction. If user logging is
enabled for the databases, mode 3 generates multiple
entries in the log file in order to mark multiple database
transactions.
- Mode 4: Write contents of the logging buffer in memory to disk, and
end the multiple database transaction. If user logging is
enabled for the databases, mode 4 generates one entry in
the log file in order to mark multiple database transactions.
The mode parameter has no effect with Eloquence.
- status
-
is the name of an array of 10 halfwords in which the database returns
status information about the procedure. If the procedure executes
successfully, the status array contents are:
| Element |
Contents |
| 1 |
If the procedure succeeds, the return status is 0.
Otherwise it provides a status code to describe the failure.
|
| 2-4 |
Unchanged.
|
| 5-10 |
Information about the current procedure call and its results.
|
- textlen
-
is an integer equal to the number of halfwords to be logged from the text
parameter, or is a negative integer equal to the number of bytes. Length
can be zero.
Notes:
- Static transactions are not supported and DBEND has no
effect besides verfying the arguments.
Used to log user data (ASCII or binary) to the log file.
Static transactions are currently not supported with Eloquence
and DBMEMO has no effect. Eloquence relies on dynamic
transactions internally.
A future version of Eloquence may add support for static
transactions for use with forward recovery or auditing purposes.
DBMEMO(base,text,mode,status,textlen)
- base
-
is the name of the array used as the base parameter when opening the
database. The first element of the array must contain the base ID
returned by DBOPEN. (Refer to DBOPEN for more information about the
base ID.)
The base argument is ignored with Eloquence.
- text
-
is an array of up to 512 bytes that contains user data (ASCII or binary) to
be written to the log file as part of the DBMEMO log record.
- mode
-
must be an integer equal to 1.
- status
-
is the name of an array of 10 halfwords in which the database returns
status information about the procedure. If the procedure executes
successfully, the status array contents are:
| Element |
Contents |
| 1 |
If the procedure succeeds, the return status is 0.
Otherwise it provides a status code to describe the failure.
|
| 2-4 |
Unchanged.
|
| 5-10 |
Information about the current procedure call and its results.
|
- textlen
-
is an integer equal to the number of halfwords to be logged from the text
parameter, or is a negative integer equal to the number of bytes. Length
can be zero.
Notes:
- Static transactions are not supported and DBMEMO has no
effect besides verfying the arguments.
A user name and password is required to connect to a database.
Unless specified by either DBLOGON or DBOPEN a default user ("public")
is used.
DBLOGON saves the identity for usage with a subsequent DBOPEN.
DBLOGON(user,password,status)
- user
-
is an array of up to 128 bytes that contains the user name.
It must be terminated by either a semicolon,
a space a NUL character.
- password
-
is an array of up to 128 bytes that contains the password associated
with the user. It must be terminated by either a semicolon,
a space a NUL character.
- status
-
is the name of an array of 10 halfwords in which the database returns
status information about the procedure. If the procedure executes
successfully, the status array contents are:
| Element |
Contents |
| 1 |
If the procedure succeeds, the return status is 0.
Otherwise it provides a status code to describe the failure.
|
| 2-4 |
Unchanged.
|
| 5-10 |
Information about the current procedure call and its results.
|
Discussion:
DBLOGON does not verify the arguments but merely saves the
information for usage by a subsequent DBOPEN.
DBLOGON is called impliceitely by specifying a user name
and password with the DBOPEN password parameter.
To reset a previously established identity (to force using the
default user name), call DBLOGON with an empty string for the
user name.
Notes:
|
|
