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 “Values Returned to status Parameter” 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
| |
"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 “File System Error Codes” 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.