HP 3000 Manuals HP 3000 Manuals
Using TurboIMAGE/XL Intrinsics (Continued)
DBPUT (Continued)
Discussion for Master Data Sets. [REV END]
When adding entries to master data sets, the following rules apply:
* The data set must be a manual master.
* The key item must be referenced in the list array and its value in
the buffer array must be unique in relation to other entries in
the master.[REV BEG]
* Space must be available in the master set, or must be dynamically
expandable to add an entry.
* If dynamic capacity expansion parameters are specified for the
master data, when the master data set is almost full, expansion is
done by the incremental amount. If the expansion is successful,
the new record is added to the database. If the expansion is not
successful, an error message is displayed, and the record is not
added to the database. If there is insufficient disc space to
expand the data set to the full incremental amount, DBPUT will
perform a partial expansion up to the disc space available. DBPUT
will terminate if there is no available group or account disc
space even if there is enough system disc space. (The current
capacity for a data set can be displayed by the SHOW CAPACITY
command in DBUTIL or the output buffer from DBINFO modes 202 and
205.)[REV END]
* The order of data item values in the new entry is determined by
the set definition in the schema and not by the order of the
items' occurrence in the list and buffer arrays.
* Values for data items not included in the list array are filled
with binary zeros.
* The caller must have a lock on the data set or the database if the
database is open in access mode 1.
[REV BEG]
* DBPUT to an indexed master triggers a similar operation to indexed
master's B-Tree index file.[REV END]
[REV BEG]
Discussion for Detail Data Sets. [REV END]
When adding entries to detail data sets, the following rules apply:
* The data set must have free space for the entry.
* If the database is opened in access mode 1, the caller must have a
lock covering the entry to be added.
* All search and sort items defined for the entry must be referenced
in the list array.
* Each related manual master data set must contain a matching entry
for the corresponding search item value. If any automatic master
does not have a matching entry, it must have space to add one.
This addition occurs automatically.
* The order of data item values in the new entry is determined by
the set definition in the schema and not by the order of the
items' occurrence in the list and buffer arrays.
* Values for data items not included in the list array are filled
with binary zeros.
* The new entry is linked into one chain for each search item, or
path, defined according to the search item value. It is linked to
the end of chains having no sort items and into its sorted
position according to the collating sequence of the sort item
values in the chain. If two or more entries have the same sort
item value, their position in the chain is determined by the
values of the items following the sort item in the entry. The
position of an entry on a sorted chain is determined by a backward
search of the chain beginning at the last entry. The position is
maintained by logical pointers rather than physical placement in
the file.
* Proper Native Language collating sequence must be maintained for
chain sorting.
* If dynamic capacity expansion is allowed for the detail data set,
when the detail data set reaches the end of the current allocation
(that is, data set free count is zero), expansion is requested by
the incremental amount. If the expansion is successful, the new
record is added to the database. If the expansion is not
successful, an error message is displayed, and the record is not
added to the database. If there is insufficient disc space to
expand the data set to the full incremental amount, DBPUT will
perform a partial expansion up to the disc space available. DBPUT
will terminate if there is no available group or account disc
space even if there is enough system disc space. (The current
capacity for a data set can be displayed by the SHOW CAPACITY
command in DBUTIL or the output buffer from DBINFO modes 202 and
205.)
The record in which the new data entry is placed becomes the current
record for the data set. The forward and backward pointers reflect the
new entry's position. Refer to the description of status elements 7
through 10.
The record number of the new data entry is returned to status halfwords
3-4; and its forward and backward pointers are returned in status
halfwords 7-8 and 9-10, respectively. If you intend to use these numbers
for directed reads (see "Directed Access" in chapter 4), save them
because subsequent TurboIMAGE/XL procedure calls can overwrite the status
area.
The execution of a call to DBPUT could require extensive resources
depending on the amount of chain maintenance required. For example, when
an entry is added to a detail data set, the new entry must be linked to
all other related entries with the same key values and to all of its
related master entries. 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 on other
processes until the call to DBPUT completes. The timing of this
temporary lock can be controlled with the PREFETCH option of DBUTIL.
Refer to "Coordinating Additions to a Database" in chapter 4 for
considerations when enabling or disabling this option.
Performance may be impacted by the number of entries incremented when
DBPUT is used to dynamically expand the detail data set. The number of
disc extents used for the data set file may also impact the performance
of TurboIMAGE/XL.
If the process is logging, a call to DBPUT causes a log record to be
written with such information as the time, date, user identification
number, and a copy of the new record to be added.
If DBPUT is called within a dynamic transaction, a log record is written
after the physical transaction has been successfully completed. If the
intrinsic cannot be completed, 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 dynamic transaction. DBXEND will terminate the dynamic
transaction; the modifications completed thus far within the transaction
will remain in the database.
Table 5-21. DBPUT 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 added. (Occurs |
| | | only if database is open in access mode 1.) |
| | -14 | Illegal intrinsic in current access mode. |
| | -21 | Bad data set reference. |
| | -23 | Data set not writable. |
| | -24 | Operation not allowed on automatic master data set. |
| | -31 | Bad mode. |
| | -51 | Bad list length. |
| | -52 | Bad list or bad item. |
| | -53 | Missing search or sort item. |
| | -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. |
| | | |
----------------------------------------------------------------------------------------------
Table 5-21. DBPUT Return Status Values (cont.)
----------------------------------------------------------------------------------------------
| Exceptional Conditions: | -193 | DBU control block is full. |
| | -196 | DBB control block is full. |
| | -212 | Database corruption detected. |
| | -264 | XM write procedure returned 1030 or 1040. |
| | -312 | Internal error encountered while reading database |
| | -314 | block. |
| | -322 | Error while obtaining path information for set. |
| | -332 | Error returned by process list. |
| | 16 | Error in QLOCK table operation. |
| | | Data set full. |
| | | (In the following messages, dataset# and FSERR # |
| | | will be replaced by the actual number.) |
| | | DBPUT cannot expand dataset#: dataset at maximum |
| | | capacity. |
| | | DBPUT dataset# incomplete expansion: File system |
| | | error #. |
| | | DBPUT cannot expand dataset#: Out of disc space |
| | 18 | (FSERR #). |
| | | Broken chain; forward and backward pointers not |
| | 43 | consistent. |
| | 62 | Duplicate key item value. |
| | 63 | DBG control block is full. |
| | 1nn | DBG disabled; potential damage; only DBCLOSE |
| | 2nn | allowed. |
| | 3nn | Missing chain head for path number nn. |
| | 4nn | Full chain for path number nn. |
| | | Internal error. |
| | | Full synonym chain. |
| | | |
----------------------------------------------------------------------------------------------
Refer to appendix A for more information about these conditions.
DBUNLOCK
INTRINSIC NUMBER 410.
Relinquishes the locks acquired by all previous calls to DBLOCK.
Redundant calls are ignored. If the calling process has the same
database opened multiple times, only those locks put into effect for the
specified access path are unlocked.
If DBUNLOCK is called when a dynamic transaction is active and a modify
intrinsic (DBPUT, DBDELETE, or DBUPDATE) has already been used in the
dynamic transaction (that is, the database is modified), the DBUNLOCK
fails. You must check the error condition. You may use DBERROR or
DBEXPLAIN to display the error message. When a DBUNLOCK fails within the
dynamic transaction, dynamic intrinsic rollback allows the following
choices:
* Use DBXEND to end the dynamic transaction.
* Continue with the remainder of the dynamic transaction taking into
account that DBUNLOCK failed and locks are still in place.
* Use DBXUNDO to rollback the entire dynamic transaction.
Syntax.
DBUNLOCK,base,dset,mode,status
Parameters.
base is the name of the array used for the base
parameter when opening the database. The first
element of the array must contain the base ID
returned by DBOPEN.
dset is currently unused. Use the Not_Used_Parm or
DUMMY variable as recommended at the beginning of
this chapter or any dset array used for other
procedures.
mode must be an integer equal to 1.
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-22 describes
the contents of element 1 when the
procedure does not succeed.
2 Number of lock descriptors released by
this call. Each data set lock or
database lock is counted as one
descriptor.
3-4 Reserved for internal use.
5-10 Information about the procedure call and
its results. Refer to "Library
Procedure Error Messages" in appendix A
for a description of this information.
Table 5-22. DBUNLOCK Return Status Values
----------------------------------------------------------------------------------------------
| | | |
| File System, Memory | -4 | MPE file error nn returned by DBUNLOCK on |
| Management, and | | FREADLABEL. |
| Transaction Management | -6 | MPE file error nn returned by DBUNLOCK on |
| Failures: | | FWRITELABEL. |
| | -167 | Cannot begin MPE XL XM transaction: XM error nn. |
| | -199 | Cannot end MPE XL XM transaction: XM error nn. |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Calling Errors: | -11 | Bad database reference. |
| | -31 | Bad mode. |
| | -215 | XM error nn encountered when rolling out dynamic |
| | | transaction. |
| | -222 | Only DBXUNDO allowed when a dynamic transaction |
| | | encounters an error. |
| | -230 | A DBUNLOCK inside a dynamic transaction is not |
| | | allowed. |
| | -231 | During Dynamic Rollback recovery, internal |
| | | procedure failed; error nn. |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Communications Errors: | -102 | DSWRITE failure. |
| | -106 | Remote 3000 data inconsistent. |
| | -107 | NS 3000 or DS 3000 system error. |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Exceptional Conditions: | 63 | DBG disabled; potential damage; only DBCLOSE |
| | | allowed. |
| | | |
----------------------------------------------------------------------------------------------
Appendix A contains more information about these conditions.
DBUPDATE
INTRINSIC NUMBER 406.
Modifies values of data items in the entry residing at the current record
address of a specified data set. To call DBUPDATE, you must open the
database in access mode 1, 2, 3, or 4. The update is always carried out
correctly against the latest version of the data, regardless of
modifications made by other users.
In database access mode 1, 3, or 4, you can use DBUPDATE to modify the
values of detail data set search and sort items if permitted by the
critical item update (CIUPDATE) option settings for the database and the
current process. Master data set key item values cannot be modified even
if CIUPDATE is permitted.
Syntax.
DBUPDATE,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 be read, 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 DBUPDATE 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 operates successfully,
the status array contents are:
Element Contents
1 If the procedure succeeds, the return
status is 0. Table 5-23 describes
the contents of element 1 when the
procedure does not succeed.
2 Length of the values in buffer (in
halfwords).
3-10 Same word values set by preceding
procedure call which positioned the data
set at the current entry. If critical
item update is permitted, the value
contained in element 3 determines the
message returned.
list is the name of an array containing an ordered set
of data item identifiers, either names or numbers.
Values supplied in the buffer array replace the
values of data items occupying the same relative
position in the list array. The user class
established when the database is opened must allow
at least read access to all the items included in
the list array.
If the corresponding buffer array values are the
same as the current data item values, the list
array can include data items to which the user has
read access only, such as, key, search and sort
items. This feature permits reading and updating
with the same list array contents. Those items to
be updated must allow write access and cannot be
key, search, or sort items.
The list array can contain a left-justified set of
data item names, separated by commas and terminated
by a semicolon or a blank. No embedded blanks are
allowed and no name can appear more than once.
When referencing by number, the first element of
the list array is an integer n followed by n unique
data item numbers (one-halfword positive integers).
The list not only specifies the data items to be
updated immediately but is saved internally by
TurboIMAGE/XL as the current list for this 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 with the DBPUT
procedure. List processing is a relatively high
overhead operation that can be shortened
substantially in subsequent calls by using the
asterisk construct to specify that the current list
is to be used.
buffer is the name of an array containing concatenated
values to replace the values of data items
occupying the same relative position in the list
array. The number of halfwords for each value must
correspond to the number of halfwords required by
its type multiplied by the sub-item count. Search
and sort item values can be included in this update
list if their values will not change.