%MACRO Statement

Begins a macro definition.

Type:	Macro statement
Restriction:	Allowed in macro definitions or open code
See:	%MEND Statement and SYSPBUFF Automatic Macro Variable

Syntax

Details

Examples

Example 1: Using the %MACRO Statement with Positional Parameters

Example 2: Using the %MACRO Statement with Keyword Parameters

Example 3: Using the %MACRO Statement with the PARMBUFF Option

Example 4: Using the %MACRO Statement with the SOURCE Option

Example 5: Using the %MACRO Statement with the STORE and SECURE Options

Syntax

%MACRO macro-name <(parameter-list)> </ option-1 <...option-n>> ;

Required Arguments

macro-name: names the macro. A macro name must be a SAS name, which you supply; you cannot use a text expression to generate a macro name in a %MACRO statement. In addition, do not use macro reserved words as a macro name. (For a list of macro reserved words, see Reserved Words in the Macro Facility.)

parameter-list

names one or more local macro variables whose values you specify when you invoke the macro. Parameters are local to the macro that defines them. You must supply each parameter name; you cannot use a text expression to generate it. A parameter list can contain any number of macro parameters separated by commas. The macro variables in the parameter list are usually referenced in the macro.

parameter-list can be

<positional parameter-1><. . . ,positional parameter-n>
<keyword-parameter=<value> <. . . ,keyword-parameter-n=<value>>>

positional-parameter-1 <. . . ,positional-parameter-n>

specifies one or more positional parameters. You can specify positional parameters in any order, but in the macro invocation, the order in which you specify the values must match the order that you list them in the %MACRO statement. If you define more than one positional parameter, use a comma to separate the parameters. If at invocation that you do not supply a value for a positional parameter, the macro facility assigns a null value to that parameter.

keyword-parameter=<value> <. . . ,keyword-parameter-n=<value>>

names one or more macro parameters followed by equal signs. You can specify default values after the equal signs. If you omit a default value after an equal sign, the keyword parameter has a null value. Using default values enables you to write more flexible macro definitions and reduces the number of parameters that must be specified to invoke the macro. To override the default value, specify the macro variable name followed by an equal sign and the new value in the macro invocation.

Note: You can define an unlimited number of parameters. If both positional and keyword parameters appear in a macro definition, positional parameters must come first.

option-1 <...option-n>

can be one or more of these optional arguments:

CMD: specifies that the macro can accept either a name-style invocation or a command-style invocation. Macros defined with the CMD option are sometimes called command-style macros.

Use the CMD option only for macros that you plan to execute from the command line of a SAS window. The SAS system option CMDMAC must be in effect to use command-style invocations. If CMDMAC is in effect and you have defined a command-style macro in your program, the macro processor scans the first word of every SAS command to see whether it is a command-style macro invocation. When the SAS system option NOCMDMAC option is in effect, the macro processor treats only the words following the % symbols as potential macro invocations. If the CMDMAC option is not in effect, you still can use a name-style invocation for a macro defined with the CMD option.

DES='text': specifies a description for the macro entry in the macro catalog. The description text can be up to 256 characters in length. Enclose the description in quotation marks. This description appears in the CATALOG window when you display the contents of the catalog containing the stored compiled macros. The DES= option is especially useful when you use the stored compiled macro facility.

MINDELIMITER='single character';: specifies a value that will override the value of the MINDELIMITER= global option. The value must be a single character enclosed in single quotation marks and can appear only once in a %MACRO statement.

MINOPERATOR | NOMINOPERATOR: specifies that the macro processor recognizes and evaluates the mnemonic IN and the special character # as logical operators when evaluating arithmetic or logical expressions during the execution of the macro. The setting of this argument overrides the setting of the NOMINOPERATOR global system option.

The NOMINOPERATOR argument specifies that the macro processor does not recognize the mnemonic IN and the special character # as logical operators when evaluating arithmetic or logical expressions during the execution of the macro. The setting of this argument overrides the setting of the MINOPERATOR global system option.

PARMBUFF: assigns the entire list of parameter values in a macro call, including the parentheses in a name-style invocation, as the value of the automatic macro variable SYSPBUFF. Using the PARMBUFF option, you can define a macro that accepts a varying number of parameter values.

If the macro definition includes both a set of parameters and the PARMBUFF option, the macro invocation causes the parameters to receive values. It also causes the entire invocation list of values to be assigned to SYSPBUFF.

To invoke a macro defined with the PARMBUFF option in a windowing environment or interactive line mode session without supplying a value list, enter an empty set of parentheses or more program statements after the invocation. This action indicates the absence of a value list, even if the macro definition contains no parameters.

SECURE | NOSECURE: causes the contents of a macro to be encrypted when stored in a stored compiled macro library. This feature enables you to write secure macros that will protect intellectual property that is contained in the macros. The macros are secured using the Encryption Algorithm Manager.

A NOSECURE option has been implemented to aid in the global edit of a source file or library to turn on security. For example, when you are creating several macros that will need to be secure. When creating the macros, use the NOSECURE option. When all macros are completed and ready for production, you can do a global edit and change NOSECURE to SECURE.

If you use the SECURE and SOURCE options on a macro, no output is produced when you use the %COPY statement. The following NOTE is written to the SAS log:

NOTE: The macro %name was compiled with the SECURE option. No output will be produced for this %COPY statement.

STMT: specifies that the macro can accept either a name-style invocation or a statement-style invocation. Macros defined with the STMT option are sometimes called statement-style macros.

The IMPLMAC system option must be in effect to use statement-style macro invocations. If IMPLMAC is in effect and you have defined a statement-style macro in your program, the macro processor scans the first word of every SAS statement to see whether it is a statement-style macro invocation. When the NOIMPLMAC option is in effect, the macro processor treats only the words following the % symbols as potential macro invocations. If the IMPLMAC option is not in effect, you still can use a name-style invocation for a macro defined with the STMT option.

SOURCE SRC: combines and stores the source of the compiled macro with the compiled macro code as an entry in a SAS catalog in a permanent SAS library. The SOURCE option requires that the STORE option and the MSTORED option be set. You can use the SASMSTORE= option to identify a permanent SAS library. You can store a macro or call a stored compiled macro only when the MSTORED option is in effect. (For more information, see Storing and Reusing Macros.)

Note: The source code saved by the SOURCE option begins with the %MACRO keyword and ends with the semi-colon following the %MEND statement.

CAUTION:

The SOURCE option cannot be used on nested macro definitions (macro definitions contained within another macro).

STORE: stores the compiled macro as an entry in a SAS catalog in a permanent SAS library. Use the SAS system option SASMSTORE= to identify a permanent SAS library. You can store a macro or call a stored compiled macro only when the SAS system option MSTORED is in effect. (For more information, see Storing and Reusing Macros.)

Details

The %MACRO statement begins the definition of a macro, assigns the macro a name, and can include a list of macro parameters, a list of options, or both.

A macro definition must precede the invocation of that macro in your code. The %MACRO statement can appear anywhere in a SAS program, except within data lines. A macro definition cannot contain a CARDS statement, a DATALINES statement, a PARMCARDS statement, or data lines. Use an INFILE statement instead.

By default, a defined macro is an entry in a SAS catalog in the WORK library. You can also store a macro in a permanent SAS catalog for future use. However, in SAS 6 and earlier, SAS does not support copying, renaming, or transporting macros.

You can nest macro definitions, but doing so is rarely necessary and is often inefficient. If you nest a macro definition, then it is compiled every time you invoke the macro that includes it. Instead, nesting a macro invocation inside another macro definition is sufficient in most cases.

Examples

Example 1: Using the %MACRO Statement with Positional Parameters

In this example, the macro PRNT generates a PROC PRINT step. The parameter in the first position is VAR, which represents the SAS variables that appear in the VAR statement. The parameter in the second position is SUM, which represents the SAS variables that appear in the SUM statement.

%macro prnt(var,sum);
   proc print data=srhigh;
      var &var;
      sum &sum;
   run;
%mend prnt;

In the macro invocation, all text up to the comma is the value of parameter VAR; text following the comma is the value of parameter SUM.

%prnt(school district enrollmt, enrollmt)

During execution, macro PRNT generates the following statements:

PROC PRINT DATA=SRHIGH;
   VAR SCHOOL DISTRICT ENROLLMT;
   SUM ENROLLMT;
RUN;

Example 2: Using the %MACRO Statement with Keyword Parameters

In the macro FINANCE, the %MACRO statement defines two keyword parameters, YVAR and XVAR, and uses the PLOT procedure to plot their values. Because the keyword parameters are usually EXPENSES and DIVISION, default values for YVAR and XVAR are supplied in the %MACRO statement.

%macro finance(yvar=expenses,xvar=division);
   proc plot data=yearend;
      plot &yvar*&xvar;
   run;
%mend finance;

To use the default values, invoke the macro with no parameters.
```
%finance()
```
or
```
%finance;
```
The macro processor generates this SAS code:
```
PROC PLOT DATA=YEAREND;
   PLOT EXPENSES*DIVISION;
RUN;
```
To assign a new value, give the name of the parameter, an equal sign, and the value:
```
%finance(xvar=year)
```
Because the value of YVAR did not change, it retains its default value. Macro execution produces this code:
```
PROC PLOT DATA=YEAREND;
   PLOT EXPENSES*YEAR;
RUN;
```

Example 3: Using the %MACRO Statement with the PARMBUFF Option

The macro PRINTZ uses the PARMBUFF option to enable you to input a different number of arguments each time you invoke it:

%macro printz/parmbuff;
   %let num=1;
   %let dsname=%scan(&syspbuff,&num);
   %do %while(&dsname ne);
      proc print data=&dsname;
      run;
      %let num=%eval(&num+1);
      %let dsname=%scan(&syspbuff,&num);
   %end;
%mend printz;

This invocation of PRINTZ contains four parameter values, PURPLE, RED, BLUE, and TEAL although the macro definition does not contain any individual parameters:

%printz(purple,red,blue,teal)

As a result, SAS receives these statements:

PROC PRINT DATA=PURPLE;
RUN;
PROC PRINT DATA=RED;
RUN;
PROC PRINT DATA=BLUE;
RUN;
PROC PRINT DATA=TEAL; 
RUN;

Example 4: Using the %MACRO Statement with the SOURCE Option

The SOURCE option combines and stores the source of the compiled macro with the compiled macro code. Use the %COPY statement to write the source to the SAS log. For more information about viewing or retrieving the stored source, see %COPY Statement.

/* commentary */  %macro foobar(arg) /store source
      des="This macro does not do much";
%put arg = &arg;
* this is commentary!!!;
%* this is macro commentary;
%mend /* commentary; */;      /* Further commentary */
NOTE: The macro FOOBAR completed compilation without errors.
%copy foobar/source;

The following results are written to the SAS log:

%macro foobar(arg) /store source
des="This macro does not do much";
%put arg = &arg;
* this is commentary!!!;
%* this is macro commentary;
%mend /* commentary; */;

Example 5: Using the %MACRO Statement with the STORE and SECURE Options

The SECURE option can be used only in conjunction with the STORE option. The following example demonstrates the use of the STORE and an implied NOSECURE option to create a macro that is stored in plain text.

  options mstored sasmstore=mylib;
  libname mylib "mylib";
  %macro nonsecure/store; /* This macro is stored in plain text */
    data _null_;
      x=1;
      put "This data step was generated from a non-secure macro.";
    run;
  %mend nonsecure;
  %nonsecure
  filename maccat catalog 'mylib.sasmacr.nonsecure.macro';
  data _null_;
    infile maccat;
    input;
    list;
  run;

The following example demonstrates the use of the STORE and SECURE options to create a macro that is encrypted.

options mstored sasmstore=mylib;
libname mylib "mylib";
%macro secure/store secure; /* This macro is encrypted */
    data _null_;
      x=1;
      put "This data step was generated from a secure macro.";
    run;
  %mend secure;
  %secure
  filename maccat catalog 'mylib.sasmacr.secure.macro';
  data _null_;
    infile maccat;
    input;
    list;
  run;