String

Purpose

Declares one or more String variables.

Syntax

To declare string variables:

String {
    identifier
}
[{
    identifier
}] {globalStringLength}

Where:

{identifier} is the name of a new String variable.
{identifier} may be between 1 and 4096 characters in length, must start with a letter, and may not contain spaces. Recommended characters are 0-9, a-z, A-Z, and _ (underscore).
{globalStringLength} (Optional) is an integer that may be specified in the range of 1 to 4096 to change the default maximum length of a global string (default is 80).

To declare array variables of type String:

String {dimension-list} {identifier} […{identifier}]

Where:

{dimension-list} is a list of one or more array dimensions for the array. A dimension list is declared using square brackets []. One pair of brackets is used to declare each dimension. If the array is static, then you must specify the static size of each dimension between each pair of brackets, e.g., [{size}]. For more information about declaring arrays, refer to Array Variable Assignments.
{identifier} may be between 1 and 4096 characters in length, must start with a letter, and may not contain spaces. Recommended characters are 0-9, a-z, A-Z, and _ (underscore).

Multiline Strings

DataFlex supports multiline strings by placing the @ symbol in front of the opening quote.

An example of a multi-line string:

String sPhrase
Move @"My Summer Reading List:
- We Are Legion
- Ringworld
- Project Hail Mary" to sPhrase

See Character Strings for more information on this.

Aligned Multiline Strings

DataFlex supports aligned multiline strings via 3 opening and closing quotes.

String sPhrase
Move """
My Summer Reading List:
- We Are Legion
- Ringworld
- Project Hail Mary
""" to sPhrase

See Character Strings for more information on this.

What It Does

String declares string variables. Strings are typically used to contain data other than dates and quantities. String data encompasses any and all printable characters in any desired order.

We recommend storing binary data in UChar arrays instead of strings.

Multiple variables may be declared on one command line, with their names separated from each other by spaces.

Examples

Procedure RunTest
    String sSong sKey sTempo sLyrics
End_Procedure

In this example, local string variables sSong, sKey, sTempo, and sLyrics are created inside Procedure RunTest.

Literal material which is to be moved to a string variable should be enclosed in quotation marks.

String sEquation
Move "(m *(c ^2))" to sEquation

In this example, (m *(c ^2)) is moved to string variable sEquation.

If a statement moves numbers, dates, or expressions not enclosed in quotation marks to a String, the value of the variable or expression will be converted to a string and moved to the String variable.

String sEquation
Number m c
Move 8 to m
Move 4 to c
Move (m *(c ^2)) to sEquation

In this example, the value of m *(c ^2) (128) is moved to string variable sEquation.

String[] sStudents

This example declares a dynamic array variable named sStudents, containing an undefined number of elements of type string.

String[5] sStudents

This example declares a static array variable named sStudents, containing 5 elements of type string.

String[][3] sStudents

This example creates a two-dimensional dynamic array variable named sStudents, containing an undefined number of elements of type string. Conceptually, this represents a rectangular array with an undefined number of rows, each of 3 columns.

You can declare dynamic multi-dimensional arrays where all dimensions are dynamic; these are called jagged arrays.

Notes

An exclamation point "!" is a reserved character in DataFlex's command macro language. Moving "!" into a string when followed by any character in source code will most likely lead to a replacement of those two characters in that string with another value, which can have unintended consequences at runtime:
```
Move "!s" to s  // s = "4761" at runtime
```
If you need to include ! in a string, you can do so by using the character function:
```
Move (Character(33) + "s") to s
```
If you move or append data to a global string variable which exceeds its declared length, the characters in excess will be truncated from the value of the variable. No error will be declared.
```
String gsShort 5
Move "1234567890" to gsShort
```
After these commands, variable gsShort will have contents of 12345, having truncated all characters moved to it in excess of its declared length.
If you need to define a global string variable, you should use the global_variable command to do so.