4 Database Manipulation
The DBOPEN Statement
DBOPEN syntax:
DBOPEN (base name, password, mode, status)
The parameters are:
- base name
- A string variable containing the database name preceded by two blank spaces.
- password
- A string expression containing a left-justified ASCII string.
- mode
- A numeric expression equal to 1, 3, 8 or 9.
- status
- An integer array variable that returns status information after DBOPEN is executed. The array must contain at least ten elements in its right-most dimension.
Eloquence A.06.00 uses the client/server model to connect to a database server. Since the data base server can run on a different machine and there could be more than one server on a machine, the DBOPEN syntax accomplish this.
- The data base name uses an extended syntax.
- The Eloquence A.06.00 data base provides a new authorization scheme.
The data base password is ignored with the Eloquence A.06.00 data base. It is
still used when connecting to a A.05.xx data base (through the eloqdb5 server).
The DBOPEN statement uses a database specification, which consists of three terms:
- The machine, the data base server is running on, this defaults to the local system.
Otherwise, the server hostname or "IP address" is required.
- The data base server is listening on a certain port for connections. If this port
has not the one mapped to the default service name (eloqdb), the service name or
port number must be specified. This port is mapped to a service name in the con
figuration file "/etc/services" (on UNIX).
- The database server handles any number of data bases in one data base environment. The data base name is required.
- The A.05.xx database server (eloqdb5) needs an absolute path to locate the data base ROOT file in the file system. An absolute path must be specified.
- All elements besides the data base name can be defined in a VOLUME definition, so there should be no impact for existing programs.
The syntax is as below:
[[server][:service]/][Database]
- server
- The name or IP number of the system running the database server. If it is omitted, the local system is assumed.
- service
- The service name or port number of the data base server. If it is omitted, the default service name "eloqdb" is assumed.
- database
- The database name.
* For Eloquence A.05.xx databases, this is the absolute path.
* For Eloquence A.06.xx, this is simply the data base name.
NOTE: The data base name is not case sensitive.
For example:
Db$=" sampledb"
DBOPEN(Db$,"",1,S(*))
This opens the database sampledb on the local system, using the default service.
Db$=" server/sampledb"
This would connect the default data base server running on the system named "server".
Db$=" server:eloqdb5/path/to/sampledb"
This would connect the data base server, running on the system named "server" using the port associated with the service name "eloqdb5". For Eloquence A.05.xx compatible data bases, it is required to specify an absolute path.
All the connection details could be hidden in a VOLUME definition. If a volume DBVOL is defined as below (for example in your .eloqrc file)
DBVOL="server:eloqdb5/path/to"
then the code below
Db$=" sampledb,DBVOL"
would connect to data base server:eloqdb5/path/to/sampledb.
DBOPEN Modes
A database may be opened in one of four modes. These modes determine the type of operations that can be performed by all users accessing the database.
Mode 1: Modify shared with database locking. Data entries may be read and written within the constraint of the user-class number granted by DBOPEN. Databases opened in mode 1 should be locked (DBLOCK) before data set entries may be added, deleted, or modified. If one user uses DBLOCK, all others also have to lock.
Mode 3: Modify exclusive. DBLOCK and DBUNLOCK statements are not required in this mode. Exclusive access is obtained for reading and/or writing. Although the database may change in content, it does so under your exclusive control. Control is relinquished after executing a DBCLOSE operation. Other requests for access to the database are refused until a DBCLOSE operation is executed.
Mode 8: Read shared. The database is opened for shared read access. Writing to the database is not permitted.
Mode 9: Open for read, allow concurrent update. The database is opened for read access. Other programs may open database in modes 1 and 8.
If successful, DBOPEN replaces the first two characters of the base name string variable, formerly blanks, with an ASCII database number between 00 and 09. This is the internal ID number of the database and should not be altered.
A corrupt database is accessible in mode 8. Status ERROR -94 is returned if the database is corrupt.
DBOPEN Status Array
A DBOPEN error assigns a non-zero conditional word (CW) to the first element of the status array. A list of all CW values and their meanings appear in page 197 . The following table describes the status array contents after a successful DBOPEN.
| Array Element | Value | Description |
| 1 | 0 | CW. |
| 2 | 0 through 31 | User-class number. |
| 3 | 0 | |
| 4 | 0 | |
| 5 | 0 | |
| 6 | Bits 0 through 11 | The DBOPEN identification number (401). |
| | Bits 12 through 15 | The mode value used to open the database. |
| 7 | Program line number | |
| 8 | 0 | |
| 9 | Mode number | DBOPEN-mode parameter value (same as bits 12 through 15 of element 6). |
| 10 | Any value | Reserved. |
Eloquence Database Manual - 19 DEC 2002