This chapter explains what file status is and how you can use it in your programs. See the chapter File Status Code Tables for a list of all the file status codes that can be returned.
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.
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 |
Condition |
|---|---|
| 0 | Successful operation |
| 1 | AT END |
| 2 | Invalid Key |
| 3 | Permanent Error |
| 4 | Logic Error (improper sequence of I/O operations) |
| 9 | 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 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.
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 environment division. 000020 input-output section. 000030 file-control. 000040 select file1 000050 assign "tst.fil" 000060 status is file1-stat. 000070 data division. 000080 file section. 000090 fd file1. 000100 01 f1-rec pic x(80)
000110 working-storage section. 000120 01 file1-stat. 000130 03 s1 pic x. 000140 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.
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-mf-error-message.
Of course, in your own program, you need to process these errors, not simply display them.
The demo directory below your COBOL system installation directory contains a suite of programs that show how an on-line stock control system can run on a network:
mudemo.cbl
stockin.cbl
stockout.cbl
stockioa.cbl
stockiom.cbl
These programs perform extensive file status checking.
This COBOL system supports a number of file status conventions. Each convention has a separate set of codes defined, although there is some overlap. The conventions supported are:
If you compile your program with the directive NOANS85, then ANSI'74 file status codes are produced. If you do not specify NOANS85 when compiling, then ANSI'85 file status codes are produced. If you want to use ANSI'85 syntax, but have ANSI'74 file status codes, replace the NOANS85 directive with ANS85"SYNTAX".
If you are using the standard system loaded for ANSI'85 operation, then ANSI'85 codes are produced by default.
If you are not using the Callable File Handler, you can compile your program with the directives MS"2" and NOANS85 in order to display Microsoft COBOL V2 file status codes. If you do not specify NOANS85 when compiling, then ANSI'85 file status codes are produced. If you want to use ANSI'85 syntax, but have Microsoft COBOL V2 file status codes replace the NOANS85 directive with ANS85(SYNTAX).
16-bit:
On the 16-bit system, a conversion routine,
Rmstat, is available to
convert file status codes to RM/COBOL values. This is invoked by setting the
environment variable COBFSTATCONV
to the value RMSTAT and compiling your program with the COBFSTATCONV directive.
This converts all status values on indexed files. If sequential and relative
files also need to be converted, you must set the CALLFH Compiler directive.
32-bit:
By default on 32-bit systems, when the Q
run-time switch is set, file I/O errors with a value of 9 in the first byte are
mapped onto RM/COBOL file status 9 codes. You can change this by altering the
alternate file status table. See the section Alternate File Status Table
later in this chapter for details.
16-bit:
On the 16-bit system, a conversion routine,
Hoststat, is available to convert file status codes to IBM mainframe values.
This is invoked by setting the environment variable COBFSTATCONV
to the value HOSTSTAT and compiling the program with the COBFSTATCONV
directive. This converts all status values on indexed files. If sequential and
relative files also need to be converted, then the CALLFH
Compiler directive must be set when compiling the source.
IBM mainframe 9<x> file status codes (see your "Mainframe Programmer's Guide" for details) are within the range 90 to 99 where the second byte <x> is a single alphanumeric character. Micro Focus extended file status codes have the character 9 as the first byte and the second byte is a binary value equivalent to a run-time error number. If you do not specify a file status data item for a file, file errors with a first byte value of 9 result in display of a run-time error message. If you are using HOSTSTAT, therefore, you must ensure that a file status data item is defined within your program, otherwise, on receipt of a 9<x> file status, the run-time system assumes this is an extended file status code, treats the second byte as a binary value and displays an invalid run-time error message. You should also ensure that your own code treats the second byte of file status codes beginning with the character 9 as a single alphanumeric character and not as a binary value.
The
ANSI'74 and ANSI'85 file status conventions described above are augmented with
more detailed extended file status codes. Extended file status codes have the
character "9" in the first byte. The second byte is a binary (COMP-X)
number, which is equivalent to a run-time error number. These are written as
9/nnn where nnn is the binary number in the second byte.
For example, if you are writing a file to disk and the disk runs out of space, the ANSI'74 file status would be a "30", which translates into the error message:
Permanent error - no other information is available
This is a very general error message; a "permanent error" could mean that the disk has failed, or that the disk drive door is open. So, rather than return a generic file status, this COBOL system returns an extended file status of 9/007 (that is, the character, "9", in the first byte, and binary 7 in the second) meaning "disk full".
When using ANSI'74 or ANSI'85 file status codes, the run-time system returns extended status codes if the extended file status is more specific than what would normally be returned.
The following example demonstrates how to redefine a "standard" file status so that it can be used as an extended file status.
Assume for this example that the input file does not exist. When the OPEN INPUT statement is executed, a file status of 9/013 is returned meaning "file not found".
select in-file assign to ... . . . file status is ans74-file-status. working-storage section. 01 ans74-file-status. 05 ans74-status-key-1 pic x. 05 ans74-status-key-2 pic x. 05 ans74-status-key-2-binary redefines ans74-status-key-2 pic 99 comp-x.
procedure division. open input in-file if ans74-file-status not = "00" if ans74-status-key-1 = "9" if ans74-status-key-2-binary = 13 display "File not found" . . . . . .
If you want to display the extended file status, you need to move the second byte of the file status to a display field that is large enough to hold a maximum value of 255:
select in-file assign to ... . . . file status is ans74-file-status. working-storage section. 01 ans74-file-status. 05 ans74-status-key-1 pic x. 05 ans74-status-key-2 pic x. 05 ans74-status-key-2-binary redefines ans74-status-key-2 pic 99 comp-x.
01 display-ext-status 05 filler pic xx value "9/" 05 display-key 2 pic 999
procedure division. open input in-file
if ans74-file-status not = "00"
display "Error. File status ="
with no advancing
if ans74-status-key-1 = "9"
move ans74-status-key-2-binary to
display-key-2
display display-ext-status
else
display ans74-file-status
end-if
. . . . . .
If you are using the Callable File Handler, you can supply a COBOL routine that is called automatically to convert file status codes before they are returned to your program. The sections that follow describe how to implement such a conversion program.
If you are using the 16-bit COBOL system, you can enable the conversion routine by setting the COBFSTATCONV environment variable.
Before setting COBFSTATCONV you must compile your program with the CALLFH and COBFSTATCONV directives set.
The Callable File Handler calls the program specified by the COBFSTATCONV environment variable on every operation before returning to the calling program.
The programs RMSTAT and HOSTSTAT are supplied to provide RM/COBOL and IBM mainframe status codes.
Example
set cobfstatconv=rmstat
set cobfstatconv=usrstat
The file status conversion routine is a callable program that expects a single parameter, the FCD (the first two bytes of this are the file status). The Callable File Handler passes the file status in this parameter (see the chapter Callable File Handler for further information). The routine performs whatever conversion is required and returns the converted file status in the same parameter.
Examples of COBOL file status conversion routines are supplied with this COBOL system. One is shown below and can be used as the basis for your conversion.
COBOL Example
*****************MODULE XFHCONV.CBL****************
* This module is used to convert file statuses to
* different values from those supplied by the
* Callable File Handler ExtFH. The code below can
* be used as a basis for customized conversion
* routines.
***************************************************
linkage section.
01 fcd-parameter.
copy "xfhfcd.cpy".
procedure division using fcd-parameter.
* Example of status conversion; converting status
* 9/90 to 8/9.
evaluate fcd-status-key1
when 9
evaluate fcd-binary
when 90
move 8 to status-key-1
move 9 to status-key-2
end evaluate
end evaluate
exit program.
On 32-bit systems, you can convert all extended file status codes before they are returned to your program by setting the Q run-time switch.
If you set the Q run-time switch, all extended file status codes reported in your code are mapped, using an internal RTS table, to a status that conforms to the status codes returned in the COBOL dialect of your choice. You can configure the COBOL dialect that you want to use. Any undefined or unrecognized status values are mapped onto status "30", permanent I/O error.
UNIX:
On UNIX, a C source file is supplied,
filestat.c, which contains tables of the file status values defined by
ANSI '74 and ANSI '85 standards. We recommend that you do not change these
tables in any way.
However, this file also contains a table giving an alternate set of extended file status codes. You can alter this table if you want to. By default, this alternate set of error numbers is output by RM/COBOL.
If you want this COBOL system to output error messages from this list, rather than from its standard list of run-time error messages, you must either:
The C source file, filestat.c, containing the alternate file status tables is stored in $COBDIR/src. If you want to alter the default table of alternate file status codes to a set of values which conform to the status codes returned in the COBOL dialect of your choice, you must index the table using the second byte of any status 9 items. The table entry then contains the new value for that file status in Binary Coded Decimal (BCD) format. Any undefined or unrecognized status values are mapped onto status 30 "permanent I/O error".
Once you have altered the table, you must rebuild the run-time system so that it uses your altered version of filestat.c rather than the original version. You can do this either globally or individually for each run-time system.
To globally rebuild the run-time system so that it uses your altered version of filestat.c:
cc -c filestat.c
As any further run-time systems that you build will use the new version of filestat.c, we recommend that you keep a copy of the original version.
ar rv $COBDIR/coblib/libcobol.a filestat.o
cd $COBDIR/SRC/RTS mkrts
Note: If your COBOL system uses shared object libraries, you cannot replace filestat.o as described in step 2. Instead, you must link in your new version of filestat.o by specifying it on the command line in step 3 as follows:
mkrts filestat.o
You can use the cob command to rebuild a single run-time system so that it uses your altered version of fil estat.c:
If you have not already compiled filestat.c, enter:
cob -o rts32 filestat.c -e ""
If you have compiled filestat.c, enter:
cob -o rts32 filestat.o -e ""
As usual, you can include any COBOL or C programs or other object modules in the command line.
Copyright © 2002 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.