COPY REPLACING

A copybook that can only be used once is a small gift. COPY ... REPLACING makes it reusable: the compiler replaces text in the copy while it inserts it, so one file can define a record, a record with another name, a wider record and a record of another file. The first listings are fragments of files that need the copybook beside them, for the reason the previous lesson gave; the section on what REPLACING writes out is a complete program that builds on its own.

COPY REPLACING

The copybook is the one of the previous lesson, saved as cusrec.cpy: a 16-byte customer record.

01 CUS-REC. 05 CUS-ID PIC X(3). 05 CUS-NAME PIC X(8). 05 CUS-BAL PIC 9(5).

REPLACING takes pairs of ==pseudo-text==: the first of a pair is the text to find, the second is the text to write in its place. Each pair is one line of the statement, and the statement follows the member name:

DATA DIVISION. WORKING-STORAGE SECTION. COPY "cusrec.cpy". COPY "cusrec.cpy" REPLACING ==CUS-REC== BY ==OLD-REC== ==CUS-ID== BY ==OLD-ID== ==CUS-NAME== BY ==OLD-NAME== ==CUS-BAL== BY ==OLD-BAL==. PROCEDURE DIVISION. MOVE "A10" TO CUS-ID. MOVE "Ada" TO CUS-NAME. MOVE 1250 TO CUS-BAL. MOVE CUS-REC TO OLD-REC. MOVE 9999 TO OLD-BAL. DISPLAY "new " CUS-ID " " CUS-NAME " " CUS-BAL. DISPLAY "old " OLD-ID " " OLD-NAME " " OLD-BAL. STOP RUN.

cobc -x -free -Wall -o rep1 rep1.cob
./rep1

new A10 Ada 01250
old A10 Ada 09999

One file, two records, and the program moved the bytes of the first into the second and changed one of them. The copy of the copybook carries the replaced names, the original keeps its own, and no line of the program knows which is which.

What REPLACING writes out

The replacement happens in the text the compiler reads, so the program it compiles is the two records written out under different names. That expansion is a complete program of its own, and it prints the same two lines as rep1.cob:

IDENTIFICATION DIVISION. PROGRAM-ID. REP1PLAIN. DATA DIVISION. WORKING-STORAGE SECTION. 01 CUS-REC. 05 CUS-ID PIC X(3). 05 CUS-NAME PIC X(8). 05 CUS-BAL PIC 9(5). 01 OLD-REC. 05 OLD-ID PIC X(3). 05 OLD-NAME PIC X(8). 05 OLD-BAL PIC 9(5). PROCEDURE DIVISION. MOVE "A10" TO CUS-ID. MOVE "Ada" TO CUS-NAME. MOVE 1250 TO CUS-BAL. MOVE CUS-REC TO OLD-REC. MOVE 9999 TO OLD-BAL. DISPLAY "new " CUS-ID " " CUS-NAME " " CUS-BAL. DISPLAY "old " OLD-ID " " OLD-NAME " " OLD-BAL. STOP RUN.

cobc -x -free -Wall -o rep1plain rep1plain.cob
./rep1plain

new A10 Ada 01250
old A10 Ada 09999

Reading the expansion is the way to debug a REPLACING that did not do what its author expected: the names in the second record are exactly the words of the pseudo-text on the right of BY, and a word the list forgets keeps its original name and collides with the first copy.

The same copybook twice

Without REPLACING the second copy is a redefinition of everything the first one declared, and the compiler refuses the program at the first use of a name; the exercise at the end of the page asks for that message. With it, the two copies are two records, which is the pattern of a before image and an after image: read the record, move it to the old one, change the new one, rewrite.

That pattern of a rewrite is more honest than it looks: the old image is what an audit trail stores, and a program that keeps it has the value the file held before the change without reading the file again.

Replacing a clause

Pseudo-text is not limited to names. A whole clause can be replaced, which is how one copybook serves a record of 16 bytes and a wider version of it:

DATA DIVISION. WORKING-STORAGE SECTION. COPY "cusrec.cpy" REPLACING ==PIC 9(5)== BY ==PIC 9(7)==. PROCEDURE DIVISION. MOVE 1250 TO CUS-BAL. DISPLAY "balance " CUS-BAL. DISPLAY "record is " LENGTH OF CUS-REC " bytes". STOP RUN.

cobc -x -free -Wall -o rep2 rep2.cob
./rep2

balance 0001250
record is 18 bytes

The record grew from 16 bytes to 18, so the balance field is the seven-digit one. The pseudo-text compares words and their punctuation, which is why PIC 9(5) matched as written and PIC 9 (5) would not have.

What it will not replace

The text to find is a sequence of COBOL words, not a substring. The intuitive attempt to rename a record by its prefix, replacing CUS- with OLD-, matches nothing at all:

DATA DIVISION. WORKING-STORAGE SECTION. COPY "cusrec.cpy". COPY "cusrec.cpy" REPLACING ==CUS-== BY ==OLD-==. PROCEDURE DIVISION. MOVE "A10" TO CUS-ID. DISPLAY CUS-ID. STOP RUN.

cobc -x -free -Wall -o rep3 rep3.cob

cusrec.cpy:1: warning: redefinition of 'CUS-REC' [-Wredefinition]
1 > 01 CUS-REC.
2 | 05 CUS-ID PIC X(3).
3 | 05 CUS-NAME PIC X(8).
cusrec.cpy:1: note: 'CUS-REC' previously defined here [-Wredefinition]
1 > 01 CUS-REC.
2 | 05 CUS-ID PIC X(3).
3 | 05 CUS-NAME PIC X(8).
rep3.cob:8: error: 'CUS-ID' is ambiguous; needs qualification
6 | COPY "cusrec.cpy" REPLACING ==CUS-== BY ==OLD-==.
7 | PROCEDURE DIVISION.
8 > MOVE "A10" TO CUS-ID.
9 | DISPLAY CUS-ID.
10 | STOP RUN.
cusrec.cpy:2: note: 'CUS-ID IN CUS-REC' defined here

The warning names the redefinition, the error says that CUS-ID is now two fields, and the note points at the copybook line. CUS- is not a word of its own: the words in the copybook are CUS-ID, CUS-NAME and CUS-BAL, and only a whole one of those can be replaced. The lesson of the three lines is to run the build after the statement, not to trust the intention.

Exercises

  1. Replace only CUS-BAL in the second copy of the first program and print the two records. Which bytes differ?
  2. Add a third copy of the copybook with the prefix HIST-. How many records does the program hold?
  3. Replace ==05== with ==10== in cusrec.cpy. What does the record look like, and why is that legal?
  4. Write the replacement of the limit section as four separate pairs and run the build again. Which line of the program is now accepted?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does COPY REPLACING compare?

    Answer

    Whole COBOL words and their punctuation, not substrings

    The prefix CUS- matched nothing and the copybook was inserted twice unchanged.

  2. What is ==pseudo-text== in a REPLACING clause?

    Answer

    The text between the double equals signs: what to find and what to write

    Each pair of the statement was written as ==old== BY ==new==.

  3. Why copy one copybook twice with different replacements?

    Answer

    To keep the before and after image of a record, or two records of the same layout

    The program moved the record into the renamed one and changed one field.

  4. What did the PIC replacement change?

    Answer

    The record grew from 16 to 18 bytes

    The program printed balance 0001250 and record is 18 bytes.

  5. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A. 05 W-ID PIC X(3) VALUE "A10". 01 W-B. 05 W-ID PIC X(3) VALUE "B20". PROCEDURE DIVISION. DISPLAY W-ID OF W-A " " W-ID OF W-B. STOP RUN.

    Answer

    A10 B20

    Two records of the same layout need the qualification, as the note of the failing build says.

  6. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A. 05 W-BAL PIC 9(5) VALUE 1250. 01 W-B. 05 W-BAL PIC 9(7) VALUE 0. PROCEDURE DIVISION. MOVE W-BAL OF W-A TO W-BAL OF W-B. DISPLAY W-BAL OF W-B. STOP RUN.

    Answer

    0001250

    The wider field takes the five digits and pads the rest with zeros.

  7. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A. 05 W-BAL PIC 9(5) VALUE 1250. PROCEDURE DIVISION. DISPLAY LENGTH OF W-A. STOP RUN.

    Answer

    5

    The record holds one five-digit field.

  8. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-N PIC 9 VALUE 1. 01 W-T PIC 9(3) VALUE 0. PROCEDURE DIVISION. PERFORM UNTIL W-N IS GREATER THAN 3 ADD W-N TO W-T ADD 1 TO W-N END-PERFORM. DISPLAY W-T. STOP RUN.

    Answer

    006

    The loop adds 1, 2 and 3 into a three-digit field.

  9. What does the compiler say when a COPY REPLACING pair matches nothing?

    Answer

    Nothing about the statement: the copybook is inserted as it is and the redefinition is reported

    The build warned about CUS-REC being defined twice and failed on the ambiguous CUS-ID.

  10. Which qualification makes an ambiguous copybook name usable?

    Answer

    The record name after IN or OF, as in CUS-ID OF OLD-REC

    That is what the note of the failing build asks for: a qualified name.

The code on this page was built with cobc (GnuCOBOL) 3.2.0 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev