Append Command

Append (Obsolete Command)

Purpose

To add the contents of one or more strings onto the contents of a string.

Syntax

append destination source [... source]

Argument Explanation

destination: May not be a constant or an expression.
source: May be any class of data.

What It Does

Append attaches the contents of one or more sources to destination. If the length of destination is set in the string command which established it to a length (###) shorter than the combined appended length, then only the first ### characters of the appended value remain in destination. No error is declared if this occurs.

To append to an existing string:

append size weight " cat"

If size has a value of "big" and if weight has a value of "fat", this command gives size a value of "big fat cat".

To append to an empty string:

Make the string empty.
Append to it.

move "" to size
append size weight " cat"

Upon declaration with the string command, a string is "full" of spaces, rather than empty. Append does not clear these spaces, nor any other contents which may be in destination. Therefore, the move command above, followed by a pair of quotation marks (""), is required to clear the contents of size even if size has never been used before. If weight has a value of "fat", the append command above gives size a value of "fat cat".

Notes

You can use other string commands, such as right, ascii, character, etc., to create the values of the sources and destination.
Use care not to lose characters when you append to destination. If you append two 10 character variables to a destination which itself has a declared length of only 10 characters, the resulting string will still only be 10 characters long. There will be no error message, and the resulting string will be truncated on the right.
With string commands such as append, use in-memory variables rather than windows or fields to preserve the integrity of the data. Windows always strip trailing spaces, and fields maintain their full defined length with padded spaces. These characteristics may frustrate the attainment of the desired results of using append.
The trim command is an effective way to remove spaces from fields before using append.

Wrong Example:

open companies
find companies by recnum
append companies.name " Incorporated"
save companies

In this example, the word "Incorporated" (with a leading space) is appended to the value of the name field of Database File companies. Since the field contents always contain spaces out to the full defined length of the field, this command would leave the contents of the field unchanged.

Right Example:

string tempstr
open companies
find companies by recnum
trim companies.name to tempstr
append tempstr " Incorporated"
move tempstr to companies.name
save companies

In this example, the contents of field name in Database File companies are trimmed to a temporary variable (tempstr). The word "Incorporated" (with a leading space) is then appended to tempstr, and the appended value is moved back to companies.name.

Although append is normally used with String type variables, it may be used with any type, or combination of types, of variable.

integer shapes kinds
move 34 to kinds
move 12 to shapes
append kinds shapes

This will place the value 3412 in kinds, since the 12 and the 34 are appended, not added.

Source and destination may be the same variable. Where this is the case, appending will double the content of the original variable, up to the declared length in the string command which established the variable.