OVERLAY statement

Inserts content from a specified expression into a field or variable replacing existing characters, bytes, or columns.

Syntax

OVERLAY ( target , position[ , length[ , type ]] ) = expression

target

The name of a CHARACTER field or variable, or a LONGCHAR variable, that you want to overlay with the expression.

position

An integer expression that indicates the first position in the target where you want to overlay the expression. The value of the position must be positive. If the position is longer than the target, ABL pads the target with blanks to match the position.

length

An integer expression that indicates the number of positions you want to allocate for the storage of the expression. The expression is truncated or padded with blanks to match length. If you do not use the length argument or specify -1 as the length, OVERLAY uses the entire expression.

type

A character expression that directs ABL to interpret the specified position and length values as character units, bytes, or columns. A double-byte character registers as one character unit. By default, ABL interprets the specified position and length values as character units.

There are three valid types: "CHARACTER," "RAW," and "COLUMN." The expression "CHARACTER" specifies character units. The expression "RAW" specifies bytes. The expression "COLUMN" specifies display or print character-columns. If you specify the type as a constant expression, ABL validates the type specification at compile time. If you specify the type as a non-constant expression, the AVM validates the type specification at run time.

Note: If the target is a LONGCHAR expression, "CHARACTER" is the only valid type.

expression

A CHARACTER or LONGCHAR expression that results in a character string you want to overlay on the target. If you specify the length, the expression is truncated or padded with blanks to match the length.

Example

The r-replc1.p procedure lets you search for, and replace text strings in a paragraph in a window. When you run the procedure, you see the paragraph, which is an array with an extent of five. You also see a prompt. Enter the text string you want the system to search for, and the new text you want in its place. The procedure searches the paragraph, one line at a time, for the text you entered. The procedure uses the OVERLAY statement to replace the string of old text with the string of new text. The procedure also determines the length of the old text and the new text.

r-replc1.p

DEFINE VARIABLE chktext  AS CHARACTER NO-UNDO.
DEFINE VARIABLE ix       AS INTEGER   NO-UNDO.
DEFINE VARIABLE chkndx   AS INTEGER   NO-UNDO.
DEFINE VARIABLE ndx      AS INTEGER   NO-UNDO.
DEFINE VARIABLE old-text AS CHARACTER NO-UNDO.
DEFINE VARIABLE new-text AS CHARACTER NO-UNDO.
DEFINE VARIABLE max-len  AS INTEGER   NO-UNDO.
DEFINE VARIABLE comment  AS CHARACTER NO-UNDO FORMAT "x(49)" EXTENT 5
  INITIAL ["You are probably interested in OpenEdge because",
    "you have a lot of information to organize.  You",
    "want to get at the information, add to it, and",
    "change it, without a lot of work and aggravation.",
    "You made the right choice with OpenEdge." ].

DISPLAY comment WITH CENTERED FRAME comm NO-LABELS
  TITLE "Why You Chose OpenEdge" ROW 4.

REPEAT:
  SET old-text LABEL "Enter text to search for"
    new-text LABEL "Enter text to replace with"
    WITH FRAME replace SIDE-LABELS CENTERED.

  max-len = MAXIMUM(LENGTH(old-text), LENGTH(new-text)).
  DO ix = 1 TO 5:
    ndx = 1.
    DO ndx = 1 TO LENGTH(comment[ix]):
      chktext = SUBSTRING(comment[ix], ndx).
      chkndx = INDEX(chktext, old-text).
      IF chkndx <> 0 THEN DO:
        ndx = ndx + chkndx - 1.
        OVERLAY(comment[ix], ndx, max-len, "CHARACTER") = new-text.
        ndx = max-len.
      END.
    END.
    DISPLAY comment[ix] WITH FRAME comm.
  END.
END.

Notes

• The SUBSTRING and OVERLAY statements use the length option differently. For both, the length indicates how much of the target to replace. However, SUBSTRING always inserts the full expression and never pads the expression to match the length. By contrast, the length in OVERLAY determines how much ABL adds to the target, even if ABL must truncate the expression or pad it with spaces. See the r-sub-over.p procedure for an illustration the differences between these two statements.
• Do not split double-byte characters. This statement allows you to overlay either the lead or trail-byte of the target string when you specify "RAW" as the type parameter.

See also

SUBSTRING function, SUBSTRING statement