SAS Macro Language: Reference

Using the %STR and %NRSTR Functions

If a special character or mnemonic affects the way the macro processor constructs macro program statements, you must mask the item during macro compilation (or during the compilation of a macro program statement in open code) by using either the %STR or %NRSTR macro quoting functions.

These macro quoting functions mask the following special characters and mnemonics:

blank

;

¬

^

~

, (comma)

'

"

In addition to these, %NRSTR masks & and %.

Note: If an unmatched single or double quotation mark or a left or right parenthesis is used with %STR or %NRSTR, these characters must be preceded by a percent sign (%). See "Using Unmatched Quotation Marks and Parentheses with %STR and %NRSTR" later in this chapter for more information. [cautionend]

When you use %STR or %NRSTR, the macro processor does not receive these functions and their arguments when it executes a macro. It receives only the results of these functions because these functions work when a macro compiles. This means by the time the macro executes, the string is already masked by a macro quoting function. Therefore, %STR and %NRSTR are useful for masking strings that are constants, such as sections of SAS code. In particular, %NRSTR is a good choice for masking strings that contain % and & signs. However, these functions are not so useful for masking strings that contain references to macro variables because it is possible that the macro variable could resolve to a value not quotable by %STR or %NRSTR. For example, the string could contain an unmarked, unmatched left parenthesis.

Using Unmatched Quotation Marks and Parentheses with %STR and %NRSTR

If the argument to %STR or %NRSTR contains an unmatched single or double quotation mark or an unmatched left or right parenthesis, precede each of these characters with a % sign. Examples of Marking Unmatched Quotation Marks and Parenthese with %STR and %NRSTR shows some examples of this technique.

Examples of Marking Unmatched Quotation Marks and Parenthese with %STR and %NRSTR
Notation Description Example Quoted Value Stored

%' unmatched single quotation mark %let myvar=%str(a%'); a'

%" unmatched double quotation mark %let myvar=%str(title %"first);
title "first

%( unmatched left parenthesis %let myvar=%str (log%(12);
log(12

%) unmatched right parenthesis %let myvar=%str (345%));
345)

***Examples of Marking Unmatched Quotation Marks and Parenthese with %STR and %NRSTR***
Notation	Description	Example	Quoted Value Stored
%'	unmatched single quotation mark	`%let myvar=%str(a%');`	`a'`
%"	unmatched double quotation mark	`%let myvar=%str(title %"first);`	`title "first`
%(	unmatched left parenthesis	`%let myvar=%str (log%(12);`	`log(12`
%)	unmatched right parenthesis	`%let myvar=%str (345%));`	`345)`

Using % Signs with %STR

In general, if you want to mask a % sign with a macro quoting function at compilation, use %NRSTR. There is one case where you can use %STR to mask a % sign: when the % sign does not have any text following it that could be construed by the macro processor as a macro name. The % sign must be marked by another % sign. Here are some examples.

Examples of Masking % Signs with %STR
Notation Description Example Quoted Value Stored

'%' % sign before a matched single quotation mark %let myvar=%str('%'); '%'

%%%' % sign before an unmatched single quotation mark %let myvar=%str(%%%'); %'

""%% % sign after a matched double quotation mark %let myvar=%str(""%%);
""%

%%%% two % signs in a row %let myvar=%str(%%%%);
%%

***Examples of Masking % Signs with %STR***
Notation	Description	Example	Quoted Value Stored
'%'	% sign before a matched single quotation mark	`%let myvar=%str('%');`	'%'
%%%'	% sign before an unmatched single quotation mark	`%let myvar=%str(%%%');`	`%'`
""%%	% sign after a matched double quotation mark	`%let myvar=%str(""%%);`	`""%`
%%%%	two % signs in a row	`%let myvar=%str(%%%%);`	`%%`

Examples Using %STR

The %STR function in the following %LET statement prevents the semicolon after PROC PRINT from being interpreted as the ending semicolon for the %LET statement:

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

As a more complex example, the macro KEEPIT1 shows how the %STR function works in a macro definition:

%macro keepit1(size);
   %if &size=big %then %str(keep city _numeric_;);
   %else %str(keep city;);
%mend keepit1;

Call the macro as follows:

%keepit1(big)

This produces the following statement:

keep city _numeric_;

When you use the %STR function in the %IF-%THEN statement, the macro processor interprets the first semicolon after the word %THEN as text. The second semicolon ends the %THEN statement, and the %ELSE statement immediately follows the %THEN statement. Thus, the macro processor compiles the statements as you intended. However, if you omit the %STR function, the macro processor interprets the first semicolon after the word %THEN as the end of the %THEN clause and the next semicolon as constant text. Because constant text cannot appear between a %THEN and a %ELSE clause, the macro processor does not compile the macro. Instead, it issues an error message.

In the %ELSE statement, the %STR function causes the macro processor to treat the first semicolon in the statement as text and the second one as the end of the %ELSE clause. Therefore, the semicolon that ends the KEEP statement is part of the conditional execution. If you omit the %STR function, the first semicolon ends the %ELSE clause and the second semicolon is outside the conditional execution. It is generated as text each time the macro executes. (In this example, the placement of the semicolon does not affect the SAS code.) Again, using %STR causes the macro KEEPIT1 to compile as you intended.

Here is an example that uses %STR to mask a string that contains an unmatched single quotation mark. Note the use of the % sign before the quotation mark:

%let innocent=%str(I didn%'t do it!);

Examples Using %NRSTR

Suppose you want the name (not the value) of a macro variable to be printed by the %PUT statement. To do so, you must use the %NRSTR function to mask the & and prevent the resolution of the macro variable, as in the following example:

%macro example;
   %local myvar;
   %let myvar=abc;
   %put %nrstr(The string &myvar appears in log output,);
   %put instead of the variable value.;
%mend example;

%example

This code writes the following text to the SAS log:

The string &myvar appears in log output,
instead of the variable value.

If you did not use the %NRSTR function or if you used %STR, the following undesired output would appear in the SAS log:

The string abc appears in log output,
instead of the variable value.

The %NRSTR function prevents the & from triggering macro variable resolution.

The %NRSTR function is also useful when the macro definition contains patterns that the macro processor would ordinarily recognize as macro variable references, as in the following program:

%macro credits(d=%nrstr(Mary&Stacy&Joan Ltd.));
   footnote "Designed by &d";
%mend credits;

Using %NRSTR causes the macro processor to treat &STACY and &JOAN simply as part of the text in the value of D; the macro processor does not issue warning messages for unresolvable macro variable references. Suppose you invoke the macro CREDITS with the default value of D, as follows:

%credits()

Submitting this program generates the following FOOTNOTE statement:

footnote "Designed by Mary&Stacy&Joan Ltd.";

If you omit the %NRSTR function, the macro processor attempts to resolve the references &STACY and &JOAN as part of the resolution of &D in the FOOTNOTE statement. The macro processor issues these warning messages (assuming the SERROR system option, described in Chapter 13, is active) because no such macro variables exist:

WARNING: Apparent symbolic reference STACY not resolved.
WARNING: Apparent symbolic reference JOAN not resolved.

Here is a final example of using %NRSTR. Suppose you wanted to have a text string include the name of a macro function: This is the result of %NRSTR. Here is the program:

%put This is the result of %nrstr(%nrstr);

You must use %NRSTR to mask the % sign at compilation, so the macro processor does not try to invoke %NRSTR a second time. If you did not use %NRSTR to mask the string %nrstr, the macro processor would complain about a missing open parenthesis for the function.

Chapter Contents
Previous
Next
Top of Page