Micro Focus Visual COBOL 2.3 Update 2 for Eclipse (Windows) > General Reference > COBOL Language Reference > Part 2. Program Definition > Procedure Division > Statements > The MERGE Statement

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

Directives

In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
- CALLSORT"EXTSM" - enables you to specify up to 128 files in the USING or GIVING clause. Without this directive the limit is 10 file-names.

Syntax Rules

File-name-1 must be described in a sort-merge file description entry in the Data Division.
Procedure-name-1 represents the name of an output procedure.
Procedure-name-1 and procedure-name-2 must be section-names.
This restriction is removed.
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.
File-name-2, file-name-3, and file-name-4 must be described in file description entries, not in sort-merge file description entries, in the Data Division.
The words THRU and THROUGH are equivalent.
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 positions 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 records are merged in numeric order.
No more than one file-name from a multiple file reel can appear in the MERGE statement.
File-names must not be repeated in the MERGE statement.
MERGE statements can appear anywhere except in the declaratives portion of the Procedure Division.
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.
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.

General Rules

The MERGE statement merges all records contained on the files referenced by file-name-2 and file-name-3.
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.
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 most significant key, and so on.
1. When the ASCENDING phrase is specified, the merged sequence is 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 is 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.
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.
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.
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.
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.
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 topic Explicit and Implicit Transfers of Control in the chapter Concepts of the COBOL Language.)
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.
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.
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 has 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.
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.
Segmentation, as defined in the topic Segmentation, 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.
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.