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

Syntax

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

A field or variable of type CHARACTER or LONGCHAR in which you want to store the specified expression.

position

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.

length

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.

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 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 for a multi-byte codepage.

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

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.

Note: The += Addition assignment operator can be used with the SUBSTRING statement.

Examples

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.

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 following 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.

Notes

  • Do not split double-byte characters. This statement allows you to replace either the lead- or trail-byte of the target string when you specify "RAW" for the type parameter.

See also

OVERLAY statement, SUBSTRING function