A customer copybook already has separate first-name, middle-name, and last-name fields, but one routine needs to move the three fields as a single display name. The COBOL RENAMES clause can give that contiguous byte range another name. It does not create a buffer or copy data; the level-66 name refers to storage that is already part of the record.
What the COBOL RENAMES clause does
RENAMES defines an alternative name for one existing data item or for a contiguous range of items. IBM describes it as a way to specify alternative, and possibly overlapping, groupings of elementary data items. The special level number is 66, so a RENAMES entry is not a normal subordinate field in the record hierarchy.
Changing bytes through the level-66 name changes the original fields because both names address the same storage. There is no automatic initialization, conversion, or duplicate copy. This behavior makes RENAMES useful for a group move, comparison, or display operation when the required bytes are already adjacent.
COBOL RENAMES syntax
66 data-name-1 RENAMES data-name-2
[THROUGH data-name-3].
66 data-name-1 RENAMES data-name-2
[THRU data-name-3].data-name-1 is the new level-66 name. data-name-2 identifies the existing item at the beginning of the range. When THROUGH or THRU is present, data-name-3 identifies the range endpoint. IBM treats THROUGH and THRU as equivalent words.
Single-item RENAMES example
A level-66 name can refer to one item without a THRU phrase:
01 MAIL-RECORD.
05 POSTAL-CODE PIC X(10).
66 ZIP-CODE RENAMES POSTAL-CODE.ZIP-CODE occupies the same ten bytes as POSTAL-CODE and inherits the characteristics of that item. The alias can help code shared between naming conventions, although a new program should normally choose one clear field name unless compatibility requires another.
RENAMES THRU range example
The more common use is to name a contiguous range inside a record:
01 CUSTOMER-RECORD.
05 CUSTOMER-ID PIC X(8).
05 CUSTOMER-NAME.
10 FIRST-NAME PIC X(12).
10 MIDDLE-NAME PIC X(12).
10 LAST-NAME PIC X(18).
05 CUSTOMER-STATUS PIC X.
66 DISPLAY-NAME RENAMES FIRST-NAME THRU LAST-NAME.DISPLAY-NAME spans 42 bytes: the first, middle, and last name fields in their physical sequence. It excludes CUSTOMER-ID and CUSTOMER-STATUS. A statement such as MOVE SPACES TO DISPLAY-NAME therefore clears all three name fields at once.
How storage is shared
| Bytes | Original description | Level-66 view |
|---|---|---|
| 1–8 | CUSTOMER-ID | Not included |
| 9–20 | FIRST-NAME | DISPLAY-NAME, 42 contiguous bytes |
| 21–32 | MIDDLE-NAME | |
| 33–50 | LAST-NAME | |
| 51 | CUSTOMER-STATUS | Not included |
The table shows why RENAMES is a storage view, not an allocation. The size and position come from the underlying record description. For the hierarchy behind 01, 05, 10, and 66 entries, see the COBOL record-description guide and the broader COBOL Data Division guide.
Where the level-66 entry must appear
All RENAMES entries associated with a logical record must immediately follow the record's last data-description entry. In the example, the 66 entry follows CUSTOMER-STATUS, even though the renamed bytes end at LAST-NAME. Do not insert the 66 entry inside the 05 group that contains the fields.
Valid items and level-number restrictions
A RENAMES operand can identify an elementary item, an alphanumeric group, or a national group, subject to the compiler's rules. The item being renamed cannot be level 01, 66, 77, or 88. Both endpoints of a THRU range must belong to the same associated level-01 record, and they cannot be the same data-name.
The end item must not precede the start item in storage. It also cannot be completely subordinate to the start item. Think in terms of the inclusive physical byte range: from the first elementary item in the starting operand through the last elementary item in the ending operand.
OCCURS and variable-length restrictions
Neither range endpoint may have an OCCURS clause, and neither may be subordinate to an item that has OCCURS. IBM also prohibits an OCCURS DEPENDING ON item anywhere between the endpoints. These rules prevent one level-66 name from describing storage whose occurrence or length is not fixed in the required way.
01 SALES-RECORD.
05 SALES-COUNT PIC 9(2).
05 SALES-AMOUNT PIC 9(7)V99 OCCURS 12 TIMES.
05 SALES-TOTAL PIC 9(9)V99.
66 SALES-VIEW RENAMES SALES-AMOUNT THRU SALES-TOTAL.
*> Invalid: the starting item has OCCURS.When repeated items must be processed, use the table name with a subscript or index and design the operation around an individual occurrence. Do not use RENAMES to bypass the table's declared structure.
Qualification rules for a RENAMES name
The new name, data-name-1, cannot be used as a qualifier for another name. IBM allows that level-66 name to be qualified only by the associated level indicator or level-01 data-name. If identical 66-level names exist in different records, qualify them with the record name when necessary.
Clear, unique names are usually easier to maintain than relying on qualification. Match the name to the operation or business view—such as DISPLAY-NAME—rather than using a vague label such as ALT-GROUP.
Group moves and data representation
A renamed range is commonly used as a group item. COBOL group operations are byte-oriented: a group move does not perform the elementary numeric conversions and editing implied by each subordinate PICTURE clause. That is safe when the range is intentionally treated as text or raw record data, but it can be misleading when it contains packed decimal, binary, or edited numeric fields.
RENAMES versus REDEFINES
| Question | RENAMES | REDEFINES |
|---|---|---|
| Primary purpose | Gives an existing item or contiguous range another group name. | Provides an alternative data description for the same storage area. |
| Level | Uses special level 66. | Uses a normal data-description level compatible with the redefined item. |
| New subordinate layout | No; it points to previously described fields. | Yes; the redefining item can have a different subordinate layout. |
| Typical use | Move or compare adjacent existing fields as one unit. | Interpret one record area as different layouts or formats. |
Use the COBOL REDEFINES guide when the requirement is an alternate record layout. Use RENAMES when the required fields are already defined and physically adjacent. Both share storage, but they solve different record-description problems.
RENAMES versus reference modification
Reference modification selects a substring at the point of use, for example DISPLAY-NAME(1:12). RENAMES creates a declared data-name for a fixed item or range in the record description. Reference modification can be suitable for a one-off slice; RENAMES is clearer when the same meaningful range is used repeatedly and satisfies the level-66 rules.
A declared RENAMES range also follows field boundaries, which documents intent. Reference modification is based on an offset and length, so layout changes can make a hard-coded slice incorrect even when it still compiles.
Common compiler errors
- Wrong placement: a normal 05 or 10 entry appears after the level-66 entry for the same record.
- Invalid level: an operand names a level 01, 66, 77, or 88 item.
- Different records: THRU endpoints do not belong to the same level-01 record.
- Reversed range: the ending item appears before the starting item in storage.
- OCCURS conflict: an endpoint or one of its ancestors is repeated, or an ODO item lies in the range.
- Invalid qualification: the level-66 name is used as a qualifier for another data-name.
- Unexpected bytes: the range compiles, but includes a filler, packed field, or status byte that the move was not meant to touch.
Production review checklist
- Confirm that one existing item or one contiguous range is the real requirement.
- Calculate the byte positions and total length from the current copybook.
- Verify that both THRU endpoints are in the same level-01 record and in forward order.
- Check the endpoints, their ancestors, and the intervening items for OCCURS and OCCURS DEPENDING ON.
- Place all 66 entries immediately after the final normal entry for the record.
- Review group operations for packed, binary, signed, or edited fields.
- Compile with the site's supported Enterprise COBOL options and retain the complete diagnostic.
The same copybook can be used in WORKING-STORAGE, LOCAL-STORAGE, or a file record, but lifetime and allocation belong to the containing section—not to the RENAMES entry. The WORKING-STORAGE versus LOCAL-STORAGE guide explains that separate choice.
IBM Enterprise COBOL references
- IBM: RENAMES clause syntax and rules
- IBM: special level numbers
- IBM: level numbers in data descriptions
- IBM: levels and record hierarchy
- IBM: REDEFINES clause
- IBM: classes and categories of group items
- IBM: reference modification
COBOL RENAMES clause FAQ
Does level 66 allocate new storage?
No. A level-66 entry gives another name to existing storage. Updating the RENAMES item updates the underlying field or fields.
Are THROUGH and THRU different in a RENAMES clause?
No. IBM treats THROUGH and THRU as equivalent. Both identify the inclusive range from the starting item to the ending item.
Can RENAMES include a field defined with OCCURS?
No. A range endpoint cannot have OCCURS or be subordinate to an OCCURS item. An OCCURS DEPENDING ON item is also prohibited between the endpoints.
When should I use RENAMES instead of REDEFINES?
Use RENAMES to give an existing item or contiguous set of fields another group name. Use REDEFINES when the same storage needs a different data description or subordinate layout.
Final check: draw the record as bytes, mark the first and last byte of the proposed range, and confirm that every byte between them belongs in the operation.
This comment has been removed by a blog administrator.
ReplyDelete