HP 3000 Manuals HP 3000 Manuals
DBCONTROL
INTRINSIC NUMBER 411
Allows a process accessing the database to have control over two DBUTIL
options. In exclusive mode (DBOPEN mode 3), DBCONTROL can be used to
enable or disable the deferred output (AUTODEFER) option. For database
access modes 1, 3, and 4, DBCONTROL can be used to temporarily enable or
disable the critical item update (CIUPDATE) option, depending on the
setting for the database, without impacting other processes operating on
the same database. Using DBCONTROL does not alter the permanent
AUTODEFER or CIUPDATE setting for the database set with DBUTIL.
Syntax
DBCONTROL,base,qualifier,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.)
qualifier is currently ignored by DBCONTROL.
mode must be an integer equal to 1, 2, 5, 6, 9 or 10
indicating the following:
Mode 1: Turn on the deferred output
option. If AUTODEFER has not
been enabled for the database
(using DBUTIL >>ENABLE), mode
1 enables the deferred output
option for the duration of
only the current DBOPEN. When
the database is closed,
AUTODEFER will no longer be
enabled. Mode 1 is not
allowed while a dynamic
transaction is active.
Mode 2: Turn off the deferred output
option. If AUTODEFER has
been enabled for the database
(using DBUTIL >>ENABLE), mode
2 disables the deferred
output option for the
duration of only the current
DBOPEN. When the database is
closed, AUTODEFER will again
be enabled.
Mode 5: Enable the critical item
update option. If CIUPDATE
has been set to ALLOWED for
the database (using DBUTIL
>>SET), mode 5 enables the
option for the current DBOPEN
until either a DBCONTROL mode
6 call disables the option or
the database is closed. You
can call mode 5 successfully
if the CIUPDATE setting for
the database equals ON, but
the call has no impact on the
option setting for the
current process unless an
intervening call to DBCONTROL
mode 6 disabled the option.
If the CIUPDATE flag is
DISALLOWED, a call to mode 5
returns an error. The
CIUPDATE option is available
only in database access modes
1, 3, and 4.
Mode 6: Disable the critical item
update option. If CIUPDATE
has been set to ON for the
database (using DBUTIL
>>SET), mode 6 disables the
option for the current DBOPEN
until either a DBCONTROL mode
5 call enables the option or
the database is closed. If
the CIUPDATE option setting
for the database equals
ALLOWED and the process has
called DBCONTROL in mode 5 to
enable the option, then mode
6 disables the option for
that same process. The
CIUPDATE option is available
only in database access modes
1, 3, and 4.[REV BEG]
Mode 9: Enable the HWMPUT option of
DBPUT for the current DBOPEN.
This causes DBPUT to try
placing entries at the
high-water mark first instead
of at the delete chain head
first.
Mode 10: Disable the HWMPUT option of
DBPUT for the current DBOPEN.
This causes DBPUT to try
placing entries at the delete
chain head first. This is
the default action if
DBCONTROL is not called.
[REV END]
If your database is enabled for third-party
indexing (TPI), refer to your vendor documentation
for additional DBCONTROL modes. 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. If the
procedure executes successfully, the status array
contents are as follows:
Element Contents
1 If the procedure succeeds, the return
status is 0. Table 5-7 describes
the contents of element 1 when the
procedure does not succeed.
2-4 Unchanged from previous procedure call
using this array.
5-10 Procedure call information. Refer to
"Library Procedure Error Messages" in
appendix A for a description of this
information.
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.
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.
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 has been set to ALLOWED
and an earlier call to DBCONTROL mode 5 enabled the option. 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.
[REV BEG]
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 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 |
| | -179 | nn. |
| | | Cannot begin MPE XL transaction for attach: XM |
| | -189 | error nn. |
| | | 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. |
----------------------------------------------------------------------------------------------
- Communications Errors: - -102 - DSWRITE failure. -
----------------------------------------------------------------------------------------------
| Exceptional Conditions: | 63 | DBG disabled; potential damage; only DBCLOSE |
| | | allowed. |
----------------------------------------------------------------------------------------------
Consult appendix A for more information about these conditions.