REPLACE statement

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 ends with 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.

Format 1

Read syntax diagramSkip visual syntax diagramREPLACE  == pseudo-text-1 == BY == pseudo-text-2 == LEADINGTRAILING == partial-word-1 == BY == partial-word-2 == .

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

Format 2

Read syntax diagramSkip visual syntax diagramREPLACE OFF.

Any text replacement currently in effect is discontinued with the format-2 form of REPLACE. If format 2 is not specified, a specific 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

Must contain one or more text words. Character-strings can be continued in accordance with normal source code rules.

pseudo-text-1 can consist solely of a separator comma or a separator semicolon.

pseudo-text-2
Can contain zero, one, or more text words. Character strings can be continued in accordance with normal source code rules.

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 COBOL words and separators must not appear in library text or pseudo-text except in comment lines, comment-entries, inline comments, 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 or comment entries.

Individual character-strings within pseudo-text can be up to 322 characters long, except that strings that contain multibyte characters cannot be continued.

partial-word-1, partial-word-2
A single text word that is bounded by, but not including, pseudo-text delimiters (==). Both characters of each pseudo-text delimiter must appear on one line. However, the text word within a partial-word can be continued.
The following rules apply to partial-word-1 and partial-word-2:
  • partial-word-1 consists of one text word.
  • partial-word-2 consists of zero or one text word.
  • partial-word-1 and partial-word-2 cannot be an alphanumeric literal, national literal, DBCS literal, or multibyte word.

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 that is produced as a result of the processing of a REPLACE statement must not contain a REPLACE statement.

Continuation rules for pseudo-text

The character-strings and separators that comprise pseudo-text can start in either Area A or Area B. However, if a hyphen is in the indicator area of a line, and that hyphen 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.

Example

The following example shows the use of REPLACE statement to replace source text.
IDENTIFICATION DIVISION.                                 
PROGRAM-ID. REPLEXMP.                                    
DATA DIVISION.                                           
WORKING-STORAGE SECTION.                                 
    REPLACE =="(Hello, World!)"== BY =="(Hello, Mom!)"==.
01 WS-STRING1 PIC X(30) VALUE "(Hello, World!)".         
01 WS-STRING2 PIC X(30) VALUE "Hello, COBOL!".           
PROCEDURE DIVISION.                                      
    DISPLAY "Original: " WS-STRING1                      
    REPLACE LEADING ==XX-==  BY ====                     
                    ==:TAG:==  BY ==STRING==             
            TRAILING ==1== BY ==2==.                     
    DISPLAY "Modified: " XX-WS-:TAG:1                    
    REPLACE OFF.                                         
    GOBACK.
The output of this program is:
Original: (Hello, Mom!) 
Modified: Hello, COBOL!