SUBSTRING statement

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


SUBSTRING ( `target` , `position` [ , `length` [ , `type` ] ] ) = `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 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.

The r-sub.p 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.

r-sub.p
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.

r-sub.p

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 r-sub-over.p (1 of 2) procedure illustrates the differences between these two statements.

r-sub-over.p
/* 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.

r-sub-over.p

/* 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.