HP 3000 Manuals HP 3000 Manuals
DBOPEN
INTRINSIC NUMBER 401
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.
Syntax
DBOPEN,base,password,mode,status
Parameters
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 (maximum 6 characters) and terminated by a
semicolon or blank (_), for example, "_ _ orders;".
If the database is successfully opened,
TurboIMAGE/XL replaces the two blanks 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.
__________________________________________________
NOTE The base ID cannot be passed between
processes in an attempt to reduce the number
of required DBOPEN calls.
__________________________________________________
To access a database catalogued in a group other
than the user's log-on group, the database name
must be followed by a period and the group name,
for example, ORDERS.GROUPX. If the database is in
an account other than the user's account, the group
name must be followed by a period and the account
name, for example, ORDERS.GROUPX.ACCOUNT1.
You can use an MPE/iX FILE command before executing
the application program to equate the database name
or the database-access file name to another
database or database-access file name. You can use
only the formal file designator, actual file
designator, and the DEV= parameters. For
additional information on the database-access file,
refer to chapter 9.
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):
_[/USERIDENT] Access class zero (0).
;[/USERIDENT] Creator access.
password[/USERIDENT] Password access.
If either the password or the user identifier
string is less than eight characters long, it must
be terminated with a semicolon or a blank.
The password establishes a user class number as
described in chapter 2. A semicolon supplied as
the password implies creator class 64. The user
identifier is used by the program DBRECOV to
distinguish between users logged on under the same
name and account.
The following are valid examples:
;
CLERK_
CLERK;
CLERK;/JOE;
CLERK_/JOE;
_/DBA
mode is an integer between 1 and 8, inclusive,
corresponding to the valid TurboIMAGE/XL access
modes described in chapter 4. Here is a brief
summary:
Access Associated Concurrent
Mode Capabilities Modes
Allowed
----------------------------------------------------
1 Modify with enforced locking. 1,5
Allow concurrent modify.
2 Update, allow concurrent 2,6
update.
3 Modify exclusive. none
4 Modify, allow concurrent read. 6
5 Read, allow concurrent modify. 1,5
6 Read, allow concurrent modify. 6 and either
2, one 4, or
8
7 Read, exclusive. none
8 Read, allow concurrent read. 6,8
__________________________________________________
NOTE If the database is open in database access
mode 1, a lock must be in effect on either
the data set or the whole database when
adding to or deleting from master data sets.
If a data entry level lock is specified, any
subsequent DBPUTs or DBDELETEs will fail with
error number -12 and the following message is
returned:
intrinsic name CALLED WITHOUT COVERING LOCK IN EFFECT
[REV BEG]
Lock either the entire database or data set
with a data entry lock by using an @ sign to
specify all data sets or all data items.
__________________________________________________
[REV END]
The figure in appendix B summarizes the results of
multiple access to the same database. If a
database cannot be opened successfully in a
particular mode, this information can be used to
determine the problem and to select an alternate
mode.
If your database is enabled for third-party
indexing (TPI), refer to your vendor documentation
for additional DBOPEN mode information. The
section on DBUTIL in chapter 8 of this book has a
brief description of the TPI option.
status is the name of an array of 10 halfwords in which
TurboIMAGE/XL 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. Table 5-19 describes
the contents of element 1 when the
procedure does not succeed.
2 User class number, 0 to 63 (or a 64 if
the database creator enters a semicolon
";" in place of a password).
3 Current size of the DBG (in halfwords)
or 32767, whichever is smaller. If it
is 32767, the DBG size exceeds the
maximum halfword value limit.
4 Size of the DBU (in halfwords) or 32767,
whichever is smaller. If it is 32767,
the DBU size exceeds the maximum
half-word value limit.
5-10 Information about the current procedure
call and its results. This same
information is returned for all
TurboIMAGE/XL procedures if an error
occurs. It is described in "Library
Procedure Error Messages" in appendix A.
Discussion
A process can concurrently use the database through independent, unique
access paths by issuing as many as 127 calls to DBOPEN (63 calls per
database) and specifying a different base array in each call. Subsequent
calls to other TurboIMAGE/XL procedures must use the appropriate base
array so that the correct base ID is used.
CAUTION Although a single process can call DBOPEN a maximum of 127 times
(63 per database), DBOPEN can encounter an MPE/iX system limit
and fail. For example, DBOPEN would fail if the limit was
exceeded for mapped file space or if the process attempted to
open more than the allowable number of files.
The database activity controlled on one access path relates to that
controlled on other access paths in the same way the database activity of
one process relates to that of another. The access modes established by
each DBOPEN call must be compatible, but otherwise the activity
controlled by each access path and the pointers maintained by it are
completely independent. The only exception to this access path
independence relates to locking. If a process makes a lock request on
one access path, it cannot issue a lock on another access path unless the
program has multiple RIN capability (CAP=MR) or first calls DBUNLOCK to
release the locks on the first access path.
[REV BEG]
DBOPEN performs expansion recovery if necessary. During the first open
of the database using any open mode, DBOPEN automatically performs
expansion recovery for any detail data set with the "expansion in
progress" flag turned on and a previous DBPUT capacity expansion had not
completed. Recovery correctly adjusts the data set free count and the
root file data set capacity fields using the actual data set file size.
Use the SHOW CAPACITY command in DBUTIL to detect if recovery is required
for the data set. If the message, "dynamic capacity expansion in
progress flag is on," is displayed for the data set, and asterisks are in
the "no. of entries" and "%max cap" fields, then recovery is required
for the data set(s). QUERY or any application performing the first
DBOPEN of the database can be used to recover the detail data set
capacity. Use DBChange Plus or a third-party application to change an
existing detail data set to have parameters for dynamic expansion.
For more information on DBChange Plus, see MPE/iX Release 5.0
Communicator.[REV END]
If the database is enabled for logging, and the program calls DBOPEN in
one of modes 1-4, then TurboIMAGE/XL attempts to access a log file using
the MPE/iX OPENLOG intrinsic. OPENLOG succeeds only if the following
have been completed:
1. A valid log identifier and log password have been set into the
database root file using the DBUTIL >>SET command, and
2. A corresponding system log process has been initiated by the
console operator to handle any calls to the logging system.
If OPENLOG fails, DBOPEN also fails and returns an appropriate error
condition. If OPENLOG succeeds, DBOPEN causes a log record to be written
which includes such information as time, date, user name, user program,
mode, and security class. (Refer to appendix E for a full description of
log record contents and formats.)
A process is logging if it successfully opens a database in one of modes
1-4, and the database is enabled for logging. A program does not log if
it opens in one of modes 5-8, or if the database is not enabled for
logging.
If DBRECOV roll-back recovery is enabled, the first DBOPEN checks if the
user logging file and the database are attached to the same Transaction
Management (XM) user log set. The database and the user logging file
must be kept synchronized at the XM level in order for DBRECOV roll-back
recovery to work.
DBOPEN initiates recovery of the incomplete dynamic transactions, if
necessary; then DBRECOV rolls back the incomplete static transactions.
Dynamic transactions are not allowed with DBOPEN mode 2.
Table 5-19. DBOPEN Return Status Values
-----------------------------------------------------------------------------------------------
| File System, Memory | -1 | HPFOPEN or FOPEN failure. |
| Management, and | -2 | FCLOSE failure. |
| Transaction | -3 | FREADDIR failure. |
| Management Failures: | -4 | FREADLABEL failure. |
| | -6 | FWRITELABEL error. |
| | -8 | FUNLOCK failure. |
| | -9 | Cannot create a control block. |
| | -10 | FFILEINFO failure. |
| | -168 | Cannot attach n to MPE XL XM: file system error nn. |
| | -169 | Invalid mode for XM attach options. |
| | -175 | Cannot attach n to MPE XL XM: XM error nn. |
| | -176 | Cannot detach n from MPE XL XM: XM error nn. |
| | -177 | User log file is not in the same volume set as database. |
| | -178 | Cannot detach n from MPE XL XM: file system error nn. |
| | -179 | Cannot begin MPE XL XM transaction for attach. |
| | -198 | Total DBOPEN count/user exceeds limit. |
| | -208 | FLABELINFO failure. |
| | -209 | Invalid mode for XM detach. |
| | -210 | MPE error decimal integer while getting log file name. |
-----------------------------------------------------------------------------------------------
| Calling Errors: | -11 | Bad database reference. |
| | -13 | Must be creator of root file or database. |
| | -21 | Bad password. |
| | -22 | Maintenance word required. |
| | -31 | Bad mode. |
| | -32 | Unobtainable mode. |
| | -34 | Database must be recovered before access is allowed. |
| | -90 | Root file bad: unrecognized state: % octal integer. |
| | -91 | Bad root modification level. |
| | -92 | Database not created. |
| | -94 | Database bad: Was being modified with output deferred, |
| | | may not be accessed in mode decimal integer. |
| | -95 | Database bad: Creation was in process (create again). |
| | -96 | Database bad: Erase was in process (erase again). |
| | -220 | Database and user log not attached to the same XM log |
| | | set. |
-----------------------------------------------------------------------------------------------
| Communications | -15 | DSLINE or remote HELLO failure; setup for RDBA failed. |
| Errors: | -60 | Illegal file equation on root file. |
| | -100 | DSOPEN failure. |
| | -101 | DSCLOSE failure. |
| | -102 | DSWRITE failure. |
| | -103 | Remote 3000 space insufficient. |
| | -104 | Remote system does not support TurboIMAGE/XL. |
| | -105 | Remote 3000 cannot create control block. |
| | -106 | Remote 3000 data inconsistent. |
| | -107 | NS 3000 or DS 3000 system error. |
-----------------------------------------------------------------------------------------------
| Logging System | -110 | OPENLOG failure. |
| Failures: | -111 | WRITELOG failure. |
| | -114 | Roll-back enabled without logging. |
-----------------------------------------------------------------------------------------------
| Native Language | -200 | Database language not system supported. |
| Support Errors: | -201 | Native Language Support not installed. |
| | -202 | MPE Native Language Support error decimal integer |
| | | returned by NLINFO. |
-----------------------------------------------------------------------------------------------
Table 5-19. DBOPEN Return Status Values (cont.)
-----------------------------------------------------------------------------------------------
| Exceptional | -167 | Cannot begin MPE XL XM transaction: XM error nn. |
| Conditions: | -191 | DBS control block is full. |
| | -199 | Cannot end MPE XL XM transaction: XM error nn. |
| | -226 | Error occurred when the 00 file was created. |
| | -227 | Error occurred in 00 file recovery. |
| | -234 | Cannot purge the 00 file. |
| | -236 | Internal error occurred when opening the AUX file: |
| | -253 | error nn. |
| | | Database enabled for indexing, but third-party indexing |
| | 60 | is not configured. |
| | 61 | Database access disabled. |
| | 62 | This database opened more than 63 times by the same |
| | 63 | process. |
| | 64 | DBG full. |
| | 66 | DBG disabled; potential damage; only DBCLOSE allowed. |
| | 68 | PCBX full. |
| | | The current DBG for the database does not appear correct |
| | | (TurboIMAGE internal error). |
| | | DBB disabled by an abort. |
-----------------------------------------------------------------------------------------------
Consult appendix A for more information about these conditions and
appendix B for results of multiple access.