HP 3000 Manuals HP 3000 Manuals
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.
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--in this case, the synonym chain information
for the automatic master is set to zero (refer to chapter 10 for more
information).
The current record is unchanged. 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.
[REV BEG]
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.[REV END]
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 | Data set not writable. |
| | -31 | Bad mode. |
| | -222 | Only DBXUNDO allowed when a dynamic transaction |
| | | encounters an error. |
----------------------------------------------------------------------------------------------
| 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. |
| | -3nn | Internal error. |
| | 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.