[an error occurred while processing this directive]

HP OpenVMS Systems Documentation
Content starts here

HP COBOL
Reference Manual

Previous Contents Index

8.1.2 REPLACE

Function

The REPLACE statement is used to replace source program text.

pseudo-text-1

is a text-matching argument that the compiler compares against text-words in the source text.

pseudo-text-2

is a replacement item that the compiler inserts into the source program.

Syntax Rules

  1. A REPLACE statement can be inserted anywhere that a character-string can be used. This statement must be preceded by a separator period unless it is the first statement in a separately compiled program.
  2. A REPLACE statement must be terminated by the separator period.
  3. pseudo-text-1 must contain at least one text-word.
  4. pseudo-text-2 can contain zero, one, or more text-words.
  5. Character-strings within pseudo-text-1 and pseudo-text-2 can be continued.
  6. pseudo-text-1 must not consist entirely of a separator comma or a separator semicolon.
  7. The word REPLACE is considered part of a comment-entry if it appears in the comment-entry or in the place where a comment-entry can appear.

General Rules

Format 1

  1. Each matched occurrence of pseudo-text-1 in the source program is replaced by the corresponding pseudo-text-2.

Format 2

  1. Any text replacement currently in effect is discontinued.

Both Formats

  1. A REPLACE statement remains in effect until the next occurrence of a REPLACE statement or until the end of a separately compiled program has been reached.
  2. Any occurrence of a REPLACE statement in a source program is processed after all COPY statements in the source program have been processed.
  3. pseudo-text-2 must not contain a REPLACE statement.
  4. The comparison operation starts with the leftmost source text word and the first text-matching argument. The compiler compares the entire text-matching argument to an equivalent number of consecutive source text-words.
  5. A text-matching argument matches the source text only if the ordered sequence of text-words that forms the text-matching argument is equal, character for character, to the ordered sequence of source text-words.
    In the matching operation, the compiler treats each occurrence or combination of the following items in source text as a single space:
    • Separator comma
    • Separator semicolon
    • A sequence of one or more separator spaces
  6. If no match occurs, the compiler repeats the comparison operation with each successive text-matching argument until a match is found or there are no more text-matching arguments.
  7. If no match occurs after the compiler has compared all of the text-matching arguments, the next successive source text-word becomes the leftmost text-word, and the comparison resumes with the first occurrence of pseudo-text-1.
  8. If a match occurs between a text-matching argument and the source program text, the compiler inserts the replacement text into the source program. The source text-word immediately following the rightmost replaced text-word becomes the leftmost text-word for the next cycle. The comparison cycle resumes with the first occurrence of pseudo-text-1.
  9. The comparison cycles continue until the rightmost text-word in the source text that is within the scope of the REPLACE statement has been either:
    • Matched and replaced
    • Used as the leftmost source text-word in a comparison cycle
  10. The rules for Reference Format determine the sequence of text-words in the source text and the text-matching arguments.
  11. The compiler ignores comment lines and blank lines in the source program and in pseudo-text-1 for matching.
  12. When the compiler inserts pseudo-text-2 in the source program, it inserts comment lines and blank lines in pseudo-text-2 without modification.
  13. Debugging lines are permitted in pseudo-text-1 and pseudo-text-2. The compiler treats the comparison of debugging lines as if the conditional compilation character does not appear in the indicator area.
  14. The compiler cannot determine the syntactic correctness of source text or the source program until all COPY and REPLACE statements have been processed.
  15. Text words that are inserted as a result of a processed REPLACE statement are placed in the source program according to the rules for Reference Format.
  16. When the compiler inserts text words of pseudo-text-2 into the source program, additional spaces may be introduced between text words where spaces already exist (including the assumed space between source lines).
  17. If additional lines are added to the source program as a result of a REPLACE operation, the indicator area of the added lines contains the same character as the line on which the text being replaced begins (unless that line contains a hyphen, in which case the introduced line contains a space).
    If a literal within pseudo-text-2 cannot be contained on a single line without a continuation to another line in the resultant program and the literal is not being placed on a debugging line, additional continuation lines are introduced that contain the remainder of the literal. If replacement requires the continued literal to be continued on a debugging line, the program is in error.

Additional Reference

See Section 1.3, Source Reference Format.

Examples

In the following examples, uppercase words represent text-words that have been replaced.

  1. REPLACE statement with multiple replacement items: 


             8 working-storage section.
         9 replace ==alpha== by ==NUM-1==
        10         ==num== by ==ALPHA-1==.
 R      11 01  NUM-1  pic 9(10).
 R      12 01  ALPHA-1
        13            pic x(10).
        14 procedure division.
  2. Multiple REPLACE statements:
    A given occurrence of the REPLACE statement is in effect from the point at which it is specified until the next occurrence of the REPLACE statement. The new REPLACE statement supersedes the text-matching established by the previous REPLACE statement. 


             7 working-storage section.
         8 01  total           pic 9(4)v99.
         9 replace ==class== by ==CLASS1==
        10         ==total== by ==ORDER-AMT==.
        11 01  customer-rec.
 R      12     03  CLASS1      pic x(02).
        13     03  name        pic x(25).
        14     03  address.
        15         05  street  pic x(20).
        16         05  city    pic x(20).
        17         05  state   pic xx.
        18         05  zip     pic 9(5).
        19     03  orders occurs 6 times.
        20         05  order-numb  pic 9(6).
        21         05  order-date  pic 9(6).
 R      22         05  ORDER-AMT   pic 9(4)v99.
        23 procedure division.
        24 replace ==class== by ==CLASS1==.
        25 p0.  add order-amt of orders(3) to total.

    In the previous example, the word total on line 25 is not replaced because the REPLACE statement on line 24 reestablished the text-matching arguments.

  3. REPLACE OFF:
    Any text-matching currently in effect is turned off. 


           11 working-storage section.
       12 replace ==add== by ==PIC 9(18)==.
 R     13 01  a1              PIC 9(18).
 R     14 01  a2              PIC 9(18).
       15 procedure division.
       16     replace off.
       17 p0. add a1 to a2.

    In the previous example, the word add on line 17 is not replaced because the REPLACE statement on line 16 turned off all text-matching arguments.
  4. COPY interaction:
    In the following example, library text is copied from the library file DATAFILE.LIB: 


    Contents of "DATAFILE.LIB":
01      customer-rec.
        03  class       pic x(02).
        03  name        pic x(25).
        03  address.
            05  street  pic x(20).
            05  city    pic x(20).
            05  state   pic xx.
            05  zip     pic 9(5).
        03  orders occurs 6 times.
            05  order-number    pic 9(6).
            05  order-date      pic 9(6).
            05  order-amt       pic 9(4)v99.

    The text-matching specified by an active REPLACE statement occurs after COPY (and COPY REPLACING) processing is complete. 


             7 working-storage section.
         8 replace ==class== by ==CLASS1==.
         9 copy datafile.
L       10 01  customer-rec.
L       11     03  CLASS1      pic x(02).
L       12     03  name        pic x(25).
L       13     03  address.
L       14         05  street  pic x(20).
L       15         05  city    pic x(20).
L       16         05  state   pic xx.
L       17         05  zip     pic 9(5).
L       18     03  orders occurs 6 times.
L       19         05  order-number    pic 9(6).
L       20         05  order-date      pic 9(6).
L       21         05  order-amt       pic 9(4)v99.
        22 procedure division.

Previous Next Contents Index