HP 3000 Manuals HP 3000 Manuals
Using TurboIMAGE/XL Intrinsics (Continued)
DBCLOSE
INTRINSIC NUMBER 403.
Terminates access to a database or a data set, or rewinds a data set.
DBCLOSE is used in conjunction with DBOPEN to establish and terminate
access to a database.
Syntax.
DBCLOSE,base,dset,mode,status
Parameters.
base is the name of an 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 to be closed,
or is an integer referencing the data set by number
if mode equals 2 or 3. If mode equals 1, this
parameter is ignored. The data set name can be up
to 16 characters long. If shorter, it must be
terminated by a semicolon or a blank.
mode is an integer equal to 1, 2, or 3 indicating the
type of termination desired as follows:
Mode 1: Access to the database is
terminated. Any locks held
by this user for this base ID
are released. If DBCLOSE
mode 1 is called while a
dynamic transaction is still
active, an error is returned,
the transaction is aborted,
and the database is closed
automatically. You do not
need to call DBXEND or
DBXUNDO.
Mode 2: The data set referenced by
the dset array is closed, but
locks held in the data set
are not released. If DBCLOSE
mode 2 is called while a
dynamic transaction is still
active, an error is returned.
You must check the error and
decide to use DBXEND,
DBXUNDO, or continue with the
transaction even if DBCLOSE
mode 2 failed. 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.
Mode 3: If mode equals 3, the data
set referenced by the dset
array is reinitialized but
not closed.
If your database is enabled for third-party
indexing (TPI), refer to your vendor documentation
for additional DBCLOSE 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-6 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.
You must call DBCLOSE mode 1 to terminate access to the database when you
have completed all the tasks you want to perform. If a process has
issued multiple calls to DBOPEN for the same database, only the access
path specified in the DBCLOSE base parameter is affected by the call to
DBCLOSE.
The capability to reset and close a data set is provided to perform
functions such as reinitializing dynamic status information for a process
accessing a particular data set and returning system resources. In both
modes 2 and 3, status information is reinitialized, but system resources
are returned in mode 2 only. The current list is not reset. Table 5-5
summarizes the functions performed in each mode.
Table 5-5. DBCLOSE Modes 2 and 3 Functions
-----------------------------------------------------------------------------------------------
| | | |
| Function | Mode 2 | Mode 3 |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Reinitialize dynamic status information for the | YES | YES |
| data set (chain count, forward and backward | | |
| pointers, current record number and last return | | |
| status). | | |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Close the data set. | YES | NO |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Release locks held within the data set. | NO | NO |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Current list reset. | NO | NO |
| | | |
-----------------------------------------------------------------------------------------------
Because mode 3 does not close and reopen a data set, it is more efficient
than mode 2 if the data set is to be accessed again before the database
is closed.
Only mode 3 is allowed within a dynamic transaction; mode 2 will return
an error, and mode 1 will abort the transaction.
If the process is logging, a mode 1 DBCLOSE causes a DBCLOSE log record
to be written to the log file. DBCLOSE log records contain such
information as the time, date, and user log identification number. A
DBCLOSE log record is also written if the process aborts or terminates
without closing the database. If the process aborts before completing an
active transaction, a special DBEND log record is written prior to the
DBCLOSE.
DBCLOSE returns an error condition if the process has not completed an
active transaction; in other words, the process has called DBBEGIN
without a matching call to DBEND. Transactions that abort in this manner
are not automatically suppressed by DBRECOV during recovery in order to
salvage as many subsequent transactions that may depend on the aborted
transaction as possible.
Table 5-6. DBCLOSE Return Status Values
----------------------------------------------------------------------------------------------
| | | |
| File System, Memory | -2 | FCLOSE failure.[REV BEG] |
| Management, and | -3 | FREADDIR failed.[REV END] |
| Transaction Management | -5 | FWRITEDIR failure. |
| Failures: | -6 | FWRITELABEL failure. |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Calling Errors: | -11 | Bad database reference. |
| | -21 | Bad data set reference. |
| | -31 | Bad mode. |
| | -222 | Only DBXUNDO allowed when a dynamic transaction |
| | | encounters an error. |
| | -232 | Illegal DBCLOSE mode 2 used during an active |
| | | dynamic transaction. |
| | -235 | Dynamic transaction aborted due to DBCLOSE mode 1; |
| | [REV | database closed. |
| | BEG] | Feature not implemented. |
| | -420[REV | |
| | END] | |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Communications Errors: | -101 | DSCLOSE failure. |
| | -102 | DSWRITE failure. |
| | -103 | Remote 3000 stack space insufficient. |
| | -106 | Remote 3000 data inconsistent. |
| | -107 | NS 3000 or DS 3000 system error. |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Logging System Failures: | -111 | WRITELOG failure. |
| | -112 | CLOSELOG failure. |
| | -152 | Transaction is in process. |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Exceptional Conditions: | -194 | Invalid DBB. |
| | -332 | Error in QLOCK table operation. |
| | -333 | Error in QOPEN table operation. |
| | 63 | DBG disabled; potential damage; only DBCLOSE |
| | | allowed. |
| | | |
----------------------------------------------------------------------------------------------
Consult appendix A for more information about these conditions.
DBCONTROL
INTRINSIC NUMBER 411. [REV BEG]
Allows a process accessing the database to have control over some DBUTIL
options. In exclusive mode (DBOPEN mode 3), DBCONTROL can be used to
enable or disable the deferred output (AUTODEFER) option and perform
several B-Tree related tasks such as adding, dropping, or rebuilding a
B-Tree index. It can also be used to set BTREEMODE1 option to ON or OFF
and specify the wildcard character for the current DBOPEN or for the
database (permanent).
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 settings for the database set with
DBUTIL. However, the permanent setting for BTREEMODE1 and wildcard
character can be altered based on the DBCONTROL mode.[REV END]
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.)[REV BEG]
qualifier used only for certain DBCONTROL modes.
mode must be an integer equal to 1, 2, 5, 6, 7, 9, 10,
13, 14, 15, or 16 indicating the following:[REV
END]
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: [REV BEG]
Enable the critical item
update option. If CIUPDATE
is ALLOWED for the database
(default or by 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.[REV
END] 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 7: Allow the database to be
included in the dynamic
multiple database transaction
(DMDBX). DBCONTROL mode 7
needs to be done once, for
every database, before
including it in DBXBEGIN mode
3 call for DMDBX. Mode 7 is
used programmatically to
allow it for DMDBX and
remains activated until the
database is closed or the
application terminates.
Mode 7 also activates the
database for deadlock
detection. In case of a
deadlock, DBLOCK will return
an error, 26, instead of
causing a process hang. Note
that mode 7 will activate
both deadlock detection and
inclusion in DMDBX. If you
only want deadlock detection
and not DMDBX, your DBXBEGIN
call can use mode 1 instead
of 3.[REV END]
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 BEG]
Mode 13: Allow a privileged mode
caller to perform B-Tree
related tasks such as adding,
dropping, rebuilding,
releasing, or securing a
B-Tree index file. Exclusive
database access is required
to add, drop, or rebuild a
B-Tree index. Qualifier has
a structured record
containing dataset
information and directives.
Refer to chapter 11, "B-Tree
Indices" for the qualifier
layout.
Mode 14: Allow a privileged mode
caller to set BTREEMODE1
option to ON or OFF and set
wildcard character for the
database (permanent). Refer
to chapter 11, "B-Tree
Indices" for the qualifier
layout.[REV END]
[REV BEG]
Mode 15: Enable B-Tree wildcard search
for DBFIND mode 1, X and U
types, for the master data
set's key item and its
corresponding search items in
details, if the key item has
a B-Tree index. In other
words, turn on the BTREEMODE1
flag for the current database
open. The first byte of the
qualifier is examined. If it
is null or blank, then the
current wildcard character is
not changed. If it is in the
ASCII range (33...126), then
the wildcard character is
changed to that value for the
current DBOPEN.[REV END] If
the qualifier is any other
value, DBCONTROL returns an
error. Affects only the
current database open.[REV
BEG] It needs to be done once
per database and remains
activated until the database
is closed or the application
terminates. This mode allows
you to perform B-Tree
searches on ASCII types
without making application
changes.
Mode 16: Disable B-Tree wildcard
search for DBFIND mode 1
regardless of the existence
of a B-Tree index. That is,
turn off the BTREEMODE1 flag
for the current database
open. The qualifier is
ignored, and BTREEMODE 1 is
turned off. Affects the
current database open only.
It needs to be done once per
database and remains
activated until the database
is closed or the application
terminates.
[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.