SAS Macro Language: Reference

Overview of Macro Quoting

The macro language is a character-based language. Even variables that appear to be numeric are generally treated as character variables (except during expression evaluation). Therefore, the macro processor enables you to generate all sorts of special characters as text; but because the macro language is composed of some of the same special characters, an ambiguity often arises: should the macro processor interpret a particular special character (for example, a semicolon or % sign) or a mnemonic (for example, GE or AND) as text or as a symbol in the macro language? Macro quoting functions resolve these ambiguities by masking the significance of special characters so the macro processor does not misinterpret them.

The following special characters and mnemonics may require masking when they appear in text strings:

blank

;

¬

^

~

, (comma)

'

"

Understanding Why Macro Quoting is Necessary

Macro quoting functions tell the macro processor to interpret special characters and mnemonics as text rather than as part of the macro language. If you did not use a macro quoting function to mask the special characters, the macro processor or the rest of the SAS System might give the character a meaning you did not intend. Here are some examples of the kinds of ambiguities that can arise when text strings contain special characters and mnemonics:

Is %sign a call to the macro SIGN or a phrase "percent sign"?
Is OR the mnemonic Boolean operator or the abbreviation for Oregon?
Is the quote in O'Malley an unbalanced single quotation mark or just part of the name?
Is Boys&Girls a reference to the macro variable &GIRLS or a group of children?
Is GE the mnemonic for "greater than or equal" or is it short for General Electric?
Which statement does a semicolon end?
Does a comma separate parameters, or is it part of the value of one of the parameters?

Macro quoting functions enable you to clearly indicate to the macro processor how it is to interpret special characters and mnemonics.

Here is an example, using the simplest macro quoting function, %STR. Suppose you want to assign a PROC PRINT statement and a RUN statement to the macro variable PRINT. Here is the erroneous statement:

%let print=proc print; run;;  /* ERROR */

This code is ambiguous. Are the semicolons that follow PRINT and RUN part of the value of the macro variable PRINT, or does one of them end the %LET statement? If you do not tell the macro processor what to do, it interprets the semicolon after PRINT as the end of the %LET statement; the value of the PRINT macro variable is

proc print

The rest of the characters (RUN;;) are simply the next part of the program.

To avoid the ambiguity and correctly assign the value of PRINT, you must mask the semicolons with the macro quoting function %STR, as follows:

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

Understanding Macro Quoting Functions

The following macro quoting functions are most commonly used:

%STR and %NRSTR
%BQUOTE and %NRBQUOTE
%SUPERQ

For the paired macro quoting functions, the function beginning with NR affects the same category of special characters that are masked by the plain macro quoting function as well as ampersands and percent signs. In effect, the NR functions prevent macro and macro variable resolution. To help you remember which does which, try associating the NR in the macro quoting function names with the words "not resolved" -- that is, macros and macro variables are not resolved when you use these functions.

The macro quoting functions with B in their names are useful for macro quoting unmatched quotation marks and parentheses. As a help for remembering this, try associating B with "by itself".

The %SUPERQ macro quoting function is unlike the other macro quoting functions in that it does not have a mate and works differently than the other macro quoting functions. See Using %SUPERQ for more information on the %SUPERQ macro quoting function.

The macro quoting functions can also be divided into three types, depending on when they take effect:

compilation functions cause the macro processor to interpret special characters as text in a macro program statement in open code or while compiling (constructing) a macro. The %STR and %NRSTR functions are compilation functions.

execution functions cause the macro processor to treat as text special characters that result from resolving a macro expression (such as a macro variable reference, a macro invocation, or the argument of an implicit %EVAL function). They are called execution functions because resolution occurs during macro execution or during execution of a macro program statement in open code. The macro processor resolves the expression as far as possible, issues any warning messages for macro variable references or macro invocations it cannot resolve, and quotes the result. The %BQUOTE and %NRBQUOTE functions are execution functions.
An implicit %EVAL function is one that is caused by another macro statement, such as a %DO %TO statement. An explicit %EVAL function is one that is directly called by macro code.

function that prevents resolution causes the macro processor to treat the value of a macro variable as a "picture" during macro execution. It treats the value as text, without beginning the process of resolution. The %SUPERQ function prevents resolution of a macro variable's value.
The %SUPERQ function takes as its argument a macro variable name (or a macro expression that yields a macro variable name). The argument must not be a reference to the macro variable whose value you are masking; that is, do not include the & before the name.

Note: Two other execution macro quoting functions exist, %QUOTE and %NRQUOTE. They are useful for unique macro quoting needs and for compatibility with older macro applications. For more information on these two macro quoting functions, refer to Chapter 13, "Macro Language Dictionary." [cautionend]

Passing Parameters That Contain Special Characters and Mnemonics

Using an execution macro quoting function in the macro definition is the simplest and best way to have the macro processor accept resolved values that may contain special characters. However, if you discover that you need to pass parameter values such as or when a macro has not been defined with an execution macro quoting function, you can do so by masking the value in the macro invocation. The logic of the process is as follows:

When you mask a special character with a macro quoting function, it remains masked as long as it is within the macro facility (unless you use the %UNQUOTE function, described in "nquoting Text"later in this chapter).
The macro processor constructs the complete macro invocation before beginning to execute the macro.
Therefore, you can mask the value in the invocation with the %STR function. Although the masking is not needed when the macro processor is constructing the invocation, the value is already masked by a macro quoting function when macro execution begins and therefore does not cause problems during macro execution.

For example, suppose a macro named ORDERX does not use the %BQUOTE function. You can pass the value or to the ORDERX macro with the following invocation:

%orderx(%str(or))

However, placing the macro quoting function in the macro definition makes the macro much easier for you to invoke.

Chapter Contents
Previous
Next
Top of Page

compilation functions	cause the macro processor to interpret special characters as text in a macro program statement in open code or while compiling (constructing) a macro. The %STR and %NRSTR functions are compilation functions.
execution functions	cause the macro processor to treat as text special characters that result from resolving a macro expression (such as a macro variable reference, a macro invocation, or the argument of an implicit %EVAL function). They are called execution functions because resolution occurs during macro execution or during execution of a macro program statement in open code. The macro processor resolves the expression as far as possible, issues any warning messages for macro variable references or macro invocations it cannot resolve, and quotes the result. The %BQUOTE and %NRBQUOTE functions are execution functions. An implicit %EVAL function is one that is caused by another macro statement, such as a %DO %TO statement. An explicit %EVAL function is one that is directly called by macro code.
function that prevents resolution	causes the macro processor to treat the value of a macro variable as a "picture" during macro execution. It treats the value as text, without beginning the process of resolution. The %SUPERQ function prevents resolution of a macro variable's value. The %SUPERQ function takes as its argument a macro variable name (or a macro expression that yields a macro variable name). The argument must not be a reference to the macro variable whose value you are masking; that is, do not include the & before the name.