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.

As a replacement for MPE file equations, DBOPEN checks for an environment variable that matches the database name. If found, the value of this variable is used to replace the database name passed to DBOPEN.

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

For example:

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

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.