Macro Functions :: SAS(R) 9.3 Macro Language: Reference

Using Macro Functions

A macro language function processes one or more arguments and produces a result. You can use all macro functions in both macro definitions and open code. Macro functions include character functions, evaluation functions, and quoting functions. The macro language functions are listed in the following table.

Macro Functions

Function	Description
%BQUOTE, %NRBQUOTE	Mask special characters and mnemonic operators in a resolved value at macro execution.
%EVAL	Evaluates arithmetic and logical expressions using integer arithmetic.
%INDEX	Returns the position of the first character of a string.
%LENGTH	Returns the length of a string.
%QUOTE, %NRQUOTE	Mask special characters and mnemonic operators in a resolved value at macro execution. Unmatched quotation marks (“ ”) and parentheses ( () ) must be marked with a preceding %.
%SCAN, %QSCAN	Search for a word specified by its number. %QSCAN masks special characters and mnemonic operators in its result.
%STR, %NRSTR	Mask special characters and mnemonic operators in constant text at macro compilation. Unmatched quotation marks (“ ”) and parentheses ( () ) must be marked with a preceding %.
%SUBSTR, %QSUBSTR	Produce a substring of a character string. %QSUBSTR masks special characters and mnemonic operators in its result.
%SUPERQ	Masks all special characters and mnemonic operators at macro execution but prevents resolution of the value.
%SYMEXIST	Returns an indication as to whether the named macro variable exists.
%SYMGLOBL	Returns an indication as to whether the named macro variable is global in scope.
%SYMLOCAL	Returns an indication as to whether the named macro variable is local in scope.
%SYSEVALF	Evaluates arithmetic and logical expressions using floating-point arithmetic.
%SYSFUNC, %QSYSFUNC	Execute SAS functions or user-written functions. %QSYSFUNC masks special characters and mnemonic operators in its result.
%SYSGET	Returns the value of a specified host environment variable.
%SYSMACEXEC	Indicates whether a macro is currently executing.
%SYSMACEXIST	Indicates whether there is a macro definition in the WORK.SASMACR catalog.
%SYSMEXECDEPTH	Returns the depth of nesting from the point of call.
%SYSMEXECNAME	Returns the name of the macro executing at a nesting level.
%SYSPROD	Reports whether a SAS software product is licensed at the site.
%UNQUOTE	Unmasks all special characters and mnemonic operators for a value.
%UPCASE, %QUPCASE	Convert characters to uppercase. %QUPCASE masks special characters and mnemonic operators in its result.

Macro Character Functions

Character functions change character strings or provide information about them. The following table lists the macro character functions.

Macro Character Functions

Function	Description
%INDEX	Returns the position of the first character of a string.
%LENGTH	Returns the length of a string.
%SCAN, %QSCAN	Search for a word that is specified by a number. %QSCAN masks special characters and mnemonic operators in its result.
%SUBSTR, %QSUBSTR	Produce a substring of a character string. %QSUBSTR masks special characters and mnemonic operators in its result.
%UPCASE, %QUPCASE	Convert characters to uppercase. %QUPCASE masks special characters and mnemonic operators in its result.

For macro character functions that have a Q form (for example, %SCAN and %QSCAN), the two functions work alike except that the function beginning with Q masks special characters and mnemonic operators in its result. Use the function beginning with Q when an argument has been previously masked with a macro quoting function or when you want the result to be masked (for example, when the result might contain an unmatched quotation mark or parenthesis). For details, see Macro Quoting.

Many macro character functions have names corresponding to SAS character functions and perform similar tasks (such as %SUBSTR and SUBSTR). But, macro functions operate before the DATA step executes. Consider the following DATA step:

data out.%substr(&sysday,1,3);     /* macro function */
   set in.weekly (keep=name code sales);
   length location $4;
   location=substr(code,1,4);         /* SAS function */
run;

Running the program on Monday creates the data set name OUT.MON:

data out.MON;                      /* macro function */
   set in.weekly (keep=name code sales);
   length location $4;
   location=substr(code,1,4);         /* SAS function */
run;

Suppose that the IN.WEEKLY variable CODE contains the values cary18593 and apex19624. The SAS function SUBSTR operates during DATA step execution and assigns these values to the variable LOCATION: cary and apex.

Macro Evaluation Functions

Evaluation functions evaluate arithmetic and logical expressions. They temporarily convert the operands in the argument to numeric values. Then, they perform the operation specified by the operand and convert the result to a character value. The macro processor uses evaluation functions to do the following:

make character comparisons
evaluate logical (Boolean) expressions
assign numeric properties to a token, such as an integer in the argument of a function

For more information, see Macro Expressions. The following table lists the macro evaluation functions.

Macro Evaluation Functions

Function	Description
%EVAL	Evaluates arithmetic and logical expressions using integer arithmetic.
%SYSEVALF	Evaluates arithmetic and logical expressions using floating-point arithmetic.

%EVAL is called automatically by the macro processor to evaluate expressions in the arguments to the statements that perform evaluation in the following functions:

%QSCAN(argument, n<, delimiters>)
%QSUBSTR(argument, position<, length>)
%SCAN(argument, n<, delimiters>)
%SUBSTR(argument, position<, length>)

Macro Quoting Functions

Macro quoting functions mask special characters and mnemonic operators so the macro processor interprets them as text instead of elements of the macro language.

The following table lists the macro quoting functions, and also describes the special characters they mask and when they operate. (Although %QSCAN, %QSUBSTR, and %QUPCASE mask special characters and mnemonic operations in their results, they are not considered quoting functions because their purpose is to process a character value and not simply to quote a value.) For more information, see Macro Quoting.

Macro Quoting Functions

Function	Description
%BQUOTE, %NRBQUOTE	Mask special characters and mnemonic operators in a resolved value at macro execution. %BQUOTE and %NRBQUOTE are the most powerful functions for masking values at execution time because they do not require that unmatched quotation marks (“ ”) and parentheses ( () ) be marked.
%QUOTE, %NRQUOTE	Mask special characters and mnemonic operators in a resolved value at macro execution. Unmatched quotation marks (“ ”) and parentheses ( () ) must be marked with a preceding %.
%STR, %NRSTR	Mask special characters and mnemonic operators in constant text at macro compilation. Unmatched quotation marks (“ ”) and parentheses ( () ) must be marked with a preceding %.
%SUPERQ	Masks all special characters and mnemonic operators at macro execution but prevents resolution of the value.
%UNQUOTE	Unmasks all special characters and mnemonic operators for a value.

Compilation Quoting Functions

%STR and %NRSTR mask special characters and mnemonic operators in values during compilation of a macro definition or a macro language statement in open code. For example, the %STR function prevents the following %LET statement from ending prematurely. It keeps the semicolon in the PROC PRINT statement from being interpreted as the semicolon for the %LET statement.

%let printit=%str(proc print; run;);

Execution of Macro Quoting Functions

%BQUOTE, %NRBQUOTE, %QUOTE, %NRQUOTE, and %SUPERQ mask special characters and mnemonic operators in values during execution of a macro or a macro language statement in open code. Except for %SUPERQ, these functions instruct the macro processor to resolve a macro expression as far as possible and mask the result, issuing warning messages for any macro variable references or macro invocations they cannot resolve. %SUPERQ protects the value of a macro variable from any attempt at further resolution.

Of the quoting functions that resolve values during execution, %BQUOTE and %NRBQUOTE are the most flexible. For example, the %BQUOTE function prevents the following %IF statement from producing an error if the macro variable STATE resolves to OR (for Oregon). Without %BQUOTE, the macro processor would interpret the abbreviation for Oregon as the logical operator OR.

%if %bquote(&state)=nc %then %put North Carolina Dept. of
Revenue;

%SUPERQ fetches the value of a macro variable from the macro symbol table and masks it immediately, preventing the macro processor from attempting to resolve any part of the resolved value. For example, %SUPERQ prevents the following %LET statement from producing an error when it resolves to a value with an ampersand, like Smith&Jones. Without %SUPERQ, the macro processor would attempt to resolve &Jones.

%let testvar=%superq(corpname);
     /* No ampersand in argument to %superq. */

(%SUPERQ takes as its argument either a macro variable name without an ampersand or a text expression that yields a macro variable name.)

Quotation Marks and Parentheses without a Match

Syntax errors result if the arguments of %STR, %NRSTR, %QUOTE, and %NRQUOTE contain a quotation mark or parenthesis that does not have a match. To prevent these errors, mark these quotation marks and parentheses by preceding them with a percent sign. For example, write the following to store the value 345)in macro variable B:

%let b=%str(345%));

If an argument of %STR, %NRSTR, %QUOTE, or %NRQUOTE contains a percent sign that precedes a quotation mark or parenthesis, use two percent signs (%%) to specify that the argument's percent sign does not mark the quotation mark or parenthesis. For example, Write the following to store the value TITLE "20%";in macro variable P:

%let p=%str(TITLE "20%%";);

If the argument for one of these functions contains a character string with the comment symbols /* and -->, use a %STR function with each character. For example, consider these statements:

%let instruct=Comments can start with %str(/)%str(*).;
%put &instruct;

They write the following line to the SAS log:

Comments can start with /*

Note: Unexpected results can occur if the comment symbols are not quoted with a quoting function.

For more information about macro quoting, see Macro Quoting.

Macro Functions for Double-Byte Character Set (DBCS)

Because East Asian languages have thousands of characters, double (two) bytes of information are needed to represent each character. Each East Asian language usually has more than one DBCS encoding system. SAS processes the DBCS encoding information that is unique for the major East Asian languages. The following table defines the macro functions that support DBCS.

Macro Functions for DBCS

Functions	Description
%KCMPRES	Compresses multiple blanks and removes leading and trailing blanks.
%KINDEX	Returns the position of the first character of a string.
%KLEFT and %QKLEFT	Left-aligns an argument by removing leading blanks.
%KLENGTH	Returns the length of a string.
%KSCAN and %QKSCAN	Searches for a word that is specified by its position in a string.
%KSUBSTR and %QKSUBSTR	%KSUBSTR and %QKSUBSTR produces a substring of a character string.
%KUPCASE and %QKUPCASE	Converts values to uppercase.

For more information, see “Macro Functions for NLS” in SAS National Language Support (NLS): Reference Guide.

Other Macro Functions

Seven other macro functions do not fit into the earlier categories, but they provide important information. The following table lists these functions.

Other Macro Functions

Function	Description
%SYMEXIST	Returns an indication as to whether the named macro variable exists.
%SYMGLOBL	Returns an indication as to whether the named macro variable is global in scope.
%SYMLOCAL	Returns an indication as to whether the named macro variable is local in scope.
%SYSFUNC, %QSYSFUNC	Execute SAS language functions or user-written functions within the macro facility.
%SYSGET	Returns the value of the specified host environment variable. For details, see the SAS Companion for your operating environment.
%SYSPROD	Reports whether a SAS software product is licensed at the site.

The %SYSFUNC and %QSYSFUNC functions enable most of the functions from Base SAS software, a function written with the SAS/TOOLKIT software, or a function created using the FCMP procedure available to the macro facility. Consider the following examples:

• /* in a DATA step or SCL program */
     dsid=open("sasuser.houses","i");
• /* in the macro facility */
     %let dsid = %sysfunc(open(sasuser.houses,i));

For more information, see %SYSFUNC and %QSYSFUNC Functions.