| Filenames | Sharing Files | |
File status codes are used by this COBOL system to indicate the success, or otherwise, of any file operation carried out by your program.
A full list of file status codes is given in the Net Express online help. (Click Help Topics on the Help menu. Then, on the Index tab, double-click 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, file status indicates the cause of the error.
If you have a file status data-item defined for a file, 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.
You should check the file status data-item after each input/output 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.
Each file in a program can have a file status data-item associated with it by specifying FILE STATUS IS in the SELECT statement for the file and defining the file status data-item 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.
File status is a two-byte code. For all file status conventions, except extended file status codes, the data-item is defined as two alphanumeric characters (PIC XX). For extended file status codes, the second byte contains a binary number.
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:
| 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) is an alphanumeric character.
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.
The example code that follows illustrates how file status checking is performed: first the first byte (status key 1) is interrogated; then, if more information is required, the second byte (status key 2) is interrogated.
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.
This COBOL system supports a number of file status conventions. Each convention has a separate set of codes defined, although there is some overlap between conventions.
The conventions supported are:
If you are using the standard system loaded for ANSI'85 operation, ANSI'85 file status codes are produced by default.
If you compile your program with the Compiler directive NOANS85, ANSI'74 file status codes are produced.
If you need to use ANSI'85 syntax, but have ANSI'74 file status codes then replace the NOANS85 directive with ANS85"SYNTAX".
For emulation purposes, you can arrange to return file status codes other than ANSI'85 and ANSI'74. To do so:
| Compiler |
CONVERTSTATUS= |
|---|---|
| Ryan MacFarland COBOL | rmstat |
| IBM Mainframe COBOL | hoststat |
| Microsoft COBOL V2 | msstat |
You can add the CONVERTSTATUS parameter to the File Handler configuration file extfh.cfg. For more information, see the chapter File Handler Configuration.
| Compiler |
Object |
|---|---|
| Ryan MacFarland COBOL | rmstat.obj |
| IBM Mainframe COBOL | hoststat.obj |
| Microsoft COBOL V2 | msstat.obj |
Note: A list of Microsoft COBOL V2 file status codes is given in the Net Express online help. (Click Help Topics on the Help menu. Then, on the Contents tab, click Reference, File Handling, File Status.)
The ANSI'74 and ANSI'85 file status conventions are augmented with extended file status codes. Extended file status codes have the character "9" as the first byte of the file status. The second byte is a binary (COMP-X) number, which is equivalent to a run-time system error number.
Extended file status codes 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 error message is very general; 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 the binary value 7 in the second, meaning "disk full".
When using ANSI'74 or ANSI'85 file status codes, the run-time system returns extended file status codes if the extended file status code is more specific.
A full list of extended file status codes is given in the Net Express online help. (Click Help Topics on the Help menu. Then, on the Contents tab, click Reference, File Handling, File Status.)
The example code that follows illustrates 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 ("File not found") is returned.
select in-file
assign to "user.dat".
file status is file-status.
…
working-storage section.
01 file-status.
05 status-key-1 pic x.
05 status-key-2 pic x.
05 status-key-2-binary redefines status-key-2 pic 99 comp-x.
…
procedure division.
open input in-file
if file-status not = "00"
if status-key-1 = "9"
if status-key-2-binary = 13
display "File not found"
…
To display the extended file status code, move the second byte of the file status data item to a display field large enough to hold the maximum value 255:
select in-file
assign to "user.dat"
file status is file-status.
…
working-storage section.
01 ans74-file-status.
05 status-key-1 pic x.
05 status-key-2 pic x.
05 status-key-2-binary redefines 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 file-status not = "00"
display "Error. File status =" with no advancing
if status-key-1 = "9"
move status-key-2-binary to display-key-2
display display-ext-status
else
display file-status
end-if
Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Filenames | Sharing Files | |