&OVERLAY

Returns a string that has been overlaid by a supplied string.

&OVERLAY target source 
       [ start [ length [ ALIGNL [c] | ALIGNR [c] | ALIGNC [lr] ] ] ]

&OVERLAY is a built-in function and must be used to the right of an assignment statement.

&OVERLAY allows data from one string (source) to be used to replace data in a second (target) string.

Operands:

target: The constant value for the target string, or the name for a variable holding the target string.
source: The source string, or the name for the variable holding the source string, which is used to overlay the target string.
start: The location within the target string where the overlay process starts. If omitted, overlay starts at the first position in the target variable. If the start location lies beyond the end of the target variable, the target is padded with blanks up to the start location.
length: The string length for which the overlay process is to occur. If longer than the source variable, blanks are used to complete the overlay operation. If omitted, the whole of the source variable is used to overlay the target string.
ALIGNLc: If the overlay length exceeds the length of the source string, this option specifies that the source string is put to the left of the overlaid area, and the remainder of the overlaid area is to be padded to the right with the character c. If c is omitted, blanks are used as filler.
ALIGNRc: If the overlay length exceeds the length of the source string, this option specifies that the source string is placed to the right of the overlaid area and the remainder of the overlaid area is padded to the left with the character c. If c is omitted, blanks are used as filler.
ALIGNClr: If the overlay length exceeds the length of the source string, this option specifies that the source string is placed at the center of the overlaid area and the remainder of the overlaid area is padded to left and right with the (left) character l and the (right) character r. If lr is omitted, blanks are used as filler.

Examples:

&A = AAAAA 
&B = BBB &1 = &OVERLAY &A &B     -* &1 will be set to BBBAA 
&1 = &OVERLAY &A &B 2            -* &1 will be set to ABBBA 
&1 = &OVERLAY &A &B 2 1          -* &1 will be set to ABAAA 
&1 = &OVERLAY &A &B 1 4          -* &1 will be set to BBB A 
&1 = &OVERLAY &A &B 7 3          -* &1 will be set to AAAAA BBB
&C = ABCDEFGHIJK 
&D = 111 
&1 = &OVERLAY &C &D 1 7 ALIGNL0  -* &1 will be set to
                                 -* 1110000HIJK 
&1 = &OVERLAY &C &D 1 7 ALIGNR0  -* &1 will be set to 
                                 -* 0000111HIJK 
&1 = &OVERLAY &C &D 1 7 ALIGNC<> -* &1 will be set to 
                                 -* <<111>>HIJK

Notes:

Variable substitution is performed before processing the &OVERLAY statement. If a variable has a null value when substitution is performed, it is eliminated from the statement. For this reason, take care to ensure that all values are specified as desired.

&OVERLAY is used to set a repeated value. For example, to set a character string of 64 Xs:

&X64 = &OVERLAY X X 1 64 ALIGNRX

&OVERLAY is useful for string manipulation and the management of data in tabular formats.

If &CONTROL DBCS or DBCSN or DBCSP is in effect, &OVERLAY is sensitive to the presence of DBCS data.