PreviousFilenames Sharing FilesNext

Chapter 4: File Status

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

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

4.2 Defining a File Status Data-item

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.

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

The conventions supported are:

4.3.1 ANSI'85 File Status

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

4.3.2 ANSI'74 File Status

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

4.3.3 File Status Conversions

For emulation purposes, you can arrange to return file status codes other than ANSI'85 and ANSI'74. To do so:

  1. Use the CONVERTSTATUS parameter to specify the name of a program that is called to map returned status values. The program name depends upon the type of compiler:

    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.

  2. If creating a linked application, link an object into the application. The object that you link depends upon the compiler:

    Compiler
    Object
    Ryan MacFarland COBOL rmstat.obj
    IBM Mainframe COBOL hoststat.obj
    Microsoft COBOL V2 msstat.obj

  3. When compiling, use the following compiler directives:


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


4.4 Extended File Status Codes

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.

PreviousFilenames Sharing FilesNext