HP 3000 Manuals HP 3000 Manuals
DBEXPLAIN
INTRINSIC NUMBER 418
Prints a multiline message on the $STDLIST device describing a
TurboIMAGE/XL procedure call and explaining 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.
Table 5-11. DBEXPLAIN Message Format
--------------------------------------------------------------------------------------------
| | |
| Line | Format |
| | |
--------------------------------------------------------------------------------------------
| | |
| 1 | (a blank line) |
| | |
| | |
| | |
| 2 | |
| | TurboIMAGE { ERROR } [ AT offset] RETURN STATUS=retstat |
| | { RESULT} |
| | |
| | |
| 3 | |
| | { intrinsicname,MODE x,ON [ setname OF] basename} |
| | { [ ;PASSWORD=password] } |
| | { TurboIMAGE CALL INFORMATION NOT AVAILABLE } |
| | |
| | |
| 4 | |
| | { message } |
| | { UNRECOGNIZED RETURN STATUS: retstat} |
| | |
| | |
| 5 | |
| | [ HEX DUMP OF STATUS ARRAY FOLLOWS ] |
| | [ OCTAL DUMP OF STATUS ARRAY FOLLOWS] |
| | |
| | |
| 6 | |
| | [ hex display ] |
| | [ octal display] |
| 7 | (a blank line) |
| | |
--------------------------------------------------------------------------------------------
| | |
| Parameter | Explanation |
| | |
--------------------------------------------------------------------------------------------
| | |
| offset | The code offset of the TurboIMAGE/XL procedure call in a CM |
| | procedure. It is the virtual memory address of the TurboIMAGE/XL |
| | procedure call in a NM procedure. |
| | |
| retstat | The return status (from the first element of status) printed as a |
| | decimal integer and corresponding to the return statuses described in |
| | appendix A. |
| | |
| intrinsicname | The name of the TurboIMAGE/XL library procedure (intrinsic) which was |
| | called and which sets the contents of the status array. |
| | |
| x | The value of the mode parameter as a decimal integer. |
| | |
| setname | The value of the second parameter, usually a data set name or number, |
| | as passed to the procedure which set the status array contents. The |
| | second parameter can be a data item name or number if the procedure |
| | in question is DBINFO. If the procedure is DBOPEN, DBLOCK, DBUNLOCK, |
| | or certain modes of DBINFO or DBCLOSE, setname is omitted. |
| | |
| password | The word printed at the end of line 3 only if the error relates to |
| | the password parameter of DBOPEN. |
| | |
| basename | The database specified in the procedure which was called and set the |
| | status array contents. |
| | |
--------------------------------------------------------------------------------------------
Table 5-10. DBEXPLAIN Message Format (Continued)
--------------------------------------------------------------------------------------------
| | |
| Parameter | Explanation |
| | |
--------------------------------------------------------------------------------------------
| | |
| message | A description of the result based on the condition word and other |
| | status array information. The message is generated by the DBERROR |
| | procedure which is also described in this chapter. See Table 5-9 for |
| | all possible messages returned in line 4. |
| | |
| hex display | A listing of each halfword of status printed as a string of 4 hex |
| | digits. Adjacent status elements are separated by a blank and the |
| | entire line is 49 characters long. The hex display is generated for |
| | NM applications only. |
| | |
| octal display | A listing of each halfword of status printed as a string of 6 octal |
| | digits. Adjacent status elements are separated by a blank and the |
| | entire line is 49 characters long. The octal display is generated |
| | for CM applications only. |
| | |
--------------------------------------------------------------------------------------------
Figure 5-1 contains four examples of messages generated by DBEXPLAIN
for a Native Mode application.
________________________________________________________________________________
| |
| TURBOIMAGE RESULT AT $0001d76c: RETURN STATUS=0 DBOPEN=intrinsic name |
| DBOPEN,MODE1, ON ORDERS ORDERS=database name |
| SUCCESSFUL EXECUTION - NO ERROR NO ERROR=message |
| |
| TURBOIMAGE ERROR AT $0001d76c: RETURN STATUS=-12 |
| DBPUT,MODE1, ON DATE-MASTER OF ORDERS DATE-MASTER=data set name|
| DBPUT CALLED WITHOUT COVERING LOCK IN EFFECT |
| |
| TURBOIMAGE RESULT AT $0001d76c: RETURN STATUS=16 |
| DBPUT,MODE1, ON #1 OF ORDERS #1=data set number |
| THE DATA SET IS FULL |
| |
| TURBOIMAGE RESULT: RETURN STATUS=4792 |
| TURBOIMAGE CALL INFORMATION NOT AVAILABLE |
| UNRECOGNIZED RETURN STATUS: 4792 |
| HEX DUMP OF STATUS ARRAY FOLLOWS: |
| 12b8 0040 0c63 ff82 4d33 02a7 32e8 0000 0000 0000 |
| ...............hex display................... |
________________________________________________________________________________
Figure 5-1. Sample DBEXPLAIN Messages
Because the application is in Native Mode, the display is in hex. For
Compatibility Mode applications, the display is in octal.