FILE STATUS clause

The FILE STATUS clause monitors the execution of each input-output operation for the file.

When the FILE STATUS clause is specified, the system moves a value into the file status key data item after each input-output operation that explicitly or implicitly refers to this file. The value indicates the status of execution of the statement. (See the file status key description under Common processing facilities.)

data-name-1
The file status key data item can be defined in the WORKING-STORAGE, LOCAL-STORAGE, or LINKAGE SECTION as one of the following items:
  • A two-character data item of category alphanumeric
  • A two-character data item of category national
  • A two-digit data item of category numeric with usage DISPLAY or NATIONAL (an external decimal data item)

data-name-1 must not contain the PICTURE symbol 'P'.

data-name-1 can be qualified.

The file status key data item must not be variably located; that is, the data item cannot follow a data item that contains an OCCURS DEPENDING ON clause.

data-name-8
Must be defined as an alphanumeric group item of 6 bytes in the WORKING-STORAGE SECTION or LINKAGE SECTION of the DATA DIVISION.

Specify data-name-8 only if the file is a VSAM file (that is, ESDS, KSDS, RRDS).

data-name-8 holds the 6-byte VSAM return code, which is composed as follows:

  • The first 2 bytes of data-name-8 contain the VSAM return code in binary format. The value for this code is defined (by VSAM) as 0, 8, or 12.
  • The next 2 bytes of data-name-8 contain the VSAM function code in binary format. The value for this code is defined (by VSAM) as 0, 1, 2, 3, 4, or 5.
  • The last 2 bytes of data-name-8 contain the VSAM feedback code in binary format. The code value is 0 through 255.

If VSAM returns a nonzero return code, data-name-8 is set.

If FILE STATUS is returned without having called VSAM, data-name-8 is zero.

If data-name-1 is set to zero, the content of data-name-8 is undefined. VSAM status return code information is available without transformation in the currently defined COBOL FILE STATUS code. User identification and handling of exception conditions are allowed at the same level as that defined by VSAM.

Function code and feedback code are set if and only if the return code is set to a nonzero value. If they are referenced when the return code is set to zero, the contents of the fields are not dependable.

Values in the return code, function code, and feedback code fields are defined by VSAM. There are no COBOL additions, deletions, or modifications to the VSAM definitions.

For more information, see DFSMS Macro Instructions for Data Sets.