Date: Fri, 5 Aug 1994 09:54:33 EDT
Reply-To: Clarence Jackson <73021.3404@COMPUSERVE.COM>
Sender: "SAS(r) Discussion"
From: Clarence Jackson <73021.3404@COMPUSERVE.COM>
Subject: Macro Tutorial (long)
To: Multiple recipients of list SAS-L
Hi SAS-Lers,
In responce to many on Macros, something that I put together awhile back for
our In-house users. It's long, but I hope it can be used by someone out
there...
Clarence Jackson, City of Dallas, Texas
73021.3404@compuserve.com or cj@zgnews.lonestar.org
----
MACRO PAPER OUTLINE
I. Introduction
A. What is the Macro Facility
II. SAS and Macro Facility Processes
A. SAS Program Data Vector - PDV
B. SAS code without Macro statements
C. SAS code with Macro statements
III. Macro Facility Overview
A. Components of Macro Facility
1. Macro Processor
2. Macro Language
B. Macro Language Components
1. Variables
2. Statements
3. Functions
4. Expressions and Text
C. Macro Definitions and Referencing
D. Referencing Environments
E. Programming Statements
F. Functions
G. Auto Call Facility
H. System Options
IV. Quick Rules
CITY OF DALLAS MAINFRAME USERS FORUM
MACRO FACILITY HANDOUT
MAY 12, 1988
INTRO:
The purpose of this handout is to briefly describe the Macro Facility
in BASE SAS.
The information presented in this handout is based on information found in
SAS BASICS users guide and the SAS Macro Facility Guide.
The Macro Facility was introduced with the 82 Release of BASE SAS.
II. Process
To understand how SAS uses Macro's, we must look at how SAS processes any
statement or job. When we execute jobs in SAS, all SAS statements are read
into the input stack, and passed thru the SAS supervisor one token at a time.
Tokens are strings separated by blanks or operators. The SAS supervisor reads
tokens until it receives a semi-colon, which completes a SAS statement. Once
the supervisor reads a complete statement, it checks it for syntax, and passes
the statement to the wordscanner section of the supervisor. Here, the tokens
are examined for their value, ie if the token is a SAS reserve word, user name
and type, and passes the tokens on to the compiler. This process continues
until a step boundary word is read. Step boundary keywords are DATA, PROC, RUN,
ENDSAS, CARDS (and it's other formats). Then the SAS compiler compiles the code
and executes statements for that step. In oher words, only one step is
compliled and executed independently.
Macro compilation and execution are separate processes from Data or PROC
compilation and execution. Understanding the difference will help you to
understand Macro expression evaluation and how to make SAS work better for
you.
III. Macro Facility Overview:
Now, why do we use Macros? Using the Macro Facility allows you to do very
interesting things with SAS that is not possible without it. For use in
batch mode processing, SAS Macro Facility allows us to :
. Retrieve system information from the SAS Supervisor
. Perform conditional execution of SAS Data and Proc Step
. Generate data-dependent SAS statements (SAS Code)
. Communication information between SAS steps
. Generate repetitive SAS code
The Macro Facility is a tool for extending and customizing the SAS system and
for reducing the amount of text you must enter to do common tasks. The
Facility allows you to package small or large amounts of text into units
or modules that have names. From that point on, you can work with the names
rather than the text itself.
When you use a Macro Facility name in a SAS program, the Macro Facility
generates SAS statements and commands as needed. The rest of the SAS system
uses those statements and commands just like the ones you enter.
A. Components of Macro Facility
There are two components in the Macro Facility:
- The Macro processor is the portion of SAS that does the work.
- The Macro language is the language used to communicate with the Macro
processor
The Macro language has variables, program statements, expressions, and
functions - the same pieces that make up the SAS DATA step language. However,
the Macro language uses the patterns %name and &name to trigger Macro processing
activities.
B. Macro Language Components
The components of the Macro Language are:
Macro Variables
Macro Statements
Macro Functions
Macro expressions & Constant Text
Marco variables (or symbolic variables) are different from DATA step variables
and can be defined anywhere in a SAS job, except after a CARDS, CARDS4,
PARMCARDS, or PARMCARDS4 statement. Whereas a Data step variable is assigned
within that step, and must be carried within a SAS datafile past the step, a
Macro variables' value remains constant until changed or the end of the SAS
session.
C. Macro Definitions and Referencing
The simplest way to define and assign a value to a macro variable is to
use %LET statement, as in:
%LET DSN=NEWDATA;
DSN is the name of the Macro variable, and NEWDATE is its value. To reference
the value of a Macro variable, place an "&" in front of its name, as in &DSN.
The pattern &DSN is called a "Macro variable reference". After creation of the
Macro variable, the reference is resolved by the Macro processor using the
&DSN. Changing the Macro is as easy as another "%LET"
definition of the variable name. Using the %LET statement, you can create
variables values that contain entire sections of a SAS program:
%LET PLOT=%STR(PROC PLOT; PLOT INCOME + AGE;);
In this case, the value of the macro variable is enclosed in the %STR Macro
function so that the semicolons within the value are part of the TEXT, not
end of the %LET statement.
%MACRO statements defines stored text by name. The simplest type of Macro works
much like a Macro varible, but more complex code can be included.
%Macros can do many things that Macro variables cannot.
To define a %MACRO, a simple example is:
%MACRO DSN; NEWDATA %MEND DSN;
The "%MACRO" statement must begin every Macro and must contain a name for the
Macro (DSN), text (NEWDATA) and end with the %MEND statement. To invoke
a Macro, place a "%" in front of its name, as in "%DSN". The pattern
"%MACRO-NAME" is called a "Macro invocation" or a "Macro Call". After
definition of the Macro, the call is resolved by the Macro processor by
replacing the Macro name with the text from the Macro.
As with the %LET statement, you can create Macros that contain entire sections
of SAS program:
%MACRO PLOT; PROC PLOT; PLOT INCOME * AGE; %MEND PLOT;
Suppose that the plotting variables in the PROC PLOT step can change. Rewrite
the names of the PLOT variables with Macro variable references, and supply
values in %LET statements before the Macro is called:
%MACRO PLOT; PROC PLOT; PLOT &YVAR * &XVAR; %MEND PLOT;
%LET XVAR = INCOME;
%LET YVAR=AGE;
%PLOT
%LET XVAR = SAVINGS;
%PLOT
In many cases, it becomes inconvenient to keep redefining variables using Macro
%LET statements, so define the Macro variables as part of the %MACRO statement.
This can be done using either positional or keyword parameters. The following
illustrates both styles:
positional parameters -
definition - %MACRO PLOT(XVAR,XVAR);
PROC PLOT; PLOT &YVAR * &XVAR;
%MEND PLOT;
call - %PLOT(INCOME,AGE)
keyword parameters -
definition - %MACRO PLOT(YVAR=,XVAR=);
PROC PLOT; PLOT &YVAR &VAR;
%MEND PLOT;
call - %PLOT(YVAR=INCOME,XVAR=AGE)
I prefer using keyword paramaters because variables defined can be assigned
default values such as:
%MACRO PLOT(YVAR=INCOME,XVAR=AGE);
PROC PLOT&YVAR*&XVAR;
%MEND PLOT
%PLOT(XVAR=SAVINGS)
%PLOT
(Two calls are issued here. The first will produce a plot for income by
The second call will use the default value of &XVAR, 'age'.)
Macro variables can also be created during data step execution based on
within the DATA step by using the "SYMPUT" routine, and passed to the Macro
Facility to be used in other steps. By the same token, values in the Macro
Facility can be passed to the data step by using the "SYMGET" routine.
D. REFERENCING ENVIRONMENT:
When the System Option MACRO is in effect, SAS programs have one or more
referencing environments: a referencing environment is the area in which
variable is available for use. Referencing environments are important because
they determine whether the MACRO processor can locate a Macro variable that is
referenced. The two types of Referencing Environments are "GLOBAL" and "LOCAL".
The Global environment is the entire SAS job, while local environments are
within Macros. The Macro processor uses referencing environments according to
the following rules:
1) When executing Macro program statements that can create Macro variables,
the Macro processor attempts to change the value of an existing Macro variable
regardless of environment, rather than creating a new Macro variable.
2) When executing Macro program statements that can create Macro variables, and
no Macro variable of the name requested exists, the Macro processor creates a
variable in the current environment.
3) The %GLOBAL statement causes the Macro processor to create a variable in the
global environment, regardless of the current environment.
4) %LOCAL statement and Macro paramater creates Macro variable in the current
local environment even if a variable of that name exists in another environment.
E. Programming Statements
Program statements for the Macro Language can be described as "open code" and
"closed code" statements. Open code statements can be used outside any
definition as well as inside. Closed code can only be used inside a Macro
definition. All previously discussed Macro statements are open code statements.
Others include %CMS, %INPUT, %PUT, %TSO, and all Macro functions and routines.
Examples of closed code, or Inside-Macros-Only statements are %*Comment;
%WHILE, %END, %GOTO, %IF-%THEN/%ELSE, and %LABEL: All of these statements are
the same as SAS Data Step statements except that these statements program the
Macro Processor.
Using these statements allows for:
1) Conditional execution of Macro statements and the generation of SAS code
2) Branching within a Macro
3) Supplies values for Macro variables during Macro execution and
4) Creation of Macro variables and assigning values.
F. Functions
Macro Functions process one or more Macro expressions, called arguments,
produce a new character string, the result or returned value. They can be
either inside or outside a Macro. There are three categories: Character,
Evaluation, and quoting functions.
Macro character functions either change or provide information about the
character string that is their argument. Most Macro character functions have
names that correspond to DATA step character functions, and are similar
in the way each works, except that Macro functions executes while SAS is
constructing a DATA or PROC step. The DATA step function executes when the
DATA STEP executes, and is treated as constant text by the Macro Processor, and
unlike DATA step functions, Macro character functions may be paried with a "Q"
for returning quoted results.
The evaluation function is %EVAL. Because the Macro Processor is a charactor
(string) handling facility, "numbers" in Macro expressions are treated as
charactor strings. The %EVAL function assigns numeric properties to intergers
in expressions and performs calculations using integer arithmetic. The %EVAL
function also evaluates logical experssions such as &A=&B.
The quoting functions inthe Macro language perform the activity equivalant to
enclosing a portion of a SAS statement in single or double quotes. That
the Macro Facility treates the expression with the function as a unit and
not perform any evaluations on the expression. Quoting functions are
used to cause the Macro Processor to treat special characters as text. Quoting
functions are necessary because the Macro processor treats single quote (') and
double quotes (") as text.
G. AutoCall Facility
The Macro Facility AUTOCALL feature allows you to store the source statements
for Macros in a file, associate the file with a SAS job or session, and call or
include the Macros as needed. The Macro definition does not have to be part of
the current program. By specifing the MAUTOSOURCE system options and
associating the file reference (DD) SASAUTOS with a library of Marcos, the
AUTOCALL facility will automatically define and execute a Macro when it is
called into a SAS job. This facility is especially useful for defining your own
Macro functions, which you can store in an AUTOCALL library. SAS provides some
special Macros in the SAS AUTOCALL library supplies with Base SAS.
H. System Options
Normally, Macro statements don't appear on the log when executed. This ia a
problem when complex code is involved and the Macro is not working properly.
Error codes for Macros are between 1000 and 4000 indicating that problem
occurred in the Macro Facility. System options such as IMPRINT, MLOGIC,
SYMBOLGEN and MACROGEN are available and can be used either separately or in
combination. The options display information on the SAS log giving detail
about the compiliation or execution of a Macro. The types of messages that is
displayed in the log depends on the option chosen.
IV. Quick Rules
There are several sets of rules in use depending on the way the Macro Facility
and SAS is used. In the batch environment, these rules for new Macro writers
should be:
1. Define all Macros before use, preferably at the beginning of the SAS
or AUTOCALLed.
2. Know your referencing environment, global, local, and current
3. Use systems options in debugging Macros
4. Use keyword parameters with Macro variable defaults
5. Document Macros with %* comments;
If you have any questions, please contact Clarence Jackson, 214-670-5798
(670-3220 after 8/1/94)
Statistics
Back