I-O status

The status of each access operation performed on a file is stored by the runtime system in specific data items which can be assigned to every file in the program. These items, which are specified by using the FILE STATUS clause, provide information on

• whether the I-O operation was successful, and

• the type of any errors that may have occurred.

This data can be evaluated (by USE procedures in the DECLARATIVES, for example) and used by the program to analyze I-O errors. As an extension to Standard COBOL, COBOL2000 provides the option of including the keys of the DMS error messages in this analysis, thus allowing a finer differentiation between different causes of errors.

The FILE STATUS clause is specified in the FILE-CONTROL paragraph of the Environment Division. Its format is (see “COBOL2000 Reference Manual” [1]):

---

FILE STATUS IS data-name-1 [data-name-2]

---

where data-name-1 and data-name-2 (if specified) must be defined in the WORKING-STORAGE SECTION or the LINKAGE SECTION. The following rules apply with regard to the format and possible values for these two items:

data-name-1

• must be declared as a two-byte alphanumeric data item, e.g.

  01 data-name-1    PIC X(2).

• contains a two-character numeric status code following each access operation on the associated file. The table provided at the end of this section lists all such codes together with their meanings.

data-name-2

• must be declared as a 6-byte group item with the following format:

  01 data-name-2.
   02 data-name-2-1     PIC 9(2) COMP.
   02 data-name-2-2     PIC X(4).

• is used for storing the DMS error code for the relevant I-O status. Following each access operation on the associated file, data-name-2 contains a value that directly depends on the content of data-name-1. The relationship between the values is shown in the table below:

  Contents of data-name-1 not equal 0?	DMS code not equal 0?	Value of data-name-2-1	Value of data-name-2-2
  no	no	undefined	undefined
  yes	no	0	undefined
  yes	yes	64	DMS code of the associated error message

  The DMS codes and the associated error messages are given in “Introductory Guide to DMS” [4].

Caution

For line-sequential files, the only I-O status available is the one represented by data-name 1.

The status values and their meanings generally refer to record-sequential files. When line-sequential files are being processed, due consideration must be given to the peculiarities of line-sequential organization with regard to the interpretation of status values (see section "Line-sequential files").

I-O status	Meaning
	Execution successful
00	The I-O statement terminated normally. No further information regarding the I-O operation is available.
04	Record length conflict: A READ statement terminated normally. However, the length of the record read lies outside the limits defined in the record description entry for this file.
05	Successful execution of an OPEN INPUT/I-O/EXTEND on a file; however, the referenced file indicated by the OPTIONAL phrase was not present at the time the OPEN statement was executed.
07	Successful OPEN statement with NO REWIND clause on a file that is on a UNIT-RECORD medium. Successful CLOSE statement with NO REWIND, REEL/UNIT, or FOR REMOVAL clause on a file that is on a UNIT-RECORD medium.
	Execution unsuccessful: AT END condition
10	An attempt was made to execute a READ statement. However, no next logical record existed, because the end-of-file was encountered. A sequential READ statement with the OPTIONAL phrase was attempted for the first time on a nonexistent file.
	Execution unsuccessful: unrecoverable error
30	No further information regarding the I-O operation is available (the DMS code provides further information). During line-sequential processing: access to a PLAM element was unsuccessful
34	An attempt was made to write outside the sequential file boundaries set by the system.
35	An OPEN statement with the INPUT/I-O phrase was attempted on a nonexistent file.
37	OPEN statement on a file that cannot be opened in any of the following ways: OPEN OUTPUT/I-O/EXTEND on a write-protected file (password, RETENTION-PERIOD, ACCESS=READ in catalog) OPEN I-O on a tape file OPEN INPUT on a read-protected file (password)
38	An attempt was made to execute an OPEN statement for a file previously closed with the LOCK phrase.
39	The OPEN statement was unsuccessful as a result of one of the following conditions: One or more of the operands ACCESS-METHOD, RECORD-FORMAT or RECORD-SIZE were specified in the ADD-FILE-LINK command with values deviating from the corresponding explicit or implicit program specifications. Record length errors occurred for input files (catalog check if RECFORM=F). The record size is greater than the BLKSIZE entry in the catalog (in the case of input files). The catalog entry of one of the FCBTYPE, RECFORM or RECSIZE (if RECFORM=F) operands for an input file is in conflict with the corresponding explicit or implicit program specifications or with the specifications in the ADD-FILE-LINK command.
	Execution unsuccessful: logical error
41	An attempt was made to execute an OPEN statement for a file which was already open.
42	An attempt was made to execute a CLOSE statement for a file which was not open.
43	While accessing a disk file opened with OPEN I-O, the most recent I-O statement executed prior to a REWRITE statement was not a successfully executed READ statement.
44	Boundary violation: An attempt was made to execute a WRITE statement. However, the length of the record is outside the range allowed for this file. An attempt was made to execute a REWRITE statement. However, the record to be rewritten did not have the same length as the record to be replaced.
46	An attempt was made to execute a READ statement for a file in INPUT or I-O mode. However, there is no valid next record since: the preceding READ statement was unsuccessful without causing an AT END condition the preceding READ statement resulted in an AT END condition.
47	An attempt was made to execute a READ statement for a file not in INPUT or I-O mode.
48	An attempt was made to execute a WRITE statement for a file not in OUTPUT or EXTEND mode.
49	An attempt was made to execute a REWRITE statement for a file not open in I-O mode.
	Other conditions with unsuccessful execution
90	System error; no further information available regarding the cause.
91	System error; a system call terminated abnormally; either an OPEN error or no free device; the actual cause is evident from the DMS code (see “FILE STATUS clause”)
95	Incompatibility between values specified in the BLOCK-CONTROL-INFO or  BUFFER-LENGTH operand of the ADD-FILE-LINK command and the file format, block size, or the format of the used volume.

Table 24: I-O status for sequential files