INSCHARS

The INSCHARS function inserts one or more characters into a text expression.

When you are using a multibyte character set, you can use the INSBYTES function instead of the INSCHARS function.

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

INSCHARS(text-expression characters [after])

Parameters

text-expression

The expression into which the characters are to be inserted. When text-expression is a multiline TEXT value, INSCHARS preserves the line breaks in the returned value.

characters

One or more characters that you insert into text-expression.

after

An INTEGER that represents the character position after which the specified characters are to be inserted. The position of the first character in text-expression is 1. To insert characters at the beginning of the text, specify 0 for after. When you omit this argument, INSCHARS inserts the characters after the last character in text-expression.

When you specify a value for after that is greater than the length of text-expression, INSCHARS adds blanks to the last line of text-expression. The number of inserted blanks is the difference between the value of after and the length of text-expression. For example, INSCHARS('abc' 'def' 4) inserts one blank before adding 'def' to 'abc', resulting in.

abc def

Examples

Example 7-120 Inserting Characters in Text

This example shows how to insert the characters there in the TEXT value hellojoe.

INSCHARS('hellojoe', 'there', 5)

hellotherejoe