HP OpenVMS Systems Documentation
Content starts here

HP COBOL
Reference Manual

Previous Contents Index

6.8.43 WRITE

Function

The WRITE statement releases a logical record to an output or input-output file. It can also position lines vertically on a logical page.

rec-name

is the name of a logical record described in the Data Division File Section. The logical record cannot be in a sort-merge file description entry.

src-item

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

advance-num

is an integer or the identifier of an unsigned data item described as an integer. Its value can be zero.

top-of-page-name

is a mnemonic-name equated to C01 in the SPECIAL-NAMES paragraph of the Environment Division. It represents top-of-page and is equivalent to the PAGE phrase.

stment

is an imperative statement executed when the relevant condition (end-of-page or invalid key) occurs.

stment2

is an imperative statement executed when the relevant condition (not at end-of-page or not invalid key) occurs.

Syntax Rules

  1. Format 1 must be used for sequential files.
  2. Format 2 must be used for relative and indexed files.
  3. If the file description entry containing rec-name has a LINAGE clause, the WRITE statement cannot have an ADVANCING top-of-page-name phrase.
  4. If there is an END-OF-PAGE phrase, the file description entry containing rec-name must have a LINAGE clause.
  5. The words END-OF-PAGE and EOP are equivalent.
  6. In Format 2, there must be an INVALID KEY phrase if there is no applicable USE AFTER EXCEPTION procedure for the file.
  7. To use the ALLOWING option, the program must include these entries:
    • LOCK-HOLDING clause of the I-O-CONTROL paragraph
    • ALLOWING option of the OPEN statement
  8. 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.
  9. The ADVANCING PAGE and END-OF-PAGE phrase cannot be used in the same WRITE statement.
  10. ADVANCING cannot be used with LINE SEQUENTIAL (Alpha, I64).
  11. The ALLOWING clause is Hewlett-Packard 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 record is no longer available in rec-name after a WRITE statement successfully executes. However, if the associated file-name is in a SAME RECORD AREA clause, the record is available in rec-name. In this case, the record is also available in the record areas of other file-names in the same SAME RECORD AREA clause.
  2. The FROM Phrase section lists the rules for the FROM phrase.
  3. For mass storage files, the WRITE statement does not affect the File Position Indicator.
  4. The WRITE statement updates the value of the FILE STATUS data item for the file.
  5. A file's maximum record size is set when it is created. It cannot be changed later.
  6. On a mass storage device, the number of characters required to store a logical record in a file depends on file organization and record type. (See Technical Notes.)
  7. WRITE statement execution releases a logical record to the I-O system.
  8. The ALLOWING NO OTHERS option can be used only in a Hewlett-Packard 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. If you use manual locking (APPLY LOCK-HOLDING), then the ALLOWING NO OTHERS clause on the WRITE statement is required.
  9. The ALLOWING NO OTHERS option locks the current record. No other concurrent access stream can access this record until it is unlocked.
    However, on Tru64 UNIX systems, for indexed files the WRITE statement with the ALLOWING clause does not acquire a record lock. <>
  10. 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 of a FILE STATUS data item. However, it does not execute if: (a) the condition is invalid key, and (b) there is an INVALID KEY phrase.
    See the rules for the INVALID KEY phrase, Section 6.6.10.
  11. The number of character positions in the record to be written 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 WRITE statement is unsuccessful and the following occurs:
    • The WRITE 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.

Sequential or Line Sequential (Alpha, I64) Files

  1. The file must be open in the OUTPUT or EXTEND mode when the WRITE statement executes. (See Table 6-15.)
  2. The sequence of records in a sequential file is set by the order of WRITE statement executions that create the file. The relationship does not change, except when records are added to the end of the file.
  3. For a sequential file open in the extend mode, the WRITE statement adds records to the end of the file as if the file were open in the output mode. If the file has records, the first record written after execution of an OPEN statement with the EXTEND phrase is the successor of the file's last record.
  4. When a program tries to write beyond a sequential file's externally defined boundaries (for example,attempting to write to a full disk device), an exception condition exists as follows:
    • The contents of the record area are unaffected.
    • The value of the FILE STATUS data item for the file indicates a boundary violation.
    • If a USE AFTER EXCEPTION procedure applies to the file, it executes.
    • If there is no applicable USE AFTER EXCEPTION procedure, the program terminates abnormally.
  5. If the end of a reel/unit is recognized, and the WRITE does not exceed the externally defined file boundaries:
    • A reel/unit swap occurs.
    • The Current Volume Pointer points to the file's next reel/unit.
  6. If the program reaches the end of the logical page during execution of a WRITE statement with the END-OF-PAGE phrase, stment executes. The LINAGE clause associated with the file specifies the logical end.
  7. An end-of-page condition is reached when a WRITE statement with the END-OF-PAGE phrase causes printing or spacing in the footing area of the page body.
    This condition occurs when the WRITE statement causes the LINAGE-COUNTER to equal or exceed the value in the LINAGE clause FOOTING phrase. stment then executes after rec-name is written to the file.
    If this statement does not occur and the NOT END-OF-PAGE is specified, rec-name is written to the file, file status is updated, and control is transferred to stment2.
  8. An automatic page overflow condition occurs when the page body cannot fully accommodate a WRITE statement (with or without the END-OF-PAGE phrase).
    This condition occurs when WRITE statement execution would cause the LINAGE-COUNTER to exceed the number of lines in the page body specified in the LINAGE clause. When this happens, the line is presented on the logical page before or after (depending on the phrase) device positioning. The device is positioned to the first line that can be written on the next logical page (as described in the LINAGE clause). stment then executes after rec-name is written to the file.
  9. If there is no LINAGE clause FOOTING phrase, the WRITE statement operates as if the FOOTING phrase value was beyond the limits of the page. That is, the end-of-page condition occurs after the specified number of lines per page are written. No space is reserved for a footing.
  10. If there is a FOOTING phrase, and a WRITE statement would cause the LINAGE-COUNTER to exceed both the number of lines in a logical page and the value in the LINAGE clause FOOTING phrase, the WRITE statement operates as if there were no FOOTING phrase.

Relative Files

  1. The file must be open in the OUTPUT, I-O, or EXTEND mode when the WRITE statement executes. (See Table 6-15.)
  2. When a relative file with sequential access mode is open in the output mode, the WRITE statement releases a record to the I-O system. The first record has a relative record number of 1. Subsequent records have relative record numbers of 2, 3, 4, and so on. If rec-name has an associated RELATIVE KEY data item, the WRITE places the relative record number of the released record into it.
  3. When a relative file with sequential access mode is open in the extend mode, the WRITE statement releases a record to the I-O system. The first record has a relative record number one greater than the highest relative record number existing in the file. Subsequent records have consecutively higher relative record numbers. If rec-name has an associated RELATIVE KEY data item, the WRITE statement places the relative record number of the released record into it.
  4. When a relative file with random or dynamic access mode is open in the output mode, the program must place a value in the RELATIVE KEY data item before executing the WRITE statement. The value is the relative record number to associate with the record in rec-name. The WRITE statement releases the record to the I-O system.
  5. When a relative file is open in the I-O mode and the access mode is random or dynamic, the program must place a value in the RELATIVE KEY data item before executing the WRITE statement. The value is the relative record number to associate with the record in rec-name. Executing a Format 2 WRITE statement releases the record to the I-O system.
  6. The invalid key condition exists when:
    • The access mode is random or dynamic, and the RELATIVE KEY data item specifies a record that already exists in the file.
    • The program tries to write a record beyond the externally defined file boundaries.
    • The number of significant digits in the relative record number is larger than the size of the relative key data item described for the file.
  7. When the program detects an invalid key condition, WRITE statement execution is unsuccessful. The following results occur:
    • The contents of the current record area are not affected.
    • The WRITE statement sets the FILE STATUS data item for the file to indicate the cause of the condition.
    • Program execution continues according to the rules for the invalid key condition.
      See the rules for the INVALID KEY phrase, Section 6.6.10.

Previous Next Contents Index