SUBSTITUTE function

Returns a character string that is made up of a base string plus the substitution of arguments in the string. It allows you to use a single string in place of concatenated strings. The function is designed to simplify the task of translating an application from one language to another and is similar to the sprintf function in the C programming language. The data type returned reflects the data type used in its input parameter. For example, if the input parameter is a LONGCHAR, then the function returns a LONGCHAR; if the input parameter is a CHARACTER, then the function returns a CHARACTER.

Syntax

SUBSTITUTE ( base-string[ , arg ]... )

base-string

A CHARACTER or LONGCHAR variable optionally containing substitution parameters of the form &n, where n is an integer between 1 and 9, inclusive.

arg

A constant, field name, variable, or expression that results in a CHARACTER or LONGCHAR value. These argument values replace substitution parameters in base-string.

Example

These statements display the same message:

MESSAGE SUBSTITUTE("There were &1 records in &2 tables", 
  rec-count, table-count).

MESSAGE "There were" rec-count "records in" 
  table-count "tables".

You can alter the position of the substitution parameters, as in this statement:

SUBSTITUTE("&2 comes before &1", "Friday", "Monday").

Notes

• The SUBSTITUTE function is double-byte enabled. The specified base-string and arg values can contain double-byte characters.
• To include an ampersand character in base-string, enter two ampersands (&&).
• The character following the ampersand character must be a digit, or the AVM returns a run-time error.
• To display the result of the SUBSTITUTE function in a frame, you must specify FORMAT or accept the default format of X(8).
• If you use a substitution parameter in base-string but do not specify a corresponding argument, the AVM replaces the substitution parameter with an empty string.
• The SUBSTITUTE function converts Unknown value (?) parameters into empty strings.
• If the length of the resulting substitution exceeds the maximum length for the data type of the original string, an error occurs.
• Any substitution parameter can appear multiple times in base string. For example:

  phrase = "finish on time". DISPLAY SUBSTITUTE("When I say &1, I mean &1!", phrase) FORMAT "X(70)".

  The previous code fragment displays the following line:

  When I say finish on time, I mean finish on time!

See also

REPLACE function