OVERLAY(name{:pos

OVERLAY(name{:pos | *NEXT})

The OVERLAY keyword overlays the storage of one subfield with that of another subfield, or with that of the data structure itself. This keyword is allowed only for data structure subfields.

The Name-entry subfield overlays the storage specified by the name parameter at the position specified by the pos parameter. If pos is not specified, it defaults to 1.

Note:

The pos parameter is in units of bytes, regardless of the types of the subfields.

Specifying OVERLAY(name:*NEXT) positions the subfield at the next available position within the overlaid field. (This will be the first byte past all other subfields prior to this subfield that overlay the same subfield.)

The following rules apply to keyword OVERLAY:

The name parameter must be the name of a subfield defined previously in the current data structure, or the name of the current data structure.
If the data structure is qualified, the first parameter to the OVERLAY keyword must be specified without the qualifying data structure name. In the following example, subfield MsgInfo.MsgPrefix overlays subfield MsgInfo.MsgId.
```
D MsgInfo         DS                  QUALIFIED
D   MsgId                        7
D     MsgPrefix                  3    OVERLAY(MsgId)
```
The pos parameter (if specified) must be a value greater than 0 with no decimal positions. It can be a numeric literal, a built-in function returning a numeric value, or a numeric constant. If pos is a named constant, it must be defined prior to this specification.
The OVERLAY keyword is not allowed when the From-Position entry is not blank.
If the name parameter is a subfield, the subfield being defined must be contained completely within the subfield specified by the name parameter.
Alignment of subfields defined using the OVERLAY keyword must be done manually. If they are not correctly aligned, a warning message is issued.
If the subfield specified as the first parameter for the OVERLAY keyword is an array, the OVERLAY keyword applies to each element of the array. That is, the field being defined is defined as an array with the same number of elements. The first element of this array overlays the first element of the overlaid array, the second element of this array overlays the second element of the overlaid array, and so on. No array keywords may be specified for the subfield with the OVERLAY keyword in this situation. (Refer to Figure 144) See also SORTA (Sort an Array).
If the subfield name, specified as the first parameter for the OVERLAY keyword, is an array and its element length is longer than the length of the subfield being defined, the array elements of the subfield being defined are not stored contiguously. Such an array is not allowed as the Result Field of a PARM operation or in Factor 2 or the Result Field of a MOVEA operation.
If the ALIGN keyword is specified for the data structure, subfields defined with OVERLAY(name:*NEXT) are aligned to their preferred alignment. Pointer subfields are always aligned on a 16-byte boundary.
If a subfield with overlaying subfields is not otherwise defined, the subfield is implicitly defined as follows:
- The start position is the first available position in the data structure.
- The length is the minimum length that can contain all overlaying subfields. If the subfield is defined as an array, the length will be increased to ensure proper alignment of all overlaying subfields.

Examples

Figure 144. Storage Allocation of Subfields with Keywords DIM and OVERLAY

*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... *
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords++++++++++++++++++++++++++++
D DataStruct      DS
D   A                           10    DIM(5)
D     B                          5    OVERLAY(A)
D     C                          5    OVERLAY(A:6)

Allocation of fields in storage:

A(1)		A(2)		A(3)		A(4)		A(5)
B(1)	C(1)	B(2)	C(2)	B(3)	C(3)	B(4)	C(4)	B(5)	C(5)

Figure 145. Storage Allocation of Subfields with Keywords DIM and OVERLAY

*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... *
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++
D DataStruct      DS
D   A                            5
D     B                          1    OVERLAY(A) DIM(4)

Allocation of fields in storage:

A
B(1)	B(2)	B(3)	B(4)

The following example shows two equivalent ways of defining subfield overlay positions: explicitly with (name:pos) and implicitly with (name:*NEXT).

Figure 146. Defining Subfield Overlay Positions with *NEXT

*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... *
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++
 * Define subfield overlay positions explicitly
D DataStruct      DS
D   PartNumber                  10A
D     Family                     3A   OVERLAY(PartNumber)
D     Sequence                   6A   OVERLAY(PartNumber:4)
D     Language                   1A   OVERLAY(PartNumber:10)

*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... *
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++
 * Define subfield overlay positions with *NEXT
D DataStruct      DS
D   PartNumber
D     Family                     3A   OVERLAY(PartNumber)
D     Sequence                   6A   OVERLAY(PartNumber:*NEXT)
D     Language                   1A   OVERLAY(PartNumber:*NEXT)

[ Top of Page | Previous Page | Next Page | Contents | Index ]