Preliminary Draft ***** Subject to Change ***** Totally Unofficial

CAT* functions and CALL routines, version 9 and later

May 2, 2002

The CAT* functions and CALL routines concatenate character strings.

These functions and CALL routines differ in how they treat leading
and trailing blanks in character arguments, and in whether separator
strings are inserted between the concatenated strings:
* CAT does not remove leading or trailing blanks, and does not
insert separators.
* CATT trims trailing blanks, but not leading blanks, and does not
insert separators.
* CATS strips both leading and trailing blanks, and does not
insert separators.
* CATX strips both leading and trailing blanks, and inserts
separators. The first argument to CATX specifies the separator.
All of the CAT* functions and CALL routines strip both leading and
trailing blanks from numeric arguments after formatting the numeric
value with the BEST. format.
CAT can be used only as a function. CATT, CATS, and CATX can be
used as either functions or CALL routines. When used as functions,
CAT, CATT, CATS, and CATX return strings with a length of up to:
* 200 characters in WHERE clauses and/or PROC SQL.
* 32767 characters in other parts of the DATA step.
* 65534 characters when called from the macro processor.
When CATT and CATS are used as CALL routines, the result is returned
in the first argument. When CATX is used as a CALL routine, the result
is returned in the second argument (since the first argument is the
separator). The argument that contains the result must be a variable;
the following arguments are appended to the value of this variable.
If this variable is not long enough to contain the entire result, then:
* a warning is printed that the result was truncated,
* a note is printed showing the location of the function call
and telling which argument caused the truncation
* in the DATA step, _ERROR_ is set to one.
When CATT, CATS, or CATX are used as CALL routines, the result is
never assigned a blank value due to truncation. Note that this behavior
differs from that of the CAT, CATS, CATT, and CATX functions, as
described below.
If CAT, CATS, CATT, or CATX are used as functions, the result may
either be assigned directly to a variable, or returned in a temporary
buffer that the user normally is unaware of. There is no simple way
to determine which of these alternatives will occur except to try it
and see. If a temporary buffer is used, then the length of the buffer
depends on the calling environment, and the value in the buffer may

subsequently be truncated after the CAT, CATS, CATT, or CATX function

has finished, in which case there will be no message about truncation.
However, if the variable or buffer to which the result is assigned is
not long enough to contain the concatenation of all the arguments, then:
* the result is changed to a blank value in the DATA step, SQL, and
possibly other calling environments
* a warning is printed that the result was either truncated
or set to a blank value, depending on the calling environment
* a note is printed showing the location of the function call
and telling which argument caused the truncation
* in the DATA step, _ERROR_ is set to one.
If truncation occurs after the function has finished, the result
is not set to blank, no messages are printed, and _ERROR_ is not
set to one.
The results of the CAT* functions are typically equivalent to those
produced by certain combinations of the concatenation operator (||)
and the TRIM and LEFT functions. However, the CAT* functions are
faster, more convenient, and can be used with variable lists in
calling environments that support variable lists. The following
table shows equivalents of the CAT* functions using || and other
functions, assuming that X1, X2, X3, and X4 are character variables:
Function
Equivalent || code
-----------------------------------CAT(OF X1-X4)

X1||X2||X3||X4

CATT(OF X1-X4)

TRIM(X1)||TRIM(X2)||TRIM(X3)||TRIM(X4)

CATS(OF X1-X4)

TRIM(LEFT(X1))||TRIM(LEFT(X2))||TRIM(LEFT(X3))||
TRIM(LEFT(X4))

CATX(SP,OF X1-X4) TRIM(LEFT(X1))||SP||TRIM(LEFT(X2))||SP||

TRIM(LEFT(X3))||SP||TRIM(LEFT(X4))
(where SP is a separator such as a blank or comma)
The following table shows statements that are equivalent to the
use of CATT, CATS, and CATX as CALL routines:
CALL Routine
Equivalent statement
-------------------------------------------CALL CATT(OF X1-X4);

X1=TRIM(X1)||TRIM(X2)||TRIM(X3)||TRIM(X4);

CALL CATS(OF X1-X4);

X1=TRIM(LEFT(X1))||TRIM(LEFT(X2))||
TRIM(LEFT(X3))||TRIM(LEFT(X4));

CALL CATX(SP,OF X1-X4); X1=TRIM(LEFT(X1))||SP||TRIM(LEFT(X2))||SP||

TRIM(LEFT(X3))||SP||TRIM(LEFT(X4)); (where SP
is a separator such as a blank or comma)
CATX differs slightly from the || code shown above, in the CATX omits
the corresponding separator if any of the arguments to be concatenated
is completely blank. For example, CATX("+","X"," ","Z"," ") produces

"X+Z".
Examples:
In this DATA step, the CALL CATS routine prints messages because the
variable A has a length of only 4, which is not long enough to hold
the concatentation of two strings with a nonblank length of 3:
data _null_;
length a b $4;
a = 'abc';
b = 'xyz';
call cats(a,b);
put a= b=;
run;
In this DATA step, truncation is done silently after the CATS function
finishes:
data _null_;
length a b $4;
a = 'abc';
b = 'xyz';
a = cats(a,b);
put a= b=;
run;
In this DATA step, truncation occurs inside the CATS function,
appropriate messages are issued, and the result is set to a blank
value:
data _null_;
length a b c $4;
a = 'abc';
b = 'xyz';
c = cats(a,b);
put a= b= c=;
run;
In this DATA step, truncation is done silently:
data _null_;
length a b c $4;
a = 'abc';
b = 'xyz';
c = trim(cats(a,b));
put a= b= c=;
run;