Using file status keys

After each input or output statement is performed on a file, the system updates values in the two digit positions of the file status key. In general, a zero in the first position indicates a successful operation, and a zero in both positions means that nothing abnormal occurred.

Establish a file status key by coding:

  • The FILE STATUS clause in the FILE-CONTROL paragraph:
    FILE STATUS IS data-name-1
  • Data definitions in the DATA DIVISION (WORKING-STORAGE, LOCAL-STORAGE, or LINKAGE SECTION), for example:
    01  data-name-1  PIC 9(2)  USAGE NATIONAL.

Specify the file status key data-name-1 as a two-character category alphanumeric or category national item, or as a two-digit zoned decimal or national decimal item. This data-name-1 cannot be variably located.

Your program can check the file status key to discover whether an error occurred, and, if so, what type of error occurred. For example, suppose that a FILE STATUS clause is coded like this:


FS-CODE is used by COBOL to hold status information like this:

This image shows FS-CODE 21, where 2 is marked invalid key and 1 is marked sequence error.

Follow these rules for each file:

  • Define a different file status key for each file.

    Doing so means that you can determine the cause of a file input or output exception, such as an application logic error or a disk error.

  • Check the file status key after each input or output request.

    If the file status key contains a value other than 0, your program can issue an error message or can take action based on that value.

    You do not have to reset the file status key code, because it is set after each input or output attempt.

For VSAM files, you can additionally code a second identifier in the FILE STATUS clause to get more detailed information about VSAM input or output requests.

You can use the file status key alone or in conjunction with the INVALID KEY phrase, or to supplement the EXCEPTION or ERROR declarative. Using the file status key in this way gives you precise information about the results of each input or output operation.

Related references  
FILE STATUS clause (Enterprise COBOL for z/OS® Language Reference)  
File status key (Enterprise COBOL for z/OS Language Reference)