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

Chapter 5 175
TurboIMAGE/XL Library Procedures
DBEXPLAIN
DBEXPLAIN
INTRINSIC NUMBER 418
Prints a multiline message on the $STDLIST device which describes a TurboIMAGE/XL
procedure call and explains the call's results as recorded in the calling program's status
array.
Syntax
DBEXPLAIN, status
Parameters
status is the name of the array used as the status parameter in the
TurboIMAGE/XL procedure call about which information is requested.
NOTE The call to DBEXPLAIN must be made immediately after receiving an error
status before any other intrinsics are executed to ensure the display of valid
messages.
Discussion
Table 5-11. contains the general format for lines 2 through 6 of the message which is sent
to $STDLIST. Elements surrounded by brackets are sometimes omitted. Braces indicate
that only one of the choices shown will be printed. Lines 5 and 6 are printed only if, during
the preparation of lines 2, 3, and 4, TurboIMAGE/XL detects that the status array
contents are invalid, unrecognizable, or incomplete, or if a message must be truncated to
fit on a single line.
If the status array contents appear to be the result of something other than a
TurboIMAGE/XL procedure call or if the array is used by the called procedure for
information other than that discussed here, the second choice for line 3 is printed. This
would be the case for a successful call to DBGET which uses all 10 status elements to return
a return status, lengths, and record numbers.
If the status array contains an unrecognized error code, the second line 4 choice is printed.
If the return status is greater than or equal to zero, the word ERROR in line 2 is replaced
by RESULT because non-negative return statuses indicate success or exceptional
conditions, such as end-of-chain. Return status values are explained in appendix A.
You can use the offset information to locate the specific call statement that generated the
status array contents if the call is made with a programming language which enables you
to determine displacements of program statements or labels within the code. The identity
of the code segment is not printed because it cannot be determined by DBEXPLAIN.
Therefore, you need to be familiar with the program's functioning in order to locate the
correct call. The offset portion of line 2 is printed only if the status array appears to be set
by a TurboIMAGE/XL library procedure call and contains valid offset information.