SUBSTITUTE function

This function returns a character string that is made up of a base string plus the substitution of arguments in the string. (The data type of the returned value matches the data type of the expression passed to the function.) It allows you to use a single string in place of concatenated strings. It is designed to simplify the task of translating an application from one language to another. This function is similar to the sprintf function in the C programming language.

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