REPLACE Statement

General Format

Format 1

REPLACE { { old-text BY new-text }             } ... ] .
        { { {LEADING } literal-1 BY {literal-2} } }
        { { {TRAILING}              {SPACE    } } }
        { {                         {SPACES   } } }

Format 2

REPLACE OFF.

Syntax Rules

1. The REPLACE statement must be terminated by a period. The period is part of the REPLACE statement and does not otherwise affect the program.
2. The REPLACE statement may be used anywhere a separator may occur. It may be placed in Area A or Area B.
3. old-text and new-text may be any of the following:
   • A series of text words placed between == delimiters. For example ==WORD-1 WORD-2== specifies a two-word sequence. In old-text, at least one word must be specified. In new-text, zero words may be used
   • A numeric or nonnumeric literal
   • A data name, including qualifiers, subscripts, and reference modification
   • Any single text word
4. For purposes of the REPLACE statement, a text word is a contiguous sequence of characters in Area A or Area B that form one of the following:
   • A separator, except for: space, a pseudo-text delimiter (==), and the opening and closing delimiters for nonnumeric literals
   • A numeric or nonnumeric literal
   • Any of a sequence of characters except comment lines and the word COPY, bounded by separators, which is neither a separator nor a literal
5. literal-1 and literal-2 are nonnumeric literals
6. The phrases SPACE and SPACES are equivalent. When one of these is used instead of literal-2, literal-1 is deleted and no spaces are actually substituted

General Rules

1. The REPLACE statement specifies conversion of source statements containing old-text into new-text. The scope of a REPLACE statement continues from the first text word following the REPLACE statement to the beginning of the next REPLACE statement, or the end of the program. A Format 2 REPLACE statement terminates the scope of any preceding REPLACE statement.
2. REPLACE statements are processed after COPY statements. The text produced by the action of a REPLACE statement must not contain a REPLACE statement.
3. Within the scope of a REPLACE statement, any source text that matches old-text is logically replaced by new-text. The comparison operation that determines text replacement is done as follows:
   1. The leftmost source text word is the first text word used for comparison. Starting with this word, and the first old-text specified, the entire old-text sequence is compared with an equivalent number of contiguous source text words.
   2. old-text matches the source text only if the ordered sequence of text words of old-text is identical to the ordered sequence of source text words. For purposes of matching, a separator semicolon, comma, or space is considered a space, and a sequence of one or more spaces is considered a single space. Also, lower-case characters are considered the same as upper-case characters in all text words except for nonnumeric literals.
   3. If no match occurs, the comparison is repeated for each old-text specified until a match is found or each old-text has been tried.
   4. After all old-text comparisons have been tried and no match has occurred, the next source text word is then considered as the leftmost word and the cycle is repeated.
   5. Whenever a match occurs between the source text and old-text, the corresponding new-text replaces old-text in the source program. The source text word that follows the rightmost word that participated in the match then becomes the new leftmost word for subsequent cycles.
   6. When you are using the LEADING/TRAILING option, a match between library text and literal-1 will replace only the specific LEADING or TRAILING characters indicated in the REPLACE statement with the text in literal-2. These characters can be a substring or a whole word. If a SPACE or SPACES phrase is used, the LEADING or TRAILING characters are deleted.
   7. The comparison cycle continues until the rightmost text word in the REPLACE scope has either participated in a match or has been the leftmost word of a comparison cycle.
4. Comment lines and blank lines occurring in old-text are ignored for purposes of matching.
5. Debugging lines may appear in old-text. Text words appearing in a debugging line participate in the matching rules as if the line were old-text a normal text line.
6. When new-text is copied into the source program, the first word of new-text is copied into the same Area as the leftmost word of the replaced text. Subsequent words of new-text are copied into Area B.
7. It is possible to use the REPLACE statement to replace substrings. In addition to the use of single and double quotes to delimit the substring, the following delimiters are also allowed:

   ==(XYZ)==
   ==*XYZ*==
   ==:XYZ:==

Code Examples

REPLACE 
   ==STANDARD-ALPHA==    BY   ==ALPHA-UPPER-CASE==
   ==TABLE-SIZE==        BY   ==MAX-TABLE-SIZE==
   ==PAGE-BUFFER-SIZE==  BY   ==SHORT-PAGE-SIZE==
   ==WITH-DEBUG-MODE==   BY   ====.
*delete matched text
...
REPLACE OFF.
*turns off REPLACE 

Highlights for first-time users

1. Multiple REPLACE statements are permitted. The REPLACE statement can appear anywhere in the program source.
2. The substitution actions of the REPLACE statement continue to affect the program source until the REPLACE statement is either superseded by a new REPLACE statement or turned off by the REPLACE OFF statement.
3. REPLACE statements are processed after COPY statements.
4. REPLACE statements can not contain COPY statements. COPY statements may contain REPLACE statements.
5. The replaced text does not appear in the listing produced by the ACUCOBOL-GT compiler (-Lo filename compiler argument). This is a common source of confusion for users who check the compilation listing file for verification that the replacing action occurred. You can, however, use the -Lp compiler option to create an output file that includes the replaced text.