Opening a database
Eloquence A.06.00 uses client/server model to connect to a data base
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 has
been extended to accomplish this.
- The data base name uses an extended syntax.
- The new 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.
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 configuration file "/etc/services" (on UNIX).
- The A.06.00 data base server handles any number of data bases in one
data base environment. The data base name is required.
- The A.05.xx data base server 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. Please note, that 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 default data base server, running on the system
named "server" using the port associated with the service name "eloqdb5".
For Eloquence A.05.xx compatible databases, 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.
Authorization
The new Eloquence A.06.00 data base provides a new authorization scheme.
A list of users is maintained per data base server. For each data base,
there are authorization groups which have specific rights on this
particular data base.
A user can be a member of up to eight authorization groups.
The DBLOGON statement is used to provide authorization data which
are transmitted to the data base server, when a data base is openend.
The Eloquence A.06.00 data base no longer uses data base passwords.
For Eloquence A.05.xx data bases, the logon information is ignored.
Syntax:
DBLOGON(User$,Pswd$)
Description:
- User$
- A string variable containing the user name, for example "fred".
- Pswd$
- A string variable containing the password for the given user,
for example "secret".
When no DBLOGON statement is executed before opening a data base,
the data base server will try to access the data base as user "public" and
an empty password.
For example:
User$="fred"
Pswd$="secret"
DBLOGON(User$,Pswd$)
...
DBOPEN(Db$,"",1,S(*))
Transactions
The new Eloquence A.06.00 data base provides transactions. Transactions
are used to ensure data base integrity. After a DBBEGIN statement,
data base modifications are no longer stored permanently in the data base.
A subsequent DBCOMMIT statement is required to make any pending
operations permanent in the database.
The DBROLLBACK statement provides a rollback operation, that reverts
pending database operations.
After a successful (top level) commit, the transaction is guaranteed to be
present in the data base, even in case of a server crash.
So it can be guaranteed, that either all dependend operations are saved
entirely or no modifications are done.
Pending data base changes are neither visible to other users nor can they
be changed concurrently. All pending data base records are locked
automatically by the data base server and any attempt to modify them will
cause the concurrent task to become paused.
Transactions can be nested. The DBCOMMIT or DBROLLBACK
statements usually operate on the last (sub-) transaction.
Data base modifications are not stored permanently in the data base, until
a top level DBCOMMIT is executed.
The DBROLLBACK statement can be used to undo all pending
modifications until a specific checkpoint.
Please note, that the transaction handling statements do not operate on a
particular data base. Instead they operate on all data bases at once.
A pending commit or rollback is even performed after closing the data base.
In case a data base server connection is lost (for example, because the
server has been killed), all pending modifications on all data bases are
automatically reverted.
The DBBEGIN statement
The DBBEGIN statement begins a new (sub-) transaction.
When this is the first transaction, it is called top level transaction.
No modifications are permanently saved in the Eloquence A.06.00 data base
until the top level transaction is committed.
A subsequent DBBEGIN begins a new subtransaction, which can
be controlled separately with the DBCOMMIT and DBROLLBACK
statements.
Syntax:
DBBEGIN(Comment$,Mode,Status(*))
Description:
- Comment$
- An arbitrary comment, which is logged on the server.
- Mode
-
| Mode | Description |
|---|
| 1 | Begin transaction |
- Status(*)
- The status array. On success, the following elements are defined:
| Element | Description |
|---|
| 1 | Completion code |
| 2 | Transaction ID |
| 3 | Transaction nesting level |
Up to 20 transactions can be nested. Each DBBEGIN statement
returns a unique (process specific) transaction id, which can be used
with the DBROLLBACK statement to revert all modifications
until this state.
The DBCOMMIT statement
The DBCOMMIT statement commits a transaction. If this is a top level
transaction, modifications are made permanently in the data base.
If a subtransaction is committed, it becomes part of its parent
transaction.
Syntax:
DBCOMMIT(Mode,Status(*))
Description:
- Mode
-
| Mode | Description |
|---|
| 1 | Commit current (sub-)transaction |
| 2 | Commit top level transaction |
- Status(*)
- The status array. On success, the following elements are defined:
| Element | Description |
|---|
| 1 | Completion code |
The DBROLLBACK statement
The DBROLLBACK statement is used to undo a pending transaction.
If this is a top level transaction, all pending modifications are reverted.
If applied to a subtransaction all modifications including the enclosing
DBBEGIN statement are reverted.
Syntax:
DBROLLBACK(Id,Mode,Status(*))
Description:
- Id
- Transactions id, used with mode 2.
- Mode
-
| Mode | Description |
|---|
| 1 | Rollback current (sub-)transaction |
| 2 | Rollback given transaction |
| 3 | Rollback top level transaction |
- Status(*)
- The status array. On success, the following elements are defined:
| Element | Description |
|---|
| 1 | Completion code |
| 3 | Transaction nesting level |
In Mode 2, a transaction id must be specified which was obtained
from DBBEGIN. This can be used to revert up to a specific
checkpoint.
The DBEXPLAIN$ function
The DBEXPLAIN$ function translates the given status into a descriptive
message.
X$=DBEXPLAIN$(Status(*))
X$=DBEXPLAIN$(n)
New status codes
The following data base status codes are new to A.06.00:
Status codes -801 to -806 usually indicate internal problems. In this
case, the status element 10 provides more detailed information.
With the Eloquence A.06.00 database, the following status codes
can no longer happen:
