Common processing facilities

Several common processing facilities apply to more than one input-output statement.

The common processing facilities provided are:

Discussions in the following sections use the terms volume and reel. The term volume refers to all non-unit-record input-output devices. The term reel applies only to tape devices. Treatment of direct-access devices in the sequential access mode is logically equivalent to the treatment of tape devices.

File status key

If the FILE STATUS clause is specified in the file-control entry, a value is placed in the specified file status key (the two-character data item named in the FILE STATUS clause) during execution of any request on that file; the value indicates the status of that request.

The value is placed in the file status key before execution of any EXCEPTION/ERROR declarative, INVALID KEY phrase, or AT END phrase associated with the request.

There are two file status key data-names. One is described by data-name-1 in the FILE STATUS clause of the file-control entry. This is a two-character data item with the first character known as file status key 1 and the second character known as file status key 2. The combinations of possible values and their meanings are shown in Table 1.

The other file status key is described by data-name-8 in the FILE STATUS clause of the file-control entry. data-name-8 does not apply to QSAM files. For more information about data-name-8, see FILE STATUS clause.

Table 1. File status key values and meanings
High-order digit Meaning Low-order digit Meaning
0 Successful completion 0 No further information
2 This file status value applies only to indexed files with alternate keys that allow duplicates.

The input-output statement was successfully executed, but a duplicate key was detected. For a READ statement, the key value for the current key of reference was equal to the value of the same key in the next record within the current key of reference. For a REWRITE or WRITE statement, the record just written created a duplicate key value for at least one alternate record key for which duplicates are allowed.

4 A READ statement was successfully executed, but the number of character positions that were read was less than the minimum size or was greater than the maximum size specified by the record description entries associated with the FD for the file.
Note: Start of changeIf the VLR(COMPAT) option is in effect, you will get the status value of 00 when READ statements encounter a record length conflict. For details about the VLR option, see VLR in the Enterprise COBOL Programming Guide. End of change
5 An OPEN statement was successfully executed, but the referenced optional file was unavailable at the time the OPEN statement was executed. The file had been created if the open mode was I-O or EXTEND. This does not apply to VSAM sequential files.
7 For a CLOSE statement with the NO REWIND, REEL/UNIT, or FOR REMOVAL phrase or for an OPEN statement with the NO REWIND phrase, the referenced file was on a non-reel/unit medium.
1 At-end condition 0 A sequential READ statement was attempted and no next logical record existed in the file because the end of the file had been reached. Or the first READ was attempted on an optional input file that was unavailable.
4 A sequential READ statement was attempted for a relative file, and the number of significant digits in the relative record number was larger than the size of the relative key data item described for the file.
2 Invalid key condition 1 A sequence error exists for a sequentially accessed indexed file. The prime record key value was changed by the program between the successful execution of a READ statement and the execution of the next REWRITE statement for that file. Or the ascending requirements for successive record key values were violated.
2 An attempt was made to write a record that would create a duplicate key in a relative file. Or an attempt was made to write or rewrite a record that would create a duplicate prime record key or a duplicate alternate record key without the DUPLICATES phrase in an indexed file.
3 An attempt was made to randomly access a record that does not exist in the file. Or a START or random READ statement was attempted on an optional input file that was unavailable.
4 An attempt was made to write beyond the externally defined boundaries of a relative or indexed file. Or a sequential WRITE statement was attempted for a relative file and the number of significant digits in the relative record number was larger than the size of the relative key data item described for the file.
3 Permanent error condition 0 No further information
4 A permanent error exists because of a boundary violation; an attempt was made to write beyond the externally defined boundaries of a sequential file.
5 An OPEN statement with the INPUT, I-O, or EXTEND phrase was attempted on a nonoptional file that was unavailable.
7 An OPEN statement was attempted on a file that would not support the open mode specified in the OPEN statement. Possible violations are:
  • The EXTEND or OUTPUT phrase was specified but the file would not support write operations.
  • The I-O phrase was specified but the file would not support the input and output operations permitted.
  • The INPUT phrase was specified but the file would not support read operations.
8 An OPEN statement was attempted on a file previously closed with lock.
9 The OPEN statement was unsuccessful because a conflict was detected between the fixed file attributes and the attributes specified for that file in the program. These attributes include the organization of the file (sequential, relative, or indexed), the prime record key, the alternate record keys, the code set, the maximum record size, the record type (fixed or variable), and the blocking factor.
4 Logic error condition 1 An OPEN statement was attempted for a file in the open mode.
2 A CLOSE statement was attempted for a file not in the open mode.
3 For a mass storage file in the sequential access mode, the last input-output statement executed for the associated file prior to the execution of a REWRITE statement was not a successfully executed READ statement.

For relative and indexed files in the sequential access mode, the last input-output statement executed for the file prior to the execution of a DELETE or REWRITE statement was not a successfully executed READ statement.

4 A boundary violation exists because an attempt was made to rewrite a record to a file and the record was not the same size as the record being replaced. Or an attempt was made to write or rewrite a record that was larger than the largest or smaller than the smallest record allowed by the RECORD IS VARYING clause of the associated file-name.
6 A sequential READ statement was attempted on a file open in the input or I-O mode and no valid next record had been established because:
  • The preceding READ statement was unsuccessful but did not cause an at-end condition.
  • The preceding READ statement caused an at-end condition.
7 The execution of a READ statement was attempted on a file not open in the input or I-O mode.
8 The execution of a WRITE statement was attempted on a file not open in the I-O, output, or extend mode.
9 The execution of a DELETE or REWRITE statement was attempted on a file not open in the I-O mode.
9 Implementor-defined condition 0
  • For multithreading only: A CLOSE of a VSAM or QSAM file was attempted on a thread that did not open the file.
  • Without multithreading: For VSAM only: See the information about VSAM return codes in Using VSAM status codes (VSAM files only) in the Enterprise COBOL Programming Guide.
  • QSAM files: No further information available. See the DFSMS error message for more information.
1 For VSAM only: Password failure
2 Logic error
3 For all files, except QSAM: Resource unavailable
5 For all files except QSAM: Invalid or incomplete file information
6 For VSAM file: An OPEN statement with the OUTPUT phrase was attempted, or an OPEN statement with the I-O or EXTEND phrase was attempted for an optional file but no DD statement was specified for the file.

For QSAM file: An OPEN statement with the OUTPUT phrase was attempted, or an OPEN statement with the I-O or EXTEND phrase was attempted for an optional file but no DD statement was specified for the file and the CBLQDA(OFF) runtime option was specified.

7 For VSAM only: OPEN statement execution successful: File integrity verified
Note: Start of changeIf the VSAMOPENFS(SUCC) option is in effect, you will get the status value of 00 when a VSAM OPEN statement is successfully verified. For details about the VSAMOPENFS option, see VSAMOPENFS in the Enterprise COBOL Programming Guide. End of change
8 Open failed due to the invalid contents of an environment variable specified in a SELECT ... ASSIGN clause or due to dynamic allocation failure. For more information about the contents of environment variables, see ASSIGN clause.

Invalid key condition

The invalid key condition can occur during execution of a START, READ, WRITE, REWRITE, or DELETE statement. When an invalid key condition occurs, the input-output statement that caused the condition is unsuccessful.

When the invalid key condition is recognized, actions are taken in the following order:
  1. If the FILE STATUS clause is specified in the file-control entry, a value is placed into the file status key to indicate an invalid key condition, as shown in Table 1.
  2. If the INVALID KEY phrase is specified in the statement that caused the condition, control is transferred to the INVALID KEY imperative statement. Any EXCEPTION/ERROR declarative procedure specified for this file is not executed. Execution then continues according to the rules for each statement specified in the imperative statement.
  3. If the INVALID KEY phrase is not specified in the input-output statement for a file and an applicable EXCEPTION/ERROR procedure exists, that procedure is executed. The NOT INVALID KEY phrase, if specified, is ignored.

Both the INVALID KEY phrase and the EXCEPTION/ERROR procedure can be omitted.

If the invalid key condition does not exist after execution of the input-output operation, the INVALID KEY phrase is ignored, if specified, and the following actions are taken:

  • If an exception condition that is not an invalid key condition exists, control is transferred according to the rules of the USE statement following the execution of any USE AFTER EXCEPTION procedure.
  • If no exception condition exists, control is transferred to the end of the input-output statement or the imperative statement specified in the NOT INVALID KEY phrase, if it is specified.

INTO and FROM phrases

The INTO and FROM phrases are valid for READ, RETURN, RELEASE, REWRITE, and WRITE statements.

You must specify an identifier that is the name of an entry in the WORKING-STORAGE SECTION or the LINKAGE SECTION, or of a record description for another previously opened file.

Format: INTO and FROM phrases of input-output statements

Read syntax diagramSkip visual syntax diagramREADRETURNfile-name-1RECORDINTOidentifier-1RELEASEREWRITEWRITErecord-name-1FROMidentifier-1
  • record-name-1 and identifier-1 must not refer to the same storage area.
  • If record-name-1 or identifier-1 refers to a national group item, the item is processed as an elementary data item of category national.
  • The INTO phrase can be specified in a READ or RETURN statement.

    The result of the execution of a READ or RETURN statement with the INTO phrase is equivalent to the application of the following rules in the order specified:

    • The execution of the same READ or RETURN statement without the INTO phrase.
    • The current record is moved from the record area to the area specified by identifier-1 according to the rules for the MOVE statement without the CORRESPONDING phrase. The size of the current record is determined by rules specified in the RECORD clause. If the file description entry contains a RECORD IS VARYING clause, the implied move is a group move. The implied MOVE statement does not occur if the execution of the READ or RETURN statement was unsuccessful. Any subscripting or reference-modification associated with identifier-1 is evaluated after the record has been read or returned and immediately before it is moved to the data item. The record is available in both the record area and the data item referenced by identifier-1.
  • The FROM phrase can be specified in a RELEASE, REWRITE, or WRITE statement.

    The result of the execution of a RELEASE, REWRITE, or WRITE statement with the FROM phrase is equivalent to the execution of the following statements in the order specified:

    1. MOVE identifier-1 TO record-name-1
    2. The same RELEASE, REWRITE, or WRITE statement without the FROM phrase

    After the execution of the RELEASE, REWRITE or WRITE statement is complete, the information in the area referenced by identifier-1 is available even though the information in the area referenced by record-name-1 is unavailable, except as specified by the SAME RECORD AREA clause.

File position indicator

The file position indicator is a conceptual entity used in this document to facilitate exact specification of the next record to be accessed within a given file during certain sequences of input-output operations.

The setting of the file position indicator is affected only by the OPEN, CLOSE, READ and START statements. The concept of a file position indicator has no meaning for a file opened in the output or extend mode.