HP 3000 Manuals HP 3000 Manuals
Using TurboIMAGE/XL Intrinsics (Cont.)
DBUPDATE (Cont.)
Discussion.
Before performing an update for a database opened in access mode 1,
TurboIMAGE/XL verifies that locks are in effect to cover the data entry
both before and after it is modified.
The current record number, forward and backward pointers are unchanged.
(Refer to the description of status words 3 through 10.)
If the process is logging, a call to DBUPDATE causes a log record to be
written with such information as the time, date, user identification
number, and a copy of both the old and new data item values.
When DBUPDATE is called within a dynamic transaction, a log record is
written after the successful completion of the physical transaction. 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 transaction. DBXEND will terminate the dynamic
transaction; the modifications completed thus far within the transaction
will remain in the database.
Table 5-23. DBUPDATE Return Status Values
----------------------------------------------------------------------------------------------
| | | |
| File System, Memory | -1 | FOPEN failure. |
| Management, and | -3 | FREADDIR failure. |
| Transaction Management | -4 | FREADLABEL failure. |
| Failures: | -5 | FWRITEDIR failure. |
| | -167 | Cannot begin MPE XL XM transaction: XM error. |
| | -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 locks cover the data entry to be updated. |
| | | (Occurs only if database is open in access mode 1.) |
| | -14 | Illegal intrinsic in current access mode. |
| | -21 | Bad data set reference. |
| | -31 | Bad mode. |
| | -51 | Bad list length. |
| | -52 | Bad list or bad item. |
| | -82 | CIUPDATE is set to DISALLOWED; cannot use critical |
| | | item update. |
| | -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. |
| | -264 | Error while writing to TPI files. |
| | -3nn | Internal error. |
| | -312 | Error while reading database file. |
| | -314 | Error while getting path information for set. |
| | -332 | Error in QLOCK table operation. |
| | 17 | No entry. |
| | 41 | DBUPDATE attempted to modify value of critical |
| | | item--key, search or sort. |
| | 42 | Read only item. |
| | 49 | Illegal buffer address. |
| | 50 | Buffer too small. |
| | 62 | DBG full. |
| | 63 | DBG disabled; potential damage; only DBCLOSE |
| | 68 | allowed. |
| | | DBB disabled. |
| | | |
----------------------------------------------------------------------------------------------
Appendix A contains more information about these conditions.
DBXBEGIN
INTRINSIC NUMBER 420. [REV BEG]
Designates the beginning of a sequence of TurboIMAGE/XL procedure calls
that are to be regarded as a dynamic transaction of a single database or
dynamic transaction spanning multiple databases (DMDBX) for the purposes
of logging and dynamic roll-back recovery.[REV END] The text parameter
can be used to log user information to the log file. DBXBEGIN is used in
conjunction with DBXEND to begin and end a dynamic transaction.
Syntax. [REV BEG]
DBXBEGIN, {base },text,mode,status,textlen
{baseidlist}
[REV END]
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]
baseidlist is the name of the integer array containing the
base IDs of the databases which are involved in a
DMDBX. Use baseidlist when calling DBXBEGIN mode 3
(DMDBX). The layout of this array is shown here
(each element is a halfword or two bytes):
Element Contents
1-2 Application program must set these two
halfwords to binary 0s before calling
DBXBEGIN. After returning to the calling
program, these two halfwords contain the
transaction ID. Use this same baseidlist
with the corresponding DBXEND or DBXUNDO
intrinsics.
3 Number of base IDs involved in the
DMDBX. This must be a number between 1
and 15 inclusive.
4-n Base IDs of the databases involved in
the DMDBX. Each base ID occupies one
half-word or 2 bytes and it is the first
halfword of the base parameter used to
call TurboIMAGE/XL intrinsics.
[REV END]
text is the name of an array up to 256 halfwords long
that contains user ASCII or binary data to be
written to the log file as part of the DBXBEGIN log
record. The text argument is used to assign each
particular transaction a distinct name. (Refer to
"Discussion" below for more information.)[REV BEG]
mode is an integer indicating the transaction type:
Mode 1: Indicates a dynamic
transaction which spans only
one database.
Mode 3: Indicates a dynamic
transaction spanning multiple
databases (DMDBX).[REV END]
If user logging is enabled
for the databases, mode 3
generates multiple entries in
the log file, one for each
database.
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:
Element Contents
1 If the procedure succeeds, the return
status is 0. Table 5-24 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.
textlen is an integer equal to the number of halfwords to
be logged from the text parameter, or is a negative
integer equal to the number of bytes. Length can
be zero.
Discussion.
DBXBEGIN is called to designate the beginning of a sequence of
TurboIMAGE/XL procedure calls that are jointly considered a single
dynamic transaction. The end of such a sequence is designated by a
matching call to DBXEND. DBXBEGIN cannot be called if another transaction
started by DBXBEGIN or DBBEGIN is active. The intrinsic does not begin a
dynamic transaction if AUTODEFER is enabled for the database.[REV BEG]
Before including a database in a DMDBX, DBXBEGIN mode 3, DBCONTROL mode 7
needs to have been done once for each of the databases in the DMDBX.
DBCONTROL mode 7 remains active until the database is closed or the
application terminates. DBCONTROL mode 7 also enables the database for
deadlock detection. If deadlock is encountered, it returns an error 26,
instead of triggering a process hang.
NOTE DBXBEGIN is not allowed with DBOPEN mode 2 nor with AUTODEFER
enabled.
[REV END]
Logging and DBRECOV are not needed with dynamic transactions, because the
database can be recovered dynamically. However, if the calling process
is logging, DBXBEGIN causes a record to be written to the log file to
identify the beginning of a dynamic transaction.
Table 5-24. DBXBEGIN Return Status Values
----------------------------------------------------------------------------------------------
| | | |
| File System, Memory | -4 | FREADLABEL error. |
| Management, and | -228 | DBXBEGIN encountered XM error nn when starting |
| Transaction Management | | dynamic transaction. |
| Failures: | | |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Calling Errors: | -11 | Bad database reference. |
| | -31 | Bad (unrecognized) DBXBEGIN mode: n. |
| | -139 | Invalid number of base IDs. |
| | -140 | Bad base ID list.[REV END] |
| | -151 | Text length greater than 512 bytes. |
| | -152 | DBXBEGIN called while a transaction is in progress. |
| | -217 | DBOPEN mode n incompatible with Dynamic Rollback. |
| | -218 | Output deferred not compatible with DBX. |
| | -219 | Remote database access incompatible with Dynamic |
| | | Rollback. |
| | -221 | Cannot begin transaction when a dynamic transaction |
| | | is active. |
| | -222 | Only DBXUNDO allowed when a dynamic transaction |
| | | encounters an error. |
| | -242[REV | Error in TurboGTX file operation. |
| | BEG] | |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Logging System Failures: | -111 | WRITELOG intrinsic failure. |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Exceptional Conditions: | 67 | DBU disabled; potential damage; only DBCLOSE |
| | -332 | allowed. |
| | | Error in QLOCK table operation. |
| | | |
----------------------------------------------------------------------------------------------
Consult appendix A for more information about these conditions.
DBXEND
INTRINSIC NUMBER 421.
Designates the end of a sequence of TurboIMAGE/XL procedure calls
regarded as a dynamic transaction for the purposes of logging and dynamic
roll-back recovery. The text parameter can be used to log user
information to the log file. DBXEND is used in conjunction with DBXBEGIN
to begin and end a dynamic transaction.
Syntax. [REV BEG]
DBXEND ,{base } text,mode,status,textlen
{baseidlist}
[REV END]
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]
baseidlist is the name of the integer array containing the
base IDs of the databases which are involved in the
DMDBX. Use the same baseidlist used with DBXBEGIN
when calling DBXEND mode 3 to end the DMDBX. The
layout of this array is same as in DBXBEGIN, except
that the transaction ID is already set in the first
two halfwords by DBXBEGIN.[REV END]
text is an array up to 256 halfwords long that contains
user ASCII or binary data to be written to the log
file as part of the DBXEND log record.[REV BEG]
mode must be a halfword equal to 1, 2 or 3.
Mode 1: End of dynamic transaction spanning one
database.
Mode 2: End of dynamic transaction spanning one
database, started with DBXBEGIN mode 1,
and write contents of the transaction
management (XM) logging buffer in memory
to disk. If logging is enabled, the
contents of the logging buffer in memory
will also be written to disk.
Mode 3: Indicates the end of a DMDBX started
with DBXBEGIN mode 3. If user logging
is enabled for the databases, mode 3
generates multiple entries in the log
file, one for each database in the
DMDBX, in order to mark the end of a
dynamic transaction.[REV END]
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 as follows:
Element Contents
1 If the procedure succeeds, the return
status is 0. Table 5-25 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.
textlen is an integer equal to the number of halfwords to
be logged from the text parameter, or is a negative
integer equal to the number of bytes. Length can
be zero.
Discussion.
DBXEND is called to designate the end of a sequence of TurboIMAGE/XL
procedure calls that are collectively considered a dynamic transaction.
If an intrinsic fails within a dynamic transaction, you may use DBXEND to
end the dynamic transaction at that point. The modifications completed
until that point will remain in the database(s). The beginning of such a
sequence is designated by a previous call to DBXBEGIN. DBXEND cannot be
called to end a transaction started by DBBEGIN.
Logging and DBRECOV are not needed with dynamic transactions, because the
database can be recovered dynamically. However, if the calling process
is logging, DBXEND causes a record to be written to the log file to
identify the end of a dynamic transaction.
If you call DBXEND with mode 2, DBXEND forces the XM log buffer (and user
log buffer if the process is logging) to be written from memory to disk
before returning to the calling process. Use this option only for
critical transactions; too many mode 2 DBXEND calls can degrade
performance by causing a disk access each time a dynamic transaction
ends.
DBXEND returns an error condition if it is called without a prior
matching call to DBXBEGIN. DBXEND is not necessary after a DBXUNDO.
Table 5-25. DBXEND Return Status Values
----------------------------------------------------------------------------------------------
| | | |
| File System, Memory | -213 | DBXEND encountered XM error nn when ending dynamic |
| Management, and | | transaction. |
| Transaction Management | | |
| Failures: | | |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Calling Errors: | -11 | Bad database reference. |
| | -31 | Bad (unrecognized) DBXEND mode: n. |
| | -140 | Bad baseid list. |
| | -151 | Text length greater than 512 bytes. |
| | -219 | Remote database access incompatible with Dynamic |
| | | Rollback. |
| | -222 | Only DBXUNDO allowed when a dynamic transaction |
| | | encounters an error. |
| | -223 | Cannot DBXEND or DBXUNDO a transaction which was |
| | | not active. |
| | -237 | Cannot DBXEND or DBXUNDO a DBBEGIN transaction. |
| | -238 | MDBX DBXBEGIN, DBXEND mode mismatch. |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Logging System Failures: | -111 | WRITELOG failure. |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| Exceptional Conditions: | 67 | DBU disabled; potential damage; only DBCLOSE |
| | -213 | allowed. |
| | -242 | XM error on DBXEND. |
| | -332 | Error in TurboGTX file operation. |
| | | Error in QLOCK table operation. |
| | | |
----------------------------------------------------------------------------------------------
Consult appendix A for more information about these conditions.