The REPLACE statement is used to replace source text.
A REPLACE statement can occur anywhere in the source text that a character-string can occur. It must be preceded by a separator period except when it is the first statement in a separately compiled program. It must be terminated by a separator period.
The REPLACE statement provides a means of applying a change to an entire COBOL compilation group, or part of a compilation group, without manually having to find and modify all places that need to be changed. It is an easy method of doing simple string substitutions. It is similar in action to the REPLACING phrase of the COPY statement, except that it acts on the entire source text, not just on the text in COPY libraries.
If the word REPLACE appears in a comment-entry or in the place where a comment-entry can appear, it is considered part of the comment-entry.
Each matched occurrence of pseudo-text-1 in the source text is replaced by the corresponding pseudo-text-2.
| Format 2 |
|---|
|
Any text replacement currently in effect is discontinued with the format-2 form of REPLACE. If format 2 is not specified, a given occurrence of the REPLACE statement is in effect from the point at which it is specified until the next occurrence of a REPLACE statement or the end of the separately compiled program.
pseudo-text-1 can consist solely of a separator comma or a separator semicolon.
pseudo-text-1 and pseudo-text-2 can contain any text words (except the word COPY) that can be written in source text, including national literals, DBCS literals, and multibyte user-defined words.
Characters outside those allowed for COBOL words and separators must not appear in library text or pseudo-text except in comment lines, comment-entries, alphanumeric literals, DBCS literals, or national literals.
Multibyte user-defined words must be wholly formed; that is, there is no partial-word replacement for multibyte words.
pseudo-text-1 and pseudo-text-2 can contain single-byte and multibyte characters in comment lines and comment entries.
Individual character-strings within pseudo-text can be up to 322 characters long, except that strings containing multibyte characters cannot be continued.
The compiler processes REPLACE statements in source text after the processing of any COPY statements. COPY must be processed first, to assemble complete source text. Then REPLACE can be used to modify that source text, performing simple string substitution. REPLACE statements cannot themselves contain COPY statements.
The text produced as a result of the processing of a REPLACE statement must not contain a REPLACE statement.
The character-strings and separators comprising pseudo-text can start in either area A or area B. If, however, there is a hyphen in the indicator area of a line that follows the opening pseudo-text delimiter, area A of the line must be blank; and the normal rules for continuation of lines apply to the formation of text words. (See Continuation lines.)
The comparison operation to determine text replacement starts with the leftmost source text word following the REPLACE statement, and with the first pseudo-text-1. pseudo-text-1 is compared to an equivalent number of contiguous source text words. pseudo-text-1 matches the source text if, and only if, the ordered sequence of text words that forms pseudo-text-1 is equal, character for character, to the ordered sequence of source text words.
For purposes of matching, each occurrence of a separator comma, semicolon, or space, and each sequence of one or more space separators is considered to be a single space.
However, when pseudo-text-1 consists solely of a separator comma or semicolon, the comma or semicolon participates in the match as a text word (in this case, the space following the comma or semicolon separator can be omitted).
If no match occurs, the comparison is repeated with each successive occurrence of pseudo-text-1, until either a match is found or there is no next successive occurrence of pseudo-text-1.
When all occurrences of pseudo-text-1 have been compared and no match has occurred, the next successive source text word is then considered as the leftmost source text word, and the comparison cycle starts again with the first occurrence of pseudo-text-1.
Whenever a match occurs between pseudo-text-1 and the source text, the corresponding pseudo-text-2 replaces the matched text in the source text. The source text word immediately following the rightmost text word that participated in the match is then considered as the leftmost source text word. The comparison cycle starts again with the first occurrence of pseudo-text-1.
The comparison operation continues until the rightmost text word in the source text that is within the scope of the REPLACE statement has either participated in a match or been considered as a leftmost source text word and participated in a complete comparison cycle.
Comment lines or blank lines occurring in the source text and in pseudo-text-1 are ignored for purposes of matching. The sequence of text words in the source text and in pseudo-text-1 is determined by the rules for reference format (see Reference format). Comment lines or blank lines in pseudo-text-2 are placed into the resultant program unchanged whenever pseudo-text-2 is placed into the source text as a result of text replacement. Comment lines or blank lines appearing in source text are retained unchanged with the following exception: a comment line or blank line in source text is not retained if that comment line or blank line appears within the sequence of text words that match pseudo-text-1.
Lines containing *CONTROL (*CBL), EJECT, SKIP1/2/3, or TITLE statements can occur in source text. Such lines are treated as comment lines during REPLACE statement processing.
Debugging lines are permitted in pseudo-text. Text words within a debugging line participate in the matching rules as if the letter “D” did not appear in the indicator area.
When a REPLACE statement is specified on a debugging line, the statement is treated as if the letter “D” did not appear in the indicator area.
After all COPY and REPLACE statements have been processed, a debugging line will be considered to have all the characteristics of a comment line if the WITH DEBUGGING MODE clause is not specified in the SOURCE-COMPUTER paragraph.
Except for COPY and REPLACE statements, the syntactic correctness of the source text cannot be determined until after all COPY and REPLACE statements have been completely processed.
Text words inserted into the source text as a result of processing a REPLACE statement are placed in the source text according to the rules for reference format. When inserting text words of pseudo-text-2 into the source text, additional spaces are introduced only between text words where there already exists a space (including the assumed space between source lines).
If additional lines are introduced into the source text as a result of the processing of REPLACE statements, the indicator area of the introduced 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 any literal within pseudo-text-2 is of a length too great to be accommodated on a single line without 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.
Each word in pseudo-text-2 that is to be placed into the resultant program begins in the same area of the resultant program as it appears in pseudo-text-2.