JOINCHARS

The JOINCHARS function joins two or more text values as a single line.

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

JOINCHARS(first-expression, next-expression...)

Arguments

first-expression: An expression to which JOINCHARS joins next-expression. When the first-expression has a data type other than TEXT or NTEXT, JOINCHARS converts it to TEXT. See "Converting Expressions That Are not TEXT or NTEXT".
next-expression...: One or more expressions to join with first-expression. When an expression you want to concatenate has a data type other than TEXT or NTEXT, JOINCHARS converts it to TEXT. See "Converting Expressions That Are not TEXT or NTEXT".

Notes

Converting Expressions That Are not TEXT or NTEXT

When the data type of an expression is not TEXT or NTEXT, JOINCHARS automatically converts its value to TEXT before concatenating it with the other values. For example, when you put a number in a JOINCHARS function, the number is automatically converted to TEXT and no extra step is needed to accomplish this. The format of the result depends on the settings of the COMMAS, DECIMALS, and PARENS options. (When PARENS is set to YES, a space is inserted wherever a parenthesis would appear between joined expressions.)

NA Values

JOINCHARS ignores any arguments that have a value of NA.

Maximum Length of Joined Line

The maximum length of a joined line is 4,000 bytes. When the length of the joined line exceeds 4,000 bytes, JOINCHARS automatically breaks the line and puts the remaining characters on the next line. When the line break would occur between the two bytes of a double-byte character, JOINCHARS does not split the double-byte character. It puts both bytes of the double-byte character on the next line.

Line Breaks

JOINCHARS removes line breaks from the text it joins. To preserve the breaks in a multiline text expression, use the INSCHARS function.

multibyte Characters

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

Examples

Example 15-26 Using JOINCHARS to Concatonate Values

This example shows how you can use JOINCHARS to combine text with the current values of the two variables name.product and price. The variable price has a data type of DECIMAL; however, JOINCHARS automatically converts its value to TEXT in order to join it with the other text values.

LIMIT product TO 'Canoes'
LIMIT month TO 'Dec96'

The JOINCHARS function

JOINCHARS('Current Price for ' name.product ' is:  $' price)

returns the following value.

Current Price for Aluminum Canoes is:  $200.03