HP 3000 Manuals HP 3000 Manuals
Using TurboIMAGE/XL Intrinsics (Cont.)
DBCONTROL (Cont.)
Discussion.
DBCONTROL can be called by a program for the following purposes:
* To enable or disable the AUTODEFER option for the current mode 3
DBOPEN.
* To enable or disable the critical item update option for the
current process accessing the database in mode 1, 3, or 4
depending on the CIUPDATE setting for the database.
* To enable or disable the HWMPUT for the current DBOPEN.[REV BEG]
* To include a database in dynamic multiple database transaction.
* To activate deadlock detection for the database.
* To perform B-Tree index related tasks.[REV END]
In TurboIMAGE/XL default mode, MPE/iX Transaction Management (XM) is used
to log database modifications (DBPUTs, DBDELETEs, DBUPDATEs) to the XM
log file. With deferred output, MPE/iX Transaction Management is not
used. Instead, the MPE/iX file system default mode is used. This mode
keeps data pages in memory for as long as possible, either until file
close time or until no more memory is available.
Thus, with deferred output, database modifications caused by calls to
DBPUT, DBUPDATE, or DBDELETE cannot be written to the disk (or can only
be partially written). Although TurboIMAGE/XL generally operates more
efficiently in this mode, a system failure while the database is
operating in this mode has a very high probability of causing internal
structural damage to the database.
A program that opens the database exclusively can call DBCONTROL mode 1
to enter the deferred mode of operation, except when a dynamic
transaction is active. In this case, all database modifications will be
kept in memory for as long as possible, either until the database is
closed or until no more memory is available.
A program that opens the database exclusively can call DBCONTROL mode 2
to turn off the deferred mode of operation. In this case, all database
modifications will be written to the MPE/iX Transaction Management log
file until the database is closed.
Programs that are designed to modify the values of detail data set search
and sort items can call DBCONTROL mode 5 if the CIUPDATE setting for a
database equals ALLOWED. The CIUPDATE option is available only in
database access modes 1, 3, and 4. The mode 5 call enables CIUPDATE for
only this process until either a DBCONTROL mode 6 call disables the
option for the process or the database is closed. Other processes
operating on the same database are not impacted by these calls.
[REV BEG]
A program, which must ensure that the values of detail data set search
and sort items remain unchanged for the duration or a portion of the
process, can call DBCONTROL mode 6 to disable CIUPDATE if this option has
been set to ON for the database, or if the option is ALLOWED (default or
set by DBUTIL) and an earlier call to DBCONTROL mode 5 enabled the
option.[REV END] CIUPDATE is available only in database access modes 1,
3, and 4. When DBCONTROL mode 6 is used to disable CIUPDATE, the option
is disabled for that process alone until a call to DBCONTROL mode 5
enables the option for the process or the database is closed. Other
processes operating on the same database are not affected by these calls.
NOTE If HWMPUT is enabled, DBPUT will not inform you when it has reached
the end of file and has started using the delete chain head. In
general, it is not a good practice to toggle HWMPUT.
If you plan to use roll-forward recovery, do not toggle HWMPUT
after storing the database.
By default, DBPUT first checks the delete chain head, then if it is
empty, DBPUT places the new entry at the high-water mark. If the
high-water mark option (HWMPUT) is enabled, DBPUT will place the entry at
the high-water mark first; after the high-water mark reaches the file
limit, DBPUT will use the delete chain head. Use DBCONTROL mode 9 to
enable or mode 10 to disable this feature.
[REV BEG]
DBCONTROL allows DBUTIL and privileged callers to perform several B-Tree
index file related functions such as adding, deleting, or rebuilding of a
B-Tree index file for a specified master dataset. There are four new
DBCONTROL modes pertaining to B-Tree indices: modes 13, 14, 15, and 16.
Refer to chapter 11, "B-Tree Indices," for more information.
Consult appendix A for more information about the conditions for the
return status values shown in Table 5-7.
[REV END]
Table 5-7. DBCONTROL Return Status Values
----------------------------------------------------------------------------------------------
| | | |
| File System, Memory | -4 | FREADLABEL failure. |
| | | |
| Management, and | -168 | Cannot attach n to MPE XL XM: file system error nn. |
| | | |
| Transaction Management | -175 | Cannot attach n to MPE XL XM: XM error nn. |
| | | |
| Failures: | -176 | Cannot detach n from MPE XL XM: XM error nn. |
| | | |
| | -178 | Cannot detach n from MPE XL XM: file system error |
| | | nn. |
| | | |
| | -179 | Cannot begin MPE XL transaction for attach: XM |
| | | error nn. |
| | | |
| | -189 | Cannot begin MPE XL transaction for detach: XM |
| | | error nn. |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Calling Errors: | -11 | Bad database reference. |
| | | |
| | -14 | Illegal intrinsic in current access mode. |
| | | |
| | -31 | Bad mode. |
| | | |
| | -80 | Output deferred not allowed when ILR enabled. |
| | | |
| | -81 | Output deferred not allowed with roll-back enabled. |
| | | |
| | -82 | CIUPDATE is set to DISALLOWED; cannot use critical |
| | | item update. |
| | | |
| | -222 | Only DBXUNDO allowed when a dynamic transaction |
| | | encounters an error. |
| | | |
| | -224 | DBCONTROL mode 1 not allowed inside a dynamic |
| | | transaction.[REV BEG] |
| | | |
| | -421 | BTE: unknown qualifier value for DBCONTROL mode 13. |
| | | |
| | -422 | BTE: data set# not in valid range. |
| | | |
| | -423 | BTE: B-Tree already exists. |
| | | |
| | -424 | BTE: Failed to create B-Tree. |
| | | |
| | -425 | BTE: DB not opened exclusively. |
| | | |
| | -426 | BTE: B-Tree doesn't exist. |
| | | |
| | -427 | BTE: FCLOSE, purge failed. |
| | | |
| | -428 | BTE: Rebuildindex failed. |
| | | |
| | -432 | BTE: Bad wildcard character. |
| | | |
| | -434 | BTE: Data set is detail and not master. |
| | | |
| | -436 | BTE: Failed to extract data from root file. |
| | | |
| | -440 | BTE: XM Attach of index file failed |
| | | |
| | -441 | BTE: XM Detach of index file failed. |
| | | |
| | -442 | BTE: RELEASE of index file failed. |
| | | |
| | -443 | BTE: SECURE of index file failed. |
| | | |
| | -451 | BTE: Root version less than "C"4. |
| | | |
| | -452 | BTE: Key length greater than 252 bytes (maximum |
| | | index key size). |
| | | |
| | 92 | Need PM capability.[REV END] |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Communications Errors: | -102 | DSWRITE failure. |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Exceptional Conditions: | 63 | DBG disabled; potential damage; only DBCLOSE |
| | | allowed. |
| | | |
----------------------------------------------------------------------------------------------
DBDELETE
INTRINSIC NUMBER 408.
Deletes the current entry from a manual master or detail data set. The
database must be opened in access mode 1, 3, or 4.
Syntax.
DBDELETE,base,dset,mode,status
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
the base ID.)
dset is the name of an array containing the
left-justified name of the data set from which the
entry is to be deleted, 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 DBDELETE 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-8 describes
the contents of element 1 when the
procedure does not succeed.
2 Zero.
3-4 Unchanged current record number.
5-6 Number of entries in a chain.
If master data set, the number is zero
unless the deleted entry was a primary
entry with synonyms. In this case, the
number is one less than its previous
value.
If detail data set, the number is
unchanged from the preceding procedure
call.
7-10 Unchanged preceding and succeeding
record numbers of a chain. If master
data set and the new synonym chain count
is greater than zero, the numbers
reference the last and first synonym
chain entries, respectively.
Discussion.
When deleting entries from detail data sets, and if the database is open
in access mode 1, you must establish a lock covering the data entry to be
deleted, the data set, or the database.
When deleting entries from master data sets, the following rules apply:
* All pointer information for chains indexed by the entry must
indicate that the chains are empty. In other words, there cannot
be any detail entries on the paths defined by the master which
have the same search item value as the key item in the master
entry to be deleted.
* If the database is open in access mode 1, a lock must be in effect
on the data set or the whole database.
[REV BEG]
DBDELETE to an indexed master triggers a similar operation to the indexed
master's B-Tree file and is considered atomic with the DBDELETE
intrinsic.[REV END]
Because of the way TurboIMAGE/XL handles synonym chains, it is possible
to write a routine to read and delete all the entries in a master data
set and still leave some entries in the set. If the deleted entry is a
primary with synonyms, TurboIMAGE/XL moves the first synonym in the chain
to the deleted primary's location. A subsequent DBGET mode 3 will read
the next sequential entry, leaving an entry (the new primary) in the
previous location.
A solution to this problem is to check elements 5 and 6 of the status
parameter following each DBDELETE call. If the synonym count in these
elements is not zero, reread the location (using DBGET, mode 1) and call
DBDELETE again. Repeat the reread and DBDELETE until the count is zero,
then continue reading and deleting in a serial manner. (Refer to chapter
4 for a discussion of serial access and to chapter 10 for a discussion of
synonym chains.)
TurboIMAGE/XL performs the required changes to chain linkages and other
chain information, including the chain heads in related master data sets.
If the last member of each detail chain linked to the same automatic
master entry has been deleted, DBDELETE also deletes the master entry
containing the chain heads.[REV DEL]
If a primary data entry with synonyms is deleted from a master data set
and a secondary migrates, the backward and forward pointers reflect the
new primary. In all other cases, the backward and forward pointers are
unchanged when an entry is deleted.
The execution of a call to DBDELETE could require extensive resources
depending on the amount of chain maintenance required. For example, when
an entry is deleted from a detail data set, the links connecting that
entry to all other related entries with the same key values and to all
other related master entries are eliminated. This operation could
involve many blocks of data. TurboIMAGE/XL prevents data block access
conflicts with all other users and ensures data integrity by applying a
temporary lock against other processes until the call to DBDELETE
completes. The timing of this temporary lock can be controlled with the
PREFETCH option of DBUTIL. Refer to "Coordinating Deletions to a
Database" in chapter 4 for what to consider when enabling or disabling
this option.
If the process is logging, a call to DBDELETE causes a log record to be
written with such information as the time, date, user identification
number, and a copy of the record to be deleted.
In a dynamic transaction, DBDELETE causes a log record to be written
after the physical transaction has been successfully completed. If
DBDELETE cannot complete within a dynamic transaction, an error is
returned. This error condition must be checked, and you must decide to
use DBXUNDO, DBXEND, or continue with the remainder of the dynamic
transaction. DBXUNDO will abort the entire transaction. DBXEND will
terminate the dynamic transaction; the modifications completed thus far
within the transaction will remain in the database.
Table 5-8. DBDELETE Return Status Values
----------------------------------------------------------------------------------------------
| | | |
| File System, Memory | -1 | FOPEN failure. |
| Management, and | -3 | FREADDIR failure. |
| Transaction Management | -4 | FREADLABEL failure. |
| Failures: | -5 | FWRITEDIR failure. |
| | -6 | FWRITELABEL failure. |
| | -167 | Cannot begin MPE XL XM transaction: XM error nn. |
| | -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. |
| | -178 | Cannot detach n from MPE XL XM: file system error |
| | -199 | nn. |
| | -209 | Cannot end MPE XL XM transaction: XM error nn. |
| | | Invalid mode for XM detach options. |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Calling Errors: | -11 | Bad database reference. |
| | -12 | No lock covers the data entry to be deleted. |
| | | (Occurs only if database open in access mode 1.) |
| | -14 | Illegal intrinsic in current access mode. |
| | -21 | Bad data set reference. |
| | -23[REV | Data set not writable. |
| | BEG] | DBDelete not allowed on Auto Master. |
| | -24[REV | Bad mode. |
| | END] | Only DBXUNDO allowed when a dynamic transaction |
| | -31 | encounters an error. |
| | -222 | |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Communications Errors: | -102 | DSWRITE failure. |
| | -106 | Remote 3000 data inconsistent. |
| | -107 | NS 3000 or DS 3000 system error. |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Logging System Failures: | -111 | WRITELOG failure. |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Exceptional Conditions: | -193 | DBU control block is full. |
| | -196 | DBB control block is full. |
| | -264 | Error while writing to TPI files. |
| | -3nn | Internal error. |
| | -314 | Error while obtaining patch information for set. |
| | -322 | Error while validating qualifier parameter. |
| | -332 | Error in QLOCK table operations. |
| | 17 | No entry. |
| | 44 | Can't delete master entry with non-empty detail |
| | 63 | chains. |
| | | DBG disabled; potential damage; only DBCLOSE |
| | | allowed. |
| | | |
----------------------------------------------------------------------------------------------
Consult appendix A for more information about these conditions.