Rational Developer for System z
COBOL for Windows, Version 7.5, Language Reference


Common processing facilities

There are several common processing facilities that 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 File status key values and meanings (Table 36).

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 line-sequential files. For more information about data-name-8, see FILE STATUS clause.

Table 36. 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 length of the record being processed did not conform to the fixed file attributes for that file, or the record for an RSD file was not followed by a new-line character.
5 An OPEN statement is successfully executed but the referenced optional file is not present at the time the OPEN statement is executed. The file has been created if the open mode is I-O or EXTEND.
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 not present.
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 not present.
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 A WRITE statement with the BEFORE, AFTER phrase was attempted on an RSD file.
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 not present.
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.

An RSD file was declared with the indexed or relative organization, variable-length records, or the LINAGE clause.

File status 39 is not supported for line-sequential files or Btrieve files.

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 No further information.
1 Authorization failure
2 Logic error
3 Resource not available
4 Concurrent open error
5 Invalid or incomplete file information
6 File system not available
8 Open failed due to locked file
9 Record access failed due to locked record

Invalid key condition

The invalid key condition can occur during execution of a START, READ, WRITE, REWRITE, or DELETE statement. (For details of the causes for the condition, see information about the appropriate statement in the environment division.) 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. (See File status key values and meanings (Table 36).)
  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:

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
Read syntax diagramSkip visual syntax diagram>>-+-+-READ---+--file-name-1--+--------+--+--------------------+-+-><
   | '-RETURN-'               '-RECORD-'  '-INTO--identifier-1-' |  
   '-+-RELEASE-+--record-name-1--+--------------------+----------'  
     +-REWRITE-+                 '-FROM--identifier-1-'             
     '-WRITE---'                                                    
 

File position indicator

The file position indicator is a conceptual entity used in this document to facilitate exact specification of the next record (or, alternatively, the previous 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.


Terms of use | Feedback

Copyright IBM Corporation 1996, 2008.
This information center is powered by Eclipse technology. (http://www.eclipse.org)