Program Error Handling:

File Status Checking and On Size Error Checking

This article discusses two areas of COBOL error handling, one or both of which are relevant in the
majority of applications written using Micro Focus COBOL products. The information here applies to
all Micro Focus compiler products.

File Status Checking

Introduction

‘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, then the file status indicates the cause of the error. If you
have a file status data item defined for a file, then after every input/output operation on the file (OPEN,
CLOSE, READ, WRITE, REWRITE, START and DELETE) the run-time system updates it to indicate
how the operation completed.

Defining a file status data item is optional; if a file status data item is not declared and a serious file
error occurs, the COBOL run-time system displays an error message and aborts your program.
Defining a file status item, and then monitoring its value, allows you to determine your own actions
when errors occur.

You should, therefore, check the file status data item after each file I/O operation, to see if the
operation completed successfully. 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 data
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 data 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 data item, determine from it that
the disk is full, and take the appropriate action.

A file status item is declared in the SELECT…ASSIGN statement. The corresponding field is then
defined in the Working-Storage Section:

SELECT IN-FILE
ASSIGN TO "USER.DAT"
FILE STATUS IS WS-FILE-STATUS.
...
...
...
WORKING-STORAGE SECTION.
01 WS-FILE-STATUS PIC XX.

A separate data item can be used for each file or a single data item can be used for multiple files. It is
highly recommended that a separate data item be used for each file defined within a program.

File status codes can be one of two types: ANSI standard, or extended. The extended code will be
returned when more information is returned by the runtime system. (The Micro Focus documentation
gives full information on both types of codes.) The first byte of the file status data item is known as
status key 1 and indicates one of the following conditions upon completion of an I/O operation:

First byte Meaning

0 Successful operation
1 AT END
2 Invalid key
3 Permanent error
4 Logic error (an I-O operation has been executed out of sequence)
9 Extended file status code, returned by the runtime system.

Page 1 of 4
Program Error Handling:
File Status Checking and On Size Error Checking
If the first byte is in the range 0-4, then the second byte is an alphanumeric character. If, however, the
first byte is 9, then the second byte is a binary character. The second byte should therefore be
redefined, in case this binary view of the data is needed.

01 WS-FILE-STATUS
03 STATUS-KEY-1 PIC X.
03 STATUS-KEY-2 PIC X.
03 BINARY-STATUS
REDEFINES STATUS-KEY-2 PIC 99 COMP-X.

An example of file status checking

Below is some sample code, showing the use of file status for both ANSI and extended status codes.
The code tests for commonly encountered statuses.

SELECT INFILE ASSIGN TO "RECSEQ.DAT"

FILE STATUS IS WS-FILE-STATUS .
FILE SECTION .
FD INFILE .
01 RECSEQ-FD-RECORD PIC X(80).
WORKING-STORAGE SECTION .
01 WS-FILE-STATUS .
03 STATUS-KEY-1 PIC X .
03 STATUS-KEY-2 PIC X .
03 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"
PERFORM CHECK-EOF-STATUS
WHEN "2"
DISPLAY "INVALID KEY DETECTED"
PERFORM CHECK-INVALID-KEY-STATUS
WHEN "3"
DISPLAY "PERMANENT ERROR"
PERFORM CHECK-PERMANENT-ERROR-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 .

Page 2 of 4
Program Error Handling:
File Status Checking and On Size Error Checking
CHECK-INVALID-KEY-STATUS .
EVALUATE STATUS-KEY-2
WHEN "2"
DISPLAY "ATTEMPT TO WRITE DUPLICATE KEY"
WHEN "3"
DISPLAY "NO RECORD FOUND"
END-EVALUATE .

CHECK-PERMANENT-ERROR-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 004 DISPLAY "ILLEGAL FILE NAME SPECIFICATION”
WHEN 007 DISPLAY "DISK SPACE EXHAUSTED"
WHEN 010 DISPLAY "FILE NAME NOT SUPPLIED”
WHEN 012 DISPLAY "ATTEMPT TO OPEN AN ALREADY OPEN FILE”
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 125 DISPLAY "FILE/RECORD LOCK TIME OUT”
WHEN 146 DISPLAY "NO CURRENT RECORD "
WHEN 147 DISPLAY "WRONG OPEN OR ACCESS MODE FOR READ/START”
WHEN 148 DISPLAY "WRONG OPEN MODE FOR WRITE”
WHEN 151 DISPLAY "RANDOM READ ON A SEQUENTIAL FILE”
WHEN 180 DISPLAY "FILE MALFORMED "
WHEN 208 DISPLAY "NETWORK ERROR "
WHEN 213 DISPLAY "TOO MANY LOCKS "
WHEN OTHER
DISPLAY "UNEXPECTED STATUS "
DISPLAY BINARY-STATUS
END-EVALUATE .

File status checking will never be seen as one of the more exciting aspects of COBOL coding.
However, it is a very useful way of spotting and dealing with file handling errors. Furthermore, as the
code needed is essentially generic, it can be copied and pasted into different programs with little
alteration.

Page 3 of 4
Program Error Handling:
File Status Checking and On Size Error Checking

On Size Error Checking

The ON SIZE ERROR clause is well known, but rarely used, as it is normally assumed that the picture
of data items used in arithmetic calculations will be large enough to cope with any possible results.
There are good reasons for using the clause, however:

(1) Through human error, the data items may simply not be large enough to cope with every possible
value. For example, many programmers believe that a PIC 9(6) will hold the value of one million.
(2) Although it is normally assumed that a SIZE ERROR can only occur on the final result of a
calculation, it can also happen with intermediate results when using the verbs DIVIDE and
MULTIPLY, and also possibly COMPUTE.
(3) Division by zero will also trigger a SIZE ERROR condition. If there is the slightest possibility that a
divisor is zero, then this must be catered for.

The clause can be added to any arithmetic statement. For example:

ADD IN-SALES(WEEK-SUB) TO WS-SALES-TOTAL

ON SIZE ERROR DISPLAY “SALES TOTAL NOT LARGE ENOUGH”
STOP RUN
END-ADD .

If a SIZE ERROR condition occurs, and there is no ON SIZE ERROR clause, then the results of the
calculation are undefined. In the past, Micro Focus customers have queried this, assuming that the
result will be truncated in a predictable way, but this assumption is not correct.

Note: Using the On Size Error statement will have a slight effect on the performance of the individual
statements on which it is used, as additional error checking will be executed. The trade off in performance vs
the additional error checking will need to be evaluated to determine which best suits your individual application
performance and functionality targets.

Conclusion
The topics discussed in this document are unglamorous, but extremely useful. Using the FILE
STATUS clause to monitor the success of file access, and ON SIZE ERROR to ensure that all
calculations are accurate, can protect you against these easily avoidable errors.

Page 4 of 4