REDEFINES

REDEFINES gives a second description to storage that already has one. It is not a copy and not a conversion: the two items start at the same byte, take the space of the one that was declared first, and every write through one of them is a write through the other. It is how COBOL reads a record as a header or as a detail depending on its first byte, and how a date stored as eight characters can be used as a year, a month and a day.

One storage, two descriptions

The date below is stored as eight characters, the way a file would carry it. A REDEFINES over it names the first four as the year, the next two as the month and the last two as the day:

IDENTIFICATION DIVISION. PROGRAM-ID. OVERLAY. DATA DIVISION. WORKING-STORAGE SECTION. 01 RAW-DATE PIC X(8) VALUE "20261118". 01 DATE-GRP REDEFINES RAW-DATE. 05 YYYY PIC X(4). 05 MM PIC X(2). 05 DD PIC X(2). PROCEDURE DIVISION. DISPLAY "raw [" RAW-DATE "]". DISPLAY "parts [" YYYY "/" MM "/" DD "]". MOVE "2027" TO YYYY. DISPLAY "after [" RAW-DATE "]". STOP RUN.

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

raw [20261118]
parts [2026/11/18]
after [20271118]

The third line is the whole idea. Writing the year through YYYY changed RAW-DATE, because there is only one storage and the two names are two ways to look at it. The year, the month and the day are still four, two and two bytes: the split costs nothing, which is why the layout survives in files from 1970 to today.

The parts of a number

The same trick splits a decimal amount into its whole part and its cents, because a decimal field is stored as its digits:

IDENTIFICATION DIVISION. PROGRAM-ID. CENTS. DATA DIVISION. WORKING-STORAGE SECTION. 01 AMT-F PIC 9(3)V99 VALUE 12.34. 01 AMT-PARTS REDEFINES AMT-F. 05 WHOLE-F PIC 9(3). 05 CENTS-F PIC 9(2). PROCEDURE DIVISION. DISPLAY "amount [" AMT-F "]". DISPLAY "whole [" WHOLE-F "] cents [" CENTS-F "]". MOVE 99 TO CENTS-F. DISPLAY "after [" AMT-F "]". STOP RUN.

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

amount [012.34]
whole [012] cents [34]
after [012.99]

Five bytes in both descriptions: three digits and two digits, and the point exists only in the picture of AMT-F. Setting the cents to ninety-nine made the amount 12.99, and no statement had to add or subtract anything.

This works because the amount is USAGE DISPLAY. The same overlay on a COMP-3 field would put WHOLE-F over a half byte of a digit, and the last chapter shows what a redefinition of a binary field reads instead.

A buffer with two record types

Here is the case the clause was designed for. One buffer of thirteen characters holds a header or a detail, and the first character says which. Three descriptions lie over the same thirteen bytes:

IDENTIFICATION DIVISION. PROGRAM-ID. RECBUF. DATA DIVISION. WORKING-STORAGE SECTION. 01 LINE-BUF PIC X(13) VALUE "H03ANNALEE ". 01 KEY-REC REDEFINES LINE-BUF. 05 LINE-KEY PIC X. 01 HEADER-REC REDEFINES LINE-BUF. 05 H-KEY PIC X. 05 H-COUNT PIC 9(2). 05 H-NAME PIC X(10). 01 DETAIL-REC REDEFINES LINE-BUF. 05 D-KEY PIC X. 05 D-AMT PIC 9(7). 05 D-CODE PIC X(5). PROCEDURE DIVISION. DISPLAY "buffer [" LINE-BUF "]". IF LINE-KEY = "H" DISPLAY "header count [" H-COUNT "] name [" H-NAME "]" END-IF. DISPLAY "as detail [" D-KEY "][" D-AMT "][" D-CODE "]". MOVE 42 TO D-AMT. DISPLAY "after [" LINE-BUF "]". STOP RUN.

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

buffer [H03ANNALEE ]
header count [03] name [ANNALEE ]
as detail [H][03ANNAL][EE ]
after [H0000042EE ]

KEY-REC is the one-byte view the dispatcher tests. HEADER-REC makes sense of the bytes when the key is H, and DETAIL-REC makes a different sense of the same bytes, which the program prints to show that a description is a promise and not a check. The last line is the aliasing again: the amount went in through the detail view and the buffer changed.

Real programs put the IF around the use and never print the wrong view; the point of the second line here is that the wrong view is possible, and that only the key character keeps the program away from it.

The rules

Three rules are worth knowing because two of them are warnings rather than errors. The first is order: the redefining entry comes immediately after the entry it redefines, at the same level. An entry between them is refused:

IDENTIFICATION DIVISION. PROGRAM-ID. RULEGAP. DATA DIVISION. WORKING-STORAGE SECTION. 01 A-FLD PIC X(4) VALUE "ABCD". 01 C-FLD PIC X VALUE "C". 01 B-FLD REDEFINES A-FLD PIC X(4). PROCEDURE DIVISION. DISPLAY A-FLD B-FLD C-FLD. STOP RUN.

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

rulegap.cob:8: error: REDEFINES must follow the original definition
6 | 01 A-FLD PIC X(4) VALUE "ABCD".
7 | 01 C-FLD PIC X VALUE "C".
8 > 01 B-FLD REDEFINES A-FLD PIC X(4).
9 |
10 | PROCEDURE DIVISION.

The second rule is about the value. A redefining entry cannot give a value to storage that the original already initializes, so the compiler ignores the clause and says so:

IDENTIFICATION DIVISION. PROGRAM-ID. RULEVAL. DATA DIVISION. WORKING-STORAGE SECTION. 01 A-FLD PIC X(4) VALUE "ABCD". 01 B-FLD REDEFINES A-FLD PIC X(4) VALUE "WXYZ". PROCEDURE DIVISION. DISPLAY A-FLD B-FLD. STOP RUN.

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

ruleval.cob:7: warning: initial VALUE clause ignored for REDEFINES item 'B-FLD' [-Winitial-value]
5 | WORKING-STORAGE SECTION.
6 | 01 A-FLD PIC X(4) VALUE "ABCD".
7 > 01 B-FLD REDEFINES A-FLD PIC X(4) VALUE "WXYZ".
8 |
9 | PROCEDURE DIVISION.
ABCDABCD

The third rule is size. A redefining entry may be shorter than the original, which is a useful way to look at a part of a record, but a longer one reaches past the storage it renames. GnuCOBOL builds it and warns:

IDENTIFICATION DIVISION. PROGRAM-ID. RULELONG. DATA DIVISION. WORKING-STORAGE SECTION. 01 A-FLD PIC X(4) VALUE "ABCD". 01 B-FLD REDEFINES A-FLD PIC X(6) VALUE "ABCDEF". PROCEDURE DIVISION. DISPLAY A-FLD. STOP RUN.

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

rulelong.cob:7: warning: initial VALUE clause ignored for REDEFINES item 'B-FLD' [-Winitial-value]
5 | WORKING-STORAGE SECTION.
6 | 01 A-FLD PIC X(4) VALUE "ABCD".
7 > 01 B-FLD REDEFINES A-FLD PIC X(6) VALUE "ABCDEF".
8 |
9 | PROCEDURE DIVISION.
rulelong.cob:7: warning: size of 'B-FLD' larger than size of 'A-FLD' [-Wlarger-01-redefines]
5 | WORKING-STORAGE SECTION.
6 | 01 A-FLD PIC X(4) VALUE "ABCD".
7 > 01 B-FLD REDEFINES A-FLD PIC X(6) VALUE "ABCDEF".
8 |
9 | PROCEDURE DIVISION.

The bytes past the original belong to whatever the compiler put next, which is what the warning is about. A record description with such a clause is a description of something else.

REDEFINES is not a conversion

The temptation is to read a number through a PIC X and expect its digits. A DISPLAY field does hold its digits, but a binary field holds bytes:

IDENTIFICATION DIVISION. PROGRAM-ID. RAWBIN. DATA DIVISION. WORKING-STORAGE SECTION. 01 BIN-F PIC 9(4) COMP VALUE 258. 01 BIN-RAW REDEFINES BIN-F PIC X(2). PROCEDURE DIVISION. DISPLAY "COMP 258 bytes [" FUNCTION HEX-OF(BIN-RAW) "]". STOP RUN.

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

COMP 258 bytes [0102]

Two bytes, 01 and 02, and no digit of 258 among them: the number is binary, as the lesson on COMP shows. A redefinition reads storage; only a MOVE converts. The clause is right when the bytes are meant to be read two ways, which is the file record and the date, and wrong when the two descriptions mean different numbers.

Exercises

  1. Add a field to the date program that holds the whole date as PIC 9(8) and give it the value of the raw date with a MOVE. Which of the two ways changes the other one, and which copies?
  2. Make WHOLE-F four digits instead of three in the cents program, build, and read the warning.
  3. In the buffer program, set LINE-KEY to "D" and print the header view. Which bytes of the buffer became the count?
  4. Redefine a PIC S9(3) COMP-3 field as PIC X(2) and print the hex. What do the bytes look like, and why is that what a file would contain?

Questions

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

  1. What does a REDEFINES clause do?

    Answer

    It gives existing storage a second description, without a copy or a conversion

    The two entries start at the same byte, so a write through one is a write through the other and no data is moved.

  2. What happens to a VALUE clause on a redefining entry?

    Answer

    It is ignored, with a warning about the initial value

    Only the original entry initializes the storage; GnuCOBOL warns that the clause is ignored because two values cannot both be the initial one.

  3. Where must a redefining entry be declared?

    Answer

    Immediately after the original, at the same level

    The compiler pairs the entry with the one before it, so anything in between is an error: REDEFINES must follow the original definition.

  4. A redefining entry is longer than the original. What does GnuCOBOL do?

    Answer

    It warns that the size is larger and builds the program

    The clause reaches past the storage it renames, which is a warning under -Wall and a record layout that describes something else.

  5. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q1. DATA DIVISION. WORKING-STORAGE SECTION. 01 RAW-DATE PIC X(8) VALUE "20261118". 01 DATE-GRP REDEFINES RAW-DATE. 05 YYYY PIC X(4). 05 MM PIC X(2). 05 DD PIC X(2). PROCEDURE DIVISION. MOVE "2027" TO YYYY. DISPLAY "[" RAW-DATE "]". STOP RUN.

    Answer

    [20271118]

    The year is the first four bytes of the same storage, so writing it changes the raw date in place.

  6. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q2. DATA DIVISION. WORKING-STORAGE SECTION. 01 AMT-F PIC 9(3)V99 VALUE 12.34. 01 AMT-PARTS REDEFINES AMT-F. 05 WHOLE-F PIC 9(3). 05 CENTS-F PIC 9(2). PROCEDURE DIVISION. DISPLAY "[" WHOLE-F "][" CENTS-F "]". STOP RUN.

    Answer

    [012][34]

    Five digits of the amount, split three and two: 012 and 34, because the point of the picture takes no byte.

  7. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q3. DATA DIVISION. WORKING-STORAGE SECTION. 01 AMT-F PIC 9(3)V99 VALUE 12.34. 01 AMT-PARTS REDEFINES AMT-F. 05 WHOLE-F PIC 9(3). 05 CENTS-F PIC 9(2). PROCEDURE DIVISION. MOVE 99 TO CENTS-F. DISPLAY "[" AMT-F "]". STOP RUN.

    Answer

    [012.99]

    CENTS-F covers the last two bytes of the amount, so the write changes the cents and nothing else.

  8. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q4. DATA DIVISION. WORKING-STORAGE SECTION. 01 LINE-BUF PIC X(13) VALUE "H03ANNALEE ". 01 DETAIL-REC REDEFINES LINE-BUF. 05 D-KEY PIC X. 05 D-AMT PIC 9(7). 05 D-CODE PIC X(5). PROCEDURE DIVISION. DISPLAY "[" D-KEY "][" D-AMT "][" D-CODE "]". STOP RUN.

    Answer

    [H][03ANNAL][EE ]

    The detail view takes one, seven and five bytes of the buffer, so the digits of the header line land where the amount is.

  9. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 BIN-F PIC 9(4) COMP VALUE 258. 01 BIN-RAW REDEFINES BIN-F PIC X(2). PROCEDURE DIVISION. DISPLAY FUNCTION HEX-OF(BIN-RAW). STOP RUN.

    Answer

    0102

    The redefinition reads the binary bytes, which are 01 and 02, not the decimal digits of 258.

  10. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 A-FLD PIC X(4) VALUE "ABCD". 01 B-FLD REDEFINES A-FLD PIC X(4) VALUE "WXYZ". PROCEDURE DIVISION. DISPLAY "[" A-FLD "][" B-FLD "]". STOP RUN.

    Answer

    [ABCD][ABCD]

    The VALUE of the redefining entry is ignored with a warning, and both names show the initial value of the original storage.

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

Banner image