Functions and CALL Routines

CATQ Function

Concatenates character or numeric values by using a delimiter to separate items and by adding quotation marks to strings that contain the delimiter.

Category:

Character

Syntax
Arguments
Details
	Length of Returned Variable
	The Basics
Comparisons
Examples
See Also

Syntax

CATQ(modifiers<, delimiter>, item-1 <, ..., item-n>)

specifies a character constant, variable, or expression in which each non-blank character modifies the action of the CATQ function. Blanks are ignored. You can use the following characters as modifiers:

1 or '	uses single quotation marks when CATQ adds quotation marks to a string.
2 or "	uses double quotation marks when CATQ adds quotation marks to a string.
a or A	adds quotation marks to all of the item arguments.
b or B	adds quotation marks to item arguments that have leading or trailing blanks that are not removed by the S or T modifiers.
c or C	uses a comma as a delimiter.
d or D	indicates that you have specified the delimiter argument.
h or H	uses a horizontal tab as the delimiter.
m or M	inserts a delimiter for every item argument after the first. If you do not use the M modifier, then CATQ does not insert delimiters for item arguments that have a length of zero after processing that is specified by other modifiers. The M modifier can cause delimiters to appear at the beginning or end of the result and can cause multiple consecutive delimiters to appear in the result.
n or N	converts item arguments to name literals when the value does not conform to the usual syntactic conventions for a SAS name. A name literal is a string in quotation marks that is followed by the letter "n" without any intervening blanks. To use name literals in SAS statements, you must specify the SAS option, VALIDVARNAME=ANY.
q or Q	adds quotation marks to item arguments that already contain quotation marks.
s or S	strips leading and trailing blanks from subsequently processed arguments: To strip leading and trailing blanks from the delimiter argument, specify the S modifier before the D modifier. To strip leading and trailing blanks from the item arguments but not from the delimiter argument, specify the S modifier after the D modifier.
t or T	trims trailing blanks from subsequently processed arguments: To trim trailing blanks from the delimiter argument, specify the T modifier before the D modifier. To trim trailing blanks from the item arguments but not from the delimiter argument, specify the T modifier after the D modifier.
x or X	converts item arguments to hexadecimal literals when the value contains nonprintable characters.

Tip:	If modifier is a constant, enclose it in quotation marks. You can also express modifier as a variable name or an expression.
Tip:	The A, B, N, Q, S, T, and X modifiers operate internally to the CATQ function. If an item argument is a variable, then the value of that variable is not changed by CATQ unless the result is assigned to that variable.

delimiter

specifies a character constant, variable, or expression that is used as a delimiter between concatenated strings. If you specify this argument, then you must also specify the D modifier.

item

specifies a constant, variable, or expression, either character or numeric. If item is numeric, then its value is converted to a character string by using the BESTw. format. In this case, leading blanks are removed and SAS does not write a note to the log.

Details

Length of Returned Variable

The CATQ function returns a value to a variable or if CATQ is called inside an expression, CATQ returns a value to a temporary buffer. The value that is returned has the following length:

up to 200 characters in WHERE clauses and in PROC SQL
up to 32767 characters in the DATA step except in WHERE clauses
up to 65534 characters when CATQ is called from the macro processor

If the length of the variable or the buffer is not large enough to contain the result of the concatenation, then SAS does the following steps:

changes the result to a blank value in the DATA step and in PROC SQL
writes a warning message to the log stating that the result was either truncated or set to a blank value, depending on the calling environment
writes a note to the log that shows the location of the function call and lists the argument that caused the truncation
sets _ERROR_ to 1 in the DATA step

If CATQ returns a value in a temporary buffer, then the length of the buffer depends on the calling environment, and the value in the buffer can be truncated after CATQ finishes processing. In this case, SAS does not write a message about the truncation to the log.

The Basics

If you do not use the C, D, or H modifiers, then CATQ uses a blank as a delimiter.

If you specify neither a quotation mark in modifier nor the 1 or 2 modifiers, then CATQ decides independently for each item argument which type of quotation mark to use, if quotation marks are required. The following rules apply:

CATQ uses single quotation marks for strings that contain an ampersand (&) or percent (%) sign, or that contain more double quotation marks than single quotation marks.
CATQ uses double quotation marks for all other strings.

The CATQ function initializes the result to a length of zero and then performs the following actions for each item argument:

If item is not a character string, then CATQ converts item to a character string by using the BESTw. format and removes leading blanks.
If you used the S modifier, then CATQ removes leading blanks from the string.
If you used the S or T modifiers, then CATQ removes trailing blanks from the string.
CATQ determines whether to add quotation marks based on the following conditions:
- If you use the X modifier and the string contains control characters, then the string is converted to a hexadecimal literal.
- If you use the N modifier, then the string is converted to a name literal if either of the following conditions is true:
  - The first character in the string is not an underscore or an English letter.
  - The string contains any character that is not a digit, underscore, or English letter.
- If you did not use the X or the N modifiers, then CATQ adds quotation marks to the string if any of the following conditions is true:
  - You used the A modifier.
  - You used the B modifier and the string contains leading or trailing blanks that were not removed by the S or T modifiers.
  - You used the Q modifier and the string contains quotation marks.
  - The string contains a substring that equals the delimiter with leading and trailing blanks omitted.
For the second and subsequent item arguments, CATQ appends the delimiter to the result if either of the following conditions is true:
- You used the M modifier.
- The string has a length greater than zero after it has been processed by the preceding steps.
CATQ appends the string to the result.

Comparisons

The CATX function is similar to the CATQ function except that CATX does not add quotation marks.

Examples

The following example shows how the CATQ function concatenates strings.

options ls=110;

data _null_;
   result1=CATQ(' ',
                'noblanks',
                'one blank',
                12345,
                '  lots of blanks    ');
   result2=CATQ('CS',
                'Period (.)                 ',
                'Ampersand (&)              ',
                'Comma (,)                  ',
                'Double quotation marks (") ',
                '   Leading Blanks');
   result3=CATQ('BCQT',
                'Period (.)                 ',
                'Ampersand (&)              ',
                'Comma (,)                  ',
                'Double quotation marks (") ',
                '   Leading Blanks');
   result4=CATQ('ADT',
                '#=#',
                'Period (.)                 ',
                'Ampersand (&)              ',
                'Comma (,)                  ',
                'Double quotation marks (") ',
                '   Leading Blanks');
   result5=CATQ('N',
                'ABC_123   ',
                '123    ',
                'ABC 123');
   put (result1-result5) (=/);
run;

SAS writes the following output to the log.

result1=noblanks "one blank" 12345 "  lots of blanks    "
result2=Period (.),Ampersand (&),"Comma (,)",Double quotation marks ("),Leading Blanks
result3=Period (.),Ampersand (&),"Comma (,)",'Double quotation marks (")',"   Leading Blanks"
result4="Period (.)"#=#'Ampersand (&)'#=#"Comma (,)"#=#'Double quotation marks (")'#=#"   Leading Blanks"
result5=ABC_123 "123"n "ABC 123"n

CATQ Function

Syntax

Arguments

Length of Returned Variable

The Basics