Function
The REPLACE statement is used to replace source text.
Format 1
REPLACE {==pseudo-text-1== BY ==pseudo-text-2==}... .
Format 2
REPLACE OFF.
Syntax rules
If a REPLACE statement is not the first statement in a separately compiled program, it must be preceded by the period separator character or some other separator symbol. One REPLACE statement must be terminated before another REPLACE statement is started.
A REPLACE statement is recognized anywhere within a program except:
in comment lines
within non-numeric literals
pseudo-text-1 must contain at least one word, while pseudo-text-2 may be empty (
====) or may contain only spaces, comma, semicolon, and comment lines.
General rules
Format 1 of the REPLACE statement specifies that each occurrence of pseudo-text-1 is to be replaced by pseudo-text-2.
Format 2 of the REPLACE statement terminates the current text replacement operation.
A REPLACE statement remains effective from the point where it is specified up to the next REPLACE statement or up to the end of a separately compiled program.
All REPLACE statements in a compilation unit or in a library text are executed only after all COPY statements in the compilation unit or library text have been executed. The operands of a REPLACE statement cannot be modified with the REPLACING phrase of a COPY statement.
The text which results from execution of a REPLACE statement must not contain either a REPLACE statement or a COPY statement.
Lowercase letters that are used in text words are equivalent to the corresponding uppercase letters.
The comparison operation whose results determine whether or not a text is to be replaced is executed as follows (the term "source text" is used here to mean both the compilation unit text and the library text):
Starting with the first text word of the source text after the REPLACE statement and the first word of pseudo-text-1, pseudo-text-1 is compared with the corresponding number of consecutive text words.
pseudo-text-1 matches the source text only if the sequence of text words in pseudo-text-1 is identical, character for character, with the corresponding sequence of text words in the source text.
If no match is found, the comparison is repeated with each subsequent occurrence of pseudo-text-1 until a match is found or until there is no further pseudo-text-1.
When each specified pseudo-text-1 has been compared with the source text without finding a match, the next word of the source text is regarded as the first text word and the comparison operation starts again with the first pseudo-text-1.
If a match between pseudo-text-1 and the source text is found, this part of the source text is replaced with the corresponding pseudo-text-2. The text word in the source text which immediately follows the replaced text is then regarded as the first text word and the comparison operation starts again with the first pseudo-text-1.
The comparison operation continues until the last text word affected by the REPLACE statement has been replaced or has been compared as the first text word with every pseudo-text-1.
Comment lines and empty lines in the source text or in pseudo-text-1 are treated as spaces for the comparison operation. The order of the text words in the source text and in pseudo-text-1 is defined by the reference format (see section "Statements and sentences").
Any comment lines or empty lines in pseudo-text-2 are transferred unchanged to the compilation unit. Any comment line or empty line in the source text which lies within a sequence of text words which matches pseudo-text-1 will not appear in the final version of the program text.Debugging lines are permitted in the pseudo-text. Text words in pseudo-text-1 which lie in a debugging line are treated, during comparison, as if there were no ’D’ in the indicator area (column 7).
Except for the COPY and REPLACE statements themselves, the syntax of the source text cannot be checked until all COPY and REPLACE statements have been fully executed.
Text words introduced by a REPLACE statement are placed in the program text in accordance with the reference format. When text words from pseudo-text-2 are moved to the program text, additional spaces are inserted only where they existed in the original text or in pseudo-text-2. This includes the implicit space between lines of the compilation unit.
If a REPLACE statement introduces additional lines to the compilation unit, the indicator area of each of these lines is marked with the character specified in the first line which was replaced. The only exception to this is where the original compilation unit line contained a hyphen: in this case, the inserted line contains a space.
If a COPY statement with the REPLACING phrase causes a line to be lengthened such that additional lines are required, corresponding continuation lines are generated. These lines may contain a continuation character in column 7.
If the replacement operation requires continuation of a literal in a debugging line, there is an error in the compilation unit.The reference format which applies for the REPLACE statement must be the same as that which also applies for the parts of the library text which may need to be replaced.