|
|
|
The &OVERLAY built-in function is used to replace data, at a specified offset and for a specified length, with some other data. In the case where the data is single byte data only, this is a simple function. When DBCS strings are included, it is difficult to ensure that the integrity of DBCS strings in the data is preserved. The &OVERLAY process must consider the contents of the data at the start and end of the area which is being overlaid, to determine if any shift characters need to be added or removed to maintain valid DBCS strings.
With &CONTROL DBCS, DBCSN, or DBCSP in effect, the offset and length is subject to variation due to the contents of the data. For example, if the original string contains shift characters, and &CONTROL DBCSN is in effect, the shift characters are not included in the calculation of the offset or length of the data which is to be overlaid.
If additional shift out or shift in characters must be added to the resultant string to preserve the integrity of the DBCS data, and shift characters are included in the length of the string, the string could be truncated to ensure that the length of the overlaid area is not greater than the length specified. If any truncation occurs, it occurs at the right hand side of the data to be overlaid, regardless of the alignment option specified.
If the data at the start of the overlaid area is the second byte of a DBCS character, the offset is adjusted by one, to exclude the character from the overlaid area. To ensure that data following the overlaid area is at the same logical offset relative to the start of the data, after the operation, as it was before the operation, the length of the overlaid area will be reduced by one. If the data at the end of the overlaid area is the first byte of a DBCS character, the length of the overlaid area is reduced by one to ensure that the DBCS character remains complete.
If the data at the start of the overlaid area is SBCS data, and the data to be placed in the string starts with DBCS data, a shift out character will be added to the start of the data when it is inserted. If shift characters are counted in the length of the string, the length of the overlaid area will be reduced by one to compensate for the shift out character. If the data at the start of the overlaid area is DBCS, and the data to be placed in the string starts with SBCS data, a shift in character will be added to the start of the data when it is inserted. If shift characters are counted in the length of the string, the length of the overlaid area will be reduced by one to compensate for the shift character.
If the data at the end of the overlaid area is SBCS data, and the data to be placed in the string ends with DBCS data, a shift in character will be added to the end of the data when it is inserted. If shift characters are counted in the length of the string, the length of the overlaid area will be reduced by one to compensate for the shift out character. If the data at the end of the overlaid area is DBCS data, and the data to be placed in the string ends with SBCS data, a shift out character will be added to the front of the data when it is inserted. If shift characters are counted in the length of the string, the length of the overlaid area will be reduced by one to compensate for the shift character.
If the data to be inserted starts with a shift out character, it is removed to allow the data to start with a DBCS character, but the shift out character is not included in the length of the data being inserted, even if &CONTROL DBCS is in effect. Similarly, if the data ends with a shift in character, the shift in character is removed, but is not included in the length of the data. In this case, the shift out and shift in characters are present only to identify the data as DBCS data. This makes it possible to overlay DBCS data onto DBCS data, while &CONTROL DBCS is in use, without adjusting the overlay length for the shift out and shift in characters.
Alignment (left, right, and center) is supported under all circumstances. However, the pad characters can only be single byte characters.
Examples: &OVERLAY
&CONTROL DBCS &A = &OVERLAY AAAA <.A> 2 1
results in
&A = AAAA
Note: The data has been truncated because the length of the area (1) is not sufficient for any DBCS data.
&CONTROL DBCS &A = &OVERLAY AAAA <.A> 2 2
results in
&A = A<>A
An attempt has been made to insert a double byte character in the middle of a single byte string. However, the length of the area (2) is not large enough to contain a DBCS character as well as shift characters, so only the required shift out and shift in have been inserted.
&CONTROL DBCSN &A = &OVERLAY AAAA <.A> 2 2
results in
&A = A<.A>A
Note: The shift out and shift in characters are not included in the length of the overlaid area.
&CONTROL DBCS &A = &OVERLAY <.A.B.C.D.E> A 6 1
results in
&A = <.A.B.C.D.E>
There is not sufficient room in the overlay area for the data, due to the requirement to insert shift out and shift in characters, so the resulting string is unchanged.
&CONTROL DBCS &A = &OVERLAY <.A.B.C.D.E> A 6 2
results in
&A = <.A.B><.D.E>
An attempt has been made to insert a single byte character in the middle of a double byte string. However the length of the area (2) is only enough for the insertion of shift in and shift out characters, so the data has been truncated.
&CONTROL DBCSN &A = &OVERLAY <.A.B.C.D.E> A 5 2 ALIGNL-
results in
&A = <.A.B>A-<.D.E>
The single byte A has replaced the double byte character .C and one pad character has been required to maintain the total length of the string. The shift in and shift out characters are not included in the offset or length of the overlaid area.
&CONTROL DBCS &A = &OVERLAY <.A.B.C.D.E> A 6 4 ALIGNR-
results in
&A = <.A.B>-A<.E>
Four bytes of DBCS data have been overlaid. Some shift in and shift out characters have been required, reducing the length of the data to 2, and the data has been inserted in a right aligned manner with padding to the left.
&CONTROL DBCS &A = &OVERLAY <.A.B.C.D.E> <.Z.Z> 4 4
results in
&A = <.A.Z.Z.D.E>
The shift out and shift in characters in the data being inserted have not been included in the data length.
| Copyright © 2009 CA. All rights reserved. |
|