# Compaq COBOL
Reference Manual

Previous | Contents | Index

Format 1

10. Executing the INSPECT statement does not initialize the value of tally-ctr.
11. If the ALL phrase is present, the value of tally-ctr is incremented by one for each occurrence of compare-val in src-string.
12. If the LEADING phrase is present, the value of tally-ctr is incremented by one for each contiguous occurrence of compare-val in src-string. The leftmost occurrence of compare-val must be at the position where comparison begins in the first comparison cycle. Otherwise, no tallying occurs.
13. If the CHARACTERS phrase is present, the value of tally-ctr is incremented by one for each character matched in src-string (see General Rule 6e).

Format 2

14. The adjectives ALL, LEADING, and FIRST apply to succeeding BY phrases until the next adjective appears.
15. If the CHARACTERS phrase is present, each character matched in src-string is replaced by replace-char (see General Rule 6e).
16. When ALL is present, each occurrence of compare-val in src-string is replaced by replace-val.
17. When LEADING is present, each contiguous occurrence of compare-val in src-string is replaced by replace-val. The leftmost occurrence of compare-val must be at the position where comparison begins in the first comparison cycle. Otherwise, no replacement occurs.
18. When FIRST is present, the leftmost occurrence of compare-val in src-string is replaced by replace-val.

Format 3

19. A Format 3 INSPECT statement executes as if there were two successive INSPECT statements with the same src-string. Execution proceeds as if:
    - The first statement were a Format 1 statement with TALLYING phrases identical to those in the Format 3 statement
    - The second statement were a Format 2 statement with REPLACING phrases identical to those in the Format 3 statement
    The General Rules for Formats 1 and 2 apply to the corresponding phrases in the Format 3 statement.

Format 4

20. A Format 4 statement executes as if:
    - It were a Format 2 INSPECT statement with a series of ALL phrases, one for each character of compare-chars
    - compare-val in each ALL phrase referred to a single character of compare-chars
    - replace-val in each ALL phrase referred to a single character of replace-chars
    The individual characters of compare-chars and replace-chars correspond by ordinal position in the data items.

Additional Reference

- Section 6.8.22, MOVE

Examples

In the following examples, the initial values of COUNT1 and COUNT2 are zero.

1. TALLYING phrase with BEFORE option:

       INSPECT ITEMA TALLYING COUNT1 FOR LEADING "L" BEFORE "A",
              COUNT2 FOR LEADING "A" BEFORE "L".

   ITEMA | COUNT1 | COUNT2
   --- | --- | ---
   LARGE | 1 | 0
   ANALYST | 0 | 1

2. TALLYING phrase and REPLACING LEADING phrase with AFTER option:

       INSPECT ITEMA TALLYING COUNT1 FOR ALL "L" "R"
              REPLACING LEADING "A" BY "E" AFTER INITIAL "L".

   ITEMA | COUNT1 | ITEMA
   --- | --- | ---
   CALLAR | 3 | CALLAR
   SALAMI | 1 | SALEMI
   LATTER | 2 | LETTER

3. REPLACING ALL phrase with BEFORE option:

       INSPECT ITEMA REPLACING ALL "A" BY "G" BEFORE "X".

   ITEMA | ITEMA
   --- | ---
   ARXAX | GRXAX
   HANDAX | HGNDGX
   HANDAA | HGNDGG

4. TALLYING and REPLACING ALL phrases:

       INSPECT ITEMA TALLYING COUNT1 FOR CHARACTERS AFTER "J"
              REPLACING ALL "A" BY "B".

   ITEMA | COUNT1 | ITEMA
   --- | --- | ---
   ADJECTIVE | 6 | BDJECTIVE
   JACK | 3 | JBCK
   JUJMAB | 5 | JUJMBB

5. REPLACING ALL phrase:

       INSPECT ITEMA REPLACING ALL "X" BY "Y", "B" BY "Z",
              "W" BY "Q" AFTER "R".

   ITEMA | ITEMA
   --- | ---
   RXXBQWY | RYYZQQY
   YZACDWBR | YZACDWZR
   RAWRXEB | RAQRYEZ

6. REPLACING CHARACTERS phrase:

       INSPECT ITEMA REPLACING CHARACTERS BY "B" BEFORE "A".

   ITEMA | ITEMA
   --- | ---
   12RXZABCD | BBBBBABCD
   12RXZBBCD | BBBBBBBBB

7. REPLACING ALL phrase:

       INSPECT ITEMA REPLACING ALL "A" BY "X" ALL "R" BY "X"
              AFTER "XXL".

   ITEMA | ITEMA
   --- | ---
   AALRRRA | XXLRRRX
   AXXLRRR | XXXLXXX

8. CONVERTING phrase:

       INSPECT ITEMA CONVERTING "SIR" TO "DTA"
              AFTER QUOTE BEFORE "@".

   ITEMA | ITEMA
   --- | ---
   TIRMS"SRXIL@STAR | TIRMS"DAXTL@STAR

## 6.8.21 MERGE

Function

The MERGE statement takes two or more identically sequenced files and combines them according to the key values you specify. During the process, it makes records available, in merged order, to routines in OUTPUT PROCEDURE or to an output file.

> ### mergefile

> is a file-name described in a sort-merge file description (SD) entry in the Data Division.

> ### mergekey

> is the data-name of a data item in a record associated with mergefile.

> ### alpha

> is an alphabet-name defined in the SPECIAL-NAMES paragraph of the Environment Division.

> ### infile

> is the file-name of an input file. It must be described in a file description (FD) entry in the Data Division.

> ### first-proc

> is the section-name or paragraph-name of the output procedure's first (or only) section or paragraph.

> ### end-proc

> is the section-name or paragraph-name of the output procedure's last section or paragraph.

> ### outfile

> is the file-name of an output file. It must be described in a file description (FD) entry in the Data Division.

Syntax Rules

1. MERGE statements can appear anywhere in the Procedure Division except in:
   - DECLARATIVES
   - Sections of a SORT or MERGE statement's INPUT or OUTPUT PROCEDURE
2. If mergefile contains variable length records, infile records must not be smaller than the smallest record in mergefile nor larger than the largest.
3. If mergefile contains fixed-length records, infile records must not be larger than the largest record described for mergefile.
4. If outfile contains variable length records, mergefile records must not be smaller than the smallest record in outfile nor larger than the largest.
5. If outfile contains fixed-length records, mergefile records must not be larger than the largest record described for outfile.
6. Each mergekey must be described in records associated with mergefile.
7. mergekey can be qualified.
8. mergekey cannot be a group that contains variable occurrence data items.
9. The description of mergekey cannot contain an OCCURS clause or be subordinate to one that does.
10. mergefile can have more than one record description. However, mergekey need not be described in more than one of the record descriptions. The character positions referenced by mergekey are used as the key for all the file's records.
11. The words THRU and THROUGH are equivalent.
12. If outfile is an indexed file, the first mergekey must be in the ASCENDING phrase. It must specify the same character positions in its record as the prime record key for outfile.

General Rules

1. The MERGE statement merges all records in the infile files.
2. If mergefile contains fixed-length records, any shorter infile records are space-filled on the right after the last character. Space-filling occurs before the infile record is released to mergefile.
3. The leftmost mergekey is the major key, and the next mergekey is the next most significant key. The significance of mergekey data items is not affected by how they are divided into KEY phrases. Only left-to-right order determines significance.
4. The ASCENDING phrase causes the merged sequence to be from the lowest mergekey value to the highest.
5. The DESCENDING phrase causes the merged sequence to be from the highest mergekey value to the lowest.
6. Merge sequence follows the rules for relation condition comparisons.
7. When the contents of all key data items of one record equal the contents of the corresponding key data items in another record, the order of return from the merge:
   - Follows the order of the associated input files in the MERGE statement
   - Causes all records with equal key values from one input file to be returned before any are returned from another
8. The MERGE statement determines the comparison collating sequence for nonnumeric mergekey items when it begins execution. If there is a COLLATING SEQUENCE phrase in the MERGE statement, MERGE uses that sequence. Otherwise, it uses the collating sequence that was established for the program as a whole in the PROGRAM COLLATING SEQUENCE clause of the OBJECT-COMPUTER paragraph. If you do not specify the collating sequence in either the MERGE statement or the OBJECT-COMPUTER paragraph, the program uses the NATIVE collating sequence.
9. The results of the merge are undefined unless the records in the infile files are ordered as described in the MERGE statement's ASCENDING or DESCENDING KEY clause.
10. The MERGE statement transfers all records in infile to mergefile. When the MERGE statement executes, infile must not be open.
11. For each infile, the MERGE statement:
    - Begins file processing as if the program had executed an OPEN statement with the INPUT phrase.
    - Obtains the logical records and releases them to the merge operation. MERGE obtains each record as if the program had executed a READ statement with the NEXT and AT END phrases.
    - Terminates file processing as if the program had executed a CLOSE statement with no optional phrases.
    These implicit OPEN, READ, and CLOSE operations cause associated USE procedures to execute if an exception condition occurs.
12. OUTPUT PROCEDURE consists of one or more sections that are as follows:
    - Contiguous in the source program
    - Not a part of any other procedure
13. When the MERGE statement enters the OUTPUT PROCEDURE range, it is ready to select the next record in merged order. Statements in the OUTPUT PROCEDURE range must execute at least one RETURN statement to make records available for processing.
14. The OUTPUT PROCEDURE can consist of any procedure needed to select, modify, or copy the next record made available by the RETURN statement in merged order from the file referenced by mergefile.
15. The range of the OUTPUT PROCEDURE additionally includes all statements executed as a result of a CALL, EXIT, GO TO, or PERFORM statement. The range of the OUTPUT PROCEDURE also includes all statements in the Declaratives Section that can be executed if control is transferred from statements in the range of the OUTPUT PROCEDURE.
16. The range of the OUTPUT PROCEDURE must not contain MERGE, SORT, or RELEASE statements.
17. If the MERGE statement is in a fixed segment, the OUTPUT PROCEDURE range must be either:
    - Completely in fixed segments
    - Completely contained in one independent segment
18. If the MERGE statement is in an independent segment, the OUTPUT PROCEDURE range must be either:
    - Completely in fixed segments
    - Completely contained in the same independent segment as the MERGE statement itself
19. If OUTPUT PROCEDURE is used, control passes to its sections during execution of the MERGE statement. When control passes to the last statement in the OUTPUT PROCEDURE range, the MERGE statement ends. Control then transfers to the next executable statement after the MERGE statement.
20. During execution of statements in the OUTPUT PROCEDURE range---or any USE AFTER EXCEPTION procedure implicitly invoked during the MERGE statement---no statement outside the range can manipulate the files or record areas associated with infile or outfile.
21. If there is a GIVING phrase, the MERGE statement writes all merged records to each outfile. This transfer is an implied MERGE statement OUTPUT PROCEDURE. Therefore, when the MERGE statement executes, outfile must not be open.
22. The MERGE statement begins outfile processing as if the program had executed an OPEN statement with the OUTPUT phrase.
23. The MERGE statement gets the merged logical records and writes them to each outfile. MERGE writes each record as if the program had executed a WRITE statement with no optional phrases.
    For relative files, the value of the relative key data item is 1 for the first returned record, 2 for the second, and so on. When the MERGE statement ends, the value of the relative key data item indicates the number of outfile records.
24. The MERGE statement terminates outfile processing as if the program had executed a CLOSE statement with no optional phrases.
25. These implicit OPEN, WRITE, and CLOSE operations cause associated USE procedures to execute if an exception condition occurs. If the MERGE statement tries to write beyond the boundaries of outfile, the applicable USE AFTER EXCEPTION procedure executes. If control returns from the USE procedure, or if there is no USE procedure, outfile processing terminates as if the program had executed a CLOSE statement with no optional phrases.
26. If outfile contains fixed-length records, any shorter mergefile records are space-filled on the right after the last character. Space-filling occurs before the mergefile record is released to outfile.

Additional References

- Section 4.1.2 paragraph in Chapter 4
- Section 4.1.3 paragraph in Chapter 4
- Section 4.2.10 paragraph in Chapter 4
- Section 6.8.42 statement

## 6.8.22 MOVE

Function

The MOVE statement transfers data to one or more data areas. The editing rules control data transfer.

> ### src-item

> is an identifier that represents the sending area.

> ### lit

> is a literal that represents the sending area.

> ### dest-item

> is an identifier that represents the receiving area.

Syntax Rules

1. CORR is an abbreviation for CORRESPONDING.
2. In the CORRESPONDING phrase, both src-item and dest-item must be group items, and there can be only one dest-item.
3. If any dest-item is numeric or numeric edited, lit cannot be any of the following:
   - HIGH-VALUE
   - HIGH-VALUES
   - LOW-VALUE
   - LOW-VALUES
   - SPACE
   - SPACES
   - QUOTE
   - QUOTES
4. If lit is the figurative constant ALL literal and the usage of dest-item is COMP-1 or COMP-2, the MOVE statement uses only one occurrence of literal.
5. No operand can be an index data item.

General Rules

1. In Format 2, when the CORRESPONDING phrase is present, selected items in src-item are moved to selected items in dest-item. The rules for the CORRESPONDING option control these moves. The results are the same as if the MOVE statement were replaced by separate MOVE statements for each pair of corresponding items in src-item and dest-item.
2. In Format 1, the MOVE statement moves the sending area to the first dest-item, then to each additional dest-item, in the same order in which they appear in the statement.
3. If src-item is reference-modified, subscripted, or indexed, or is a function-identifier, the reference modifier, subscript, index, or function-identifier is evaluated once, immediately before the move to the first dest-item.
4. Subscript or index evaluation for a dest-item occurs immediately before the move to that item.
5. The length of src-item is evaluated once, immediately before the move to the first dest-item.
6. The length of each dest-item is evaluated immediately before the move to that item.
7. The result of the first of the following MOVE statements is equivalent to the three that follow. The word temp represents an intermediate result item supplied by the compiler.

       MOVE ITEMA (ITEMB) TO ITEMB, ITEMC (ITEMB).

       MOVE ITEMA (ITEMB) TO temp.
       MOVE temp TO ITEMB.
       MOVE temp TO ITEMC (ITEMB).

Elementary Moves

8. A move is elementary when dest-item is an elementary item, and the sending area is either an elementary data item or a literal.
   1. An elementary item belongs to one of these categories, depending on its PICTURE clause:
      - Numeric
      - Alphabetic
      - Alphanumeric
      - Numeric edited
      - Alphanumeric edited
   2. Numeric literals are numeric. Nonnumeric literals are alphanumeric.
   3. The figurative constant ZERO is numeric when moved to a numeric or numeric edited item. Otherwise, it is alphanumeric.
   4. The figurative constant SPACE is alphabetic.
   5. All other figurative constants are alphanumeric.
9. These rules apply to elementary moves between categories:
   1. The figurative constant SPACE, or an alphanumeric edited or alphabetic data item, cannot be moved to a numeric or numeric edited data item.
   2. A numeric literal, the figurative constant ZERO, or a numeric or numeric edited data item, cannot be moved to an alphabetic data item.
   3. A noninteger numeric literal or data item cannot be moved to an alphanumeric or alphanumeric edited data item.
   4. All other elementary moves are valid.

Editing, De-Editing, and Data Conversion During Elementary Moves

10. Editing, de-editing, or other required internal data conversions occur during elementary moves. They are controlled by the description of dest-item.
11. When dest-item is alphanumeric or alphanumeric edited, alignment and space-filling occur according to the Standard Alignment Rules.
    If lit or src-item is signed numeric, the operational sign is not moved. If the operational sign occupies a separate character position:
    1. The sign character is not moved.
    2. The size of lit or src-item is considered to be one less than its actual size (in terms of Standard Data Format characters).
    If the sending operand is numeric and contains the PICTURE symbol (P), all digit positions specified with this symbol are considered to have the value zero and are counted in the size of the sending operand.
12. When dest-item is numeric or numeric edited, decimal point alignment and zero-filling occur according to the Standard Alignment Rules.
    1. When dest-item is a signed numeric item, the sign from lit or src-item is placed in it. If the sending item is unsigned, a positive sign is placed in dest-item.
    2. When dest-item is an unsigned numeric item, the absolute value of lit or src-item is moved.
    3. When lit or src-item is alphanumeric, the move occurs as if the sending item were described as an unsigned numeric integer.
    4. When src-item is numeric edited, the compiler de-edits it before moving it to dest-item. Src-item can be signed.
13. When dest-item is alphabetic, justification and space-filling occur according to the Standard Alignment Rules.

Nonelementary Moves

14. A nonelementary move occurs as if it were an alphanumeric-to-alphanumeric elementary move. However, there is no internal data conversion. The move is not affected by individual elementary or group items in either src-item or dest-item, except as noted in the General Rules for the OCCURS clause.

Summary

Table 6-13 summarizes the valid types of MOVE statements. References after slash marks show the applicable General Rule. For example, moving a numeric edited item to an alphabetic item is invalid because of General Rule 9b.

Table 6-13 Valid MOVE Statements
| Category of Receiving Data Item (dest-item)
--- | ---
Category of Sending Data Item (lit or src-item) | Alphabetic | Alphanumeric Edited Alphanumeric | Numeric Integer Numeric Noninteger Numeric Edited
Alphabetic | Yes/13 | Yes/11 | No/9a
Alphanumeric | Yes/13 | Yes/11 | Yes/12
Alphanumeric Edited | Yes/13 | Yes/11 | No/9a
Numeric Integer | No/9b | Yes/11 | Yes/12
Numeric Noninteger | No/9b | No/9c | Yes/12
Numeric Edited | No/9b | Yes/11 | Yes/12

Additional References

- Section 5.2.2, COBOL Standard Alignment Rules
- Section 5.3.35, OCCURS clause in Chapter 5
- Section 5.3.37, PICTURE clause in Chapter 5
- Section 5.3.46, SIGN clause in Chapter 5
- Section 6.6.5, CORRESPONDING Phrase

Examples

The following examples show the result of executing the statement:

    MOVE ITEMA TO ITEMB.

An s indicates a space character.

- Numeric edited receiving item:
  (The PICTURE of ITEMA is S9999V99.)

  | ITEMA Value | ITEMB PICTURE | ITEMB Contents
  --- | --- | --- | ---
  a. | +0023.00 | ZZZZ.99 | ss23.00
  b. | -0036.93 | ++++.99 | s-36.93
  c. | +1234.56 | Z,ZZZ.99 | 1,234.56
  d. | +1234.56 | Z,ZZZ.99- | 1,234.56s
  e. | +1234.56 | Z,ZZZ.99+ | 1,234.56+
  f. | -1234.56 | $,$$$,$$$.99DB | sss$1,234.56DB
  g. | -1234.56 | $,$$$.99- | s$234.56-
  h. | +0001.25 | $,$$$.99 | sss$1.25
  i. | -0001.25 | $,$$$.99 | sss$1.25
  j. | +0000.00 | $,$$9.99 | sss$0.00
  k. | +0000.00 | $,$$$.$$ | ssssssss

  Previous | Next | Contents | Index