JOINBYTES

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

Return Value

TEXT

Syntax

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

Arguments

first-expression: An expression to which JOINBYTES joins next-expression. When the first-expression has a data type other than TEXT, JOINBYTES converts it to TEXT. See "Converting Expressions to TEXT".
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, JOINBYTES converts it to TEXT.

Notes

Converting Expressions to TEXT

When the data type of an expression is not TEXT, JOINBYTES automatically converts its value to TEXT before concatenating it with the other values. For example, when you put a number in a JOINBYTES 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

JOINBYTES 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, JOINBYTES automatically breaks the line and puts the remaining bytes on the next line. The line break could occur between the two bytes of a double-byte character. JOINBYTES would then end one line with the first byte of the double-byte character and start the next line with the second byte of the character.

Line Breaks

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

Single-Byte Characters

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

NTEXT Data Type

This function does not accept NTEXT arguments, because it is oriented toward byte-manipulation instead of character manipulation. It always returns values of type TEXT. When you must use this function on NTEXT values, use the CONVERT or TO_CHAR function to convert the NTEXT value to TEXT.

Examples

Example 15-25 Using JOINBYTES to Concatenate Values

This example shows how you can use JOINBYTES 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, JOINBYTES 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 JOINBYTES function

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

returns the following value.

Current Price for Aluminum Canoes is:  $200.03