INSCOLS

The INSCOLS function inserts into the columns of a multiline TEXT value all the columns of another TEXT value. The inserted columns are placed after the column position you specify, and the original columns in each line are moved to the right. The function returns a multiline TEXT value composed of the resulting columns.

Return Value

TEXT or NTEXT

This function accepts TEXT values and NTEXT values as arguments. The data type of the return value depends on the data type of the values specified for the arguments:

When all arguments are TEXT values, the return value is TEXT.
When all arguments are NTEXT values, the return value is NTEXT.
When the arguments include both TEXT and NTEXT values, the function converts all TEXT values to NTEXT before performing the function operation, and the return value is NTEXT.

Syntax

INSCOLS(text-expression columns [after])

Arguments

text-expression: The expression into which you want to insert columns.
columns: The expression containing one or more columns in each line. All the columns of this expression will be inserted into the corresponding lines of text-expression.
after: An integer between 0 and 4,000 representing the column position after which columns should be inserted. The column position of the first character in each line is 1. When you do not specify after, insertion begins at the end of each line. The total length of a line cannot exceed 4,000 columns of single-byte characters or 2,000 columns of double-byte characters.

Notes

Number of Lines Returned

The number of lines in the return value is always the same as the number of lines in text-expression. When the columns TEXT expression has fewer lines, INSCOLS repeats its last line in each subsequent line of the return value.

After Column Beyond the End of a Line

When you specify an after column that is to the right of the last character in a given line in text-expression, the corresponding line in the return value will have spaces filling in the intervening columns.

Examples

Example 15-12 Inserting Text Columns

In the following example, a color code (stored in the multiline TEXT value itemcolor) is inserted into item identifiers that are stored in the itemid text value. The columns are inserted after Column 3.

itemcolor has the following value.

Blu
Red
Gre
Ora

itemid has the following value.

542-Fra
379-Eng
968-USA
369-Can

The INSCOLS function call

INSCOLS(itemid itemcolor 3)

returns the following.

542Blu-Fra
379Red-Eng
968Gre-USA
369Ora-Can