Inserts content from a specified expression into a field or variable, optionally replacing existing characters, bytes, or columns.
A field or variable of type CHARACTER or LONGCHAR in which you want to store the specified expression.
An integer expression that indicates the position in the target where you want to start storing the expression. If the position is longer than the target, ABL pads the target with blanks to equal the length of the position.
An integer expression that indicates the number of positions you want to replace in the target. If you specify a length of 0, the entire expression is inserted at the position and everything else moves to the right. If you do not use the length argument or specify -1 as the length, SUBSTRING puts the entire expression into the target, replacing an equal amount of the target.
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 type values: "CHARACTER", "RAW", and "COLUMN". The value "CHARACTER" specifies character units. The value "RAW" specifies bytes. The value "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.
A constant, field name, variable name, or expression of CHARACTER or LONGCHAR data type that results in a character string whose value you want to insert in the target. ABL does not pad or truncate expression.
The following procedure uses the SUBSTRING statement to replace a segment of text with the expression in the SUBSTRING statement XXXXXXXXX. The procedure first displays the text you can work with in the Original Text frame. Then the procedure prompts you for the start position of the replacement and the length of the replacement. Under the WORD heading, you see the revised text.
DEFINE VARIABLE rtext AS CHARACTER NO-UNDO FORMAT "x(50)". DEFINE VARIABLE orig AS CHARACTER NO-UNDO FORMAT "x(31)". DEFINE VARIABLE strt AS INTEGER NO-UNDO FORMAT ">9". DEFINE VARIABLE leng AS INTEGER NO-UNDO FORMAT ">9". orig = "Now is the time to use OpenEdge". DISPLAY orig WITH CENTERED TITLE "Original Text" NO-LABEL. REPEAT: rtext = orig. UPDATE strt LABEL "START" leng LABEL "LENGTH". SUBSTRING(rtext, strt, leng, "CHARACTER") = "XXXXXXXXX". DISPLAY rtext LABEL "WORD" WITH CENTERED. END. |
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. The following procedure illustrates the differences between these two statements.
/* This procedure illustrates the differences between the SUBSTRING and OVERLAY statements. */ DEFINE VARIABLE cOriginal AS CHARACTER NO-UNDO INITIAL "OpenEdge". DEFINE VARIABLE cSubstring AS CHARACTER NO-UNDO. DEFINE VARIABLE cOverlay AS CHARACTER NO-UNDO. DEFINE VARIABLE cResults AS CHARACTER NO-UNDO. /* Default behavior without optional LENGTH. */ ASSIGN cSubstring = cOriginal SUBSTRING(cSubstring,2) = "***" cOverlay = cOriginal OVERLAY(cOverlay,2) = "***" cResults = "target = ~"OpenEdge~". ~n~n" + "If you do not supply a length, SUBSTRING and OVERLAY default as follows: ~n~n" + "SUBSTRING(target,2) = ~"***~" yields: " + cSubstring + ". ~n" + "OVERLAY(target,2) = ~"***~" yields: " + cOverlay + ".". /* Behavior with zero LENGTH. */ ASSIGN cSubstring = cOriginal SUBSTRING(cSubstring,2,0) = "***" cOverlay = cOriginal OVERLAY(cOverlay,2,0) = "***" cResults = cResults + "~n~n" + "For a zero length, SUBSTRING and OVERLAY behave as follows: ~n~n" + "SUBSTRING(target,2,0) = ~"***~" yields: " + cSubstring + ". ~n" + "OVERLAY(target,2,0) = ~"***~" yields: " + cOverlay + ".". /* Behavior with LENGTH < replacement. */ ASSIGN cSubstring = cOriginal SUBSTRING(cSubstring,2,1) = "***" cOverlay = cOriginal OVERLAY(cOverlay,2,1) = "***" cResults = cResults + "~n~n" + "For a length shorter than the replacement, SUBSTRING and OVERLAY behave as follows: ~n~n" + "SUBSTRING(target,2,1) = ~"***~" yields: " + cSubstring + ". ~n" + "OVERLAY(target,2,1) = ~"***~" yields: " + cOverlay + ".". /* Behavior with LENGTH = replacement. */ ASSIGN cSubstring = cOriginal SUBSTRING(cSubstring,2,3) = "***" cOverlay = cOriginal OVERLAY(cOverlay,2,3) = "***" cResults = cResults + "~n~n" + "For a length equal to the replacement, SUBSTRING and OVERLAY behave as follows: ~n~n" + "SUBSTRING(target,2,3) = ~"***~" yields: " + cSubstring + ". ~n" + "OVERLAY(target,2,3) = ~"***~" yields: " + cOverlay + ".". /* Behavior with LENGTH > replacement. */ ASSIGN cSubstring = cOriginal SUBSTRING(cSubstring,2,6) = "***" cOverlay = cOriginal OVERLAY(cOverlay,2,6) = "***" cResults = cResults + "~n~n" + "For a length greater than the repalcement, SUBSTRING and OVERLAY behave as follows: ~n~n" + "SUBSTRING(target,2,6) = ~"***~" yields: " + cSubstring + ". ~n" + "OVERLAY(target,2,6) = ~"***~" yields: " + cOverlay + ".". MESSAGE cResults VIEW-AS ALERT-BOX. |