SAS Macro Language: Reference

Macro Functions

In general, 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 Macro Functions.

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 executin. Unmatched quotation marks ('") and parentheses ( () ) must be marked with a preceding %.

%SCAN, %QSCAN search for a warod 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 characater 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.

%SYSEVALF evaluates arithmetic and logical expressions using floating point arithmetic.

%SYSFUNC, %QSYSFUNC execute SAS functions or user-written functions. %QSYSFUNC masks special charactaers and mnemonic operators in its result.

%SYSGET returns the value of a specified host environment variable.

%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 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 executin. Unmatched quotation marks ('") and parentheses ( () ) must be marked with a preceding %.
%SCAN, %QSCAN	search for a warod 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 characater 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.
%SYSEVALF	evaluates arithmetic and logical expressions using floating point arithmetic.
%SYSFUNC, %QSYSFUNC	execute SAS functions or user-written functions. %QSYSFUNC masks special charactaers and mnemonic operators in its result.
%SYSGET	returns the value of a specified host environment variable.
%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.

Character Functions

Character functions change character strings or provide information about them. Macro Character Functions 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 operataors 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 charactaers and mnemonic operators in its result.

***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 operataors 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 charactaers 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. In general, 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 may contain an unmatched quotation mark or parenthesis). For details, see Chapter 7, "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 this 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, as shown:

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.

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:

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 Chapter 6. Macro Evaluation Functions 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

***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, listed on Statements That Perform Automatic Evaluation, and in the following functions:

%QSCAN(argument,n<,delimiters>)

%QSUBSTR(argument,position<,length>)

%SCAN(argument,n<,delimiters>)

%SUBSTR(argument,position<,length>)

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.

Macro Quoting Functions 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 Chapter 7, "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 ( () ) are marked.

%QUOTE, %NRQUOTE mask special charactaers and mnemoinic 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 mnemlonic 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 charactaers and mnemonic operators for a value.

***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 ( () ) are marked.
%QUOTE, %NRQUOTE	mask special charactaers and mnemoinic 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 mnemlonic 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 charactaers 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 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, to store the value 345) in macro variable B, write

%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, to store the value TITLE "20%"; in macro variable P, write

%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 the statements:

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

They write to the log:

Comments can start with /*

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

For more information about macro quoting, see Chapter 7.

Other Functions

Three other macro functions do not fit into the earlier categories, but they provide important information. Macro Quoting Functions lists these functions:

Macro Quoting Functions
Function Description

%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 system.

%SYSPROD reports whether a SAS software product is licensed at the site.

***Macro Quoting Functions***
Function	Description
%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 system.
%SYSPROD	reports whether a SAS software product is licensed at the site.

The %SYSFUNC and %QSYSFUNC functions make most of the functions from base SAS software and Screen Control Language available to the macro facility. Consider these 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 on each of these functions, see Chapter 13, "Macro Language Dictionary."

Chapter Contents
Previous
Next
Top of Page