Compaq COBOL
Reference Manual

DISPLAY "Enter two dates in a row: " NO ADVANCING. ACCEPT INMESSAGE. MOVE 1 TO PTR. PERFORM DISPLAY-TWO 2 TIMES. GO TO DISPLAYED-TWO. DISPLAY-TWO. MOVE SPACES TO THEDATE. MOVE 0 TO FIELD-COUNT MONTH-COUNT DAY-COUNT YEAR-COUNT. UNSTRING INMESSAGE DELIMITED BY "-" OR "/" OR ALL " " INTO THEMONTH DELIMITER IN HOLD-DELIM COUNT MONTH-COUNT THEDAY DELIMITER IN HOLD-DELIM COUNT DAY-COUNT THEYEAR DELIMITER IN HOLD-DELIM COUNT YEAR-COUNT WITH POINTER PTR TALLYING IN FIELD-COUNT. INSPECT THEDATE REPLACING ALL " " BY "0". DISPLAY THEDATE " " PTR " " FIELD-COUNT " : " MONTH-COUNT "-" DAY-COUNT "-" YEAR-COUNT. DISPLAYED-TWO. EXIT.

Results

Enter two dates in a row: 6/13/87 8/15/87 870613 09 03 : 01-02-02 870815 21 03 : 01-02-02 Enter two dates in a row: 10 15 87-1 1 88 871015 10 03 : 02-02-02 880101 21 03 : 01-01-02 Enter two dates in a row: 6/13/87-12/31/87 870613 09 03 : 01-02-02 871231 21 03 : 02-02-02 Enter two dates in a row: 6/13/87-12/31 870613 09 03 : 01-02-02 001231 21 02 : 02-02-00 Enter two dates in a row: 6/13/87/12/31/87 870613 09 03 : 01-02-02 871231 21 03 : 02-02-02

6.8.42 USE

Function

The USE statement specifies Declarative USE procedures to handle input/output exceptions and errors. It can also specify procedures to be executed before the program processes a specific report group.

file-name

is the name of a file connector described in a file description entry in a Data Division. It cannot refer to a sort or merge file.

group-data-name

is the name of a report group in a report group description entry in a Data Division. It must not appear in more than one USE statement.

Syntax Rules

All Formats

1. A USE statement can be used only in a sentence immediately after a section header in the Procedure Division declaratives area. It must be the only statement in the sentence. The rest of the section can contain zero, one, or more paragraphs to define the USE procedures.
2. The USE statement itself does not execute. It defines the conditions that cause execution of the USE procedure.

Format 1

3. The ERROR and EXCEPTION syntax are equivalent and interchangeable.

Format 2

4. Of the four Report Writer Procedure Division verbs (SUPPRESS, GENERATE, INITIATE, or TERMINATE), only the SUPPRESS statement can appear in a USE BEFORE REPORTING procedure. A PERFORM statement in a USE BEFORE REPORTING procedure must not have GENERATE, INITIATE, or TERMINATE statements in its range.
   The USE procedure must not alter the value of any control data item.

General Rules

All Formats

1. At run time, two special precedence rules apply for the selection of a USE procedure when a program is contained within another program. In applying these rules, only the first qualifying USE procedure is selected for execution. The order of precedence for the selection of a USE procedure is as follows:
   • First, select the applicable USE procedure within the program containing the statement that caused the qualifying condition.
   • If a USE procedure is not found in the program using the previous rule, the Run-Time System searches all programs directly or indirectly containing that program for a USE GLOBAL procedure. This search continues until the Run-Time System either: (a) finds an applicable USE GLOBAL procedure, or (b) finds the outermost containing program, if there is no applicable USE GLOBAL procedure. Either condition terminates the search.
2. A Declarative USE procedure cannot refer to a non-Declarative procedure. However, only the PERFORM statement can transfer execution control from:
   • A Declarative USE procedure to another Declarative USE procedure
   • A non-Declarative procedure to a Declarative USE procedure
3. After a USE procedure executes, control returns to the next executable statement in the invoking routine, if one is defined. Otherwise, control transfers according to the rules for Explicit and Implicit Transfers of Control.
4. A program must not execute a statement in a USE procedure that would cause execution of a USE procedure that had been previously executed and had not yet returned control to the routine that invoked it.

Format 1

5. A USE procedure executes automatically:
   • After the system's input-output exception processing completes
   • When an invalid key or at end condition results from an input-output statement that has no INVALID KEY or AT END clause
6. 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 there is an INVALID KEY phrase, or (b) the condition is at end, and there is an AT END phrase.
7. One input-output exception cannot cause more than one USE AFTER EXCEPTION procedure to execute.
8. More than one USE AFTER EXCEPTION procedure can relate to an input-output operation when there is one procedure for file-name and another for the applicable open mode. In this case, only the procedure for file-name executes. This rule applies only to USE procedures in the same program.
9. If no applicable USE procedures are found in the local program, then containing programs are searched upwards for: (a) USE GLOBAL procedures for the file, and then (b) for USE GLOBAL procedures for the input-output type.
10. A USE AFTER EXCEPTION procedure specifying an open mode applies to an input-output operation only when all of the following are true:
    • The open mode (INPUT, OUTPUT, I-O, or EXTEND) specified in the USE AFTER EXCEPTION procedure is identical to the open mode in effect (that is, the open mode established by the OPEN statement).
    • The file is open or in the process of being opened.
    • There is no file-name declarative procedure for that file within the same program.
11. If an input-output error occurs for a file that is not open or not in the process of being opened, the only applicable USE procedure is a file-name USE procedure.

Format 2

12. The Report Writer Control System (RWCS) executes the USE BEFORE REPORTING procedure before it processes the named group-data-name report group. Only during the processing of the report group does the RWCS change prior values, execute control breaks, adjust LINE-COUNTER and PAGE-COUNTER, and present the report group.

Additional References

• Section 6.2.6, Scope of Names
• Section 6.3.1, Explicit and Implicit Procedure Division References
• Description of exception handling in the Compaq COBOL User Manual.

Example

*************************************************************** * This example assumes that SELECT and FD statements exist * for FILE1-SEQ, FILE1-RAN, FILE1-DYN and FILE1-EXT. * All three USE procedures are local to the program * that hosts this fragment. * At run-time if there is an exception on opening FILE1-RAN * or FILE1-DYN, FILE1-ERR section can be invoked. * If there is an exception on opening FILE1-SEQ, INPUT-ERR * section can be invoked. Since there is no USE procedure * declared for the EXTEND mode or for FILE1-EXT, * an exception on opening that file will cause an abnormal * termination of the program. Also, since FILE1-SEQ in the * fragment is not opened for OUTPUT mode, the OUTPUT-ERR USE * procedure is not eligible to be invoked here. *********************************************************** PROCEDURE DIVISION. DECLARATIVES. INPUT-ERR SECTION. USE AFTER STANDARD ERROR PROCEDURE ON INPUT. INP-1. DISPLAY "INVOKED USE PROCEDURE FOR INPUT". OUTPUT-ERR SECTION. USE AFTER STANDARD ERROR PROCEDURE ON OUTPUT. OUT-1. DISPLAY "INVOKED USE PROCEDURE FOR OUTPUT". FILE1-ERR SECTION. USE AFTER STANDARD ERROR PROCEDURE ON FILE1-RAN, FILE1-DYN. FILE1-1. DISPLAY "INVOKED USE PROCEDURE FOR FILES". END DECLARATIVES. MAIN-PROGRAM SECTION. P0. DISPLAY "***ENTERED USE TEST PROGRAM FRAGMENT***". OPEN INPUT FILE1-SEQ. OPEN OUTPUT FILE1-RAN. OPEN I-O FILE1-DYN. OPEN EXTEND FILE1-EXT. ...

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.
11. 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 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 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. 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 and Windows NT 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 Files

12. The file must be open in the OUTPUT or EXTEND mode when the WRITE statement executes. (See Table 6-15.)
13. 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.
14. 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.
15. 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.
16. 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.
17. 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.
18. 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.
19. 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.
20. 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.
21. 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

22. The file must be open in the OUTPUT, I-O, or EXTEND mode when the WRITE statement executes. (See Table 6-15.)
23. 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.
24. 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.
25. 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.
26. 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.
27. 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.
28. 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.

Indexed Files

29. The file must be open in the OUTPUT, I-O, or EXTEND mode when the WRITE statement executes. (See Table 6-15.)
30. Executing a Format 2 WRITE statement releases a record to the I-O system. The contents of the record keys enable later record access based on any defined key.
31. When the file description entry has a RECORD KEY IS clause, the prime record key value is unique unless the DUPLICATES phrase is specified. When a program later accesses these records sequentially, the retrieval order is the same as the order in which they were written in the program.
32. The program must set the value of the prime record key data item before executing the WRITE statement.
33. If the file is open in the sequential access mode, the program must release records in ascending or descending order of prime record key values, depending on the sort order specified in the RECORD KEY clause. If the file is open in the extend mode, the first released record must have a prime record key value that logically follows the last record in the file according to the prime key sort order.
34. If the file is open in the random or dynamic access mode, the program can release records in any order.
35. When the file description entry has an ALTERNATE RECORD KEY clause, the alternate record key value is unique unless the program specifies the DUPLICATES phrase. When a program later accesses these records sequentially, the retrieval order is the same as the order in which they were written in the program.
36. The invalid key condition occurs for any of the following:
    • The file is open in the sequential access mode and in the OUTPUT or EXTEND mode, and the prime record key value does not logically follow the prime record key value of the previous record.
    • The file is open in the OUTPUT, EXTEND, or I-O mode, the prime record key value duplicates an existing record's prime record key value, and the program does not specify duplicates on the prime record key.
    • The file is open in the OUTPUT, EXTEND, or I-O mode, and the value of an alternate record key (for which duplicates are not allowed) duplicates the value of the corresponding data item in an existing record.
    • The program tries to write a record beyond the externally defined file boundaries.
37. 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.

Technical Notes

• WRITE statement execution can result in these FILE STATUS data item values:

  File Status	File Organization	Access Method	Meaning
  00	All	All	Write is successful
  02	Ind	All	Created duplicate primary or alternate key
  21	Ind	Seq	Attempted key value not in prime key sort order (invalid key)
  22	Ind, Rel	All	Duplicate key (invalid key)
  24	Ind, Rel	All	Boundary violation (relative or indexed files) or relative record number is too large for relative key data item (invalid key)
  34	Seq	Seq	Boundary violation (sequential files)
  44	All	All	Boundary violation. An attempt was made to write a record that is larger than the largest or smaller than the smallest record allowed
  48	All	All	File not open, or incompatible open mode
  92	Ind, Rel	All	Record locked by another process
  30	All	All	All other permanent errors

  
  In order to detect "device full" (file status 34) on a sequential WRITE operation, each WRITE needs to be followed by a call to SYS$FLUSH to ensure that an attempt has been made to write any buffered records to disk. For more information, at the OpenVMS system prompt, type

  HELP RMS $FLUSH

Additional References

• LOCK-HOLDING Phrase in APPLY Clause in 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.40, UNLOCK statement