PreviousProcedure Division - ENTER - INVOKE Procedure Division - PERFORM - ROLLBACKNext

Chapter 14: Procedure Division - MERGE - OPEN

14.1 COBOL verbs

14.1.1 The MERGE Statement

The MERGE statement combines two or more identically sequenced files on a set of specified keys, and during the process makes records available, in merged order, to an output procedure or to an output file.

General Format

Syntax Rules

  1. File-name-1 must be described in a sort-merge file description entry in the Data Division.

  2. Procedure-name-1 represents the name of an output procedure.

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

    This restriction is removed.

  4. If the file referenced by file-name-1 contains variable length records, the size of the records contained in the files referenced by file-name-2 and file-name-3 must not be less than the smallest record, nor greater 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 files referenced by file-name-2 and file-name-3 must not be greater than the largest record described for file-name-1.

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

  6. The words THRU and THROUGH are equivalent.

  7. 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. KEY data-names can be qualified.

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

    4. 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. The same character position referenced by a key data-name in one record description entry are taken as the key in all records of the file.

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

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

    7. If the KEY is an external floating-point item, the key is treated as alphanumeric. The sequence in which the records are merged depends on the collating sequence used.

    8. If the KEY is an internal floating-point item, the sequence of key values will be in numeric order.

  8. No more than one file-name from a multiple file reel can appear in the MERGE statement.

  9. File-names must not be repeated in the MERGE statement.

  10. MERGE statements can appear anywhere except in the declaratives portion of the Procedure Division.

  11. If file-name-4 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.

  12. If the GIVING phrase is specified and the file referenced by file-name-4 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 greater than the largest record described for file-name-4. If the file referenced by file-name-4 contains fixed length records, the size of the records contained in the file referenced by file-name-1 must not be greater than the largest record described for file-name-4.

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

General Rules

  1. The MERGE statement merges all records contained on the files referenced by file-name-2 and file-name-3.

  2. If the file referenced by file-name-1 contains only fixed length records, any record in the file referenced by file-name-2 or file-name-3 containing fewer character positions than that fixed length 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.

  3. The data-names following the word KEY are listed from left to right in the MERGE statement in order of decreasing significance without regard to how they are divided into KEY phrases. The leftmost data-name is the major key, the next data-name is the next more significant key, and so on.

    1. When the ASCENDING phrase is specified, the merged sequence will be from the lowest value of the contents of the data items identified by the key data-names to the highest value, according to the rules for comparison of operands in a relation condition.

    2. When the DESCENDING phrase is specified, the merged sequence will be from the highest value of the contents of the data items identified by the key data-names to the lowest value, according to the rules for comparison of operands in a relation condition.

  4. When, according to the rules for comparison of operands in relation condition, the contents of all the key data items of one data record are equal to the corresponding key data items of one or more other data records, the order of return of these records:

    1. follows the order of the associated input files as specified in the MERGE statement

    2. is such that all records associated with one input file are returned prior to the return of records from another input file.

  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 MERGE statement in the following order of precedence:

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

    2. Second, the collating sequence established as the program collating sequence.

  6. The results of the merge operation are undefined unless the records in the files referenced by file-name-2 and file-name-3 are ordered as described in the ASCENDING or DESCENDING KEY phrases associated with the MERGE statement.

  7. All the records in the files referenced by file-name-2 and file-name-3 are transferred to the file referenced by file-name-1. At the start of execution of the MERGE statement, the files referenced by file-name-2 and file-name-3 must not be in the open mode. For each of the files referenced by file-name-2 and file-name-3 the execution of the MERGE 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 phrase had been executed. If an output procedure is specified, this initiation is performed before control passes to the output procedure.

    2. The logical records are obtained and released to the merge operation. Each record is obtained as if a READ statement with the NEXT and the AT END phrases had been executed.

      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 content of the data item referenced in the DEPENDING ON phrase of either a RECORD IS VARYING clause or an OCCURS clause specified in the sort-merge file description entry for file-name-1.

      For a relative file, the content of the relative data key item is undefined after the execution of the MERGE statement.

    3. The processing of the file is terminated. The termination is performed as if a CLOSE statement without optional phrases had been executed. If an output procedure is specified, this termination is not performed until after control passes the last statement in the output procedure.

      These implicit functions are performed such that any associated USE AFTER EXCEPTION/ERROR procedures are executed.

      The value of the data item referenced by the DEPENDING ON phrase of a RECORD IS VARYING clause specified in the file description entry for file-name-2 or file-name-3 is undefined upon completion of the MERGE statement.

  8. 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 merged order from the file referenced by file-name-1. The range includes all statements that are executed as the result of a transfer of control by CALL, EXIT, GO TO, and PERFORM statements in the range of the output procedure, as well as all statements in declarative procedures that are executed as a result of the execution of statements in the range of the output procedure. The range of the output procedure must not cause the execution of any MERGE, RELEASE, or SORT statement. (See the section Explicit and Implicit Specifications in the chapter Concepts of the COBOL Language.)

  9. If an output procedure is specified, control passes to it during execution of the MERGE statement. The compiler inserts a return mechanism at the end of the last statement in the output procedure. When control passes the last statement in the output procedure, the return statement provides for termination of the merge, and then passes control to the next executable statement after the MERGE statement. Before entering the output procedure, the merge procedure reaches a point at which it can select the next record in merged order when requested. The RETURN statements in the output procedure are the requests for the next record.

  10. During the execution of the output procedure, no statement can be executed manipulating the file referenced by, or accessing the record area associated with, file-name-2, file-name-3, or file-name-4.

  11. If the GIVING phrase is specified, all the merged records are written on the file referenced by file-name-4 as the implied output procedure for the MERGE statement. At the start of execution of the MERGE statement, the file referenced by file-name-4 must not be in the open mode. For each of the files referenced by file-name-4, the execution of the MERGE 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.

    2. The merged logical records are returned and written onto the file. Each record is written as if a WRITE statement without any optional phrases had been executed.

      If the file referenced by file-name-4 is described with variable length records, the size of any record written to file-name-4 is the size of that record when it was read from file-name-1, regardless of the content of the data item referenced in the DEPENDING ON phrase of either a RECORD IS VARYING clause or an OCCURS clause specified in the file description entry for file-name-4.

      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 the MERGE 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/ERROR procedures are executed; however, the execution of such a USE procedure must not cause the execution of any statement manipulating the file referenced by, or accessing the record area associated with, file-name-4. On the first attempt to write beyond the externally defined boundaries of the file, any USE AFTER EXCEPTION/ERROR procedure specified for the file is executed; if control is returned from the USE procedure or if no such USE procedure is specified, the processing of the file is terminated as in paragraph 11c above.

      The value of the data item referenced by the DEPENDING ON phrase of a RECORD IS VARYING clause specified in the file description entry for file-name-1 is undefined upon completion of the MERGE statement for which the GIVING phrase is specified.

  12. If the file referenced by file-name-4 contains only fixed length records, any record in the file referenced by file-name-1 containing fewer character positions than that fixed length 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-4.

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

    1. If the MERGE statement appears in a section that is not in an independent segment, then any output procedure referenced by that merge statement must appear:

      1. totally within non-independent segments, or

      2. wholly contained in a single independent segment.

    2. If a MERGE statement appears in an independent segment, then any output procedure referenced by that MERGE statement must be contained:

      1. totally within non-independent segments, or

      2. wholly within the same independent segment as that MERGE statement.

  14. The SORT-RETURN special register is available to source elements with a MERGE statement. It contains a return code of 0 (successful) or 16 (unsuccessful) at the completion of the merge operation. You can set the special register to 16 in the output procedure to terminate a merge operation before all records are processed. The operation is terminated on the next RETURN statement.

14.1.2 The MOVE Statement

The MOVE statement transfers data, in accordance with the rules of editing, to one or more data areas.

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. Identifier-1 and literal represent the sending area; identifier-2 represents the receiving area.

  2. A data item must not be specified as an operand of a MOVE statement, if its usage is one of the following:

    INDEX

    OBJECT-REFERENCE

    POINTER, PROCEDURE-POINTER

    ENTRY-POINTER, MONITOR-POINTER, MUTEX-POINTER, SEMAPHORE-POINTER or THREAD-POINTER.

  3. If either the sending or receiving item is a DBCS (USAGE DISPLAY-1) item, then both must be DBCS items. The figurative constant SPACE can be the DBCS sending item.
Format 1
  1. When Format 1 is specified, all identifiers can be either group or elementary items. The data in the sending area is moved into the data item referenced by each identifier-2 in the order in which it is specified.

  2. Identifier-1 may be a numeric function-identifier.

Format 2
  1. CORR is an abbreviation for CORRESPONDING.

  2. When the CORRESPONDING phrase is used, all identifiers must be group items.

  3. The following items can be part of a group that is referenced in a MOVE CORRESPONDING statement; however, no movement of this item will take place:

    POINTER, PROCEDURE-POINTER

    OBJECT-REFERENCE

    EVENT-POINTER, MONITOR-POINTER, MUTEX-POINTER, SEMAPHORE-POINTER, THREAD-POINTER.

  4. A pointer data item can be part of a group that is referenced in a MO VE CORRESPONDING statement; however, no movement of the pointer data item will take place.

General Rules

All Formats
  1. If identifier-1 is a numeric function-identifier, then identifier-2 must be either a numeric or numeric edited item.

  2. The data designated by the literal or identifier-1 is moved to the data item referenced by each identifier-2, in the order in which it is specified. The rules referring to identifier-2 also apply to the other receiving areas. Any subscripting or indexing associated with identifier-2, is evaluated immediately before the data is moved to the respective data item.

    If identifier-1 is reference modified, subscripted, or is a function- identifier, the reference modifier, subscript, or function-identifier is evaluated only once, immediately before data is moved to the first of the receiving operands.

    The result of the statement:

         MOVE a(b) TO b, c(b)

    is equivalent to:

         MOVE a(b) TO temp
         MOVE temp TO b
         MOVE temp TO c(b)

    where temp is an intermediate result item provided by your COBOL system.

  3. Any MOVE in which the sending and receiving items are both elementary items is an elementary move. Every elementary item belongs to one of the following categories: numeric, alphabetic, alphanumeric, numeric edited, alphanumeric edited

    or floating-point.

    These categories are described in the PICTURE clause. Numeric literals belong to the category numeric, and nonnumeric literals belong to the category alphanumeric. The figurative constant ZERO belongs to the category numeric when moved to a numeric or numeric-edited item. The figurative constant ZERO belongs to the category alphanumeric in all other cases. The figurative constant SPACE belongs to the category alphabetic. All other figurative constants belong to the category alphanumeric.

    The following rules apply to an elementary move between these categories:

    1.  

      1. The figurative constant SPACE, or an alphanumeric edited, or alphabetic data item must not be moved to a numeric or numeric edited data item.

      2. A numeric edited data item must not be moved to a numeric or numeric edited data item.

        This restriction is removed.

    2. A numeric literal, the figurative constant ZERO, a numeric data item or a numeric edited data item must not be moved to an alphabetic data item.

    3. A non-integer numeric literal or a non-integer numeric data item must not be moved to an alphanumeric or alphanumeric-edited data item.

    4. All other elementary moves are legal and are performed according to the rules given in General Rule 5.

  4. Any necessary conversion of data from one form of internal representation to another takes place during legal elementary moves, along with any editing specified for

    ,or de-e diting implied by,

    the receiving data item:

    1. When an alphanumeric edited or alphanumeric item is a receiving item, alignment and any necessary space filling takes place as defined in the section Standard Alignment Rules in the chapter Concepts of the COBOL Language. If the size of the sending item is greater than the size of the receiving item, the excess characters are truncated on the right after the receiving item is filled. If the sending item is described as being signed numeric, the operational sign will not be moved; if the operational sign occupies a separate character position (see the section The SIGN Clause earlier in this chapter), that character will not be moved and the size of the sending item will be considered to be one less than its actual size (in terms of standard data format characters).

    2. When a numeric or numeric edited item is the receiving item, alignment by decimal point and any necessary zero-filling takes place as defined in the section Standard Alignment Rules in the chapter Concepts of the COBOL Language, except where zeros are replaced because of editing requirements.

      When the sending operand is numeric edited, de-e diting is implied to establish the operand's unedited numeric value, which can be signed; then the unedited numeric value is moved to the receiving field. The effect of de-editing depends on the setting of the DE-EDIT Compiler directive

      When a signed numeric item is the receiving item, the sign of the sending item is placed in the receiving item. (See the section The SIGN Clause earlier in this chapter.) Conversion of the representation of the sign takes place as necessary. If the sending item is unsigned, a positive sign is generated for the receiving item.

      When an unsigned numeric item is the receiving item, the absolute value of the sending item is moved and no operational sign is generated for the receiving item.

      When a data item described as alphanumeric is the sending item, data is moved as if the sending item were described as an unsigned numeric integer.

      When the receiving item is numeric or numeric-edited and the sending item is defined as alphanumeric, if the content of the sending item is not an integer, the results of the move are undefined. If the alphanumeric sending item is a literal whose contents do not represent an integer, an error will be reported, and zero moved to the target. (See the section Incompatible Data earlier in this chapter.)

      When the numeric data item is the sending item the action of the move will be such that a reverse of the move would cause the same value to appear in the numeric edited field (except or truncation). If the data item contains data which does not conform to the edited picture, zero is moved to the target.

    3. When a receiving field is described as alphabetic, justification and any necessary space-filling takes place as defined in the section Standard Alignment Rules in the chapter Concepts of the COBOL Language. If the size of the sending item is greater than the size of the receiving item, the excess characters are truncated on the right after the receiving item is filled.

    4. When the receiving field is floating-point, the sending item is converted first to internal floating-point and then moved. When data is moved to or from an external floating-point item, the data is converted first to or from its equivalent internal floating-point value.

    5. When the receiving field is DBCS the sending item must also be DBCS; no conversion takes place. If the sending and receiving items are not the same size the data item will be either truncated or padded with DBCS spaces on the right.

  5. Any move that is not an elementary move is treated exactly as if it were an alphanumeric to alphanumeric elementary move, except that no conversion of data from one form of internal representation to another takes place. In such a move, the receiving area will be filled without consideration for the individual elementary or group items contained in either the sending or receiving area, except as noted in the General Rules of the OCCURS clause.

  6. Table 14-1 summarizes the legality of the various types of MOVE statements. The general rule reference indicates the rule that prohibits the move or the behavior of a legal move.

Format 2
  1. If the CORRESPONDING phrase is used, selected items in identifier-1 are moved to selected items in identifier-2, according to the rules given in the section The CORRESPONDING Phrase earlier in this chapter. The results are the same as if the user had referred to each pair of corresponding identifiers in separate MOVE statements.

    The process is repeated for each destination group.

    Table 14-1: MOVE Statement Data Categories

    Category of Sending Item Category of Receiving Data Items1
    Alphabetic Alphanumeric-Edited/ Alpha-numeric Numeric Integer/Non-Integer Numeric-Edited External/Internal Floating Point DBCS
    Alphabetic Yes/4c Yes/4a No/3a No/3a No/4e
    Alphanumeric Yes/4c Yes/4a Yes/4b2 Yes/4b No/4e
    Alphanumeric-Edited Yes/4c Yes/4a No/3a No/3a No/4e
    Numeric Integer No/3b Yes/4a Yes/4b Yes/4b No/4e
    Numeric Non-Integer No/3b No/3c Yes/4b Yes/4b No/4e
    Numeric-Edited No/3b Yes/4a Yes/4b Yes/4b No/4e
    DBCS No/4e No/4e No/4e No/4e Yes/4e

    1. The relevant rule number is quoted in these columns
    2. An error will be reported if a non-integer alphanumeric literal sending item is used

14.1.3 The MULTIPLY Statement

The MULTIPLY statement causes numeric data items to be multiplied and sets the values of data items equal to the results.

General Formats

Format 1

Format 2

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.

  2. Each literal must be a numeric literal.

  3. The composite of operands, which is that hypothetical data item resulting from the superimposition of all receiving data items aligned on their decimal points, must not contain more than 18 digits.

  4. Floating-point data items and literals can be used anywhere a numeric data item or literal can be specified.

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.
Format 1
  1. When Format 1 is used, the value of identifier-1 or literal-1 is multiplied by the value of identifier-2. The value of the multiplier (identifier-2) is replaced by this product; similarly for each successive occurrence of identifier-2 in the left-to-right order in which identifier-2 is specified.
Format 2
  1. When Format 2 is used, the value of identifier-1 or literal-1 is multiplied by identifier-2 or literal-2 and the result is stored in the data item referenced by each identifier-3.

14.1.4 The NEXT SENTENCE Statement

The NEXT SENTENCE statement transfers control to the next COBOL sentence, that is, following the next period. It does not transfer control to the logically next COBOL verb as occurs with the CONTINUE verb.

General Format

Syntax Rules

  1. The NEXT SENTENCE statement can be used anywhere a conditional statement or an imperative-statement can be used.

General Rules

  1. The NEXT SENTENCE statement redirects the flow of execution to the logically next COBOL verb following the next period.

14.1.5 The NOTE Statement

The NOTE statement introduces a sentence or paragraph that will be treated as comments.

General Format

Syntax Rules

  1. The character-string can be any combination of characters from the computer character set.

General Rules

  1. If a NOTE statement is the first sentence of a paragraph, the entire paragraph is treated as comment.

  2. If a NOTE statement appears as other than the first sentence of a paragraph, text up to the next separator period is treated as comment.

14.1.6 The ON Statement

The ON statement allows selective execution of procedural statements on a periodic basis.

General Format

Syntax Rules

  1. Identifier-1, identifier-2 and identifier-3 must describe unsigned integer numeric elementary items.

  2. Literal-1, literal-2 and literal-3 must be unsigned numeric literals.

General Rules

  1. Prior to the first execution of each ON statement , a counter, implicitly defined for that ON statement (the implicit-ON-counter), is initialized to be zero.

  2. Identifier-1, identifier-2 and identifier-3 should, if specified, contain positive integer values at the time of execution of the ON statement. Varying these values between executions of the ON statement will affect subsequent executions of the ON statements.

  3. The implicit ON counter cannot be affected in any way other than by transfer of execution flow to that ON statement. (The ON counter of a called program can only be reset by the cancelling of that program; execution of the EXIT PROGRAM statement and subsequent CALL of the program without intervening CANCEL has no effect upon the implicit ON counter value.)

  4. The following value-list is then evaluated:

    1. the current value of identifier-1 or literal-1,

    2. a sequence of values being the results of repeatedly adding the current value of identifier-2 or literal-2 to the current value of identifier-1 or literal-1 until the value of identifier-3 or literal-3 is reached.

    The implicit-ON-counter is then compared with each of this list of values. If an equality is found, then imperative-statement-1 is executed. If no equality is found, then imperative-statement-2, if specified, is executed.

14.1.7 The OPEN Statement

The OPEN statement initiates the processing of files. It also performs checking and/or writing of labels and other input-output operations.

The REVERSED phrase of the OPEN 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.

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

Although it is a part of the standard COBOL definition, the REVERSED phrase of the OPEN statement is explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

The OPEN statement allocates system resources for a synchronization data item and initializes the data item.

General Formats

Format 1 (Record Sequential Files)

Format 2 ( Line Sequential, Relative And Indexed Files)

where sharing-phrase is:

Format 3 (Synchronization Data Items)

Syntax Rules

All Formats (All Files)
  1. The files referenced in the OPEN statement need not all have the same organization or access.

  2. If SHARING ALL is specified and the INPUT phrase is not specified, the LOCK MODE clause must be specified in the file control entry for file-name-1.

Format 1 (Record Sequential Files)
  1. NO REWIND is documentary only.

  2. The I/ O phrase can be used only for disk files.

  3. The EXTEND phrase must be used only for files for which the LINAGE clause has not been specified.

  4. The EXTEND phrase must not be specified with multiple file reels.

Format 2 (
dialm.gifLine Sequential,
Relative and Indexed Files)
  1. The EXTEND phrase can be used for files in sequential access mode.

  2. The SHARING phrase must not be specified for files with line sequential organization.

Format 3 (Synchronization Data Items)
  1. Identifier-1 must reference an elementary data item with a USAGE of EVENT-POINTER, MONITOR-POINTER, MUTEX-POINTER or SEMAPHORE-POINTER.

General Rules

Formats 1 and 2 (All Files)
  1. Prior to the successful execution of an OPEN statement for a given file, no statement (except for a SORT or MERGE statement with the USING or GIVING phrases) can be executed that references that file, either explicitly or implicitly.

  2. The successful execution of an OPEN statement determines the availability of the file and results in the file connector referenced by the file-name being in an open mode. The successful execution of an OPEN statement associates the file with the file-name through a file connector.

    The key words INPUT, OUTPUT, I-O, and EXTEND specify the type of input-output operations intended for the file through the file connector and establish the open mode. (See table 14-4, Permissible Combinations of Statements and OPEN Modes.)

    A file is available if it is physically present and is recognized by the file handling system. Table 14-2, Opening Available and Unavailable Files (file not currently open), shows the results of opening available and unavailable files that are not currently open. Table 14-3, Opening Available Shared Files that are Currently Open by Another File Connector, shows the results of opening available and unavailable files that are currently open by another file connector.

    Table 14-2: Opening Available and Unavailable Files (file not currently open)

    Open Mode File is available File is unavailable
    INPUT Normal open Open is unsuccessful
    INPUT (optional file) Normal open Normal open; the first read causes the at end condition or invalid key condition
    I-O Normal open Open is unsuccessful
    I-O (optional file) Normal open Open causes the file to be created
    OUTPUT Normal open; the file contains no records Open causes the file to be created
    EXTEND Normal open Open is unsuccessful
    EXTEND (optional file) Normal open Open causes the file to be created

    Table 14-3: Opening available shared files that are currently open by another file connector







    Open request
    Most restrictive existing sharing mode and open mode
    sharing with no other sharing with read only sharing with all other
    extend
    I-O
    input
    output
    extend
    I-O
    output
    input extend
    I-O
    output
    input
    SHARING WITH NO OTHER EXTEND
    I-O
    INPUT
    OUTPUT
    Unsuccessful open Unsuccessful open Unsuccessful open Unsuccessful open Unsuccessful open
    SHARING WITH READ ONLY EXTEND
    I-O
    Unsuccessful open Unsuccessful open Unsuccessful open Unsuccessful open Normal open
    INPUT Unsuccessful open Unsuccessful open Normal open Unsuccessful open Normal open
    OUTPUT Unsuccessful open Unsuccessful open Unsuccessful open Unsuccessful open Unsuccessful open
    SHARING WITH ALL OTHER EXTEND
    I-O
    Unsuccessful open Unsuccessful open Unsuccessful open Normal open Normal open
    INPUT Unsuccessful open Normal open Normal open Normal open Normal open
    OUTPUT Unsuccessful open Unsuccessful open Unsuccessful open Unsuccessful open Unsuccessful open

  3. The successful execution of an OPEN statement makes the associated record area available .

  4. In Table 14-2, "X" at an intersection indicates that the specified statement, used in the access mode given for that row, can be used with the open mode given at the top of the column.

    Table 14-4: Permissible Combinations of Statements and OPEN Modes

    File Access Mode OPEN Mode
    Statement Input Output Input-Output Extend
    Sequential READ X   X  
    WRITE   X   X
    REWRITE     X  
    Random (Non-Sequential Files) READ X   X  
    WRITE   X X  
    REWRITE     X  
    START        
    DELETE     X  
    Dynamic (Non-Sequential Files) READ X   X  
    WRITE   X X  
    REWRITE     X  
    START X   X  
    DELETE     X  


    Note: The START and DELETE statements can not be used with record

    or line

    sequential files.


  5. If the WITH LOCK phrase is specified, the OPEN statement acquires a lock on the whole file. (This is equivalent to specifying LOCK MODE IS EXCLUSIVE in the SELECT statement for the file. See the section The SELECT Statement in this chapter.)

  6. If, during the execution of an OPEN statement, a file attribute conflict occurs, the execution of the OPEN statement is unsuccessful. Your COBOL system defines which of the fixed file attributes are validated during the execution of the OPEN statement. See your file handling documentation for more details. The validation of fixed file attributes can vary depending on the organization and/or storage medium of the file.

  7. A file can be opened with the INPUT, OUTPUT, EXTEND and I/O phrases in the same run unit. Following the initial execution of an OPEN statement for a file connector, each subsequent OPEN statement execution for that same file connector must be preceded by the execution of a CLOSE statement for that file connector, even if the file is optional.

  8. Execution of the OPEN statement does not obtain or release the first data record.

  9. The external name of the file specified in the SELECT clause for a file is processed as follows:

    1. When the INPUT phrase is specified, execution of the OPEN statement causes the name to be checked in accordance with the operating system conventions for opening files for input.

    2. When the OUTPUT phrase is specified, execution of the OPEN statement causes the name to be checked in accordance with the operating system conventions for opening files for output.

  10. The file description entry for file-name-1, file-name-2, file-name-3, and file-name-4 must be equivalent to that used when this file was created.

  11. For files being opened with the INPUT or I/O phrase, the OPEN statement sets the file position indicator to the first record currently existing in the file for indexed and sequential files, and record position one for relative files. If no records exist in the file, the file position indicator is set such that the next executed READ statement for an indexed or sequential file will result in an AT END condition. If the file does not exist, OPEN INPUT will cause an error status, unless the file is optional.

  12. When the I/O phrase is specified and the LABEL RECORDS clause indicates lab el records are present, the execution of the OPEN statement includes the following steps:

    1. The labels are checked in accordance with the operating system-specified conventions for input-output label checking.

    2. The new labels are written in accordance with the operating system-specified conventions for input-output label writing.

  13. Upon successful execution of an OPEN statement with the OUTPUT phrase specified, a file is created. At that time the associated file contains no data records. If a file of the same name exists it will be deleted. If write-protected an error will occur.

  14. When the EXTEND phrase is specified, the OPEN statement positions the file immediately after the last logical record for that file. The last logical record for a sequential file is the last record written in the file. In a relative file it is the currently existing record with the highest relative record number, and in an indexed file it is the currently existing record with the highest prime key value.

  15. Execution of the OPEN statement causes the value of the FILE STATUS data item to be updated (see the section I/O Status earlier in this chapter).

  16. When LOCK MODE IS EXCLUSIVE is specified in the SELECT/ ASSIGN statement of a file, successful execution of an OPEN statement of that file locks the file exclusively to that run unit.

  17. When LOCK MODE IS AUTOMATIC or LOCK MODE IS MANUAL is specified in the SELECT/ASSIGN statement of a file, the file that is referred to is shareable. More than one run unit can successfully open such a file.

  18. A file opened for OUTPUT, and relative and indexed files opened EXTEND, are implicitly defined as files with an exclusive lock, that is, they are not shareable.

  19. Only shareable files opened for I/O can acquire record locks.

  20. If execution of the OPEN statement is unsuccessful, the physical file is not affected and the following actions take place in this order:

    1. A value is placed in the I/O status associated with file-name to indicate the condition that caused the OPEN statement to be unsuccessful.

    2. Any applicable USE AFTER EXCEPTION procedure is executed. (See the section The USE Statement in this chapter.)

  21. The I/O phrase permits the opening of a file for both input and output operations. If the file does not exist, the following rules apply:

    1. If the OPTIONAL phrase is specified, the file is created

    2. If the NOT OPTIONAL phrase is specified, an error occurs

    3. If neither phrase is specified, and the directive OPTIONAL-FILE was specified when the source element was compiled, the file is created.

    4. If neither phrase is specified, and the directive NOOPTIONAL-FILE was specified when the source element was compiled, an error occurs.

  22. If an input file is designated with the OPTIONAL phrase in its SELECT clause, when the file is opened there is an interrogation for the presence or absence of this file. If the file is not present, the first READ statement for this file causes the AT END condition to occur.

  23. When the EXTEND phrase is specified, the OPEN statement positions the file immediately following the last logical record of that file. Subsequent WRITE statements referencing the file will add records to the file as though the file had been opened with the OUTPUT phrase. If the file does not exist it will be created.

  24. When the EXTEND phrase is specified and the LABEL RECORDS clause in this file's FD indicates label records are present, the execution of the OPEN statement includes the following steps:

    1. The beginning file labels are processed only in the case of a single reel/unit file.

    2. The beginning reel/unit labels on the last existing reel/unit are processed as though the file was being opened with the INPUT phrase.

    3. The existing ending file labels are processed as though the file is being opened with the INPUT phrase. These labels are then deleted.

    4. Processing then proceeds as though the file had been opened with the OUTPUT phrase.

  25. The I /O phrase permits the opening of a file for both input and output operations,

    except files with ORGANIZATION LINE SEQUENTIAL.

    If the file does not exist, it will be created and used as an empty file for input

    unless NOT OPTIONAL was specified in the SELECT statement.

    An attempt to READ from the newly created file will cause an error.

  26. The SHARING phrase can be specified only for shared files. (See Sharing mode.)

  27. The SHARING phrase specifies what operations may be performed on the file through other file connectors sharing the file. (See Sharing mode.)

  28. The SHARING phrase overrides any SHARING clause in the file control entry of the file connector associated with the file-name. If there is no SHARING phrase on the OPEN statement, then file sharing is completely specified in the file control entry. If neither a SHARING phrase on the OPEN statement nor a SHARING clause in the file control entry is specified, the sharing mode is established for the file connector in accordance with Sharing mode.

Format 1 (Record Sequential Files)
  1. If the storage medium for the file permits rewinding, the following rules apply:

    1. Execution of the OPEN statement causes the file to be positioned at its beginning.

    2. When the REVERSED phrase is specified, the file is positioned at its end by execution of the OPEN statement.

  2. When the REVERSED phrase is specified, the subsequent READ statements for the file make the data available in reversed order; that is, starting with the last record.

Format 2 (Line Sequential Files)
  1. I/O mode is not allowed for line sequential files unless the REWRITE-LS Compiler directive is set.

Format 3 (Synchronization Data Items)
  1. Prior to the successful execution of an OPEN statement for a given synchronization data item, no statement can be executed that references that data item.

  2. The successful execution of an OPEN statement determines the availability of the synchronization data item.

  3. Execution of the OPEN statement causes the RETURN-CODE special register to be updated with one of the values specified for the CBL_MUTEX APIs.

  4. Following the initial execution of an OPEN statement for a synchronization data item, each subsequent OPEN statement execution for that same data item must be preceded by the execution of a CLOSE statement for that data item.

  5. If identifier-1 references an event data item, the execution of the OPEN statement initializes the data item to FALSE.

  6. If identifier-1 references a monitor data item, the execution of the OPEN statement initializes the monitor to NOT BROWSING, NOT READING, and NOT WRITING.

  7. If identifier-1 references a mutex data item, the execution of the OPEN statement initializes the data item to OFF.

  8. If identifier-1 references a semaphore data item, the execution of the OPEN statement initializes the data item to zero.


Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousProcedure Division - ENTER - INVOKE Procedure Division - PERFORM - ROLLBACKNext