PreviousCOBOL File Organizations Sorting FilesNext"

Chapter 4: Using File Status

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.

4.1 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.


4.2 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
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 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.

4.3 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 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.

4.4 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-mf-error-message.

Of course, in your own program, you need to process these errors, not simply display them.

4.4.1 Sample Programs

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.

4.5 File Status Conventions

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:

4.5.1 ANSI'74 File Status

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".

4.5.2 ANSI'85 File Status

If you are using the standard system loaded for ANSI'85 operation, then ANSI'85 codes are produced by default.

4.5.3 Microsoft COBOL V2 File Status

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).

4.5.4 RM/COBOL File Status

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.

4.5.5 IBM Mainframe Status Codes

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.

4.5.6 Extended File Status

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
             . . .           . . .

4.6 File Status Conversion

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.

4.6.1 File Status Conversion on the 16-bit System

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

4.6.1.1 Form of the Conversion Routine

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.

4.6.1.2 Writing a COBOL File Status Conversion Routine

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.

4.6.2 File Status Conversion on 32-bit Systems

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.

4.6.2.1 Alternate File Status Table

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.

4.6.2.1.1 Globally Altering File Status Values

To globally rebuild the run-time system so that it uses your altered version of filestat.c:

  1. Compile your new version of the module by entering the command:
    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.

  2. Replace filestat.o in the COBOL library by entering:
    ar rv $COBDIR/coblib/libcobol.a filestat.o

  3. Rebuild the run-time system using the mkrts script supplied in $COBDIR/SRC/RTS. For example:
    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


4.6.2.1.2 Altering File Status Values for Individual Run-time Systems

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 © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousCOBOL File Organizations Sorting FilesNext"