HP 3000 Manuals HP 3000 Manuals
STATUS PARAMETER
The status parameter is a four-character string variable to which the
status of the input-output operation is returned. It is the second
parameter in every KSAM procedure call except BKERROR, in which it is the
first parameter. The first character of the status string determines its
general type. The other three characters supply specific codes to
further define the status. The operation of a called procedure is
successful only if the first character returned in status is zero. Other
values returned to status indicate the reason an operation was not
successful. You can convert any status value to a printable message by
calling BKERROR. (Refer to Table 6-2 for possible status values).
Table 6-2. Values Returned to status Parameter
--------------------------------------------------------------------------------------------
| | |
| FIRST CHARACTER | REMAINING CHARACTERS |
| | |
--------------------------------------------------------------------------------------------
| | |
| "0" successful completion | "0" no further information |
| | "2" duplicate key value |
| | |
--------------------------------------------------------------------------------------------
| | |
| "1" at end or beginning of file | "0" no further information |
| | |
--------------------------------------------------------------------------------------------
| | |
| "2" invalid key | "1" sequence error |
| | "2" duplicate key error |
| | "3" no record found |
| | "4" boundary violation |
| | |
--------------------------------------------------------------------------------------------
| | |
| "7" request denied | "1" file already locked |
| | |
--------------------------------------------------------------------------------------------
| | |
| "8" invalid call | "1" invalid number of parameters |
| | "2" invalid parameter |
| | "3" insufficient space for data in |
| | |
| | parameterlist |
| | |
--------------------------------------------------------------------------------------------
| | |
| "9" file system error | "0" through "255" |
| | corresponding to file system error codes |
| | (Refer to complete list in Appendix A.) |
| | |
--------------------------------------------------------------------------------------------
Combining the two parts of the status code, the following values may be
returned to the status parameter:
if status="00" Successful completion--The current input-output
operation was completed successfully; no duplicate keys
read or written.
="02" Successful completion; Duplicate key--
* In a call to BKREAD or BKREADBYKEY, the current key
has the same value as the equivalent key in the next
sequential record; duplicate keys are allowed for
the key.
* In a call to BKWRITE or BKREWRITE, the record just
written created a duplicate key value for at least
one key for which duplicates are allowed.
="10" At end condition--A sequential read was attempted with
BKREAD and there was no next logical record in ascending
sequence according to the primary key value or the
current altemate key value. Or an attempt was made by
BKSTART or BKREADBYKEY to position to a record whose key
value was less than the lowest key value or higher than
the highest key value.
="21" Invalid key; Sequence error--
* In a call to BKWRITE for a file opened with sequence
checking, the record being written contains a
primary key that is less than a key in a previously
written record.
* In a call to BKREWRITE, the primary key value was
changed in the program since a successful execution
of BKREAD defined the record to be rewritten.
="22" Invalid key; Duplicate key error--An attempt was made to
write or rewrite a record with BKWRITE or BKREWRITE and
the record would create a duplicate key value in a key
for which duplicates are not allowed.
="23" Invalid key; No record found--An attempt was made to
locate a record by a key value with BKSTART or
BKREADBYKEY and the record cannot be found.
="24" Invalid key; Boundary violation--An attempt was made
with BKWRITE to write beyond the externally defined
boundaries of the file; that is, to write past the
end-of-file.
="71" Request denied; File already locked--An attempt was made
to lock a file with BKLOCK and the file is already
locked.
="81" Invalid call; Invalid number of parameters--Too many or
too few parameters were specified in the procedure call
just made.
="82" Invalid call; Invalid parameter--The specified parameter
is not the correct type. For example, a string variable
was selected where only a numeric variable or expression
is allowed.
="83" Invalid call; Insufficient internal buffer space--The
data specified in the parameterlist to be read or
written will not fit into the configured internal buffer
space. You may need to have certain operating system
parameters re-valued.
="9xxx" File system error--An MPE file system error occurred for
which the three-character value, xxx is the error code.
(Refer to Table A-1 for a list of these codes.) You can
call procedure BKERROR to convert the error code
returned here to a printable message.
The value of status can be tested as a whole, or the first character can
be tested separately from the remaining characters. For example:
10 DIM S$(4) <-------- dimension status string S$
.
. /-------------------- test first character only
50 IF S$(1;1) = "0" THEN PRINT "SUCCESS"
60 ELSE PRINT "ERRORCODE=";S$ <--------- print entire string
.
.
. /---------------------------- test first character
100 IF S$(1;1)= "9" THEN DO
110 PRINT "FILE ERROR=";S$(2)
120 DOEND \--------------------- print remaining characters
.
.
. /-------------------- test entire string
200 IFS$ = "22" THEN DO
210 PRINT "DUPLICATE KEY ERROR"
220 DOEND
300 IF S$(2)= "2" THEN PRINT "DUPLICATE KEY"
\------------------------ test only remaining characters
For any status value, you can call the BKERROR procedure and a message is
returned that gives the meaning of the status code. You can then print
this message rather than writing your own.