HP 3000 Manuals HP 3000 Manuals
General Formats (Cont.) The USE Statement Function. The USE statement specifies procedures for input-output error handling, that are in addition to the standard procedures provided by the input-output control system. General Formats. Format 1 (Sequential , Relative and Indexed Files).For OSVS and VSC2 only: Format 2 (Record Sequential Files).For OSVS and VSC2 only: Format 3 (Relative And Indexed Files).Syntax Rules. All Formats (All Files). 1. Format 1 is the ERROR declarative. For VSC2 and OSVS only: Formats 2 and 3 are the LABEL declarative. 2. A USE statement, when present, must immediately follow a section header in the Declaratives Section and must be followed by a period followed by a space. 3. The USE statement itself is never executed; it merely defines the conditions calling for the execution of the USE procedures. 4. The files implicitly or explicitly referenced in a USE statement need not all have the same organization or access. Format 1 (Sequential, Relative and Indexed Files). 5. The same file-name can appear in a different specific arrangement of the format. Appearance of a file-name in a USE statement must not cause the simultaneous request for execution of more than one USE procedure. For ANS85 only: The same file-name must not appear in more than one USE AFTER EXCEPTION statement within the same Procedure Division. 6. The words ERROR and EXCEPTION are equivalent and can be used interchangeably. For OSVS and VSC2 only: Formats 2 and 3 (Record Sequential, Relative. and Indexed Files) 7. If both BEGINNING and ENDING are omitted, the effect is as though both BEGINNING and ENDING had been specified. For OSVS and VSC2 only: Format 2 (Record Sequential Files). 8. REEL and UNIT are treated as equivalent. 9. If both FILE and REEL/UNIT are omitted, the effect is as though both REEL or UNIT and FILE had been specified. 10. Any one file-name and any one OPEN mode can appear in only one declarative for each of the possible combinations of BEGINNING/ENDING and FILE/REEL as shown below: BEGINNING FILE BEGINNING REEL/UNIT ENDING FILE ENDING REEL/UNIT General Rules. All Formats (All Files). 1. After execution of a USE procedure, control is returned to the invoking routine. 2. Within a USE procedure, there must not be any reference to any non-declarative procedures. Conversely, in the non-declarative portion there must be no reference to procedure-names that appear in the declarative portion, except that PERFORM statements can refer to a USE statement. 3. Within a USE procedure, there must be no execution of any statement that would cause the execution of a USE procedure that had previously been invoked and had not yet returned control to the invoking routine. Format 1 (Sequential, Relative and Indexed Files). 4. The designated procedures are executed by the input-output system after completing the standard input-output error routine, or upon recognition of the AT END condition, when the AT END phrase has not been specified in the input-output statement. 5. For ANS85 only: When file-name-1 is specified explicitly, no other USE statement applies to file-name-1. 6. The GIVING phrase is documentary only. For OSVS and VSC2 only: Formats 2 and 3 (Record Sequential, Relative. and Indexed Files) 7. The LABEL PROCEDURE declarative is never executed unless by an explicit PERFORM statement in the non-declarative portion of the Procedure Division. 8. The statement GO TO MORE-LABELS is treated as a simple jump to the start of the declarative procedure in which it appears. The WRITE Statement Function. The WRITE statement releases a logical record for an output or input-output file. For sequential files it can also be used for vertical positioning of lines within a logical page. For XOPEN only: Although they are a part of the standard COBOL definition, mnemonic names in the ADVANCING phrase are explicitly excluded from the X/Open COBOL language definitions and should not be used in X/Open COBOL source programs. General Formats. Format 1 and Line Sequential Files).For OSVS only: Format 2 (Record Sequential Files).For OSVS, MF and VSC2 only: Format 3 (Record Sequential Files).Format 4 (Relative and Indexed Files).Directives and Run-time Switches. 1. In addition to system directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or semantics described in this section. See yourCOBOL System Reference for details. * WRITE-LOCK - causes a WRITE statement to acquire a record lock when multiple recording locking is used. * FDCLEAR - causes the contents of the record area to be predictable after a WRITE statement. 2. The following run-time switches may impact the semantics described in this section. See your COBOL System Reference for details. * N - controls the insertion of null characters before control characters when writing line sequential records. * T - controls the insertion of tab characters when writing line sequential records. Syntax Rules. All Formats (All Files). 1. For ANS85 only: If identifier-1 is a function-identifier, it must reference an alpha- numeric function. When identifier-1 is not a function-identifier, record-name and identifier-1 must not reference the same storage area. 2. Record-name is the name of a logical record in the File Section of the Data Division and can be qualified. 3. For OSVS, VSC2 and MF only: Record-name can define a floating-point item . 4. For OSVS, VSC2 and MF only: Identifier-1 can be defined as a floating-point item . Format 1 (Record Sequential Files). 5. For MF only: When the mnemonic-name associated with TAB is specified the result is to cause the paper to throw to the standard vertical tabulation position. A user-defined mnemonic-name can be used instead of TAB if it is associated in the SPECIAL-NAMES paragraph. (See the section The SPECIAL-NAMES Paragraph.) 6. When identifier-2 is used in the ADVANCING phrase, it must be the name of an elementary integer data item. 7. Integer, or the value of the data item referenced by identifier-2, can be zero. 8. For VSC2 only: Integer can be signed. 9. If the END-OF-PAGE phrase is specified, the linage clause must be specified in the file description entry for the associated file. 10. The words END-OF-PAGE and EOP are equivalent. 11. The ADVANCING mnemonic-name phrase cannot be specified when writing a record to a file whose file description entry contains the LINAGE clause. 12. For ANS85 only: The phrases ADVANCING PAGE and END-OF-PAGE must not both be specified in a single WRITE statement. For MF only: This restriction can be ignored. For OSVS, VSC2 and MF only: Alternatively, function-name can itself be used instead of an associated mnemonic name. For OSVS only: Format 2 (Record Sequential Files). 13. This format cannot be specified when writing a record to a file whose file description entry contains the LINAGE clause. 14. If this format of the WRITE statement is used for writing to a given file, then every WRITE statement used for that file should be in this format. 15. In the AFTER POSITIONING phrase, identifier-2 must be defined as a single-character alphanumeric item. See General Rule 18 for its possible values. Format 4 (Relative And Indexed Files). 16. The INVALID KEY phrase must be specified if an applicable USE procedure is not specified for the associated file. For OSVS, VSC2 and MF only: This rule is not enforced. General Rules. All Formats (All Files). 1. The results of the execution of the WRITE statement with the FROM phrase is equivalent to the execution of: a. The statement: MOVE identifier-1 TO record-name according to the rules specified for the MOVE statement, followed by: b. The same WRITE statement without the FROM phrase. The contents of the record area prior to the execution of the implicit MOVE statement have no effect on the execution of this WRITE statement. After execution of the WRITE statement is complete, the information in the area referenced by identifier-1 is available, even though the information in the area referenced by record-name can not be. (See General Rule 13.) 2. The file position indicator is unaffected by the execution of a WRITE statement. 3. The execution of the WRITE statement causes the value of the FILE STATUS data item, if any, associated with the file to be updated. (See the section I/O Status earlier in this chapter.) 4. The maximum record size for a file is established at the time the file is created and must not subsequently be changed. 5. The number of character positions on a mass storage device to store a logical record in a file may or may not be equal to the number of character positions defined by the logical description of that record in the program. 6. The execution of the WRITE statement releases a logical record to the operating system. 7. For ANS85 only: If the execution of the WRITE statement is unsuccessful, the I/O status of the file-name associated with record-name is updated and control is transferred according to the rules of the USE statement following the execution of any USE AFTER EXCEPTION procedure applicable to the file-name associated with record-name. (See the section The USE Statement in this chapter.) Format 1 (Record Sequential Files). 8. If the logical end of the representation of the printed page is reached during the execution of a WRITE statement with the END-OF-PAGE phrase, the imperative-statement specified in the END-OF-PAGE phrase is executed. The logical end is specified in the LINAGE clause associated with record-name. 9. An end-of-page condition is reached whenever the execution of a given WRITE statement with the END-OF-PAGE phrase occurs, when the execution of such a WRITE statement causes the LINAGE-COUNTER to equal or exceed the value specified by integer-2 or the data item referenced by data-name-2 of the LINAGE clause, if specified. In this case, the WRITE statement is executed and then the imperative statement in the END-OF-PAGE phrase is executed. An automatic page overflow condition is reached whenever the execution of a given WRITE statement (with or without an END-OF-PAGE phrase) cannot be fully accommodated within the current page body. This occurs when a WRITE statement, if executed, would cause the LINAGE-COUNTER to exceed the value specified by integer-1 or the data item referenced by data-name-1 of the LINAGE clause. In this case, the record is presented on the logical page before or after (depending on the phrase used) the device is repositioned to the first line that can be written on the next logical page as specified in the LINAGE clause. The imperative statement in the END-OF-PAGE clause, if specified, is executed after the record is written and the device has been repositioned. If integer-2 or data-name-2 of the LINAGE clause is not specified, no end-of-page condition distinct from the page overflow condition is detected. In this case, the end-of-page condition and page overflow condition occur simultaneously. If integer-2 or data-name-2 of the LINAGE clause is specified, but the execution of a given WRITE statement would cause LINAGE-COUNTER to simultaneously exceed the value of both integer-2 or the data item referenced by data-name-2 and integer-1 or the data item referenced by data-name-1, then the operation proceeds as if integer-2 or data-name-2 had not been specified. For MF only: Format 1 (Line Sequential Files). 10. If the ADVANCING phrase is not used, automatic advancing of one line is provided to act in accordance with the convention of your operating system text editor (usually as if you had specified BEFORE ADVANCING 1 LINE). 11. When an attempt is made to write beyond the externally defined boundaries of a sequential file, an exception condition exists and the contents of the record area are unaffected. The following actions take place: a. The value of the FILE STATUS data item, if any, of the associated file is set to a value indicating a boundary violation. (See the section I/O Status in this chapter.) b. If a USE AFTER STANDARD EXCEPTION declarative is explicitly or implicitly specified for the file, that declarative procedure will be executed. c. If a USE AFTER STANDARD EXCEPTION declarative is not explicitly or implicitly specified for the file, the result will be undefined. 12. After the recognition of an end-of-unit of an output file that is contained on more than one physical reel/unit, the WRITE statement performs the following operations: a. The standard ending reel/unit procedure. b. The reel/unit swap. c. the standard beginning of reel/unit label procedure. 13. For XOPEN only: If you have a fixed length record fle, where records of different lengths are being redefined, you need to be aware that the enr\tire buffer area is written to the file. You might, therefore, need to space-fill if the current record is shorter than the previous one. 14. For ANS85 only: If, during the successful execution of a WRITE statement with the NOT END-OF-PAGE phrase, the end-of-page condition does not occur, control is transferred to imperative-statement-2 after execution of the input-ouput operation. Format 1 (Record and Line Sequential Files). 15. Both the ADVANCING phrase and the END-OF-PAGE phrase allow control of the vertical positioning of each line on a representation of a printed page. If the ADVANCING phrase is not used, automatic advancing is provided when output is directed to a list-device (PRINTER or PRINTER-1), to act as if the user had specified AFTER ADVANCING 1 LINE. If the ADVANCING phrase is used, advancing is provided as follows: a. If identifier-2 is specified, the representation of the printed page is advanced the number of lines equal to the current value associated with identifier-2. b. If integer is specified, the representation of the printed page is advanced in the number of lines equal to the value of integer. c. If mnemonic-name is specified, the representation of the printed page is advanced as specified under the SPECIAL-NAMES paragraph. d. If the BEFORE phrase is used, the line is presented before the representation of the printed page is advanced according to rules a, b, and c above. e. If the AFTER phrase is used, the line is presented after the representation of the printed page is advanced according to rules a, b, and c above. f. If PAGE is specified, the record is presented on the logical page before or after (depending on the phrase used) the device is repositioned to the next logical page. If the record to be written is associated with a record sequential file whose file description entry contains a LINAGE clause, the device is repositioned to the first line that can be written on the next logical page as specified in the LINAGE clause. 16. The phrases ADVANCING PAGE and END-OF-PAGE must not both be specified in a single WRITE statement. Formats 1, 2, and 3 (Sequential Files). 17. The associated file must be open in the OUTPUT or EXTEND mode at the time of the execution of this statement. (See the section The OPEN Statement in this chapter.) 18. The logical record released by the execution of the WRITE statement is no longer available in the record area unless the associated file is named in a SAME RECORD AREA clause or the execution of the WRITE statement was unsuccessful due to a boundary violation. The logical record is also available to the program as a record of other files referenced in the SAME RECORD AREA clause as the associated output file, as well as to the file associated with record-name. For OSVS only: Format 2 (Record Sequential Files). 19. When the AFTER POSITIONING phrase is used in a WRITE statement, the system will move a suitable character into the first position of the record before it is written to the file. This first character position must be reserved by the user for this purpose. If the identifier-2 option is used, then the character moved into the output record is simply the value held by identifier-2 and should be one of the following: Identifier-2 Interpretation (space) Single-spacing 0 Double-spacing - Triple-spacing + Suppress spacing 1-9 Skip to channel 1-9, respectively A, B, C Skip to channel 10, 11, 12, respectively V, W Pocket select 1 or 2 If the integer-1 option is used, then the character placed in the output record is determined as follows: Integer Output Character Interpretation 0 1 Skip to channel 1 1 (space) Single-space 2 0 Double-spacing 3 - Triple-spacing 20. The END-OF-PAGE phrase, if specified, is documentary and as such is never executed. For OSVS, VSC2, and MF only: Format 3 (Record Sequential Files). 21. When an attempt is made to write beyond the externally defined boundaries of a sequential file, an INVALID KEY condition occurs. When the INVALID KEY condition is recognized by the COBOL system, the execution of the WRITE statement is unsuccessful; the contents of the record area are unaffected, and the FILE STATUS data item, if any, of the associated file is set to a value indicating the cause of the condition. Execution of the program proceeds according to the rules stated in The INVALID KEY Condition in this chapter (see also the section I/O Status in this chapter). Format 4 (Relative and Indexed Files). 22. The associated file must be open in the OUTPUT, I/O or EXTEND mode at the time of execution of this statement; an indexed file must not be open in the I/O mode with sequential access mode. (See the sections The FILE-Control Entry and The OPEN Statement in this chapter.) 23. The logical record released by the execution of the WRITE statement is available in the record area only if the associated file is named in a SAME RECORD AREA clause, or the execution of the WRITE statement is unsuccessful due to an INVALID KEY condition. The logical record is also available to the program as a record of other files referenced in the same SAME RECORD AREA clause as the associated output file, as well as to the file associated with record-name. 24. When the INVALID KEY condition is recognized, the execution of the WRITE statement is unsuccessful; the contents of the record area are unaffected, and the FILE STATUS data item, if any, of the associated file is set to a value indicating the cause of the condition. Execution of the program proceeds according to the rules stated in The INVALID KEY Condition in this chapter (see also the section I/O Status in this chapter). Format 4 (Relative Files). 25. When a file is opened in the OUTPUT mode, records can be placed into the file by one of the following: a. If access mode is sequential, the WRITE statement will cause a record to be released to the operating system. The first record will have a relative record number of one and subsequent records released will have relative record numbers of 2, 3, 4,....If the RELATIVE KEY data item has been specified in the file control entry for the associated file, the relative record number of the record just released will be placed into the RELATIVE KEY data item by the operating system during execution of the WRITE statement. b. If access mode is random or dynamic, the value of the RELATIVE KEY data item must be initialized in the program, prior to the execution of the WRITE statement, with the relative record number, or be associated with the record in the record area. That record is then released to the operating system by execution of the WRITE statement. 26. When a file is opened in I/O mode and access mode is random or dynamic, the value of the RELATIVE KEY data item must be initialized by the program with the relative record number to be associated with the record in the record area. Execution of a WRITE statement then causes the contents of the record area to be released to the operating system. 27. The INVALID KEY condition exists under the following circumstances: a. When access mode is random or dynamic, and the RELATIVE KEY data item specifies a record which already exists in the file, or: b. When an attempt is made to write beyond the externally defined boundaries of the file. Format 4 (Indexed Files). 28. Execution of the WRITE statement causes the contents of the record area to be released. The operating system uses the contents of the record keys so that subsequent access of the record can be made via any of those specified record keys. 29. The value of the prime record key should be unique within the records in the file. 30. The data item specified as the prime record key must be set by the program to the desired value prior to the execution of the WRITE statement. 31. If sequential access mode is specified for the file, records must be released to the operating system in ascending order of prime record key values. 32. If random or dynamic access mode is specified, records can be released to the operating system in any program-specified order. 33. When the ALTERNATE RECORD KEY clause is specified in the file control entry for an indexed file, the value of the alternate record key can be non-unique only if the DUPLICATES phrase is specified for that data item. In this case, the operating system provides storage of records so that when records are accessed sequentially, those records are retrieved in the order in which they are released to the operating system. 34. The INVALID KEY condition exists under the following circumstances: a. When sequential access mode is specified for a file opened in OUTPUT mode, and the value of the prime record key is not greater than the value of the prime record key of the previous record, or: b. When the file is opened in OUTPUT or I/O mode, and the value of the prime record key is equal to the value of a prime record key of a record already existing in the file, or: c. When the file is opened in OUTPUT or I/O mode, and the value of an alternate record key for which duplicates are not allowed equals the corresponding data item of a record already existing in the file, or: d. When an attempt is made to write beyond the externally defined boundaries of the file. 35. For ANS85 only: Transfer of control following the successful or unsuccessful execution of the WRITE operation depends on the presence or absence of the INVALID KEY and NOT INVALID KEY phrases. (See the section Invalid Key Condition in this chapter.)
![[]](../../pic3k/M015064/FFN2923c50.gif)
![[]](../../pic3k/M015064/FFN2933c50.gif)
![[]](../../pic3k/M015064/FFN2943c50.gif)
![[]](../../pic3k/M015064/FFN2953c50.gif)
![[]](../../pic3k/M015064/FFN2963c50.gif)
![[]](../../pic3k/M015064/FFN2973c50.gif)
![[]](../../pic3k/M015064/FFN2983c50.gif)