HPlogo Using KSAM XL and KSAM 64 > Appendix A COBOL Intrinsics

Status Parameter

MPE documents

Complete PDF
Table of Contents
Index

E0300 Edition 4 ♥
E0394 Edition 3

The status parameter is a two-character item to which the status of the input/output operation is returned. It is always the second parameter in a KSAM procedure call. The status parameter must be defined in the WORKING-STORAGE SECTION of the COBOL program.

Status consists of two separate characters: the left character is known as status-key-1, and the right is known as status-key-2. 

  /---left character----\/----right character-----\
  |----------------------|------------------------|
  |                      |                        |
  |  "status-key-1       |     "status-key-2"     |<---status word
  |----------------------|------------------------|
Combining status-key-1 with status-key-2, the following values may be returned to the status parameter as a whole:
00

Successful completion —

The current input/output operation was completed successfully; no duplicate keys were read or written.

02

Successful completion; Duplicate key —

For a CKREAD or a CKREADBYKEY call, the current alternate key has the same value as the equivalent key in the sequentially following record; duplicate keys are allowed for the key. For a CKWRITE or CKREWRITE call, the record just written created a duplicate key value for at least one alternate key for which duplicates are allowed.

10

At End condition —

In a sequential read using CKREAD, no next logical record was in the file.

21

Invalid key; Sequence error —

A call to CKWRITE attempted to write a record with a key that is not in sequentially ascending order, to a file opened for sequential access.

A call to CKREWRITE was attempted but the primary key value was changed by the program since the previous successful call to CKREAD.

22

Invalid key; Duplicate key —

An attempt was made to write or rewrite a record with CKWRITE or CKREWRITE and the record would create a duplicate key value for a key where duplicates are prohibited.

23

Invalid key; No record found —

An attempt was made with CKSTART or CKREADBYKEY to access a record identified by key, but no record is found with the specified key value at the specified location.

24

Invalid key; Boundary violation —

An attempt was made with a call to CKWRITE to write past the externally defined boundaries of the file; that is, to write past the end-of-file.

30

Lock denied —

An attempt was made to lock a file already locked by another process; or file was not opened with dynamic locking allowed.

31

Unlock denied —

An attempt was made to unlock a file with CKUNLOCK, but the file had not been locked by CKLOCK.

9n

File system error —

A call to an input/output procedure was unsuccessful as a result of a file system error, not one of the error conditions defined for the other status values. The value of status-key-2 (n) is a binary number between 0 and 255 that corresponds to an MPE file system error code. To convert this binary value to numeric display format, call the CKERROR routine.

The value of status can be tested as a whole, or the two characters can be tested separately as status-key-1 and status-key-2. In any case, the status of each call should be tested immediately following execution of the call. Unless the first character of status = 0, the call was not successful.

For example, a sample status parameter definition might be: 

  WORKING-STORAGE SECTION.
  .
  .
  .
  01 STAT.
     02 STATUS-KEY-1 PIC X.
     02 STATUS-KEY-2 PIC X.
These items can then be referenced in the PROCEDURE DIVISION. For example: to test only the first character: 

  IF STATUS-KEY-1 NOT = "0" THEN
    GO TO "ERROR-ROUTINE".
To test the entire status word: 

  IF STAT = "23" THEN
     DISPLAY "RECORD NOT FOUND".
Note that the word STATUS is reserved.



Filetable Parameter

KSAM Logical Record Pointer