HP 3000 Manuals HP 3000 Manuals
Using TurboIMAGE/XL Intrinsics (Cont.)
DBOPEN (Cont.)
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
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.
__________________________________________________
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.
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.
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. |
| | -5 | FWRITEDIR error. |
| | -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. |
| | -211 | Invalid or no userlabel. |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| 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. |
| | -61 | Error while obtaining information about file equation. |
| | -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. |
| | | |
-----------------------------------------------------------------------------------------------
Table 5-19. DBOPEN Return Status Values (cont.)
-----------------------------------------------------------------------------------------------
| 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. |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| 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. |
| | -220 | User log and database not attached to same XM log. |
| | -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: |
| | -250 | error nn. |
| | -253 | Failure in semaphore initialization. |
| | | Database enabled for indexing, but third-party indexing |
| | -331 | is not configured. |
| | -332 | Invalid DSET Capacity. |
| | -333 | Error in QLOCK table operation. |
| | 60 | Error in QOPEN table operation. |
| | 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.
DBPUT
INTRINSIC NUMBER 407.
Adds new entries to a manual master or detail data set. The database
must be opened in access mode 1, 3, or 4.
Syntax.
DBPUT,base,dset,mode,status,list,buffer
Parameters.
base is the name of the array used as the base parameter
when opening the database. The first element of
the array must contain the base ID returned by
DBOPEN. (Refer to DBOPEN for more information about
base ID.)
dset is the name of an array containing the
left-justified name of the data set to which the
entry is to be added, or is an integer referencing
the data set by number. The data set name can be
up to 16 characters long. If shorter, it must be
terminated by a semicolon or a blank.
mode must be an integer equal to 1.
If your database is enabled for third-party
indexing (TPI), refer to your vendor documentation
for additional DBPUT 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-21 describes
the contents of element 1 when the
procedure does not succeed.
2 Length of logical entry in buffer array
(in halfwords).
3-4 Word record number of new entry.
5-6 Word count of number of entries in
chain. If master data set, chain is
synonym chain. If detail data set,
chain is current chain of new entry.
7-8 If master, word record address of
predecessor on synonym chain. If
detail, word record number of
predecessor on current detail chain.
9-10 If detail, word record number of
successor on current chain. If master,
word zero.
list is the name of an array containing an ordered set
of data item identifiers; names or numbers. The
new entry contains values supplied in the buffer
array for data items in the list array. Search or
sort items defined for the entry must be included
in the list array. Fields of unreferenced items
are filled with binary zeros.
The list array can contain a left-justified set of
data item names, separated by commas and terminated
by a semicolon or blank; no embedded blanks are
allowed, and no name can appear more than once.
For example:
ACCOUNT,LAST-NAME,CITY,STATE;
When referencing by number, the first halfword of
the list array is an integer n that is followed by
n single positive integers identifying unique data
item numbers. Example: 4 1 10 3 16 lists for the
four data item numbers 1, 10, 3, and 16.
The list specifies data items for which values are
supplied in the buffer array, and is saved
internally by TurboIMAGE/XL as the current list for
the data set. The current list is unchanged until
a different list is specified in a subsequent call
to DBGET, DBPUT, or DBUPDATE for the same access
path and data set.
Some special list constructs are allowed. These
are described in Table 5-20 and illustrated in
the programs in chapter 6. List processing is a
relatively high overhead operation which can be
shortened in subsequent calls by using the asterisk
construct to specify that the current list is to be
used. Be sure a current list exists before using
the asterisk construct, or a null list is assumed.
buffer is the name of an array containing data item values
to be added. The values must be in the same order
as their data item identifiers in the list array.
The number of halfwords for each value must
correspond to the number required by its type; for
example, I2 values must be 2 halfwords long.
Table 5-20. Special list Parameter Constructs
-----------------------------------------------------------------------------------------------
| | | |
| Construct | list Array Contents | Purpose |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Empty | 0; or 0_ or ; or _ | Request no data transfer. |
| | (0 must be ASCII.) | |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Empty Numeric | 0 (n, length of data item | Request no data transfer. |
| | identifier list, is zero) | |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Asterisk | *; or *_ | Request procedure to use previous list |
| | | and apply it to same data set. This |
| | | construct saves TurboIMAGE/XL |
| | | processing time, especially if more |
| | | than one or two items are involved. |
| | | If "*" is used to define the list in |
| | | the first call to DBGET and DBPUT, |
| | | TurboIMAGE/XL treats it as a zero. |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Commercial | @; or @_ | Request procedure to use all data |
| At-Sign | | items of the data set in the order of |
| | | their occurrence in the entry. |
| | | |
-----------------------------------------------------------------------------------------------
| |
| Note: |
| |
| _ indicates blank. |
| |
-----------------------------------------------------------------------------------------------
[REV BEG]