TurboIMAGE/XL Database Management System Reference Manual (30391-90012)

226 Chapter5
TurboIMAGE/XL Library Procedures
DBPUT
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