Chapter 4

Macro Processing

Macro Processing

This section describes macro processing and shows the typical pattern that SAS follows to process a program containing macro elements. For most macro programming, you do not need this level of detail. It is provided to help you understand what is going on behind the scenes.

Defining and Calling Macros

Macros are compiled programs that you can call in a submitted SAS program or from a SAS command prompt. Like macro variables, you generally use macros to generate text. However, macros provide additional capabilities:

• Macros can contain programming statements that enable you to control how and when text is generated.

• Macros can accept parameters. You can write generic macros that can serve a number of uses.

To compile a macro, you must submit a macro definition. The following is the general form of a macro definition:

%MACRO macro_name;

<macro_text>

%MEND <macro_name>;

macro_name is a unique SAS name that identifies the macro and macro_text is any combination of macro statements, macro calls, text expressions, or constant text.

When you submit a macro definition, the macro processor compiles the definition and produces a member in the session catalog. The member consists of compiled macro program statements and text. The distinction between compiled items and noncompiled (text) items is important for macro execution. Examples of text items include:

• macro variable references

• nested macro calls

• macro functions, except %STR and %NRSTR

• arithmetic and logical macro expressions

• text to be written by %PUT statements

• field definitions in %WINDOW statements

• model text for SAS statements and SAS windowing environment commands

When you want to call the macro, you use the form

%macro_name.

Note: If your macro_text contains passwords that you want to prevent from being revealed in the SAS log, redirect the SAS log to a file. For more information, see Chapter 43, “PRINTTO Procedure” in Base SAS Procedures Guide.

How the Macro Processor Compiles a Macro Definition

When you submit a SAS program, the contents of the program goes to an area of memory called the input stack. The example program in the following figure contains a macro definition, a macro call, and a PROC PRINT step. This section illustrates how the macro definition in the example program is compiled and stored.

Figure 4.1 The Macro APP

Using the same process described in “SAS Programs and Macro Processing” on page 13 the word scanner begins tokenizing the program. When the word scanner detects % followed by a nonblank character in the first token, it triggers the macro processor. The macro processor examines the token and recognizes the beginning of a macro definition.

The macro processor pulls tokens from the input stack and compiles until the %MEND statement terminates the macro definition (Figure 4.2 on page 39).

During macro compilation, the macro processor does the following:

• creates an entry in the session catalog

• compiles and stores all macro program statements for that macro as macro instructions

• stores all noncompiled items in the macro as text

Note: Text items are underlined in the illustrations in this section.

If the macro processor detects a syntax error while compiling the macro, it checks the syntax in the rest of the macro and issues messages for any additional errors that it finds. However, the macro processor does not store the macro for execution. A macro that the macro processor compiles but does not store is called a dummy macro.

Figure 4.2 Macro APP in the Input Stack

In this example, the macro definition is compiled and stored successfully. (See the following figure.) For the sake of illustration, the compiled APP macro looks like the original macro definition that was in the input stack. The entry would actually contain compiled macro instructions with constant text. The constant text in this example is underlined.

Figure 4.3 The Compiled Macro APP

How the Macro Processor Executes a Compiled Macro

Macro execution begins with the macro processor opening the SASMacr catalog to read the appropriate macro entry. As the macro processor executes the compiled instructions in the macro entry, it performs a series of simple repetitive actions. During macro execution, the macro processor does the following:

• executes compiled macro program instructions

• places noncompiled constant text on the input stack

• waits for the word scanner to process the generated text

• resumes executing compiled macro program instructions

To continue the example from the previous section, the following figure shows the lines remaining in the input stack after the macro processor compiles the macro definition APP.

Figure 4.4 The Macro Call in the Input Stack

The word scanner examines the input stack and detects % followed by a nonblank character in the first token. It triggers the macro processor to examine the token.

Figure 4.5 Macro Call Entering Word Queue

The macro processor recognizes a macro call and begins to execute macro APP, as follows:

1. The macro processor creates a local symbol table for the macro. The macro processor examines the previously compiled definition of the macro. If there are any parameters, variable declarations, or computed GOTO statements in the macro definition, the macro processor adds entries for the parameters and variables to the newly created local symbol table.

2. The macro processor further examines the previously compiled macro definition for parameters to the macro. If no parameters were defined in the macro definition, the macro processor begins to execute the compiled instructions of the macro. If any parameters were contained in the definition, the macro processor removes tokens from the input stack to obtain values for positional parameters and non-default values for keyword parameters. The values for parameters found in the input stack are placed in the appropriate entry in the local symbol table.

   Note: Before executing any compiled instructions, the macro processor removes only enough tokens from the input stack to ensure that any tokens that are supplied by the user and pertain to the macro call have been removed.

3. The macro processor encounters the compiled %IF instruction and recognizes that the next item will be text containing a condition.

4. The macro processor places the text &sysday=Friday on the input stack ahead of the remaining text in the program. (See the following figure). The macro processor waits for the word scanner to tokenize the generated text.

Figure 4.6 Text for %IF Condition on Input Stack

1. The word scanner starts tokenizing the generated text, recognizes an ampersand followed by nonblank character in the first token, and triggers the macro processor.

2. The macro processor examines the token and finds a possible macro variable reference, &SYSDAY. The macro processor first searches the local APP symbol table for a matching entry and then the global symbol table. When the macro processor finds the entry in the global symbol table, it replaces macro variable in the input stack with the value Friday. (See the following figure.)

3. The macro processor stops and waits for the word scanner to tokenize the generated text.

Figure 4.7 Input Stack After Macro Variable Reference Is Resolved

1. The word scanner then read Friday=Friday from the input stack.

2. The macro processor evaluates the expression Friday=Friday and, because the expression is true, proceeds to the %THEN and %DO instructions.

Figure 4.8 Macro Processor Receives the Condition

1. The macro processor executes the compiled %DO instructions and recognizes that the next item is text.

2. The macro processor places the text on top of the input stack and waits for the word scanner to begin tokenization.

3. The word scanner reads the generated text from the input stack, and tokenizes it.

4. The word scanner recognizes the beginning of a DATA step, and triggers the compiler to begin accepting tokens. The word scanner transfers tokens to the compiler from the top of the stack.

Figure 4.9 Generated Text on Top of Input Stack

1. When the word scanner detects & followed by a nonblank character (the macro variable reference &GOAL), it triggers the macro processor.

2. The macro processor looks in the local APP symbol table and resolves the macro variable reference &GOAL to 10000. The macro processor places the value on top of the input stack, ahead of the remaining text in the program.

Figure 4.10 The Word Scanner Reads Generated Text

1. The word scanner resumes tokenization. When it has completed tokenizing the generated text, it triggers the macro processor.

2. The macro processor resumes processing the compiled macro instructions. It recognizes the end of the %DO group at the %END instruction and proceeds to %MEND.

3. the macro processor executes the %MEND instruction, removes the local symbol table APP, and macro APP ceases execution.

4. The macro processor triggers the word scanner to resume tokenization.

5. The word scanner reads the first token in the input stack (PROC), recognizes the beginning of a step boundary, and triggers the DATA step compiler.

6. The compiled DATA step is executed, and the DATA step compiler is cleared.

7. The word scanner signals the PRINT procedure (a separate executable not illustrated), which pulls the remaining tokens.

Figure 4.11 The Remaining Statements Are Compiled and Executed

Summary of Macro Processing

The previous sections illustrate the relationship between macro compilation and execution and DATA step compilation and execution. The relationship contains a pattern of simple repetitive actions. These actions begin when text is submitted to the input stack and the word scanner begins tokenization. At times the word scanner waits for the macro processor to perform an activity, such as searching the symbol tables or compiling a macro definition. If the macro processor generates text during its activity, then it pauses while the word scanner tokenizes the text and sends the tokens to the appropriate target. These tokens might trigger other actions in parts of SAS, such as the DATA step compiler, the command processor, or a SAS procedure. If any of these actions occur, the macro processor waits for these actions to be completed before resuming its activity. When the macro processor stops, the word scanner resumes tokenization. This process continues until the entire program has been processed.