# Compaq COBOL
Reference Manual

Previous | Contents | Index

Technical Note

- READ statement execution can result in these FILE STATUS data item values:

  File Status | File Organization | Access Method | Meaning
  --- | --- | --- | ---
  00 | All | All | Read is successful; record is available; lock acquired as requested
  02 | Ind | All | Read is successful; duplicate key detected
  04 | All | All | Record read larger or smaller than record area
  10 | All | Seq | No next logical record (at end), optional file not present (at end), or no valid next record (at end)
  14 | Rel | Seq | Relative record number too large for relative key data item (at end)
  23 | Ind, Rel | Rand | Record not in file (invalid key) or optional file not present (invalid key)
  46 | All | Seq | No valid next record
  47 | All | All | File not open, or incompatible open mode
  90 | All | All | Record locked by another user; record is available in record area; no lock is acquired (soft lock for Compaq standard locking only)
  92 | All | All | Record locked by another user; record is not available; no lock is acquired (hard lock)
  30 | All | All | All other permanent errors

- On Alpha systems, use START before initiating a sequence of either READ NEXT statements or READ PRIOR/READ PREVIOUS statements. You should use START, if you switch between READ NEXT and READ PRIOR/READ PREVIOUS or vice versa.
- On Alpha systems, the order of duplicate key values for a descending key is not necessarily the same as the order of duplicate key values for READ PRIOR/READ PREVIOUS used with an ascending key defined as the same file record location as the descending key.

Additional References

- LOCK MODE clause in the Section 4.2.1, FILE_CONTROL paragraph in Chapter 4
- Section 4.2.10, I_O_CONTROL paragraph in Chapter 4
- Section 6.1.4, Scope of Statements
- Section 6.6.8, I-O Status
- Section 6.6.10, INVALID KEY Phrase
- Section 6.6.9, AT END Phrase
- Section 6.6.12, INTO Phrase
- Section 6.8.24, OPEN statement
- Section 6.8.40, UNLOCK statement
- Section 6.8.42, USE statement

## 6.8.27 RECORD

Function

The RECORD statement creates an Oracle CDD/Repository dependency relationship between a Compaq COBOL program and the Oracle CDD/Repository entity referred to by the RECORD statement.

> ### path-name

> is a partial or complete Oracle CDD/Repository path name. It specifies a dictionary entity in CDO format.

> ### relation-type

> is a valid Oracle CDD/Repository protocol. It specifies the type of relationship to be created between the Compaq COBOL program and the CDO dictionary entity specified in the path name. The default relationship type is CDD$COMPILED_DEPENDS_ON.

Syntax Rules

1. A space must precede the word RECORD.
2. The RECORD statement must be terminated by the separator period.

General Rules

1. path-name refers to the Oracle CDD/Repository path for a dictionary entity. The entity must be in CDO format.
2. The RECORD statement creates an Oracle CDD/Repository relationship between the Compaq COBOL program through a compiled module entity (see Technical Notes) and the dictionary entity specified in the path name. This relationship information is then stored in Oracle CDD/Repository.
3. The RECORD statement is ignored unless the /DEPENDENCY_DATA compiler option is specified.
4. If the RECORD statement is in a contained program, the relationship created is between the outermost containing program and the entity specified in the path name.

Technical Notes

1. The path-name can be a nonnumeric literal or COBOL word formed according to the rules for user-defined names. It represents a complete or partial Oracle CDD/Repository path name specifying an Oracle CDD/Repository entity. If path-name is not a literal, the compiler translates hyphens in the COBOL word to underscore characters.
   The resultant path name must conform to all rules for forming Oracle CDD/Repository path names.
2. The relation-type can be a nonnumeric literal or COBOL word formed according to the rules for user-defined names. It must be a valid Oracle CDD/Repository protocol type. For example:
   - CDD$COMPILED_DEPENDS_ON is an example of a COBOL word that is a valid Oracle CDD/Repository protocol type.
   - "CDD$COMPILED_DERIVED_FROM" is an example of a nonnumeric literal that is also a valid Oracle CDD/Repository protocol type.
3. The RECORD statement creates a relationship between an Oracle CDD/Repository compiled module dictionary entity and the dictionary entity specified in the path name. A compiled module entity is automatically created and stored in Oracle CDD/Repository when the /DEPENDENCY_DATA compiler option is specified. The name of the compiled module entity is the program-name from the PROGRAM-ID paragraph, with hyphens translated to underscores.

Additional References

- The description of Oracle CDD/Repository in the Compaq COBOL User Manual
- Oracle CDD/Repository Documentation Set <>

## 6.8.28 RELEASE

Function

The RELEASE statement transfers records to the initial phase of a sort operation.

> ### rec

> is the name of a logical record in a sort-merge file description (SD) entry. It can be qualified.

> ### src-area

> is the identifier of the data item that contains the data.

Syntax Rules

1. A RELEASE statement can be used only in an input procedure in the same program as the SORT verb. The input procedure must be associated with a SORT statement for the sort or merge file that contains rec.
2. If src-area is a function-identifier, it must reference an alphanumeric function. When src-area is not a function-identifier, rec and src-area must not reference the same storage area.

General Rules

1. See the FROM Phrase section for a list of rules.
2. The RELEASE statement transfers the contents of rec to the first phase of the sort.
3. After the RELEASE statement executes, the record is no longer available in rec unless the associated sort or merge file-name is in a SAME RECORD AREA clause. In that case, the record is available to the program as a record of the sort-merge file-name. It is also available as a record of all other file-names in the same SAME RECORD AREA clause.

Additional References

- Section 4.2.10, I_O_CONTROL paragraph in Chapter 4
- Section 6.6.11, FROM Phrase phrase

## 6.8.29 RETURN

Function

The RETURN statement obtains sorted records from a sort operation. It also returns merged records in a merge operation.

> ### smrg-file

> is the name of a file described in a sort-merge file description (SD) entry.

> ### dest-area

> is the identifier of the data item to which the returned smrg-file record is moved.

> ### stment

> is an imperative statement executed for an at end condition.

> ### stment2

> is an imperative statement executed for a not at end condition.

Syntax Rules

1. A RETURN statement can be used only in an output procedure in the same program as the SORT verb. The output procedure must be associated with a SORT or MERGE statement for smrg-file.
2. The storage area associated with dest-area and the record area associated with smrg-file cannot be the same storage area.

General Rules

1. See the INTO Phrase section for a list of rules.
2. When more than one record description describes the logical records for smrg-file, the records share the same storage area. The contents of storage positions beyond the range of the returned record are undefined when the RETURN statement ends.
3. Before the output procedure executes, the File Position Indicator is updated. It points to the record whose key values make it first in the file. If there are no records, the File Position Indicator indicates the at end condition.
4. The RETURN statement makes the next record (pointed to by the File Position Indicator) available in the record area for smrg-file.
5. The File Position Indicator is updated to point to the next record in smrg-file. The key values in the SORT or MERGE statement determine the next record.
6. If smrg-file has no next record, the File Position Indicator is updated to indicate the at end condition.
7. If the File Position Indicator indicates the at end condition when the RETURN statement executes, stment executes and control is transferred to the end of the RETURN statement. If the NOT AT END phrase is specified, it is ignored. The contents of the smrg-file record areas are undefined.
8. If the File Position Indicator does not indicate an at end condition when the RETURN statement executes, after the record is made available and after executing any implicit move resulting from the presence of an INTO phrase, control is transferred to stment2, if specified. Otherwise, control is transferred to the end of the RETURN statement.
9. When the at end condition occurs:
   - RETURN statement execution is unsuccessful.
   - The File Position Indicator is not changed.
10. See the Scope of Statements section for a description of scope terminators such as END-RETURN.

Additional References

- Section 6.1.4, Scope of Statements
- Section 4.2.10, I_O_CONTROL paragraph in Chapter 4
- Section 6.6.9, AT END Phrase
- Section 6.6.12, INTO Phrase

## 6.8.30 REWRITE

Function

The REWRITE statement logically replaces a mass storage file record.

> ### rec-name

> is the name of a logical record in the Data Division File Section. It can be qualified.

> ### src-item

> is the identifier of the data item that contains the data.

> ### stment

> is an imperative statement executed for an invalid key condition.

> ### stment2

> is an imperative statement executed for a not invalid key condition.

Syntax Rules

1. To use the ALLOWING option, the program must include these entries:
   - APPLY LOCK-HOLDING clause of the I-O-CONTROL paragraph
   - ALLOWING clause of the OPEN statement
2. The INVALID KEY and the NOT INVALID KEY phrases cannot be specified in a REWRITE statement that refers to a sequential file or to a relative file with sequential access mode.
3. For a relative file with random or dynamic access mode, or for an indexed file, the REWRITE statement must have an INVALID KEY phrase when there is no applicable USE AFTER EXCEPTION procedure for the file.
4. If src-item is a function-identifier, it must reference an alphanumeric function. When src-item is not a function-identifier, rec-name and src-item must not reference the same storage area.
5. The ALLOWING clause is Compaq standard file-sharing syntax, and cannot be used for a file connector that has had X/Open standard file-sharing syntax (WITH [NO] LOCK or LOCK MODE) specified.

General Rules

All Files

1. The file associated with rec-name must be a mass storage file. It must be open in the I-O mode when the REWRITE statement executes.
   Because line sequential files (Alpha) cannot be opened in I-O mode, REWRITE cannot be used with line sequential files. <>
2. For sequential access mode files, the last input-output statement executed for the file before the REWRITE statement must be a successfully executed READ statement. The REWRITE statement logically replaces the record accessed by the READ.
3. The READ must lock the record for the REWRITE statement to be successful.
4. The record in rec-name is no longer available after the REWRITE statement successfully executes unless the associated file-name is in a SAME RECORD AREA clause. In this case, the record is also available to record areas of other file-names in the SAME RECORD AREA clause.
5. The REWRITE statement does not affect the File Position Indicator.
6. The REWRITE statement updates the value of the FILE STATUS data item for the file.
7. The ALLOWING option can be used only in a Compaq standard, manual record-locking environment. To create a manual record-locking environment, the program must OPEN file-name with an ALLOWING option and specify the APPLY LOCK-HOLDING phrase of the I-O-CONTROL paragraph.
8. The ALLOWING option locks the current record rewritten by the current access stream. No other concurrent access stream can access this record until it is unlocked.
   However, on Tru64 UNIX systems, for indexed files the REWRITE statement with the ALLOWING clause does not acquire a record lock. <>
9. See the FROM Phrase section for a list of rules for the FROM phrase.

Sequential Files

10. The record named by rec-name must be the same size as the record being replaced.

Relative Files

11. For a random or dynamic access mode file, the REWRITE statement logically replaces the record specified in the RELATIVE KEY data item for rec-name's file. If the record is not in the file, the invalid key condition exists. The update does not occur, and the data in the record area is not affected.

Indexed Files

12. For a sequential access mode file, the prime record key specifies the record to be replaced. The values of the prime record keys in the record to be replaced and the last record read from (or positioned in) the file must be equal.
13. For a random access mode file, the prime record key specifies the record to replace. If the program specifies duplicates on the prime record key, then it can replace only the first occurrence of a key value using random access mode. Replacing subsequent records with the same prime key value is done by sequentially positioning to the desired record in sequential or dynamic access mode.
14. For indexed files in dynamic access mode, the presence of DUPLICATES on the prime record key determines the behavior. If DUPLICATES are allowed, Rule 11 applies. If DUPLICATES are not allowed, Rule 12 applies.
15. For a record with an alternate record key:
    - When the REWRITE does not change the value of an alternate record key, the order of retrieval is unchanged when the key is the Key of Reference.
    - When duplicate key values are allowed, and the value of an alternate record key changes, the later retrieval order of the record changes when the key is the Key of Reference. The record's logical position is last in the group of records with the same value in the alternate record key that changed.
16. Any of the following occurrences cause the invalid key condition:
    - The access mode is sequential, and the values in the prime record keys of the record to replace and the last record read from (or positioned in) the file are not equal.
    - The value in the prime record key does not equal that of any record in the file.
    - The value in an alternate record key whose definition does not have a DUPLICATES clause equals that of a record already in the file.
    The update does not occur, and the data in the record area is not affected.
17. If there is an applicable USE AFTER EXCEPTION procedure, it executes whenever an input or output condition occurs that would result in a nonzero value in the first character position of a FILE STATUS data item. However, the INVALID KEY phrase (if present) supersedes a USE AFTER EXCEPTION procedure when there is an invalid key condition. In this case, the USE AFTER EXCEPTION procedure does not execute.
    See the rules for the INVALID KEY phrase, Section 6.6.10.
18. The number of character positions in the record to be updated must not be less than the lowest or greater than the highest number of character positions allowed by the RECORD VARYING clause. In either case, the REWRITE statement is unsuccessful and the following occurs:
    - The updating operation does not take place.
    - The contents of the record area remain unaffected.
    - The I-O status of the file is set to a value that indicates the cause of the condition.

Technical Notes

- REWRITE statement execution can result in these FILE STATUS data item values:

  File Status | File Organization | Access Method | Meaning
  --- | --- | --- | ---
  00 | All | All | Rewrite is successful.
  02 | Ind | All | Created duplicate primary or alternate key.
  21 | Ind | Seq | Primary key changed after read.
  22 | Ind | All | Duplicate primary or alternate key (invalid key).
  23 | Ind, Rel | Rand | Record not in file (invalid key).
  43 | All | Seq | No previous read or record not locked by prior READ or START.
  44 | All | All | Invalid record size.
  49 | All | All | File not open, or incompatible open mode.
  92 | Ind, Rel | All | Record locked by another user; record is not available.
  30 | All | All | All other permanent errors.

Additional References

- Section 4.2.10, I_O_CONTROL paragraph in Chapter 4
- Section 6.1.4, Scope of Statements
- Section 6.6.8, I-O Status
- Section 6.6.10, INVALID KEY Phrase
- Section 6.6.11, FROM Phrase
- Section 6.8.24, OPEN statement
- Section 6.8.26, READ statement
- Section 6.8.40, UNLOCK statement
- Section 6.8.42, USE statement

## 6.8.31 SEARCH

Function

The SEARCH statement searches for a table element that satisfies a condition. It sets the value of the associated index to point to the table element.

> ### src-table

> is a table identifier.

> ### pointr

> is an index-name or the identifier of a data item described as USAGE INDEX, or an elementary numeric data item with no positions to the right of the assumed decimal point.

> ### cond

> is any conditional expression.

> ### stment

> is an imperative statement.

> ### elemnt

> is an indexed data-name. It refers to the table element against which the argument is compared.

> ### arg

> is the argument tested against each elemnt in the search. It is an identifier, a literal, or an arithmetic expression.

> ### cond-name

> is a condition-name.

Syntax Rules

Both Formats

1. src_table must not be subscripted, indexed, or reference modified. However, its description must contain an OCCURS clause with the INDEXED BY phrase.
2. If the END-SEARCH phrase is specified, the NEXT SENTENCE phrase must not be specified.

Format 2

3. src_table must contain the KEY IS phrase in its OCCURS clause.
4. Each cond-name must be defined as having only one value. The data-name associated with cond-name must be in the KEY IS phrase of the OCCURS clause for src-table.
5. Each elemnt:
   - Can be qualified
   - Must be indexed by the first index-name associated with src-table, in addition to other indexes or literals required for uniqueness
   - Must be in the KEY IS phrase of the OCCURS clause for src-table
6. Neither arg nor any identifier in its arithmetic expression can either:
   - Be used in the KEY IS phrase of the OCCURS clause for src-table
   - Be indexed by the first index-name associated with src-table
7. When elemnt or the data-name associated with cond-name is in the KEY phrase of the OCCURS clause for src-table, each preceding data-name (or associated cond-name) in that phrase must also be referenced.

General Rules

Both Formats

1. After executing a stment that does not end with a GO TO statement, control passes to the end of the SEARCH statement.
2. src_table can be subordinate to a data item that contains an OCCURS clause. In that case, an index-name must be associated with each dimension of the table through the INDEXED BY phrase of the OCCURS clause. The SEARCH statement modifies the setting of only the index-name for src-table (and pointr, if there is one).
   A single SEARCH statement can search only one dimension of a table; therefore, you must execute SEARCH statements repeatedly to search through a multidimensional table. Before each execution, SET statements must execute to change the values of index-names that need adjustment.

Format 1

3. The Format 1 SEARCH statement searches a table serially, starting with the current index setting.
   1. The index-name associated with src-table can contain a value that indicates a higher occurrence number than is allowed for src-table. If the SEARCH statement execution starts when this condition exists, the search terminates immediately. If there is an AT END phrase, stment then executes. Otherwise, control passes to the end of the SEARCH statement.
   2. If the index-name associated with src-table indicates a valid src-table occurrence number, the SEARCH statement evaluates the conditions in the order they appear. It uses the index settings to determine the occurrence numbers of items to test.
      If no condition is satisfied, the index-name for src-table is incremented to refer to the next occurrence. The condition evaluation process repeats using the new index-name settings. However, if the new value of the index-name for src-table indicates a table element outside its range, the search terminates as in General Rule 3a.
      When a condition is satisfied:
      - The search terminates immediately.
      - The stment associated with the condition executes.
      - The index-name remains set at the occurrence that satisfied the condition.
4. If there is no VARYING phrase, the index-name used for the search is the first index-name in the OCCURS clause for src-table. Other src-table index-names are unchanged.
5. If there is a VARYING phrase, pointr can be an index-name for src-table. (pointr is named in the INDEXED BY phrase of the OCCURS clause forsrc-table.) The search then uses that index-name. Otherwise, it uses the first index-name in the INDEXED BY phrase.
6. pointr also can be an index-name for another table. (pointr is named in the INDEXED BY phrase in the OCCURS clause for that table entry.) In this case, the search increments the occurrence number represented by pointr by the same amount, and at the same time, as it increments the occurrence number represented by the src-table index-name.
7. If pointr is an index data item rather than an index-name, the search increments it by the same amount, and at the same time, as it increments the src-table index-name. If pointr is not an index data item or an index-name, the search increments it by one when it increments the src-table index-name.
8. Example 3, "Serial search with two WHEN phrases," illustrates the operation of a Format 1 SEARCH statement with two WHEN phrases.

Format 2

9. A SEARCH ALL operation yields predictable results only when:
   - The data in the table has the same order as described in the KEY IS phrase of the OCCURS clause for src-table.
   - The contents of the keys in the WHEN phrase identify a unique table element.
10. SEARCH ALL causes a nonserial (or binary) search. It ignores the initial setting of the src-table index-name and varies its setting during execution.
11. If the WHEN phrase conditions are not satisfied for any index setting in the allowed range, control passes to the AT END phrase stment, if there is one, or to the end of the SEARCH statement. In either case, the setting of the src-table index-name is not predictable.
12. If all the WHEN phrase conditions are satisfied for an index setting in the allowed range, control passes to either stment or the next sentence, whichever is in the statement. The src-table index-name then indicates the occurrence number that satisfied the conditions.
13. The index-name used for the search is the first index-name in the OCCURS clause for src-table. Other src-table index-names are unchanged.

Previous | Next | Contents | Index