Library View Topics Framed Contents Revised Topics Previous Topic Next Topic Search Search ResultsPrevious Topic MatchNext Topic Match Notes List Notes Print Download No PDF Handheld DisconnectedHandheld ConnectedHelp

8.1.4.3 Replacement and Comparison Rules
  1. Arithmetic and logical operators are considered text words and can be replaced only through the pseudo-text option.
  2. When a figurative constant is operand-1, it will match only if it appears exactly as it is specified. For example, if ALL "AB" is specified in the library text, then "ABAB" is not considered a match; only ALL "AB" is considered a match.
  3. When replacing a PICTURE character-string, the pseudo-text option should be used; to avoid ambiguities, pseudo-text-1 should specify the entire PICTURE clause, including the key word PICTURE or PIC.
  4. Any separator comma, semicolon, and/or space preceding the leftmost word in the library text is copied into the source program. Beginning with the leftmost library text word and the first operand-1 specified in the REPLACING option, the entire REPLACING operand that precedes the key word BY is compared to an equivalent number of contiguous library text words.
  5. Operand-1 matches the library text if, and only if, the ordered sequence of text words in operand-1 is equal, character for character, to the ordered sequence of library words. For matching purposes, each occurrence of a comma or semicolon separator and each sequence of one
    X or more space separators is considered to be a single space. However,
    X when operand-1 consists solely of a separator comma or semicolon, it
    X participates in the match as a text-word (in this case, the space
    X following the comma or semicolon separator can be omitted).

    X When the library text contains a closing quotation mark that is not
    X immediately followed by a separator space, comma, semicolon, or
    X period, the closing quotation mark will be considered a separator
    X quotation mark.
  6. If no match occurs, the comparison is repeated with each successive operand-1, if specified, until either a match is found or there are no further REPLACING operands.
  7. Whenever a match occurs between operand-1 and the library text, the associated operand-2 is copied into the source program.
  8. The COPY statement with REPLACING phrase can be used to replace parts of words. By inserting a dummy operand delimited by colons into the program text, the compiler will replace the dummy operand with the desired text. Example 3 shows how this is used with the dummy operand :TAG:.
    Note: The colons serve as separators and make TAG a stand-alone operand.
  9. When all operands have been compared and no match is found, the leftmost library text word is copied into the source program.
  10. The next successive uncopied library text word is then considered to be the leftmost text word, and the comparison process is repeated, beginning with the first operand-1. The process continues until the rightmost library text word has been compared.
  11. Comment lines or blank lines occurring in the library text and in pseudo-text-1 are ignored for purposes of matching; and the sequence of text words in the library text and in pseudo-text-1 is determined by the rules for reference format. Comment lines or blank lines appearing in pseudo-text-2 are copied into the resultant program unchanged whenever pseudo-text-2 is placed into the source program as a result of text replacement. Comment lines or blank lines appearing in library text are copied into the resultant source program unchanged with the following exception: a comment line or blank line in library text is not copied if that comment line or blank line appears within the sequence of text words that match pseudo-text-1.
  12. Text words, after replacement, are placed in the source program according to standard COBOL format rules.
  13. X COPY REPLACING does not affect the EJECT, SKIP1/2/3, or TITLE
    X compiler-directing statements. When text words are placed in the
    X source program, additional spaces are introduced only between text
    X words where there already exists a space (including the assumed space
    X between source lines).
Sequences of code (such as file and data descriptions, error and exception routines, etc.) that are common to a number of programs can be saved in a library, and then used in conjunction with the COPY statement. If naming conventions are established for such common code, then the REPLACING phrase need not be specified. If the names will change from one program to another, then the REPLACING phrase can be used to supply meaningful names for this program.
Example 1
In this example, the library text PAYLIB consists of the following Data Division entries: 



     01  A.
       02  B    PIC S99.
       02  C    PIC S9(5)V99.
       02  D    PIC S9999 OCCURS 1 TO 52 TIMES
           DEPENDING ON B OF A.
The programmer can use the COPY statement in the Data Division of a program as follows: 



         COPY PAYLIB.
In this program, the library text is copied; the resulting text is treated as if it had been written as follows: 



     01  A.
       02  B    PIC S99.
       02  C    PIC S9(5)V99.
       02  D    PIC S9999 OCCURS 1 TO 52 TIMES
           DEPENDING ON B OF A.
Example 2
To change some (or all) of the names within the library text, the programmer can use the REPLACING phrase: 



       COPY PAYLIB REPLACING  A BY PAYROLL
                              B BY PAY-CODE
                              C BY GROSS-PAY
                              D BY HOURS.
In this program, the library text is copied; the resulting text is treated as if it had been written as follows: 



     01  PAYROLL.
       02  PAY-CODE    PIC S99.
       02  GROSS-PAY    PIC S9(5)V99.
       02  HOURS    PIC S9999 OCCURS 1 TO 52 TIMES
           DEPENDING ON PAY-CODE OF PAYROLL.
The changes shown are made only for this program. The text, as it appears in the library, remains unchanged.
Example 3
If the following conventions are followed in library text, then parts of names (for example the prefix portion of data-names) can be changed with the REPLACING phrase.
In this example, the library text PAYLIB consists of the following Data Division entries: 



     01  :TAG:.
       02  :TAG:-WEEK          PIC S99.
       02  :TAG:-GROSS-PAY     PIC S9(5)V99.
       02  :TAG:-HOURS         PIC S999  OCCURS 1 TO 52 TIMES
           DEPENDING ON :TAG:-WEEK OF :TAG:.
The programmer can use the COPY statement in the Data Division of a program as follows: 



     COPY PAYLIB REPLACING ==:TAG:== BY ==Payroll==.
Note: It is important to notice in this example the required use of colons or parentheses as delimiters in the library text. Colons are recommended for clarity because parentheses can be used for a subscript, for instance in a table.
In this program, the library text is copied; the resulting text is treated as if it had been written as follows: 



     01  PAYROLL.
       02  PAYROLL-WEEK        PIC S99.
       02  PAYROLL-GROSS-PAY   PIC S9(5)V99.
       02  PAYROLL-HOURS       PIC S999  OCCURS 1 TO 52 TIMES
           DEPENDING ON PAYROLL-WEEK OF PAYROLL.
The changes shown are made only for this program. The text, as it appears in the library, remains unchanged.
Example 4
This example shows how to selectively replace level numbers without replacing the numbers in the PICTURE clause: 



     COPY xxx REPLACING ==(01)== BY ==(01)==
                        == 01 == BY == 05 ==.

Previous Topic Next Topic © Copyright IBM Corp. 1991, 1998

IBM Library Server Copyright 1989, 2005 IBM Corporation. All rights reserved.




Return to library:   z/OS | z/OS.e | TPF | z/VSE | z/VM | IBM Hardware | IBM System z Redbooks
Glossary:   IBM terminology
Publications:   How to order publications
Readers:   Download IBM Library Reader | Download IBM Softcopy Reader | Download Adobe® Acrobat® Reader®
Library management:   Download IBM Softcopy Librarian
Contacts:   Contact z/OS

Adobe, the Adobe logo, Acrobat, the Acrobat logo, and Acrobat Reader are registered trademarks of Adobe Systems incorporated.