4.6.45 The REWRITE Statement

The REWRITE statement logically replaces a record existing in a disk file.

General Formats

Format 1 (Line Sequential Files)

Format 2 (Record Sequential Files)

Format 2 (Relative and Indexed Files)

Directives and Run-time Switches

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or semantics described in this section.

  2. The following run-time switches may impact the semantics described in this section.

Syntax Rules

All Formats (All Files)
  1. (ANS85) If identifier is a function-identifier, it must reference an alphanumeric function. When identifier is not a function-identifier,

    record-name and identifier 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. (OSVS)(VSC2)(MF)Record-name can define a floating point or DBCS item.

  4. (OSVS)(VSC2)(MF)Identifier can be a USAGE DISPLAY-1 (DBCS) item or a floating- point item.
    Format 3 (Relative And Indexed Files)

  5. The INVALID KEY phrase must not be specified for a REWRITE statement which references a file in sequential access mode.

    (OSVS)(VSC2)However, it can be specified for an indexed file in sequential access mode.

  6. The INVALID KEY phrase must be specified in the REWRITE statement for files in the random or dynamic access mode for which an appropriate USE procedure is not specified.

General Rules

All Formats (All Files)
  1. The file associated with record-name must be a disk file and must be open in the I/O mode at the time of execution of this statement. (See the section The OPEN Statement earlier in this chapter.)

  2. For files in the sequential access mode the last input-output statement executed for the associated file prior to the execution of the REWRITE statement must have been a successfully executed READ statement. The operating system logically replaces the record that was accessed by the READ statement.

  3. The execution of a REWRITE statement with the FROM phrase is equivalent to the execution of: 
         MOVE identifier TO record-name

    followed by the execution of the same REWRITE 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 the REWRITE statement.

  4. The file position indicator is not affected by the execution of a REWRITE statement.

  5. The execution of the REWRITE 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.)

  6. (ANS85)The END-REWRITE phrase delimits the scope of the REWRITE statement.

  7. (MF)A REWRITE will not be successful if any other run unit holds a lock on the record to be rewritten.
Formats 1 and 2 (Sequential Files)
  1. The number of character positions in the record referenced by record-name must be equal to the number of character positions in the record being replaced.

  2. The logical record released by a successful execution of the REWRITE statement is no longer available in the record area unless the associated file is named in a SAME RECORD AREA clause. In this case, the record is still available to the program in the record area, not only as a record of this file, but also as a record of other files named in the SAME RECORD AREA clause.
Format 1 (Line Sequential Files)
  1. (MF)The REWRITE statement can be used and is considered successful whenever the record being written (after compacting by removing trailing spaces, tab compression and null insertion) is less than or equal to the length of the original compacted record. When a record is read, nulls and tab characters in the record can be expanded and this makes the record longer.
Format 3 (Relative And Indexed Files)
  1. The logical record released by a successful execution of the REWRITE statement is no longer available in the record area unless the associated file is named in a SAME RECORD AREA clause, in which case the logical record is available both to the program as a record of other files appearing in the same SAME RECORD AREA clause as the associated I/O file, as well as to the file associated with record-name.
Format 3 (Relative Files)
  1. For a file accessed in either random or dynamic access mode, the operating system logically replaces the record specified by the contents of the RELATIVE KEY data item associated with the file. If the file does not contain the record specified by the key, the INVALID KEY condition exists. (See the section The INVALID KEY Condition in this chapter.) The updating operation does not take place and the data in the record area is unaffected.
Format 3 (Indexed Files)
  1. For a file in sequential access mode, the record to be replaced is specified by the value contained in the prime record key. When the REWRITE statement is executed, the value contained in the prime record data item of the record to be replaced must be equal to the value of the prime record key of the last record read from this file.

  2. For a file in random or dynamic access mode, the record to be replaced is specified by the prime record key data item.

  3. The contents of alternate record key data items of the record being rewritten can differ from those in the record being replaced. The operating system uses the contents of the record key data items during execution of the REWRITE statement so that the record can subsequently be accessed via any of those specified record keys.

  4. The INVALID KEY condition exists when:

    1. Access mode is sequential and the value contained in the prime record key data item of the record to be replaced is not equal to the value of the prime record key of the last record read from this file, or:

    2. The value contained in the prime record key data item does not equal that of any record stored in the file, or:

    3. The value contained in an alternate record key data item for which a DUPLICATES clause has not been specified is equal to that of a record already stored in the file.

    The updating operation will not take place and the data in the record area will be unaffected. (See the section The INVALID KEY Condition in this chapter.)

4.6.46 The ROLLBACK Statement

(MF)

The ROLLBACK statement releases all record locks in all files held by this run unit. For COBOL systems that support the WITH...ROLLBACK clause of the SELECT statement as other than documentary, the ROLLBACK statement indicates the end of the current transaction and the effects of that transaction are cancelled.

General Format

General Rules

  1. Execution of the ROLLBACK statement causes all record locks in all files held by the run-unit to be released.

  2. The file lock on an exclusive file is not affected by the ROLLBACK statement.

  3. If your COBOL system supports the WITH ROLLBACK clause of the SELECT statement as other than documentary, then the ROLLBACK verb:

    1. Indicates completion of the current transaction

    2. Ensures all changes applied during the transaction are cancelled.

4.6.47 The SEARCH Statement

The SEARCH statement is used to search a table for a table element that satisfies the specified condition and to adjust the associated index-name to indicate that table element.

General Format

Format 1

Format 2

Note that the required relational character "=" is not underlined to avoid confusion with other symbols.

Syntax Rules

All Formats (All Files)
  1. Identifier-1 must not be subscripted or indexed, but its description must contain an OCCURS clause and an INDEXED BY clause. The description of identifier-1 in Format 2 must also contain the KEY IS phrase in its OCCURS clause.

  2. Identifier-2, when specified, must be described as USAGE IS INDEX or as a numeric elementary item without any positions to the right of the assumed decimal point.

  3. (ANS85)If the END-SEARCH phrase is specified, the NEXT SENTENCE phrase must not be specified.

    (VSC2)(MF)END-SEARCH can be specified with NEXT SENTENCE. If the NEXT SENTENCE phrase is executed, control will not pass to the next statement following the END-SEARCH, but instead will pass to the statement after the closest following period.

  4. (MF)Both imperative-statement-1 and imperative-statement-2 can be replaced by a conditional statement.
Format 1
  1. Condition-1, condition-2, and so on, can be any condition as described in the section Conditional Expressions earlier in this chapter.

  2. (OSVS)(VSC2)(MF)Identifier-1, the table element being searched, can be an internal or external floating-point item.
Format 2
  1. All referenced condition-names must be defined as having only a single value. The data-name associated with a condition-name must appear in the KEY clause of identifier-1. Each data-name-1, data-name-2 can be qualified. Each data-name-1, data-name-2 must be indexed by the first index-name associated with identifier-1 along with other indices or literals as required, and must be referenced in the KEY clause of identifier-1. Identifier-3, identifier-4, or identifiers specified in arithmetic-expression-1, arithmetic-expression-2 must not be referenced in the KEY clause of identifier-1 or be indexed by the first index-name associated with identifier-1.

    When a data-name in the KEY clause of identifier-1 is referenced, or when a condition-name associated with a data-name in the KEY clause of identifier-1 is referenced, all preceding data-names in the KEY clause of identifier-1 or their associated condition-names must also be referenced.

  2. (OSVS)(VSC2)(MF)Identifier-1, the table element being searched, can not be a floating-point item.

  3. (OSVS)(VSC2)(MF)Neither data-name-1 nor data-name-2, the key data items, can be floating point items. However, identifier-3, identifier-4, literal-1, or literal-2, the items against which the key is compared, can be floating-point items.

General Rules

All Formats
  1. The scope of a SEARCH statement can be terminated by any of the following:

    1. (ANS85)An END-SEARCH phrase at the same level of nesting.

    2. separator period.

    3. An ELSE

      (ANS85)or END-IF

      associated with a previous IF statement.

  2. After execution of imperative-statement-1 or imperative-statement-2, that does not terminate with a GO TO statement, control passes to the next executable sentence.

  3. If identifier-1 is a data item subordinate to a data item that contains an OCCURS clause (providing for a two or three dimensional table), an index-name must be associated with each dimension of the table through the INDEXED BY phrase of the OCCURS clause. Only the setting of the index-name associated with identifier-1 (and the data item identifier-2 or index-name-1, if present) is modified by the execution of the SEARCH statement. To search an entire two or three dimensional table it is necessary to execute a SEARCH statement several times. Prior to each execution of a SEARCH statement, SET statements must be executed whenever index-names must be adjusted to appropriate settings.
Format 1
  1. If Format 1 of the SEARCH is used, a serial type of search operation takes place, starting with the current index setting.

    1. If, at the start of execution of the SEARCH statement, the index-name associated with identifier-1 contains a value that corresponds to an occurrence number that is greater than the highest permissible occurrence number for identifier-1, the SEARCH is terminated immediately. The number of occurrences of identifier-1, the last of which is the highest permissible, is discussed in the OCCURS clause. (See the section The OCCURS Clause earlier in this chapter.) Then, if the AT END phrase is specified, imperative- statement-1 is executed; if the AT END phrase is not specified, control passes to the next executable sentence.

    2. If, at the start of execution of the SEARCH statement, the index-name associated with identifier-1 contains a value that corresponds to an occurrence number that is not greater than the highest permissible occurrence number for identifier-1 (the number of occurrences of identifier-1, the last of which is the highest permissible is discussed in the OCCURS clause), the SEARCH statement operates by evaluating the conditions in the order that they are written, making use of the index settings, wherever specified, to determine the occurrence of those items to be tested. If none of the conditions is satisfied, the index name for identifier-1 is incremented to obtain reference to the next occurrence. The process is then repeated using the new index-name settings unless the new value of the index-name settings for identifier-1 corresponds to a table element outside the permissible range of occurrence values, in which case the search terminates as indicated in General Rule 1a above. If one of the conditions is satisfied upon its evaluation, the search terminates immediately and the imperative statement associated with that condition is executed; the index-name remains set at the occurrence which caused the condition to be satisfied.

  2. If the VARYING phrase is not used, the index-name that is used for the search operation is the first (or only) index-name that appears in the INDEXED BY phrase of identifier-1. Any other index-names for identifier-1 remain unchanged.

  3. If the VARYING index-name-1 phrase is specified, and if index-name-1 appears in the INDEXED BY phrase of identifier-1, that index-name is used for this search. If this is not the case, or if the VARYING identifier-2 phrase is specified, the first (or only) index-name given in the INDEXED BY phrase of identifier-1 is used for the search. In addition, the following operations will occur:

    1. If the VARYING index-name-1 phrase is used, and if index-name-1 appears in the INDEXED BY phrase of another table entry, the occurrence number represented by index-name-1 is incremented by the same amount as, and at the same time as, the index-name associated with identifier-1 is incremented.

    2. If the VARYING identifier-2 phrase is specified, and identifier-2 is an index data item, then the data item referenced by identifier-2 is incremented by the same amount as, and at the same time as, the index associated with identifier-1 is incremented. If identifier-2 is not an index data item, the data item referenced by identifier-2 is incremented by the value (1) at the same time as the index referenced by the index-name associated with identifier-1 is incremented.
Format 2
  1. The results of the SEARCH ALL operation are predictable only when:

    1. The data in the table is ordered in the same manner as described in the ASCENDING/DESCENDING KEY clause associated with the description of identifier-1, and:

    2. The contents of the key(s) referenced in the WHEN clause are sufficient to identify a unique table element.

  2. If Format 2 of the SEARCH is used, a non-serial type of search operation can take place; the initial setting of the index-name for identifier-1 is ignored and its setting is varied during the search operation with the restriction that at no time is it set to a value that exceeds the value which corresponds to the last element of the table, or that is less than the value that corresponds to the first element of the table. The length of the table is discussed in the OCCURS clause. If any of the conditions specified in the WHEN clause cannot be satisfied for any setting of the index within the permitted range, control is passed to imperative-statement-1 of the AT END phrase, when specified, or to the next executable sentence when this phrase is not specified; in either case the final setting of the index is not predictable. If all conditions can be satisfied, the index indicates an occurrence that allows the conditions to be satisfied, and control passes to imperative-statement-2.

  3. The index-name that is used for the search operation is the first (or only) index-name that appears in the INDEXED BY phrase of identifier-1. Any other index-names for identifier-1 remain unchanged.

  4. (OSVS)(VSC2)(MF)Neither imperative-statement-2 nor NEXT SENTENCE is required. Without them, the SEARCH statement sets the index to the value in the table that matched the condition.

Figure 4-5 shows a flowchart of the Format 1 SEARCH operation containing two WHEN phrases.

*

Figure 4-1: Flowchart of SEARCH Operation Showing Two WHEN Phrases

1 These operations are options included only when specified in the SEARCH statement.
2 Each of these control transfers is to the next executable sentence unless the imperative-statement ends with a GO TO statement.

4.6.48 The SERVICE Statement

(OSVS)(VSC2)

The SERVICE statement is used to establish addressability to Linkage Section items usually in a CICS program.

General Format

Syntax Rules

  1. SERVICE LABEL is generated by the mainframe CICS preprocessor to indicate control flow. It is not intended for general use.

  2. The SERVICE LABEL statement can appear only in the Procedure Division, not in the Declaratives Section.

  3. Identifier should be either the first 01-level item representing the BLL-cell block in the Linkage Section, or another Linkage Section 01-level item for which addressability needs to be re-established following an EXEC CICS statement.

General Rules

  1. At the statement following the SERVICE LABEL statement, all registers that can no longer be valid are reloaded.

  2. If the OS/VS COBOL BLL mechanism is used in a CICS program, addressability to the parameter list must be established at the start of the Procedure Division. This is done by adding a SERVICE RELOAD identifier statement at the start of the Procedure Division where the identifier is the first item in Linkage Section and it includes pointers to all other entries in the Linkage Section.

  3. If a locate-mode EXEC CICS statement is included in a program compiled with the OSVS Compiler directive, then a SERVICE RELOAD statement must follow each such CICS command and the identifier must be the same pointer (BLL-cell reference) used in the CICS command.

  4. In a CICS program compiled with the OSVS Compiler directive, any time a reference is made to a Linkage Section which is greater than 4096 bytes long, a SERVICE RELOAD statement should be made to re-establish addressability to that portion of the data item greater than 4096 byte.

  5. The SERVICE RELOAD statement is documentary only in a program compiled with the VSC2 Compiler directive.

4.6.49 The SET Statement

  1. (ANS85)The SET statement is used to alter the status of external switches.

  2. (ANS85)The SET statement is used to alter the value of conditional variables.

  3. (VSC2)(MF)The SET statement is used to assign the address of a data item to a pointer data item. It is also used to adjust the contents of a pointer data item.

  4. The SET statement establishes reference points for table handling operations by setting indices associated with table elements.

  5. (MF)The SET statement is used to assign the address of a program or an entry-point in a program to a procedure-pointer data item.

General Formats

Format 1

Format 2

Format 3

Format 4

Format 5

Format 6

Format 7

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or semantics described in this section.

Syntax Rules

All Formats
  1. The figurative constant NULL or NULLS or the data item referenced by pointer-name-2 or procedure-pointer-name-2 represents the sending area. ADDRESS OF identifier-2, ENTRY identifier-8, ENTRY literal-1 or the value held in the sending area, represents the sending value.

    The data item referenced by pointer-name-1, pointer-name-3 or procedure-pointer-name-1 or the COBOL system area implied by ADDRESS OF identifier-1 represents the receiving area.

    Identifier-3, integer-1 or LENGTH OF identifier-4 represents the increment value.

Format 1
  1. (ANS85)Mnemonic-name-1 must be associated with an external switch, the status of which can be altered.

    (MF)See the section The Special-Names Paragraph for details of which external switches can be referenced in the SET statement.

Format 2
  1. (ANS85)Condition-name-1 must be associated with a conditional variable.

  2. (MF)If the FALSE phrase is specified, the FALSE phrase must be specified in the VALUE clause of the Data Description entry for condition-name-1.

  3. (MF)Each FALSE or TRUE phrase applies to the occurrences of condition-name-1 that precede that phrase and follow a previous FALSE or TRUE phrase, if any.
Format 3
  1. (VSC2)(MF)Identifier-1 must reference a level 01 or level 77 data item that is declared in the Linkage Section.

  2. (VSC2)(MF)Identifier-2 must reference a data item with a level of 77 or between 01 and 49 inclusive

    (VSC2) that is declared in the Linkage-Section.

  3. (VSC2)(MF)Pointer-name-1, pointer-name-2 must each be an identifier that references an elementary data item with USAGE IS POINTER.
Format 4
  1. (MF)Pointer-name-3 must be an identifier that references an elementary data item with USAGE IS POINTER.

  2. (MF)Identifier-3 must be an elementary numeric integer.

  3. (MF)Integer-1 may be signed.
Format 5
  1. Identifier-5 and identifier-6 must each reference an index data item or an elementary item described as an integer. If both are specified, they must not both reference an elementary item.
Formats 5 and 6
  1. Integer-2 and integer-3 may be signed. Integer-2 must be positive.
Format 6
  1. Identifier-7 must reference an elementary numeric integer.
Format 7
  1. (MF)Procedure-pointer-name-1 and procedure-pointer-name-2 must each be an identifier that references an elementary data item with USAGE IS PROCEDURE-POINTER.

  2. (MF)Identifier-8 must be defined as an alphanumeric data item such that its value can be a COBOL or a non-COBOL program name.

  3. (MF)Literal-1 must be a nonnumeric literal.

General Rules

Format 1
  1. (ANS85)The status of each external switch associated with the specified mnemonic-name-1 is modified such that the truth value resulting from evaluation of a condition-name associated with that switch will reflect an on status if the ON phrase is specified, or an off status if the OFF phrase is specified. (See the section Switch-Status Condition earlier in this chapter.)
Format 2
  1. (ANS85)The literal in the VALUE clause associated with condition-name-1 is placed in the conditional variable according to the rules of the VALUE clause (see the section The VALUE Clause earlier in this chapter.) If more than one literal is specified in the VALUE clause, the conditional variable is set to the value of the first literal that appears in the VALUE clause.

  2. (ANS85)If multiple condition-names are specified, the results are the same as if a separate SET statement had been written for each condition-name-1 in the same order as specified in the SET statement.

  3. (MF)If the FALSE phrase is specified, the literal in the FALSE phrase of the VALUE clause associated with condition-name-1 is placed in the conditional variable according to the rules for the VALUE clause. (See the section The VALUE Clause earlier in this chapter.)
Format 3
  1. (VSC2)(MF)The sending value represents the address of a data item. If pointer-name-2 is specified, the sending value is the value contained with the data item referenced by pointer-name-2. If ADDRESS OF identifier-2 is specified, the sending value represents the address of identifir-2.

  2. (VSC2)(MF)If pointer-name-1 is specified, the sending value is moved to the data name referenced by pointer-name-1.

  3. (VSC2)(MF)If ADDRESS OF identifier-1 is specified, the sending value is moved to a COBOL system area and the object program subsequently operates such that the area of storage referenced by identifier-1 is located at the address represented by the sending value.

    (MF)Whether or not the link is retained between invocations of a subprogram is dependent on the STICKY-LINKAGE Compiler directive.

Format 4
  1. (MF)Before execution of the SET statement, the value of the data item referenced by pointer-name-3 must represent the address of a data item within a logical record, the original address. After execution of the SET statement, the value of the data item referenced by pointer-name-3 represents the new address. If the original address and the new address do not both lie within the same logical record, (or, for environments in which address space is segmented, within the same segment) then the results of using the value of the data item referenced by pointer-name-3 are undefined.

  2. (MF)If the UP clause is specified, the new address is formed by adding the number of bytes given by the increment value to the original address.

  3. (MF)If the DOWN clause is specified, the new address is formed by subtracting the number of bytes given by the increment value from the original address.
Format 5

    1. Index-name-1 is set to a value causing it to refer to the table element that corresponds in occurrence number to the table element referenced by index-name-2, identifier-6, or integer-2. If identifier-6 references an index data item, or if index-name-2 is related to the same table as index-name-1, no conversion takes place.

    2. If identifier-5 references an index data item, it can be set equal to either the contents of index-name-2 or identifier-6 where identifier-6 also references an index item; no conversion takes place in either case.

    3. If identifier-5 does not reference an index data item, it can be set only to an occurrence number that corresponds to the value of index-name-2. Neither identifier-6 nor integer-2 can be used in this case.

    4. The process is repeated for all recurrence of index-name-1, or identifier-5, if specified. Each time the value of index-name-2 or identifier-6 is used as it was at the beginning of the execution of the statement. Any subscripting or indexing associated with identifier-5 and so on is evaluated immediately before the value of the respective data item is changed.

  2. Data in the following table represents the validity of various operand combinations in the SET statement. The general rule reference indicates the applicable general rule.

    Table 4-17: SET Index Statement Valid Operand Combinations

    Sending Item Receiving Item
    Integer Data Item Index-Name Index Data Item
    Integer Literal No/9c Valid/9a No/9b
    Integer Data Item No/9c Valid/9a No/9b
    Index-Name Valid/9c Valid/9a Valid/9b1
    Index Data Item No/9c Valid/9a1 Valid/9b1

    1 = No conversion takes place.

Formats 5 and 6
  1. Index-names are associated with a given table by being specified in the INDEXED BY phrase of the OCCURS clause for that table.

  2. If index-name-1 is specified, the value of the index after the execution of the SET statement must correspond to an occurrence number of an element in the table associated with index-name-1. The value of the index associated with an index-name after the execution of a PERFORM or SEARCH statement may be set to an occurrence number that is outside the range of its associated table. (See the sections The PERFORM Statement and The SEARCH Statement earlier in this chapter.)

    If index-name-2 is specified, the value of the index before the execution of the SET statement must correspond to an occurrence number of an element in the table associated with index-name-1.

    If index-name-3 is specified, the value of the index both before and after the execution of the SET statement must correspond to an occurrence number of an element in the table associated with index-name-3.

Format 6
  1. The contents of index-name-3 are incremented (UP BY) or decremented (DOWN BY) by a value that corresponds to the number of occurrences represented by the value of integer-3 or the data item referenced by identifier-7; thereafter, the process is repeated for each recurrence of index-name-3. For each repetition, the value of the data item referenced by identifier-7 is used as it was at the beginning of the execution of the statement.
Format 7
  1. (MF)The sending value represents the address of the start of a procedure within a COBOL or non-COBOL program.

  2. (MF)The sending value is moved to the data item referenced by procedure-pointer-name-1.

  3. (MF)If procedure-pointer-name-2 is specified, the sending value is the value contained within the data item referenced by procedure-pointer-name-2.

  4. (MF)Literal-1 or the content of the data item referenced by identifier-8 is the name of the referenced procedure. If the referenced procedure is a COBOL procedure, the name of the referenced procedure must contain the program-name contained in the PROGRAM-ID paragraph of the referenced program or the entry-name contained in the ENTRY statement of the referenced procedure.

    (MF)If the program being called is not a COBOL program, the rules for the formation of the program or procedure name are given in your COBOL system documentation on interfacing.

    (MF)If the referenced procedure has been previously made available and remains available at the time of execution of the SET statement, then the sending value represents the address of the referenced procedure.

    (MF)If the referenced procedure is not available at the time of execution of the SET statement, then the sending value represents the address of a COBOL system error procedure.

4.6.50 The SORT Statement

The SORT statement creates a sort file by executing input procedures or by transferring records from another file, sorts the records in the sort file on a set of specified keys, and in the final phase of the sort operation, makes available each record from the sort file, in sorted order to some output procedures or to an output file.

(MF)The SORT statement can also be used to sort the elements of a table.

Examples:

  1. Examples of using the SORT verb with input and output procedures to order elements in a file are provided in the Examples chapter in your Language Reference - Additional Topics.

  2. Examples of using the SORT verb to order elements in a table are provided in the Examples chapter in your Language Reference - Additional Topics.

General Formats

Format 1

Format 2

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or semantics described in this section.

Syntax Rules

All Formats
  1. A Format 1 SORT statement cannot appear in the declaratives portion of the Procedure Division, or in an input or output procedure associated with a SORT or MERGE statement.

    (MF)A Format 2 SORT can appear in the Declaratives Section.

  2. Data-name-1 is a KEY data-name and is subject to the following rules:

    1. KEY data-names can be qualified.

    2. The data items identified by KEY data-names must not be variable length items.

    3. KEY data items can be floating-point items.

    4. (OSVS)(VSC2)(MF)If the KEY is an external floating-point item, the compiler will treat the data item as character data, rather than numeric data. The sequence in which the records are sorted depends on the collating sequence used.

    5. (OSVS)(VSC2)(MF)If the KEY data item is internal floating-point, the sequence of key values will be in numeric order.
Format 1
  1. File-name-1 must be described in a Sort-Merge File Description entry in the Data Division.

  2. Data-name-1 is a KEY data-name and is subject to the following rules:

    1. The data items identified by KEY data-names must be described in records associated with file-name-1.

    2. If file-name-1 has more than one record description, then the data items identified by KEY data-names need be described in only one of the record descriptions.

    3. None of the data items identified by KEY data-names can be described by an entry which either contains an OCCURS clause or is subordinate to an entry which contains an OCCURS clause.

    4. If the file referenced by file-name-1 contains variable length records, all the data items identified by key data-names must be contained within the first x character positions of the record, where x equals the minimum record size specified for the file referenced by file-name-1.

  3. The words THRU and THROUGH are equivalent.

  4. File-name-2 and file-name-3 must be described in the file description entry, not in a sort-merge file description entry, in the Data Division.

  5. (ANS85)The files referenced by file-name-2 and file-name-3 can reside on the same multiple file reel.

  6. (ANS85)If file-name-3 references an indexed file, the first specification of data-name-1 must be associated with an ASCENDING phrase and the data item referenced by that data-name-1 must occupy the same character positions in its record as the data item associated with the prime record key for that file.

  7. No pair of file-names in the same SORT statement can be specified in the SAME SORT AREA or SAME SORT-MERGE AREA clause. File-names associated with the GIVING phrase can not be specified in the same SAME clause.

  8. (ANS85)If the GIVING phrase is specified and the file referenced by file-name-3 contains variable length records, the size of the records contained in the file referenced by file-name-1 must not be less than the smallest record nor larger than the largest record described for file-name-3. If the file referenced by file-name-3 contains fixed length records, the size of the records contained in the file referenced by file-name-1 must not be larger than the largest record described for the file referenced by file-name-3.

    (ANS85)If the data descriptions of the elementary items that make up these records are not identical, it is the programmer's responsibility to describe the corresponding records in such a manner as to cause equal amounts of character positions to be allocated for the corresponding records.

  9. (ANS85)If the USING phrase is specified and the file referenced by file-name-1 contains variable length records, the size of the records contained in the file referenced by file-name-2 must not be less than the smallest record nor larger than the largest record described for file-name-1. If the file referenced by file-name-1 contains fixed length records, the size of the records contained in the file referenced by file-name-2 must not be larger than the largest record described for the file referenced by file-name-1.

  10. Procedure-name-1 represents the name of an input procedure. Procedure-name-3 represents the name of an output procedure.

  11. Procedure-name-1, procedure-name-2, procedure-name-3 and procedure-name-4 must be section-names.

    (ANS85)(OSVS)This restriction is removed.

  12. If you want to specify more than 10 file-names in the USING or GIVING clause, you must use the Compiler directive CALLSORT"EXTSM"; this allows you to specify up to 255 files.
Format 2
  1. (MF)Data-name-2 can be qualified and must have an OCCURS clause in the data description entry.

  2. (MF)The data item referenced by data-name-1 must be the same as the data item referenced by data-name-2, or an entry subordinate to the data item referenced by data-name-2.

  3. (MF)Unless data-name-1 and data-name-2 are the same, the data item referenced by data-name-1 must not be described by an entry containing an OCCURS clause. The data item referenced by data-name-1 must not be subordinate to an entry containing an OCCURS clause that is also subordinate to data-name-2.

  4. (MF)The KEY phrase can be omitted only if the description of the table referenced by data-name-2 contains a KEY phrase.

  5. (MF)If data-name-2 references a data item subordinate to a data item that contains an OCCURS clause, an index-name must be associated with each data item containing an OCCURS clause to which the data item referenced by data-name-2 is subordinate.

General Rules

All Formats
  1. The words ASCENDING and DESCENDING are transitive across all occurrences of data-name-1 until another word ASCENDING or DESCENDING is encountered.

  2. The data items referenced by the specifications of data-name-1 are the key data items which determine the order in which records are returned from the file referenced by file-name-1 or the order in which the table elements are stored after sorting takes place. The order of significance of the keys is the order in which they are specified in the SORT statement, without regard to their association with ASCENDING or DESCENDING phrases.

  3. If the DUPLICATES phrase is specified and the contents of all the key data items associated with one data record or table element are equal to the contents of the corresponding key data items associated with one or more other data records or table elements, the order of return of these records is:

    1. The order of the associated input files as specified in the SORT statement, or by means of a run-time switch. Within a given input file the order is that in which the records are accessed from that file.

    2. The order in which these records are released by an input procedure, when an input procedure is specified.

    3. The relative order of the contents of these table elements before sorting takes place.

  4. If the DUPLICATES phrase is not specified and the contents of all the key data items associated with one data record or table element are equal to the contents of the corresponding key data items associated with one or more other data records or table elements, the order of return of these records or the relative order of the contents of these table elements is undefined.

  5. The collating sequence that applies to the comparison of the nonnumeric key data items specified is determined at the beginning of the execution of the SORT statement in the following order of precedence:

    1. First, the collating sequence established by the COLLATING SEQUENCE phrase, if specified, in the SORT statement.

    2. Second, the collating sequence established as the program collating sequence.
Format 1
  1. The SORT statement releases all the records in the file referenced by file-name-2 or released by an input procedure to the file referenced by file-name-1, and returns them to an output procedure, or to the file referenced by file-name-3, in an order determined by the ASCENDING and DESCENDING phrases and the values of the data items referenced by the specifications of data-name-1.

  2. To determine the relative order in which two records returned from the file referenced by file-name-1, the contents of corresponding key data items are compared according to the rules for comparison of operands in a relation condition, starting with the most significant key data item:

    1. If the contents of the corresponding key data items are not equal and the key is associated with the ASCENDING phrase, the record containing the key data item with the lower value is returned first.

    2. If the contents of the corresponding key data items are not equal and the key is associated with the DESCENDING phrase, the record containing the key data item with the higher value is returned first.

    3. If the contents of the corresponding key data items are equal, the determination is made on the contents of the next most significant key data item.

  3. The execution of the SORT statement consists of three distinct phases as follows:

    1. Records are made available to the file referenced by file-name-1. This is achieved either by the execution of RELEASE statements in the input procedure or by the implicit execution of READ statements for file-name-2. When this phase commences, the file referenced by file-name-2 must not be in the open mode. When this phase terminates, the file referenced by file-name-2 is not in the open mode.

    2. The file referenced by file-name-1 is sequenced. No processing of the files referenced by file-name-2 and file-name-3 takes place during this phase.

    3. The records of the file referenced by file-name-1 are made available in sorted order. The sorted records are either written to the file referenced by file-name-3, or, by the execution of a RETURN statement, are made available for processing by the output procedure. When this phase commences, the file referenced by file-name-3 must not be in the open mode. When this phase terminates, the file referenced by file-name-3 is not in the open mode.

  4. The input procedure can consist of any procedure needed to select, modify or copy the records that are made available one at a time by the RELEASE statement to the file referenced by file-name-1. The range includes all statements that are executed as a result of a transfer of control by CALL, EXIT without the optional PROGRAM phrase, GO TO and PERFORM statements in the range of the input procedure. The range of the input procedure must not cause the execution of any MERGE, RETURN or SORT statement.

  5. If an input procedure is specified, control is passed to the input procedure before the file referenced by file-name-1 is sequenced by the SORT statement. The compiler inserts a return mechanism at the end of the last statement in the input procedure and when control passes the last statement in the input procedure, the records that have been released to the file referenced by file-name-1 are sorted.

  6. If the USING phrase is specified, all the records in the file(s) referenced by file-name-2 are transferred to the file referenced by file-name-1. For each of the files referenced by file-name-2 the execution of the SORT statement causes the following actions to be taken:

    1. The processing of the file is initiated. The initiation is performed as if an OPEN statement with the INPUT and the WITH LOCK phrases had been executed.

    2. The logical records are obtained and released to the sort operation. Each record is obtained as if a READ statement with the NEXT and AT END phrases had been executed. If the file referenced by file-name-1 contains fixed length records, any record in the file referenced by file-name-2 containing fewer character positions than that specified for file-name-1 is space-filled on the right, beginning with the first character position after the last character in the record, when that record is released to the file referenced by file-name-1. If the file referenced by file-name-1 is described with variable-length records, the size of any record written to file-name-1 is the size of that record when it was read from file-name-2 or file-name-3, regardless of the contents of the data item referenced by a RECORD VARYING DEPENDING ON or OCCURS DEPENDING ON clause specified in the File Description entry for file-name-1.

    3. The processing of the file is terminated. The termination is performed as if a CLOSE statement without optional phrases had been executed. This termination is performed before the file referenced by file-name-1 is sequenced by the SORT statement.

      For a relative file, the content of the Relative Key data item is undefined after the execution of a SORT statement if file-name-2 is not referenced in the GIVING phrase.

      These implicit functions are performed such that any associated USE AFTER EXCEPTION procedures are executed; however, the execution of such a USE procedure must not cause the execution of any statement manipulating the file referenced by file-name-2 or accessing the record area associated with file-name-2.

      The value of the data item referenced by a RECORD VARYING DEPENDING ON clause specified in the File Description entry for file-name-2 is undefined upon completion of the SORT statement.

  7. The output procedure can consist of any procedure needed to select, modify or copy the records that are made available one at a time by the RETURN statement in sorted order from the file referenced by file-name-1. The range includes all statements that are executed as a result of a transfer of control by CALL, EXIT without the optional PROGRAM phrase, GO TO and PERFORM statements in the range of the output procedure, as well as all statements in the Declarative procedures that are executed as a result of the execution of statements in the range of the output procedure. The range of the input procedure must not cause the execution of any MERGE, RELEASE or SORT statement.

  8. If an output procedure is specified, control passes to it after the file referenced by file-name-1 has been sequenced by the SORT statement. The compiler inserts a return mechanism at the end of the last statement in the output procedure and when control passes the last statement in the output procedure, the return mechanism provides for termination of the sort and then passes control to the next executable statement after the SORT statement. Before entering the output procedure, the sort procedure reaches a point at which it can select the next record in sorted order when requested. The RETURN statements in the output procedure are the requests for the next record.

  9. If the GIVING phrase is specified, all the sorted records are written on the file referenced by file-name-3 as the implied output procedure for the SORT statement. For each of the files referenced by file-name-3, the execution of the SORT statement causes the following actions to be taken:

    1. The processing of the file is initiated. The initiation is performed as if an OPEN statement with the OUTPUT phrase had been executed. This initiation is performed after the execution of any input procedure.

    2. The logical records are returned and written onto the file. The records are written as if a WRITE statement without any optional phrases had been executed. If the file referenced by file-name-3 is described with fixed-length records, any record in the file referenced by file-name-1 containing fewer character positions than that specified for file-name-3 is space-filled on the right, beginning with the first character position after the last character in the record, when that record is returned to the file referenced by file-name-3. If the file referenced by file-name-3 is described with variable-length records,the size of any record written to file-name-3 is the size of that record when it was read from file-name-1, regardless of the contents of the data item referenced by a RECORD VARYING DEPENDING ON or OCCURS DEPENDING ON clause specified in the File Description entry for file-name-3.

      For a relative file, the Relative Key data item for the first record returned contains the value "1"; for the second record returned, the value "2", and so on. The content of the Relative Key data item is undefined after execution of a SORT statement.

    3. The processing of the file is terminated. The termination is performed as if a CLOSE statement without optional phrases had been executed.

      These implicit functions are performed such that any associated USE AFTER EXCEPTION procedures are executed; however, the execution of such a USE procedure must not cause the execution of any statement manipulating the file referenced by file-name-3 or accessing the record area associated with file-name-3. On the first attempt to write beyond the externally-defined boundaries of a file, the USE AFTER EXCEPTION procedure, if any, associated with the file is executed; if control is returned as specified by the rules of the USE statement, no additional implicit write operations are executed for that file and the processing of the file is terminated as specified in this part.

    The value of the data item referenced by a RECORDING VARYING DEPENDING ON clause specified in the File Description entry for file-name-1 is undefined upon completion of the SORT statement for which the GIVING phrase is specified.

  10. Segmentation, as defined in the chapter Segmentation in your Language Reference - Additional Topics, can be applied to programs containing the SORT statement. However, the following restrictions apply:

    1. If a SORT statement appears in a section that is not in an independent segment, then any input procedures or output procedures referenced by that SORT statement must appear:

      • Totally within non-independent segments, or

      • Wholly contained in a single independent segment.

    2. If a SORT statement appears in an independent segment, then any input procedures or output procedures referenced by that SORT statement must be contained:

      • Totally within non-independent segments, or

      • Wholly within the same independent segment as that SORT statement.

  11. (OSVS)(VSC2)(MF)The SORT-RETURN special register is available to SORT programs. It contains a return code of 0 (successful) or 16 (unsuccessful) at the completion of a sort operation. You can set the SORT-RETURN special register to 16 in an error declarative or input/output procedure to terminate a sort operation before all records are processed. The operation is terminated on the next RETURN or RELEASE statement.
Format 2
  1. (MF)The SORT statement sorts the table referenced by data-name-2 and presents the sorted table in data-name-2 either in the order determined by the ASCENDING or DESCENDING phrases, if specified, or in the order determined by the KEY phrase associated with data-name-2.

  2. (MF)To determine the relative order in which the table elements are stored after sorting, the contents of the corresponding key data items are compared according to the rules for comparison of operands in a relation condition, starting with the most significant key data item.

    1. If the contents of the corresponding key data items are not equal and the key is associated with the ASCENDING phrase, the table element containing the key data item with the lower value has the lowest occurrence number.

    2. If the contents of the corresponding key data items are not equal and the key is associated with the DESCENDING phrase, the table element containing the key data item with the higher value has the lowest occurrence number.

    3. If the contents of the corresponding key data items are equal, the determination is based on the contents of the next most significant key data item.

  3. (MF)The number of occurrences of table elements referenced by data-name-2 is determined by the rules in the OCCURS clause.

  4. (MF)If data-name-2 references a data item which is subordinate to a data item which contains an OCCURS clause, the first or only index-name associated with each such superordinate table must be set to the desired occurrence number before the SORT statement is executed.

  5. (MF)If the KEY phrase is not specified, the sequence is determined by the KEY phrase in the Data Description entry of the table referenced by data-name-2.

  6. (MF)If the KEY phrase is specified, it overrides any KEY phrase specified in the Data Description entry of the table referenced by data-name-2.

  7. (MF)If the key phrase is specified but data-name-1 is omitted, the data item referenced by data-name-2 is the key data item.

  8. (MF)The sorted table elements of the table referenced by data-name-2 are placed in the table referenced by data-name-2.

  9. (MF)The COLLATING SEQUENCE phrase is treated as documentary only.

4.6.51 The START Statement

The START statement provides a basis for logical positioning within a relative or indexed file for subsequent retrieval of records. This statement is not available for files with sequential organization.

General Formats

Format 1 (Relative Files)

Format 2 (Indexed Files)

Note that the required relational characters ">", " <", ">=", "<=" and "=" are not underlined to avoid confusion with other symbols, such as ">" (greater than or equal to).

Syntax Rules

All Formats (Relative and Indexed Files)
  1. File-name-1 must be the name of a relative or indexed file.

  2. File-name-1 must be the name of a file with sequential or dynamic access.

  3. Data-name-1 can be qualified.

  4. The INVALID KEY phrase must be specified if no applicable USE procedure is specified for file-name-1.

    (OSVS)(VSC2)(MF)This rule is not enforced.

Format 1 (Relative Files)
  1. If the KEY phrase is specified, data-name-1 must be the data item specified in the RELATIVE KEY phrase of the associated file control entry.
Format 2 (Indexed Files)
  1. If the KEY phrase is specified, data-name-1 can reference a data item specified as a record key associated with file-name-1. It can also reference any data item of category alphanumeric, subordinate to the data item specified as a record key associated with file-name-1, whose leftmost character position corresponds to the leftmost character position of that record key data item.

  2. (MF)Split-key-name-1 can reference one or more data items, and is specified as a record key associated with file-name-1.

  3. (MF)WITH SIZE specifies the number of characters in the key to be used in the positioning process.

  4. (MF)Identifier-1 must be the name of an elementary integer data item when used with the WITH SIZE phrase.

General Rules

All Formats (All Files)
  1. File-name-1 must be open in the INPUT or I/O mode at the time that the START statement is executed. (See the section The OPEN Statement earlier in this chapter.)

  2. If the KEY phrase is not specified, the relational operation IS EQUAL TO is implied.

  3. Execution of the START statement causes the value of the FILE STATUS data item, if any, associated with file-name-1 to be updated. (See the section I/O Status earlier in this chapter.)

  4. (MF)The START statement never acquires, detects or releases recordlocks.
Format 1 (Relative Files)
  1. The type of comparison specified by the relational operator in the KEY phrase occurs between a key associated with a record in the file referenced by file-name-1 and a data item as specified in General Rule 6.

    1. (ANS85)If the relational operator specifies that the key must be equal to, greater than, or greater than or equal to the data item, then

      the file position indicator is positioned to the first logical record currently existing in the file whose key satisfies the comparison.

    2. (MF)If the relational operator specifies that the key must be less than, or less than or equal to the data item, then the file position indicator is positioned to the last logical record currently existing in the file whose key satisfies the comparison.

    3. If the comparison is not satisfied by any record in the file, an INVALID KEY condition exists. The execution of the START statement will be unsuccessful, and the position of the file position indicator will be undefined. (See the section The INVALID KEY Condition in this chapter.)

  2. The comparison described in General Rule 5 uses the data item referenced by the RELATIVE KEY clause associated with file-name-1. A RELATIVE KEY clause must be associated with file-name-1.
Format 2 (Indexed Files)
  1. The type of comparison specified by the relational operator in the KEY phrase occurs between a key associated with a record in the file referenced by file-name-1 and a data item as specified in General Rule 8. If file-name-1 references an indexed file and the operands are of unequal size, the comparison proceeds as though the longer one were truncated on the right so that its length is equal to that of the shorter. All other nonnumeric comparison rules apply except that the presence of the PROGRAM COLLATING SEQUENCE clause will have no effect on the comparison. (See the section Comparison Of Nonnumeric Operands earlier in this chapter.)

    1. (ANS85)If the relational operator specifies that the key must be equal to, greater than, or greater than or equal to the data item, then

      the file position indicator is positioned to the first logical record currently existing in the file whose key satisfies the comparison.

    2. (MF)If the relational operator specifies that the key must be less than, or less than or equal to the data item, then the file position indicator is positioned to the last logical record currently existing in the file whose key satisfies the comparison. If this key has duplicate entries, the file position indicator is positioned to the last of these entries.

    3. If the comparison is not satisfied by any record in the file, an INVALID KEY condition exists, the execution of the START statement is unsuccessful, and the position of the file position indicator is undefined. (See the section The INVALID KEY Condition in this chapter.)

  2. If the KEY phrase is specified, the comparison described in General Rule 7 uses the data item referenced by data-name.

  3. If the KEY phrase is not specified, the comparison described in General Rule 7 uses the data item referenced in the RECORD KEY clause associated with file-name-1.

  4. After successful execution of the START statement, a key of reference is established and used in subsequent Format 3 READ statements as follows (see the section The READ Statement earlier in this chapter):

    1. If the KEY phrase is not specified, the prime record key specified for file-name-1 becomes the key of reference.

    2. If the KEY phrase is specified, and data-name-1

      (MF)or split-key-name-1

      is specified as a record key for file-name-1, that record key becomes the key of reference.

    3. If the KEY phrase is specified, and data-name-1

      (MF)or split-key-name-1

      is not specified as a record key for file-name-1, the record key whose leftmost character position corresponds to the leftmost character position of the data item specified by data-name-1

      (MF)or split-key-name-1

      becomes the key of reference.

  5. If execution of the START statement is not successful, the key of reference is undefined.

4.6.52 The STOP Statement

The STOP statement causes a permanent or temporary suspension of the execution of the object program.

(ANS85)The STOP literal statement is classed as an obsolete element in the ANSI'85 standard and is scheduled to be deleted from the next full revision of the ANSI Standard.

(MF)All dialects within this COBOL implementation fully support this syntax. The FLAGSTD Compiler directive can be used to detect all occurrences of this syntax.

(XOPEN)Although it is a part of the standard COBOL definition, the Stop literal format is explicitly excluded from the X/Open COBOL language definitions and should not be used in an X/Open COBOL conforming source program.

General Format

Format 1

Format 2

Syntax Rules

  1. Literal-1 must not be a figurative constant that begins with the word ALL.

  2. If literal-1 is numeric, then it must be an unsigned integer.

    (OSVS)(VSC2)A signed integer is allowed.

  3. (MF)Integer-1 may be signed.

  4. If a STOP RUN statement appears in a consecutive sequence of imperative statements within a sentence, it must appear as the last statement in that sequence.

    (OSVS)(VSC2)(MF)This rule is not enforced, although any statements in the sentence that follow the STOP RUN statement will not be executed.

  5. (MF)GIVING and RETURNING are equivalent.

  6. (MF)Identifier-1 must be no larger than 8 bytes in size.

General Rules

  1. If the RUN phrase is specified, execution of the run unit ceases and control is transferred to the operating system.

  2. During the execution of a STOP RUN statement, an implicit CLOSE statement without any optional phrases is executed for each file that is in the open mode in the run unit. Any USE procedures associated with any of these files are not executed.

  3. If the run unit has been accessing messages, the STOP RUN statement causes the message control system (MCS) to eliminate form the queue any message partially received by that unit. Any portion of a message transferred from the run unit via a send statement, but not terminated by an EMI or EGI, is purged from the system.

  4. (MF)Execution of a STOP RUN statement causes a return value to be set in the system area generally available for non-COBOL programs to return a value. If the operating system supports the facility of returning a value from a program that is run to the operating system environment then it will return the value from the system area.

    (MF)If the GIVING phrase is not specified then the object program operates as if the system area were declared as a COBOL numeric data item with USAGE COMP-5 and with a size determined by the operating environment external to the COBOL system and as if a MOVE statement had been executed with the RETURN-CODE as the sending item and the system area as the receiving item. (See the section Special Registers in the chapter Concepts of the COBOL Language for details of RETURN-CODE.)

    (MF)If the GIVING identifier-1 phrase is specified, identifier-1 must describe the same number of character positions as is required to hold the return value in the system area and must be of the type and usage that is expected by the operating system. Typically identifier-1 will need to be declared with an explicit or implicit PIC S9 (9) USAGE COMP-5. The object program operates as if a MOVE statement had been executed with identifier-1 as the sending item and the system area as the receiving item.

    (MF)IF the GIVING integer-1 phrase is specified, integer-1 must not be larger than the value that can be held in the system area. The object program operates as if a MOVE statement had been executed with integer-1 as the sending item and the system area as the receiving item.

  5. If STOP literal-1 is specified, the execution of the run unit is suspended and literal-1 is communicated to the operator. Continuation of the execution of the run unit begins with the next executable statement when the operator presses the ENTER key or its equivalent.

4.6.53 The STRING Statement

The STRING statement provides juxtaposition of the partial or complete contents of two or more data items into a single data item.

General Format

Syntax Rules

  1. Each literal can be any figurative constant without the optional word ALL.

  2. All literals must be described as nonnumeric literals, and all identifiers, except identifier-4, must be described implicitly or explicitly as USAGE IS DISPLAY.

  3. Identifier-3 must represent an elementary alphanumeric data item without editing symbols or the JUSTIFIED clause.

  4. Identifier-4 must represent an elementary numeric integer data item of sufficient size to contain a value equal to the size plus 1 of the area referenced by identifier-3. The "P" can not be used in the PICTURE character-string of identifier-4.

  5. Where identifier-1 or identifier-2 is an elementary numeric data item, it must be described as an integer without the symbol "P" in its PICTURE character-string.

  6. (ANS85)Identifier-3 must not be reference modified.

  7. (MF)Identifier-3 can be reference modified.

General Rules

  1. Identifier-1, or literal-1, represents the sending item. Identifier-3 represents the receiving item.

  2. Literal-2, identifier-2, indicate the character(s) delimiting the move. If the SIZE phrase is used, the complete data item defined by identifier-1, or literal-1, is moved. When a figurative constant is used as the delimiter, it stands for a single character nonnumeric literal.

  3. When a figurative constant is specified as literal-1, or literal-2, it refers to an implicit one-character data item whose usage is DISPLAY.

  4. When the STRING statement is executed, the transfer of data is governed by the following rules:

    1. Those characters from literal-1, or from the contents of the data item referenced by identifier-1, are transferred to the contents of identifier-3 in accordance with the rules for alphanumeric to alphanumeric moves, except that no space filling will be provided. (See the section The MOVE Statement earlier in this chapter.)

    2. If the DELIMITED phrase is specified without the SIZE phrase, the contents of the data item referenced by identifier-1, or the value of literal-1, is transferred to the receiving data item in the sequence specified in the STRING statement beginning with the leftmost character and continuing from left to right until the end of the data item is reached, or until the character(s) specified by literal-2, or by the contents of identifier-2 are encountered. The character(s) specified by literal-2, or by the data item referenced by identifier-2 are not transferred.

    3. If the DELIMITED phrase is specified with the SIZE phrase, the entire contents of literal-1, or the contents of the data item referenced by identifier-1, are transferred, in the sequence specified in the STRING statement, to the data item referenced by identifier-3 until all data has been transferred or the end of the data item referenced by identifier-3 has been reached.

  5. If the POINTER phrase is specified, identifier-4 is explicitly available to the programmer, who is then responsible for setting its initial value. The initial value must not be less than one.

  6. If the POINTER phrase is not specified, the following General
    Rules apply as if the user had specified identifier-4 with an initial value of 1.

  7. When characters are transferred to the data item referenced by identifier-3, the moves behave as though the characters were moved one at a time from the source into the character position of the data item referenced by identifier-3 designated by the value associated with identifier-4, and then identifier-4 was increased by one prior to the move of the next character. The value associated with identifier-4 is changed during execution of the STRING statement only by the behavior specified above.

  8. At the end of execution of the STRING statement, only the portion of the data item referenced by identifier-3 that was referenced during the execution of the STRING statement is changed. All other portions of the data item referenced by identifier-3 will contain data that was present before this execution of the STRING statement.

  9. Before each move of a character to the data item referenced by identifier-3, if the value associated with the data item referenced by identifier-4 is either less than one or exceeds the number of character positions in the data item referenced by identifier-3, no (further) data is transferred to the data item referenced by identifier-3,

    (ANS85) and the NOT ON OVERFLOW phrase, if specified, is ignored 

    and control is transferred to the end of the STRING statement or, if the ON OVERFLOW phrase is specified, to imperative- statement-1. If control is transferred to imperative- statement-1, execution continues according to the rules for each statement specified in imperative-statement-1. If a procedure branching or conditional statement which causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of the execution of imperative-statement-1, control is transferred to the end of the STRING statement.

  10. (ANS85)If, at the time of execution of a STRING statement with the NOT ON OVERFLOW phrase, the conditions described in General Rule 9 are not encountered, after completion of the transfer of data according to the other general rules, the ON OVERFLOW phrase, if specified, is ignored and control is transferred to the end of the STRING statement or, if the NOT ON OVERFLOW phrase is specified, to imperative- statement-2. If control is transferred to imperative- statement-2, execution continues according to the rules for each statement specified in imperative-statement-2. If a procedure branching or conditional statement which causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of the execution of imperative-statement-2, control is transferred to the end of the STRING statement.

  11. (ANS85)The END-STRING phrase delimits the scope of the STRING statement. (See the section Explicit And Implicit Scope Terminators in the chapter Concepts of the COBOL Language.)

4.6.54 The SUBTRACT Statement

The SUBTRACT statement is used to subtract one, or the sum of two or more, numeric data items from one or more items, and set the values of one or more items equal to the results.

General Formats

Format 1

Format 2

Format 3

Syntax Rules

All Formats
  1. Each identifier must refer to a numeric elementary item, except that in Format 2 each identifier following the word GIVING must refer to either an elementary numeric item or an elementary numeric edited item, and in Format 3 each identifier must refer to a group item.

  2. The composite of operands must not contain more than 18 digits. (See the section The Arithmetic Statements earlier in this chapter.)

    1. In Format 1 the composite of operands is determined by using all of the operands in a given statement.

    2. In Format 2 the composite of operands is determined by using all of the operands in a given statement excluding the data items that follow the word GIVING.

    3. In Format 3 the composite operands is determined separately for each pair of corresponding data items.
Formats 1 and 2
  1. Each literal must be a numeric literal.

  2. (OSVS)(VSC2)(MF)Floating-point data items and literals can be used anywhere numeric data items and literals can be specified.
Format 3
  1. CORR is an abbreviation for CORRESPONDING.

General Rules

All Formats
  1. See the sections The ROUNDED Phrase, The ON SIZE ERROR Phrase, Arithmetic Statements, Overlapping Operands and Multiple Results In Arithmetic Statements in this chapter.

  2. (VSC2)(MF)The COBOL system ensures enough places are carried so as not to lose significant digits during execution.
Format 1
  1. All literals or identifiers preceding the word FROM are added together and this total is subtracted from the current value of identifier-2 storing the result immediately into identifier-2, and repeating this process respectively for each operand following the word FROM.
Format 2
  1. In Format 2, all literals or identifiers preceding the word FROM are added together, the sum is subtracted from literal-2 or identifier-2 and the result of the subtraction is stored as the new value of each data item referenced by identifier-3.
Format 3
  1. If Format 3 is used, data items in identifier-1 are subtracted from and stored into corresponding data items in identifier-2.

4.6.55 The TRANSFORM Statement

(OSVS)

The TRANSFORM statement is used to alter characters according to a transformation rule.

General Format

Syntax Rules

  1. Identifier-3 can be any elementary item except a numeric item with USAGE other than DISPLAY, or a group item.

  2. Identifier-1 and identifier-2 should be elementary alphabetic or alphanumeric items.

  3. Nonnumeric-literal-2 or identifier-2 must be either one character long or the same length as nonnumeric-literal-1 or identifier-1.

General Rules

  1. The use of figurative-constant-1 and/or figurative-constant-2 is equivalent to the use of a single-character nonnumeric- literal with the same value.

  2. If either identifier-1 or identifier-2 references the same computer storage area as identifier-3, the result of the TRANSFORM is undefined. (See the section The REDEFINES Clause earlier in this chapter.)

  3. If characters are repeated in nonnumeric-literal-1 or identifier-1, then the result of the TRANSFORM operation is undefined.

  4. Execution of the TRANSFORM statement scans identifier-3 for occurrences of individual characters from identifier-1 or nonnumeric-literal-1. When a match is found, the corresponding character (or the single character of a one-character field) from identifier-2 or nonnumeric-literal-2 is substituted into that character position in identifier-3. The correspondence between identifier-1 or nonnumeric- literal-1 and identifier-2 or nonnumeric-literal-2 is by occurrence number of the character within the data item (starting from the left).

4.6.56 The UNLOCK Statement

(MF)

The UNLOCK statement releases all record locks held by the run unit on a named file.

General Format

Syntax Rule

File-name must occur in the SELECT statement of the FILE CONTROL entry.

General Rules

  1. The file referenced by file-name must already be opened with the OPEN statement.

  2. The UNLOCK statement releases all record locks held by the run unit on a named file.

4.6.57 The UNSTRING Statement

The UNSTRING statement causes contiguous data in a sending field to be separated and placed into multiple receiving fields.

General Format

Syntax Rules

  1. Each literal must be a nonnumeric literal. In addition, each literal can be any figurative constant without the optional word ALL.

  2. Identifier-1, identifier-2, identifier-3, and identifier-5 must be described, implicitly or explicitly, as an alphanumeric data-item.

  3. Identifier-4 can be described as either alphabetic (except that the symbol "B" can not be used in the PICTURE character-string), alphanumeric, or numeric (except that the symbol "P" can not be used in the PICTURE character-string), and must be described as USAGE IS DISPLAY.

  4. (MF)Syntax Rules 2 and 3 do not apply. Instead, the following
    rules apply:

  5. (OSVS)(VSC2)(MF)Identifier-4 must not be defined as a floating-point item.

  6. Identifier-6 and identifier-8 must reference integer data items, (except that the symbol " P" can not be used in the PICTURE character-string).

  7. Identifier-1 must be described as an elementary numeric integer data item of sufficient size to contain a value equal to 1 plus the size of the data item referenced by identifier-1. The symbol "P" can not be used in the PICTURE character string of identifier-7.

  8. No identifier can name a level 88 entry.

  9. The DELIMITER IN phrase and the COUNT IN phrase can be specified only if the DELIMITED BY phrase is specified.

  10. (MF)The source of an UNSTRING operation can be reference modified.

General Rules

  1. All references to identifier-2, literal-1, apply equally to identifier-3, literal-2, respectively and all recursions thereof.

  2. Identifier-1 represents the sending area.

  3. Identifier-4 represents the data receiving area. Identifier-5 represents the receiving area for delimiters.

  4. Literal-1 or the data item referenced by identifier-2 specifies a delimiter.

  5. The data item referenced by identifier-6 represents the count of the number of characters within the data item referenced by identifier-1 isolated by the delimiters for the move to the data item referenced by identifier-4. This value does not include a count of the delimiter character(s).

  6. The data item referenced by identifier-7 contains a value that indicates a relative character position within the area defined by identifier-1.

  7. The data item referenced by identifier-8 is a counter that records the number of data items acted upon during the execution of an UNSTRING statement.

  8. When a figurative constant is used as the delimiter, it stands for a single character nonnumeric literal.

    When the ALL phrase is specified, one occurrence or two or more contiguous occurrences of literal-1 (figurative constant or not) or the contents of the data item referenced by identifier-2 are treated as if it were only one occurrence, and this occurrence is moved to the receiving data item according to the rules in General Rule 13d.

  9. When any examination encounters two contiguous delimiters, the current receiving area is either space or zero filled according to the description of the receiving area.

  10. Literal-1 or the contents of the data item referenced by identifier-2 can contain any character in the computer's character set.

  11. Each literal-1 or the data item referenced by identifier-2 represents one delimiter. When a delimiter contains two or more characters, all of the characters must be present in contiguous positions of the sending item and in the order given, to be recognized as a delimiter.

  12. When two or more delimiters are specified in the DELIMITED BY phrase, an "OR" condition exists between them. Each delimiter is compared to the sending field. If a match occurs, the character(s) in the sending field is considered to be a single delimiter. No character(s) in the sending field can be considered a part of more than one delimiter.

    Each delimiter is applied to the sending field in the sequence specified in the UNSTRING statement.

  13. When the UNSTRING statement is initiated, the current receiving area is the data item referenced by identifier-4. Data transferred from the data item referenced by identifier-1 to the data item referenced by identifier-4 according to the following rules:

    1. If the POINTER phrase is specified, the string of characters referenced by identifier-1 is examined beginning with the relative character position indicated by the contents of the data item referenced by identifier-7. If the POINTER phrase is not specified, the string of characters is examined beginning with the leftmost character position.

    2. If the DELIMITED BY phrase is specified, the examination proceeds left to right until either a delimiter specified by the value of literal-1 or the data item referenced by identifier-2 is encountered. (See General Rule 11.) If the DELIMITED BY phrase is not specified, the number of characters examined is equal to the size of the current receiving area. However, if the sign of the receiving item is defined as occupying a separate character position, the number of characters examined is one less than the size of the current receiving area.

      If the end of the data item referenced by identifier-1 is encountered before the delimiting condition is met, the examination terminates with the last character examined.

    3. The characters thus examined (excluding the delimiting character(s), if any) are treated as an elementary alphanumeric data item, and are moved into the current receiving area according to the rules for the MOVE statement. (See the section The MOVE Statement earlier in this chapter.)

    4. If the DELIMITER IN phrase is specified, the delimiting character(s) are treated as an elementary alphanumeric data item and are moved into the data item referenced by identifier-5 according to the rules for the MOVE statement. (See the section The MOVE Statement earlier in this chapter.) If the delimiting condition is the end of the data item referenced by identifier-1, then the data item referenced by identifier-5 is space-filled.

    5. If the COUNT IN phrase is specified, a value equal to the number of characters thus examined (excluding the delimiter character(s) if any) is moved into the area referenced by identifier-6 according to the rules for an elementary move.

    6. If the DELIMITED BY phrase is specified the string of characters is further examined beginning with the first character to the right of the delimiter. If the DELIMITED BY phrase is not specified, the string of characters is further examined beginning with the character to the right of the last character transferred.

    7. After data is transferred to the data item referenced by identifier-4, the current receiving area is the data item referenced by the next recurrence of identifier-4. The behavior described in paragraph 13b. through 13f. is repeated until either all the characters are exhausted in the data item referenced by identifier-1, or until there are no more receiving areas.

  14. The initialization of the contents of the data items associated with the POINTER phrase or the TALLYING phrase is the responsibility of the user.

  15. The contents of the data item referenced by identifier-7 will be incremented by one for each character examined in the data item referenced by identifier-1. When the execution of an UNSTRING statement with a POINTER phrase is complete, the contents of the data item referenced by identifier-7 will contain a value equal to the initial value plus the number of characters examined in the data item referenced by identifier-1.

  16. When the execution of an UNSTRING statement with a TALLYING phrase is completed, the contents of the data item referenced by identifier-8 contains a value equal to its initial value plus the number of data receiving items acted upon.

  17. Either of the following situations causes an overflow condition:

    1. An UNSTRING is initiated, and the value in the data item referenced by identifier-7 is less than 1 or greater than the size of the data item referenced by identifier-1.

    2. If, during execution of an UNSTRING statement, all data receiving areas have been acted upon, and the data item referenced by identifier-1 contains characters that have not been examined.

  18. When an overflow condition exists, the UNSTRING operation is terminated,

    (ANS85) the NOT ON OVERFLOW phrase, if specified, is ignored and 

    control is transferred to the end of the UNSTRING statement or, if the ON OVERFLOW phrase is specified, to imperative-statement-1. If control is transferred to imperative-statement-1, execution continues according to the rules for each statement specified in imperative-statement-1. If a procedure branching or conditional statement which causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of the execution of imperative-statement-1, control is transferred to the end of the UNSTRING statement.

  19. (ANS85)The END-UNSTRING phrase delimits the scope of the UNSTRING statement. (See the section Explicit And Implicit Scope Terminators in the chapter Concepts of the COBOL Language.)

  20. If, at the time of execution of an UNSTRING statement, the conditions described in General Rule 17 are not encountered, after completion of the transfer of data according to the other general rules, the ON OVERFLOW phrase, if specified, is ignored and control is transferred to the end of the UNSTRING statement

    (ANS85)or, if the NOT ON OVERFLOW phrase is specified, to imperative-statement-2. If control is transferred to imperative- statement-2, execution continues according to the rules for each statement specified in imperative-statement-2. If a procedure branching or conditional statement which causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of the execution of imperative-statement-2, control is transferred to the end of the UNSTRING statement.

  21. The evaluation of subscription and indexing for the identifiers is as follows:

    1. Any subscripting or indexing associated with identifier-1, identifier-7, or identifier-8 is evaluated only once, immediately before any data is transferred as the result of the execution of the UNSTRING statement.

    2. Any subscripting or indexing associated with identifier-2, -3, -4, -5, or -6 is evaluated immediately before the transfer of data into the respective data item.

  22. (ANS85)22..Any subscripting associated with the DELIMITED BY identifier, the INTO identifier, the DELIMITER IN identifier, or the COUNT IN identifier is evaluated once, immediately before the examination of the sending fields for the delimiter.

  23. If identifier-1, -2 or -3, occupies the same storage area as identifier-4, -5, -6, -7 or -8, or if identifier-4, -5 or -6 , occupies the same storage area as identifier-7 or -8, or if identifier-7 and identifier-8 occupy the same storage area, the result of the execution of this statement is undefined, even if they are defined by the same data description entry.

4.6.58 The USE Statement

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)

Format 2 (Record Sequential Files)

Format 3 (Relative And Indexed Files)

Syntax Rules

All Formats (All Files)
  1. Format 1 is the ERROR declarative.

    (OSVS)(VSC2)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)
  1. 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.

    (ANS85)The same file-name must not appear in more than one USE AFTER EXCEPTION statement within the same Procedure Division.

  2. The words ERROR and EXCEPTION are equivalent and can be used interchangeably.
Formats 2 and 3 (Record Sequential, Relative and Indexed Files)
  1. (OSVS)(VSC2)If both BEGINNING and ENDING are omitted, the effect is as though both BEGINNING and ENDING had been specified.
Format 2 (Record Sequential Files)
  1. (OSVS)(VSC2)REEL and UNIT are treated as equivalent.

  2. (OSVS)(VSC2)If both FILE and REEL/UNIT are omitted, the effect is as though both REEL or UNIT and FILE had been specified.

  3. (OSVS)(VSC2)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.

    (OSVS)(VSC2)(MF)This restriction can be ignored.

  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)
  1. 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.

  2. (ANS85)When file-name-1 is specified explicitly, no other USE statement applies to file-name-1.

  3. The GIVING phrase is documentary only.
Formats 2 and 3 (Record Sequential, Relative and Indexed Files)

  1. (OSVS)(VSC2)If the BEGINNING phrase is specified explicitly or implicitly, the following actions are taken during the execution of an applicable OPEN statement:

    Open Mode Action
    INPUT Read header labels
    Execute beginning declarative
    OUTPUT Execute beginning declarative
    Write header labels
    I/O Read header labels
    Execute beginning declarative
    Write header labels
    EXTEND Read header labels
    Execute beginning declaratives (trailer labels treated as header)
    Write header labels

  2. (OSVS)(VSC2)If the ENDING phrase is specified explicitly or implicitly, the following actions are taken during the execution of an applicable CLOSE statement:

    Open Mode Action
    INPUT Read trailer labels
    Execute ending declarative
    OUTPUT Execute ending declarative
    Write trailer labels
    I/O Read trailer labels
    Execute ending declarative
    Write trailer labels
    EXTEND Execute ending declaratives
    Write trailer labels

  3. (OSVS)(VSC2)The statement GO TO MORE-LABELS is treated as a simple jump to the start of the declarative procedure in which it appears.

4.6.59 The WRITE Statement

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.

(XOPEN)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 (Record
(MF)and Line
Sequential Files)

Format 2 (Record Sequential Files)

Format 3 (Record Sequential Files)

Format 4 (Relative and Indexed Files)

Directives and Run-time Switches

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or semantics described in this section.

  2. The following run-time switches may impact the semantics described in this section.

Syntax Rules

All Formats (All Files)
  1. (ANS85)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. (OSVS)(VSC2)(MF)Record-name can define a floating-point item.

  4. (OSVS)(VSC2)(MF)Identifier-1 can be defined as a floating-point item.
Format 1 (Record Sequential Files)
  1. (MF)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.)

  2. When identifier-2 is used in the ADVANCING phrase, it must be the name of an elementary integer data item.

  3. Integer, or the value of the data item referenced by identifier-2, can be zero.

  4. (VSC2)Integer can be signed.

  5. If the END-OF-PAGE phrase is specified, the linage clause must be specified in the file description entry for the associated file.

  6. The words END-OF-PAGE and EOP are equivalent.

  7. The ADVANCING mnemonic-name phrase cannot be specified when writing a record to a file whose file description entry contains the LINAGE clause.

  8. (ANS85)The phrases ADVANCING PAGE and END-OF-PAGE must not both be specified in a single WRITE statement.

    (MF)This restriction can be ignored.

    (OSVS)(VSC2)(MF)Alternatively, function-name can itself be used instead of an associated mnemonic name.

Format 2 (Record Sequential Files)
  1. (OSVS)This format cannot be specified when writing a record to a file whose file description entry contains the LINAGE clause.

  2. (OSVS) 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.

  3. (OSVS)In the AFTER POSITIONING phrase, identifier-2 must be defined as a single-character alphanumeric item. See General Rule 18 for itspossible values.
Format 4 (Relative And Indexed Files)

  1. The INVALID KEY phrase must be specified if an applicable USE procedure is not specified for the associated file.

    (OSVS)(VSC2)(MF)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:

    1. The statement: 
           MOVE identifier-1 TO record-name

      according to the rules specified for the MOVE statement, followed by:

    2. 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. (ANS85)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)
  1. 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.

  2. 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.

Format 1 (Line Sequential Files)
  1. (MF)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).

  2. (MF)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:

    1. 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.)

    2. If a USE AFTER STANDARD EXCEPTION declarative is explicitly or implicitly specified for the file, that declarative procedure will be executed.

    3. If a USE AFTER STANDARD EXCEPTION declarative is not explicitly or implicitly specified for the file, the result will be undefined.

  3. (MF)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:

    1. The standard ending reel/unit procedure.

    2. The reel/unit swap.

    3. the standard beginning of reel/unit label procedure.

  4. (XOPEN)If you have a fixed length record file, where records of different lengths are being redefined, you need to be aware that the entire buffer area is written to the file. You might, therefore, need to space-fill if the current record is shorter than the previous one.

  5. (ANS85)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
(MF)and Line
Sequential Files)
  1. 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:

    1. 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.

    2. If integer is specified, the representation of the printed page is advanced in the number of lines equal to the value of integer.

    3. If mnemonic-name is specified, the representation of the printed page is advanced as specified under the SPECIAL-NAMES paragraph.

    4. 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.

    5. 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.

    6. 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.

  2. 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)
  1. 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.)

  2. 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.

Format 2 (Record Sequential Files)
  1. (OSVS)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
    0Double-spacing
    –Triple-spacing
    +Suppress spacing
    1-9Skip to channel 1-9, respectively
    A, B, CSkip to channel 10, 11, 12, respectively
    V, WPocket select 1 or 2

    If the integer-1 option is used, then the character placed in the output record is determined as follows:

    (space)
    Integer
    		Output Character
    		Interpretation
    01Skip to channel 1
    1Single-space
    20Double-spacing
    3–Triple-spacing

  2. (OSVS)The END-OF-PAGE phrase, if specified, is documentary and as such is never executed.

Format 3 (Record Sequential Files)
  1. (OSVS)(VSC2)(MF)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)
  1. 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.)

  2. 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.

  3. 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)
  1. When a file is opened in the OUTPUT mode, records can be placed into the file by one of the following:

    1. 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.

    2. 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.

  2. 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.

  3. The INVALID KEY condition exists under the following circumstances:

    1. When access mode is random or dynamic, and the RELATIVE KEY data item specifies a record which already exists in the file, or:

    2. When an attempt is made to write beyond the externally defined boundaries of the file.
Format 4 (Indexed Files)
  1. 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.

  2. The value of the prime record key should be unique within the records in the file.

  3. 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.

  4. 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.

  5. If random or dynamic access mode is specified, records can be released to the operating system in any program-specified order.

  6. 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.

  7. The INVALID KEY condition exists under the following circumstances:

    1. 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:

    2. 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:

    3. 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:

    4. When an attempt is made to write beyond the externally defined boundaries of the file.

  8. (ANS85)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.)

Copyright © 1996 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and namesused herein are protected by international law.