Using File Status

What is File Status?

File status is a two-byte code that indicates how a file operation completed; either successfully, or with some form of error. If an error occurs, the file status indicates the reason for the error. File status is a data item which you define in your program. Defining a file status data item is optional. If a file status data item is not declared and a file error occurs, the COBOL run-time system displays an error message and aborts your program. If you have a file status item defined for a file, then after every input/output operation on the file (that is, OPEN, CLOSE, READ, WRITE, REWRITE, START and DELETE) the run-time system updates it to indicate how the operation completed. After each operation, it is your responsibility to ensure that your program checks the file status to see if the operation completed satisfactorily. For example, when your program is writing to disk, there might not be enough disk space to complete the WRITE operation. If you have not defined a file status item and you run out of disk space, the run-time system displays an error number and aborts the program. If you have a file status item defined (for the file you are writing), it is updated and the program continues to run. The program can then check the file status, determine from it that the disk is full, and take the appropriate action.

Note: If you declare a USE procedure (in the Declarative section of your program) to handle I/O errors, the procedure is only executed if a file status is also defined for the file. The file status item is updated before the USE procedure is executed. See the Language Reference for more information about Declaratives and USE procedures.

Defining a File Status

Each file in a program can have a file status item attached to it by specifying the FILE STATUS clause in its file-control entry. A separate item can be used for each file's file status, or a single item can be used for the file status of several files. The data item to be used for the file status of a file is indicated in the SELECT clause of the File-Control paragraph for that file. The data item used for a file status is defined in the Working-Storage or Linkage Section. For all file status conventions, except extended file status codes, the data item is defined as two alphanumeric characters (that is PIC XX). Extended file status codes use the second byte as a binary (COMP-X) item. The first byte of the file status data item is known as status key 1 and indicates one of the following conditions:

Value 0 1 2 3 4 9

Condition Successful operation AT END Invalid Key Permanent Error Logic Error (improper sequence of I/O operations) COBOL run-time system error message

If the first byte of the file status data item is other than 9, the second byte (known as status key 2) should be treated as alphanumeric. The values and meanings of status key 2 are listed in the chapter File Status Code Tables. If the first byte of the file status data item is "9", the second byte is a binary field containing a Micro Focus defined RTS error code. These messages are listed and explained in your Error Messages. Example select in-file assign to.... . . . file status is ws-file-status. data division. file section. fd in-file.... . . . working-storage section. 01 ws-file-status pic xx.

Displaying File Status

If you want to display the second byte of an extended file status code with its correct decimal value, you need to redefine the file status data item to avoid truncation. The example program that follows illustrates one method of retrieving the value of the second byte of the file status for display purposes. Note how truncation has been avoided by redefining the second byte of the file status data item as PIC 99 COMP-X. 000010 000020 000030 000040 000050 000060 000070 000080 000090 000100 000110 000120 000130 000140 environment division. input-output section. file-control. select file1 assign "tst.fil" status is file1-stat. data division. file section. fd file1. 01 f1-rec pic x(80) working-storage section. 01 file1-stat. 03 s1 pic x. 03 s2 pic x.

000150 03 stat-bin redefines s2 pic 9(2) comp-x. 000160 01 disply-stat. 000170 03 s1-displ pic x. 000180 03 filler pic x(3). 000190 03 s2-displpic pic zz9. 000200 procedure division. 000210 start-test. 000220 open input file1 000230 move s1 to s1-displ 000240 if s1 not= 9 000250 move s2 to s2-displpic 000260 else 000270 move stat-bin to s2-displpic 000280 end-if 000290 display disply-stat 000300 stop run. If you have not specified a file status item in the SELECT clause of your program, file errors with a first byte value of 9 result in display of a run-time error.

Checking File Status

The example below demonstrates how to check file status. First, status-key-1 is interrogated; then, if more information about the error is required, status-key-2 is interrogated. The codes that are checked here represent some of the more common error codes. Example select recseq assign to "recseq.dat" file status is ws-file-status organization is record sequential. file section. fd recseq record contains 80 characters. 01 recseq-fd-record pic x(80). working-storage section. 01 ws-file-status. 05 status-key-1 pic x. 05 status-key-2 pic x. 05 binary-status redefines status-key-2 pic 99 comp-x. procedure division. . . . perform check-status. . . . check-status. evaluate status-key-1 when "0" next sentence when "1" display "end of file reached" perform check-eof-status when "2" display "invalid key" perform check-inv-key-status when "3" display "permanent error" perform check-perm-err-status

when "4" display "logic error" when "9" display "run-time-system error" perform check-mf-error-message end-evaluate. check-eof-status. if status-key-2 = "0" display "no next logical record" end-if. check-inv-key-status. evaluate status-key-2 when "2" display "attempt to write dup key" when "3" display "no record found" end-evaluate. check-perm-err-status. if status-key-2 = "5" display "file not found" end-if. check-mf-error-message. evaluate binary-status when 002 display "file not open" when 007 display "disk space exhausted" when 013 display "file not found" when 024 display "disk error " when 065 display "file locked " when 068 display "record locked " when 039 display "record inconsistent" when 146 display "no current record " when 180 display "file malformed " when 208 display "network error " when 213 display "too many locks " when other display "not error status " display binary-status end-evaluate. In the paragraph check-status, the value of status-key-1 is evaluated in order to determine whether status-key-2 should also be interrogated. Common run-time system errors are listed in the EVALUATE statement in the paragraph check-mferror-message. Of course, in your own program, you need to process these errors, not simply display them.