# Compaq COBOL
Reference Manual

Previous | Contents | Index

## 6.6.5 CORRESPONDING Phrase

The CORRESPONDING phrase allows you to specify group items as operands in order to use their corresponding subordinate items in an operation. See the Section 6.8.2 , Section 6.8.37 , and Section 6.8.22 statements.

The following rules apply to the identifiers of operands in a statement containing the CORRESPONDING phrase:

1. All identifiers must refer to group items.
2. The data description entries of these identifiers can contain a REDEFINES or OCCURS clause.
3. Identifiers can be subordinate to a data description entry that has a REDEFINES or OCCURS clause.
4. You cannot specify identifiers with level-number 66, 77 or 88, or the USAGE IS INDEX clause.
5. Identifiers cannot be reference-modified.

The following rules describe the requirements for correspondence between data items subordinate to the identifiers. In these rules, identifier-1 refers to the sending group item and identifier-2 refers to the group in which results of the operation are stored.

1. Data items subordinate to both identifier-1 and identifier-2 must have the same data-name.
2. All possible qualifiers for a data item contained in identifier-1 (up to but not including identifier-1), must be identical to all possible qualifiers for the matching item in identifier-2 (up to but not including identifier-2).
3. In an ADD or SUBTRACT statement, the CORRESPONDING phrase affects only elementary numeric data items. Other data items do not take part in the operation.
4. In a MOVE statement, either the sending or receiving subordinate item can be a group item, but both cannot be. The classes of the data items in any corresponding pair can be different, but the resulting move must be legal according to the MOVE statement rules. (See the Section 6.8.22 statement.)
5. The CORRESPONDING phrase disallows data items with the following:
   - Level-number 66
   - Level-number 88
   - A data description entry containing a REDEFINES, OCCURS, or USAGE IS INDEX clause
   A data item subordinate to one that is not eligible for correspondence is also disallowed.
6. FILLER data items and their subordinates are disallowed.
7. Neither identifier-1 nor identifier-2 can be reference modified.

## 6.6.6 ON EXCEPTION Phrase

The ON EXCEPTION phrase allows execution of an imperative statement when an exception (or error) condition occurs.

The NOT ON EXCEPTION phrase allows execution of an imperative statement when an exception condition (or any other error condition) does not occur.

The format is as follows:

stment is an imperative statement.

The ON EXCEPTION phrase of the CALL statement prevents control transfer of the CALL and triggers the execution of the imperative statement related to the CALL.

The ON EXCEPTION phrase of the ACCEPT statement (Formats 3 and 4) allows you to handle data entry errors when data is accepted into a numeric data field using ACCEPT WITH CONVERSION. For additional information, see the Section 6.8.1 statement.

The ON EXCEPTION phrase allows execution of an imperative statement when an ACCEPT statement (Format 5) terminates unsuccessfully. When there is an applicable CRT STATUS clause, unsuccessful termination is indicated by a value of '1' or '9' in the first character of the CRT STATUS data item (see the SPECIAL-NAMES section of Chapter 4).

When an exception condition occurs and the statement contains an ON EXCEPTION phrase:

1. The imperative statement associated with the ON EXCEPTION phrase is executed.
2. The NOT ON EXCEPTION phrase, if specified, is ignored.
3. Control is transferred to the end of the statement unless control has been transferred by executing the imperative statement of the ON EXCEPTION phrase.

When an exception condition occurs and the statement does not contain an ON EXCEPTION phrase:

1. The NOT ON EXCEPTION phrase, if specified, is ignored.
2. The program terminates abnormally.

When an exception condition does not occur:

1. The imperative statement associated with the NOT ON EXCEPTION phrase, if specified, is executed.
2. The ON EXCEPTION phrase, if specified, is ignored.
3. Control is transferred to the end of the statement unless control has been transferred by executing the imperative statement of the NOT ON EXCEPTION phrase.

## 6.6.7 Overlapping Operands and Incompatible Data

When statements refer to data items, two conditions can occur that can make program results unpredictable.

Undefined results occur when a sending and receiving item in an arithmetic statement or an INITIALIZE, INSPECT, MOVE, SET, STRING, or UNSTRING statement share a part of their storage areas.

Procedure Division references to a data item are undefined when a data item's contents are incompatible with the class of data defined by the item's PICTURE clause, or (if the item is a function) its function definition. Conditional statements containing the class condition allow you to do the following:

- Determine whether or not an item contains numeric or alphabetic data.
- Specify corrective action when it does not.

See Section 6.5.2 for more information on class condition.

## 6.6.8 I-O Status

If a file description entry has a FILE STATUS clause, a value is placed in the two-character FILE STATUS data item during execution of the following I/O statements:

- CLOSE
- DELETE
- OPEN
- READ
- REWRITE
- START
- UNLOCK
- WRITE

The two characters from the FILE STATUS data item combine to form a file status value. The first character (Status Key 1), which occupies the leftmost character position in the item, represents a specific class of I/O operation (0--success, 1--at end, 2--invalid key, 3--permanent error, 4--logic error, or 9--Compaq defined). The second character (Status Key 2), which occupies the rightmost position, provides additional information about the result of an I/O operation. In combination, Status Key 1 and Status Key 2 indicate the status of an I/O operation. For example, if you are interested in duplicate keys, you check for File Status 02.

When Status Key 1 contains 1, the AT END phrase executes. When Status Key 1 contains 2, the INVALID KEY phrase executes. When Status Key 1 contains 3, 4, or 9 the Declarative USE procedure executes. Any applicable USE AFTER EXCEPTION procedure executes after the FILE STATUS value is set.

Figure 6-1 shows the possible combinations of Status Keys 1 and 2. In the figure, X indicates a valid combination of keys.

Figure 6-1 Possible Combinations of Status Keys 1 and 2

Status Key 1

Status Key 1 indicates one of the following conditions when an input-output operation ends:

15. Successful Completion. The input-output statement executed successfully.

1. At End. A sequential READ statement unsuccessfully executed because of the following:
   - The file has no next logical record.
   - An optional file was not present.
   - The program did not establish a valid next record.

2. Invalid Key. The input-output statement executed unsuccessfully because of one of the following conditions:
   - Sequence Error
   - Duplicate Key
   - No Record Found
   - Boundary Violation on a relative or indexed file
   - Optional File Not Present

3. Permanent Error. The input-output statement executed unsuccessfully because of a boundary error for a sequential file. This value can also indicate an input-output error, such as data check, parity error, or transmission error.

4. Logic Error. The input-output statement was unsuccessfully executed as a result of an improper sequence of input-output operations that were performed on the file or as a result of violating a limit set by the user.

9. Compaq defined. The input-output statement executed unsuccessfully because of a condition defined by Compaq.

Status Key 2

Status Key 2 further describes the result of the input-output operation as follows:

- If no further information about the input-output operation is available, Status Key 2 contains 0.
- When Status Key 1 contains 0 (indicating successful completion), Status Key 2 can contain a 2, 4, 5, or 7.
  2. Applies to a REWRITE, WRITE, or READ statement.
     - For REWRITE and WRITE statements it means that the record just written created a duplicate key value for at least one alternate record key for which duplicates are allowed.
     - For READ statements it means that the record just read has duplicate key values for the current key of reference.
  4. Applies to a READ statement. It means the size of the record read does not agree with the size defined in the program.
  5. Applies to the OPEN statement. It means that the optional file was not present when the OPEN statement executed. If the open mode is I-O or EXTEND, the file has been created.
  7. Applies to the CLOSE and OPEN statements. It means one of the following:
     - The program tried to execute a CLOSE REEL/UNIT, a CLOSE NO REWIND, or a CLOSE FOR REMOVAL statement for a file on a nonreel/unit medium.
     - The program tried to execute an OPEN NO REWIND statement for a file on a nonreel/unit medium.
- When Status Key 1 contains 1 (indicating an at end condition), Status Key 2 describes the condition's cause:
  15. Indicates that the file has no next logical record or it indicates that a file you specified as optional is not present.
  4. Means that the relative record number of the record read was too big for the relative key data item.
- When Status Key 1 contains 2 (indicating an invalid key condition), Status Key 2 describes the condition's cause as follows:
  1. Indicates a sequence error for a sequential access indexed file. This means that the program changed the prime record key value between a successfully executed READ statement and the next REWRITE statement for the file. This value can also indicate that the program violated sort order sequence requirements for successive record key values. (See the Section 6.8.43 statement.)
  2. Indicates a duplicate key value. The program tried to write or rewrite a record that would have created a duplicate key in an indexed file. This value can also mean that the program tried to write a record that would have created a duplicate in a relative file.
  3. Means that the program could not find a record. The program tried to access a record identified by a key, but the record does not exist in the file, or the file you specified as optional is not present.
  4. Indicates a boundary violation. The program tried to write beyond the boundaries defined for the file by the I/O system (OpenVMS Alpha Record Management Services (RMS) on OpenVMS Alpha systems), or the program attempted a sequential WRITE statement and the number of significant digits in the relative record number is larger than the size of the relative key data item.
- When Status Key 1 contains 3 (indicating a permanent error condition), Status Key 2 describes the condition causes as follows:
  15. Indicates that no more information is available. This value results from any input-output error that cannot be described by any other combination of values in Status Keys 1 and 2. For example, "filename too long" is indicated this way.
  4. Indicates a boundary violation on a sequential file. This means that the program tried to write to a disk that was full.
  5. Indicates that the program tried to open a file that does not exist.
  7. Indicates that the program tried to create a file on a device that is not appropriate for the OPEN statement mode.
  8. Indicates that the program tried to open a file that is closed with a lock.
  9. Indicates a conflict of file attributes. The attributes of the file that the program attempted to open do not match the attributes of the file described in the program. The attributes that are checked are BLOCK SIZE, ORGANIZATION, INDEX KEYS, and MAXIMUM RECORD SIZE. (Refer to the Tru64 UNIX reference page or COBOL online help for information on the effect of the relaxed key checking option.)
  - When Status Key 1 contains 4 (indicating an error in the program's logic), Status Key 2 describes the condition's cause: )
    1. Indicates that the program tried to open a file that is already open.
    2. Indicates that the program tried to close a file that either: (a) is already closed, or (b) has not been opened during the program's execution.
    3. Indicates that the program tried to execute either: (a) a DELETE or REWRITE statement without first successfully executing a READ or START statement, or (b) an UNLOCK RECORD statement without first establishing a current record.
    4. Indicates that the program attempted to REWRITE a record that is not the same size as the record being replaced.
    6. Indicates that the program did not establish a valid next record.
       The values 10 and 46 can occur for the same READ operation when a program is in an infinite loop. In this case, the FILE STATUS data item contains the following sequence of values:
       00, 00, ... , 00, 10, 46, 46, ... , 46
    7. Indicates the program tried a READ or START operation on a file that: (a) has not been opened, or (b) has been opened in a mode that is incompatible with the operation.
    8. Indicates the program attempted a WRITE operation on a file that: (a) has not been opened, or (b) has been opened in a mode that is incompatible with the operation.
    9. Indicates the program tried a DELETE or REWRITE on a file that: (a) has not been opened, or (b) has been opened in a mode that is incompatible with the operation.
  - When Status Key 1 contains 9 (indicating a Compaq defined condition), Status Key 2 further describes the condition, as follows:
    15. Means that the record your program is reading has been locked by another access stream. Because the record is available in the record area, the input operation is successful. This condition results from using the REGARDLESS option. Without the REGARDLESS option, the same scenario causes a Status Key 2 value of 2.
    1. Indicates that a file is locked. The access stream tried to open a file that had been locked by another program.
    2. Means that a record is locked. The program tried to access a record that had been locked by another access stream.
       In this case, the record is not available in the record area, so the input operation is unsuccessful.
    5. Means that the program tried to open a file when there was not enough space on the device.
    8. Indicates that an unspecified error occurred when the program attempted to close a file.

  Appendix C lists all the possible file status values that can appear in the FILE STATUS data item, along with the I-O status condition corresponding to each value.

  ## 6.6.9 AT END Phrase

  The AT END phrase specifies the action your program takes when an at end condition occurs (when Status Key 1 contains 1).

  The NOT AT END phrase specifies the action your program takes if an at end (or any other error condition) does not occur.

  The format is as follows:

  stment is one or more imperative statements.

  When a program detects the end of a file, the condition is called the at end condition. The at end condition might occur as a result of ACCEPT, READ, RETURN, or SEARCH statement execution. (For additional information, see the previously mentioned statements.)

  When an at end condition occurs and the statement contains an AT END phrase:

  1. The imperative statement associated with the AT END phrase, if specified, executes.
  2. The NOT AT END phrase, if specified, is ignored.
  3. Control is transferred to the end of the ACCEPT, READ, RETURN, or SEARCH statement unless control has been transferred by executing the imperative statement of the AT END phrase.

  When an at end condition occurs and the statement does not contain an AT END phrase:

  1. If the at end condition is associated with a READ statement, the applicable USE AFTER EXCEPTION procedure, if specified, executes.
  2. If the at end condition is associated with an ACCEPT, RETURN, or SEARCH statement, any USE procedure associated with that file is not applicable.
  3. The NOT AT END phrase, if specified, is ignored.

  When an at end condition does not occur, and no other exception condition exists:

  1. The AT END phrase, if specified, is ignored.
  2. The imperative statement associated with the NOT AT END phrase, if specified, is executed. Otherwise, control is transferred to the end of the ACCEPT, READ, RETURN, or SEARCH statement.

  When an at end condition does not occur, and another exception condition does exist:

  - The applicable USE AFTER EXCEPTION procedure, if specified, executes and control is then transferred according to the rules of the USE statement.
  - If there is no applicable USE AFTER EXCEPTION procedure, the imperative statement associated with the NOT AT END phrase, if specified, is executed, unless the exception condition causes the run unit to terminate abnormally.
  - If there is neither a USE AFTER EXCEPTION procedure nor a NOT AT END phrase, then control is transferred to the end of the statement, unless the exception condition causes the run unit to terminate abnormally.

  ## 6.6.10 INVALID KEY Phrase

  The INVALID KEY phrase specifies the action your program takes when an invalid key condition is detected (when Status Key 1 contains 2) for the file being processed.

  The NOT INVALID KEY phrase specifies the action your program takes when an invalid key condition (or any other error condition) is not detected for the file being processed.

  The format is as follows:

  stment is one or more imperative statements.

  The invalid key condition occurs when the I/O system cannot complete a COBOL DELETE, READ, REWRITE, START, or WRITE statement because of one of the following conditions:

  - Sequence error
  - Duplicate key when the COBOL program did not specify this condition
  - No record found
  - Boundary violation on a relative or indexed file
  - Optional file not present

  (For more information on these conditions, refer to Section 6.6.8.) When the invalid key condition occurs, execution of the statement that produced the condition is unsuccessful, and the file is unaffected. (For additional information, see the previously mentioned statements.)

  When the invalid key condition occurs:

  1. A value that indicates the invalid key condition is placed in the FILE STATUS data item for the file.
  2. If the statement that caused the condition has the INVALID KEY phrase:
     1. Any USE AFTER EXCEPTION procedure is not executed.
     2. The imperative statement associated with the INVALID KEY phrase executes.
     3. The NOT INVALID KEY phrase, if specified, is ignored.
     4. Control is transferred to the end of the I-O statement unless control has been transferred by executing the imperative statement of the INVALID KEY phrase.
  3. If the statement that caused the condition does not have an INVALID KEY phrase:
     1. The NOT INVALID KEY phrase, if specified, is ignored.
     2. Control is transferred to the applicable USE AFTER EXCEPTION procedure for the file.

  When an invalid key condition does not occur, and no other exception condition exists:

  1. The INVALID KEY phrase, if specified, is ignored.
  2. The imperative statement associated with the NOT INVALID KEY phrase, if specified, is executed. Otherwise, control is transferred to the end of the I/O statement.

  When an invalid key condition does not occur, and another exception condition does exist:

  - The applicable USE AFTER EXCEPTION procedure, if specified, executes and control is then transferred according to the rules of the USE statement.
  - If there is no applicable USE AFTER EXCEPTION procedure, the imperative statement associated with the NOT INVALID KEY phrase, if specified, is executed, unless the exception condition causes the run unit to terminate abnormally.
  - If there is neither a USE AFTER EXCEPTION procedure nor a NOT INVALID KEY phrase, then control is transferred to the end of the statement, unless the exception condition causes the run unit to terminate abnormally.

  ## 6.6.11 FROM Phrase

  record-name and identifier must not refer to the same storage area.

  The result of executing a RELEASE, REWRITE, or WRITE statement with the FROM phrase is equivalent to: (1) executing the statement "MOVE identifier TO record-name" according to the rules of the MOVE statement without the CORRESPONDING phrase, followed by (2) executing the same RELEASE, REWRITE, or WRITE statement without the FROM phrase.

  After statement execution ends, the data in the area referenced by identifier is available to the program. The data is not available in the area referenced by record-name, unless there is an applicable SAME clause. (See Section 4.2.10, I_O_CONTROL, the Section 6.8.30 statement, and the Section 6.8.43 statement.)

  ## 6.6.12 INTO Phrase

  The INTO phrase implicitly moves a current record from the record storage area into an identifier.

  The format is as follows:

  A READ or RETURN statement can have the INTO phrase if either of the following conditions is true:

  - Only one record description is subordinate to the file description entry.
  - All record-names associated with file-name and the data item associated with identifier describe a group item or an elementary alphanumeric item.

  Executing a READ or RETURN statement with the INTO phrase is equivalent to: (1) executing the same statement without the INTO phrase, then (2) moving the current record from the record area to the area specified by identifier. The move occurs according to the rules of the MOVE statement without the CORRESPONDING phrase. The move does not occur for an unsuccessful execution of the READ or RETURN statement.

  Subscript or index evaluation occurs after the input operation and immediately before the move.

  The record is available to the program in both the record area and the area associated with the identifier.

  Previous | Next | Contents | Index