[an error occurred while processing this directive]

HP OpenVMS Systems Documentation
Content starts here

HP COBOL
Reference Manual

Previous Contents Index

Format 3

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

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

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
  1. REPLACING CHARACTERS phrase: 


    INSPECT ITEMA REPLACING CHARACTERS BY "B" BEFORE "A".
    ITEMA ITEMA
    12RXZABCD BBBBBABCD
    12RXZBBCD BBBBBBBBB
  2. REPLACING ALL phrase: 


    INSPECT ITEMA REPLACING ALL "A" BY "X" ALL "R" BY "X"
       AFTER "XXL".
    ITEMA ITEMA
    AALRRRA XXLRRRX
    AXXLRRR XXXLXXX
  3. 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.

Previous Next Contents Index