Secrets of Macro Quoting Functions – How and Why Susan O'Connor, SAS Institute Inc., Cary, NC ABSTRACT characters to illustrate the position of a macro delta character in macro quoting. How, why, when and where to use macro quoting functions are tricky questions for all I want to briefly define the term compiler and users. Macro quoting is not, as some think, relate it to the SAS System and to the SAS putting single and double quotation marks in or macro facility particularly. around SAS tokens. Macro quoting is actually masking special characters and mnemonic A classic definition of a compiler is a program expressions in the SAS® System so that these that decodes instructions written in pseudo code characters are not confused or ambiguous in their and produces a machine language program to be context during tokenization and execution of executed at a later time. A compiler is a program SAS or SAS macro. SAS macro quoting that translates instructions written in a high level functions also are used to mark starting and programming language into a lower-level ending delimiters. language or set of instructions that can be executed. The terms compile-time and run-time should be understood as related to macro for mastery of There are several parts of the SAS System that macro quoting functions. The differences and can be referred to as a compiler: SCL, the DATA timing of the compile-time macro quoting step, some PROCs and macro. Sometimes, the functions, %STR and %NRSTR, will be term compiler is used in a cavalier manner and, emphasized. The meaning of run-time macro in one sentence, “compiler” can mean DATA quoting functions and the individual implications step compiler or macro compiler. This confusion in your code will be covered and the differences is found in SAS documentation and in SAS between run-time and compile-time macro courses. While there are many compilers in the quoting functions will be illustrated. SAS System, they are all different. The SAS macro compiler will be the focus of this paper Details and history of %QUOTE and because it is in the SAS macro facility that macro %BQUOTE may help users remember the quoting occurs. For the purpose of illustration, I differences in what is masked in each function. will create a simple macro pseudo code to Also, the implementation of macro quoting suggest compiled macro instructions and functions with the NR-prefixes will be detailed. constant text. Macro masking of special characters is achieved A macro definition is the code found between the by using "delta" characters, unprintable ASCII or %MACRO statement and the %MEND EBCDIC characters. Just what these characters statement. In one compilation phase with two are and how to examine them and debug them passes, the SAS macro facility translates all will be covered. Mnemonic expressions are statements inside a SAS macro definition into macro quoted during explicit or implicit compiled instructions or constant text. This is evaluation. referred to as compile-time and is completed with the %MEND statement. Later, when the For debugging purposes, suggestions will be compiled macro is invoked, the macro facility made about when macro quoting is stripped. executes or runs these instructions in another phase, the run-time phase. INTRODUCTION Macro compilation creates instructions and constant text and this is a compile-time phase. In this paper I will use the emoticon J to Macro execution runs or executes the symbolize macro delta characters in macro instructions in a run-time phase. Macro quoting quoting. The use of J is just a symbol of delta functions perform the macro quoting at run-time, except for the compile-time macro quoting in because macro statements end in semicolons functions %STR and %NRSTR. also. If we want to make these tokens including the semicolons into a macro variable value with Finally, the last term to clarify is tokenization. a %LET statement, we would have confusion. Tokenization is the breaking of a character string The %LET statement begins with %LET and into the smallest independent unit, a token that ends with a semicolon. Let's try: has meaning to the programming language. %LET EXAMPLE= PROC PRINT; RUN;; WHY WE QUOTE TOKENS This code would create a macro variable EXAMPLE with a value of PROC PRINT in the One of the main jobs of the SAS supervisor is to macro symbol table, the storage location of split incoming character strings of code into macro variables and their values: tokens. These tokens are classified into SAS token types: words, numbers, integers, EXAMPLE PROC PRINT compound words, missing values, semicolons, special characters, formats and string literals. The first semicolon would be consumed by the There are also subtypes of token types, for %LET when it ends at the first semicolon. The example, double or single quoted strings in string tokens RUN and the other semicolons would be literals. Some examples of token types include: left over tokens that would be sent up to the rest of the SAS System from the word scanner where • String literals - "O'Connor", 'This is easy', they could create a 180 ERROR. '54321'x, '010111010101'b • Word tokens - DATA, WORK, x, EQ, To make this example work as we intended, we _ALL_ , Y2K, MIN need to mask or macro quote the two • Integers -100, 700,000, 0, 123456 semicolons. • Numbers - 123.50, 1.2e23, 0c1x %LET EXAMPLE=%STR( PROC PRINT; • Date, time, and date time constants – '9:25't, RUN;); '01jan2000'd • Special tokens - =, *, !, %, &, /, ;, +, “, ‘ Internally, this would mask the two semicolons in question, while they are inside the macro Basic SAS tokens are then processed by different facility. The macro name would be EXAMPLE parts of SAS with different compilers, different and the value internally would look like: grammars, and parsers. Identical tokens may have different meanings in the macro compiler J PROC PRINTJRUNJJ than in other parts of the SAS System. So the macro symbol table would contain: The reason we may need macro quoting is to avoid confusion and ambiguity with what token EXAMPLE J PROC PRINTJRUNJJ types we intend to use. For example, do we want the token OR to mean an abbreviation for the The J represents macro delta characters. Notice state of Oregon or the mnemonic logical operator that starting and ending delimiters are macro OR? Do we want a semicolon to end a macro quoted as well as the two semicolons. statement or a PROC statement? Is the name O'Connor an unclosed single quoted string or the When the macro variable name was referenced Irish surname? later in the SAS session: One of the simplest examples used to explain &EXAMPLE macro quoting is: the delimiters are removed and the printable PROC PRINT; RUN; special characters replace the unprintable delta characters as each token is sent out of the word This example contains two SAS statements scanner: ending in semicolons. By definition SAS statements end in semicolons. Confusion comes PROC PRINT;RUN; One helpful hint to see the delimiters when and stop, %QUOTE start, %NRQUOTE start, debugging macro quoting is to place an asterisk %BQUOTE start, %NRBQUOTE start, adjacent to the macro variable name in a %PUT %UNQUOTE stop, and stop macro function. We statement. For example, also map the unprintable characters as delta characters to represent special characters that %PUT *&EXAMPLE*; could be ambiguous in the SAS System: will print the following to the SAS log so you DELTA SEMICOLON ; can see the starting and ending delimiter marked DELTA AMPERSAND & by the asterisk: DELTA PERCENT % DELTA SINGLE QUOTATION ' * PROC PRINT;RUN;* DELTA DOUBLE QUOTATION " DELTA OPEN PARENTHESIS ( DELTA CLOSE PARENTHESIS ) HOW IS MACRO QUOTING DONE? DELTA PLUS + DELTA MINUS - Inside the macro facility we have a set of tables DELTA STAR * that allow the macro subsystem to translate DELTA SLASH / special characters into delta characters and to DELTA LESS THAN < translate delta characters into special characters. DELTA GREATER THAN > Changing a special character to a delta character DELTA NOT ^ is macro quoting. Changing a delta character DELTA EQUAL = back to its original character is unquoting. DELTA OR | DELTA COMMA , The characters to be masked with delta DELTA TILDE ~ characters may be either special characters, such as ampersand, percent, and semicolon, or delimiters surrounding a series of tokens, telling For example, to represent a DELTA the macro processor to do something special SEMICOLON we map the unprintable ASCII with the delimited tokens. decimal character 14 (hex 0E) as a DELTA SEMICOLON and we map the unprintable Characters used in SAS come from ASCII or EBCDIC decimal character 38 (hex 26) as a EBCDIC code tables with decimal (and DELTA SEMICOLON. corresponding hex) values. For example, the upper case A in ASCII is represented with the On most operating systems these unprintable decimal value 65 (hex 41) and in EBCDIC is characters if reflected on the monitor will look represented with the decimal value 193 (hex C1). like garbage characters. Sometimes, machine In ASCII the semicolon is represented with the specific items, such as the glyphs for an OEM or decimal value 59 (hex 3B) and in EBCDIC the how the monitor itself is set, may define semicolon is represented with the decimal value unprintable special characters as unexpected 94 (hex 5E). These are printable characters in the surprises, for example, a happy face. Regardless, code tables, but there are unprintable characters how these "unprintable" characters are reflected too. on your term monitor should not be a concern. Internally the macro processor knows that these The delta characters are unprintable characters unprintable delta characters are masking special available for use in ASCII or EBCDIC character characters.