HP 3000 Manuals

Opening the Database [ TurboIMAGE/XL Database Management System Reference Manual ] MPE/iX 5.0 Documentation

TurboIMAGE/XL Database Management System Reference Manual

Opening the Database

Before you can gain access to the data, the process you are running must
open the database with a call to the DBOPEN procedure. A process is a
unique execution of a particular program by a particular user at a
particular time, as described in the MPE/iX Intrinsics Reference Manual.
In opening a database, DBOPEN establishes an access path between the
database and your program by doing the following:

* Verifying your right to use the database under the security
provisions provided by the MPE/iX file system and the
TurboIMAGE/XL user-class-password scheme.

* Determining that the access mode you have requested in opening the
database is compatible with the access modes of other users
currently using the database.

* Opening the root file and constructing the control blocks to be
used by all other TurboIMAGE/XL procedures when they are executed.
The root file remains open until the database is closed.

Note that DBOPEN does not open the individual data sets that compose a
database.

DBOPEN also determines if the operating system supports the native
language as defined in the root file. The following error message is
returned if the language attribute of the database is not supported by
the current system configuration:

Language is not supported

Refer to chapter 6 for more information on Host Language Access and
appendix A for more information on error messages.

Database Control Blocks

TurboIMAGE/XL executes using data stored in six different types of
control blocks stored in privileged mapped files: the Database System
Control Block (DBS), the Database Globals Control Block (DBG), the
Database Buffer Area Control Block (DBB), the Database User Local Control
Block (DBU), the Remote Database Control Block (DBR), and the Database
User Local Index Control Block (DBUX). These are described below:

* The Database System Control Block (DBS) is created by DBOPEN if it
does not already exist. The DBS is used as a system-wide table to
locate the current Database Globals Control Block (DBG) for any
opened database. Each system has only one DBS, created as a
permanent file called TURBODBS in the PUB group and the SYS
account on that system.

* The Database Globals Control Block (DBG) is created for a
particular database when the first user's process calls the DBOPEN
procedure to open the database. The DBG contains global
information required by TurboIMAGE/XL intrinsics during run-time,
including a pointer to the Database Buffer Area Control Block
(DBB) and pointers to the Database User Local Control Blocks
(DBUs). Each open database has exactly one DBG regardless of the
number of concurrent access paths to the database. All
TurboIMAGE/XL procedures on a particular database (except DBERROR
and DBEXPLAIN) reference the DBG. In addition, the DBG contains
the lock table which holds user-level locking information. The
DBG is purged when the last user's process closes the database
(DBCLOSE).

* The Database Buffer Area Control Block (DBB) is created for a
particular database when the first user's process calls the DBOPEN
procedure to open the database. The DBB contains a set of buffer
headers which point to data in memory from any of the data sets,
and contains a pointer to the DBG. Global information regarding
logging and recovery is also contained within the DBB. The DBB is
used to retrieve, log, and update data located in the data set
files on disk. The DBB is purged when the last user closes the
database (DBCLOSE).

* One Database User Local Control Block (DBU) is created each time a
user's process successfully calls DBOPEN. Each DBU contains
information about the user's individual access to the database and
contains pointers to the DBS, DBG, and DBB. The privileged mapped
file containing the DBU is associated with this DBOPEN. The DBU is
purged when the corresponding DBCLOSE closes the database. A
process can open a maximum of 127 databases (or one database 63
times), depending upon the system resources; therefore, a maximum
of 127 DBUs can be created. It is recommended that a process
close a database once it is no longer needed for that process.

* One Remote Database Control Block (DBR) is created on the local
system each time a user's process successfully opens a remote
database. The DBR contains database set and item information as
well as the work areas necessary to set up communications to the
remote computer.

* The Database User Local Index Control Block (DBUX) is created the
first time the user's process calls DBOPEN. One DBUX exists for
each user's process. Its purpose is to keep track of the
addresses of all the DBUs and/or DBRs for that process. Because a
maximum of 127 entries are allowed in the DBUX, each process is
allowed 127 DBOPENs (63 per database) depending on the
availability of system resources. The DBUX remains allocated
until the user's process is terminated.

All TurboIMAGE/XL intrinsics process on the DBU except accesses for
global and buffer area information found in the two global blocks (DBG
and DBB).

Passwords

When you open the database you must provide a valid password to establish
your user class number. If you do not provide one, you will be granted
user class number 0. If you are the database creator and supply a
semicolon as a password, you are assigned user class 64, which grants you
unlimited database access privileges. Passwords and user classes are
discussed in chapter 2.

Database Access Modes

There are eight different access modes for opening the database with the
DBOPEN procedure. Each mode determines the type of operation that you
can perform on the database, as well as the types of operations other
users can perform concurrently. To simplify the definition of the
various DBOPEN modes, the following terminology is used:

* Read access modes (5, 6, 7, and 8) allow the user to locate and
read data entries.

* Update access mode (2) allows read access and permits the user to
replace values in all data items except master data set key items
and detail data set search and sort items. The critical item
update (CIUPDATE) option, which can permit the values of detail
data set search and sort items to be updated and which is
discussed later in this chapter, is not available in this mode.

* Modify access modes (1, 3, and 4) allow updates and permit the
user to add and delete entries. For access modes 1, 3, and 4
only, users can update the values of detail data set search and
sort items if the critical item update (CIUPDATE) option settings
for the database and the current process permit them to do so.
CIUPDATE is discussed later in this chapter.

The TurboIMAGE/XL library procedures (also called intrinsics) that can be
used with each type of DBOPEN mode are as follows:[REV BEG]

Library Procedures DBOPEN Modes

---------------------------------------------------------------------------------------------
| | |
| DBOPEN Mode | Library Procedures Available |
| | |
---------------------------------------------------------------------------------------------
| | |
| Read | DBFIND and DBGET |
| | |
---------------------------------------------------------------------------------------------
| | |
| Update | DBFIND, DBGET, and DBUPDATE |
| | |
---------------------------------------------------------------------------------------------
| | |
| Modify | DBFIND, DBGET, DBUPDATE, DBPUT, and DBDELETE |
| | |
---------------------------------------------------------------------------------------------

Table 4-1 summarizes the type of database access granted in each
access mode, provided the MPE/iX security provisions and your password
permit it. Access modes 3 and 7 provide exclusive access to the
database; all other modes allow shared access.

Table 4-1. Database Access Mode Summary

[REV END]

Concurrent Database Access Modes.

A database can only be shared in certain well-defined environments. The
access mode specified when a process opens a database must be acceptable
for the environment established by others who are already using the
database. Here is a summary of the acceptable environments:

* Multiple access mode 1 and access mode 5 users

* Multiple access mode 6 and access mode 2 users

* Multiple access mode 6 users and one access mode 4 user

* Multiple access mode 6 and access mode 8 users

* One access mode 3 user

* One access mode 7 user

Subsets of these environments are also allowed. For example, all users
can be access mode 5, 6, or 8 users; or there could be one access mode 1
user; and so on.

If an access mode 3 or 7 user is currently accessing the database, it
cannot be opened until that user closes the database. This is true any
time an attempt is made to open a database in an access mode that is not
compatible with the access modes of others using the database.

Database Operations.

This section explains in detail what occurs when a database is opened in
a particular mode. Locking is available in all modes. In the discussion
that follows, brief suggestions are given as to when locking can be used.
Refer to the discussion of the locking facility later in this chapter for
more information.

* Access Mode 1. The database is opened for shared modify access.
Opening in mode 1 succeeds only if all other current users of the
database are using access modes 1 or 5.

All TurboIMAGE/XL procedures are available in this mode. The
critical item update (CIUPDATE) option, which can permit you to
update the values of detail data set search and sort items, is
available in this mode. A program must obtain temporary exclusive
control of the data entries before calling any procedure that
changes them, such as, DBUPDATE, DBPUT, or DBDELETE. In this way,
changes to the database are synchronized and carried out properly.
This exclusive control must subsequently be relinquished to permit
other access mode 1 or mode 5 users to access these entries.
Acquiring and relinquishing is referred to as locking and
unlocking, respectively. These functions are supplied by the
TurboIMAGE/XL library procedures, DBLOCK and DBUNLOCK. The locking
requirements can be met by locking the affected entries, the sets
containing the entries, or the whole database.

A mode 1 (and mode 5) user who has all or part of the database
locked is assured that no concurrent user is modifying that part
of the database.

It is possible to read entries in the database using calls to
DBFIND and DBGET without locking, but the calling program must
provide for the possibility that another process could be
simultaneously modifying the database. This can result in an
entry being deleted from a chain which the calling program is
reading.

* Access Mode 2. The database is opened for shared update access.
The DBOPEN call succeeds only if all current users of the database
are using access modes 2 and 6. All TurboIMAGE/XL procedures are
available to the access mode 2 user except DBPUT and DBDELETE
which are disallowed in this mode. The critical item update
(CIUPDATE) option, which can permit you to update the values of
detail data set search and sort items, is not available in this
mode. Therefore, the access mode 2 user is able to read all data
entries and update some data entries, but is not permitted to add
or delete data entries in any data set.

The programmer must be aware of the possibility that other access
mode 2 users are simultaneously updating data entries. In many
applications, it may be possible to arrange for each user's
process to update unique data entries or data items so that the
database will correctly reflect all changes, even data items in
the same entry updated by different processes. On the other hand,
if two or more processes update the same data items of the same
entry, the database will reflect only the latest values. Locking
can be used, if desired, to coordinate update sequences to an
entry or to coordinate with access mode 6 readers.

* Access Mode 3. The database is opened for exclusive modify
access. If any other users are accessing the database, it cannot
be opened in this mode. All TurboIMAGE/XL procedures are
available to the access mode 3 user. The critical item update
(CIUPDATE) option, which can permit you to update the values of
detail data set search and sort items, is available in this mode.
No other concurrent process is permitted to gain any type of
access to the database.
[REV BEG]

* Access Mode 4. The database is opened for semi-exclusive modify
access. Only one access mode 4 user can access the database, and
all other current users must be in access mode 6 (read only). The
access mode 4 user is permitted to call any TurboIMAGE/XL
procedure and has complete control over database content. The
critical item update (CIUPDATE) option, which can permit you to
update the values of detail data set search and sort items, is
available in this mode. Other read-only users are permitted
concurrent access to the database in mode 4, but not in mode 3.
Locking can be used to coordinate with access mode 6 readers.[REV
END]

* Access Mode 5. The database is opened for shared read access.
All other concurrent users must be in access mode 1 or 5. Access
mode 5 operates the same as access mode 1, except that the
DBUPDATE, DBPUT, and DBDELETE procedures, which alter the
database, are disabled for the access mode 5 user. Locking can be
used, if desired, to ensure that data is not being modified while
you are reading it.

Access mode 5 is appropriate for inquiry-type applications if they
can tolerate the possibility of database modifications taking
place simultaneously with access mode 1 users.

* Access Mode 6. The database is opened for shared read access.
Concurrent users must be in access mode 2, 4, 6, or 8. Access
mode 6 can also be used while the database is being stored with
the TurboIMAGE/XL utility program DBSTORE. Some of these modes are
incompatible with each other as shown in the preceding discussion
of concurrent access modes. All TurboIMAGE/XL procedures that
alter the database are disabled. Locking can be used to
synchronize with users who are concurrently updating.

Access mode 6 is appropriate for inquiry-type applications if they
can tolerate the possibility of database modifications taking
place simultaneously with access mode 2 and 4 users.

* Access Mode 7. The database is opened for exclusive read access.
No other users can access the database concurrently. Access mode
7 operates the same as access mode 3, except that the DBUPDATE,
DBPUT, and DBDELETE procedures, which alter the database, are
disabled for the access mode 7 user.

* Access Mode 8. The database is opened for shared read access.
Concurrent users must either be in access mode 6 or 8, or using
the TurboIMAGE/XL utility, DBSTORE. TurboIMAGE/XL procedures that
alter the database are not permitted. Because access mode 8
allows only concurrent readers, a user program with this access
mode can be assured that the database values it reads are
unchanging.

Selecting a Database Access Mode.

When deciding which access mode to use, the following are two important
considerations:

* Use the minimum capability required to accomplish the task. For
example, select a read-only access mode (5, 6, 7, or 8) if the
program does not alter the database in any way. Read access modes
allow concurrent database STORE operations and do not set the
MPE/iX "file modified" flag.

* Allow concurrent users to have as much capability as is required
for successful completion of the task. If the task is merely
browsing through the database, producing a quick report, or
accessing an unchanging portion of the database, choose an access
mode that allows concurrent users to make database modifications
to other parts of the database. Allowing concurrent read-only
access (modes 2, 4, and 8) can be appropriate in many situations.
For programs that must be assured of no concurrent structural
changes, but can tolerate simultaneous updates to entries, mode 2
is suitable. Locking can be used to control simultaneous updates
to a data entry. If it is necessary to make additions or
deletions to a database from concurrent multiple processes, modes
1 and 5 must be used. Fully exclusive operation (modes 3 and 7)
are available if needed.

The following access mode selection guidelines are organized according to
the task to be performed. For some tasks, one of several modes can be
selected depending on the concurrent activity allowed with each mode.

* Programs that perform operations, which include adding and
deleting entries or which need to update detail data set search
and sort items via the critical item update (CIUPDATE) option,
should open with mode 1, 3, or 4. Consider the following when
choosing among access modes 1, 3, and 4:

Access Mode 1 Can be used if other processes need to add and
delete entries simultaneously. In this case, the
affected parts of the database must be locked
while performing updates, additions, or
deletions.

Access Mode 3 Can be used if the program must have exclusive
access to the database.

Access Mode 4 Can be used if exclusive ability to change the
database is required but access mode 6 processes
need to be able to read the database while
changes are being made.

* Programs that locate, read, and replace data in existing entries
but do not need to add or delete any entries, and do not want any
other processes to do so, should open the database in access mode
2. Consider the following when choosing access mode 2:

Access Mode 2 Can be used if processes are allowed to update
the database concurrently. Locking should be
used to coordinate updates. The critical item
update (CIUPDATE) option, which can permit you to
update the values of detail data set search and
sort items, is not available in this mode.

* Programs that only locate and read or report on information in the
database should open with one of the read-only access modes. In
this case, the access mode selected depends upon either the type
of process running concurrently or the need for an unchanging
database while the program is running. Consider the following
when choosing among access modes 5, 6, 7, and 8:

Access Mode 5 Can be used if concurrent processes will operate
in access mode 1 or 5. Parts or all of the
database should be locked to prevent concurrent
changes during one or more read operations.
Because concurrent access mode 1 processes are
allowed, programs performing chained reads should
lock the chain (see the discussion of DBGET in
chapter 5).

Access Mode 6 Can be used if it is not important what other
processes are doing to the database. In this
case, access mode 2 processes can update entries;
one access mode 4 user can update, add, or delete
entries; or access mode 6 or 8 users can read
entries while the program is using the database.

Access Mode 7 Can be used if the program must have exclusive
read access to the database.

Access Mode 8 Can be used if other processes are allowed to
read but not modify the database. In this case,
access mode 6 and 8 users can read entries while
the program is using the database.

Locking within a Database Process.

Refer to the locking discussion later in this chapter for considerations
when locking and unlocking transactions within a database process.

User Transaction Logging

Users opening the database in access modes 1 through 4 use the MPE/iX
user logging facility if the database administrator has enabled the
database for logging (a procedure described in chapter 7). In this case,
calls to the TurboIMAGE/XL intrinsics listed in Table 4-2 are
automatically logged to a log file. Note that nothing is logged for
programs opening the database with read-only access modes (5 through 8),
regardless if the database was enabled for logging. The logging facility
is described more fully later in this chapter and in chapter 7.

Table 4-2. Logged Intrinsics

The DBBEGIN and DBEND intrinsics are used to block logical, static
transactions for logging and recovery purposes. The DBXBEGIN and DBXEND
intrinsics are used to mark logical, dynamic transactions for dynamic
roll-back recovery. Refer to Table 4-4 later in this chapter for a
definition of TurboIMAGE/XL transaction types.

Dynamic roll-back uses the MPE/iX Transaction Management (XM) facility to
roll back transactions online while other database activity is occurring.
User logging is not required for this type of recovery, but is
recommended to guard against a hard disk failure. See chapter 7 for a
discussion of logging and recovery methods.

MPE/iX 5.0 Documentation