One of the most useful aspects of macro programming is the ability to reuse your macro programs. In Chapter 11, "Creating and Using Macro Programs," on page 371, you learned that compiled macros are stored in a temporary SAS catalog by default and are available for execution anytime during the current SAS session. You also learned that macros stored in this temporary SAS catalog are deleted at the end of the SAS session.

You might want to store your macros permanently so that you can reuse them in later SAS sessions or share them with others. There are several ways of storing your macro programs permanently and of making them accessible during a SAS session. The methods that you will learn in this chapter are

In this chapter, you learn to

Before beginning this chapter, you should complete the following chapters:

You can compile a macro by using the %INCLUDE statement to insert its definition into a program. Then you can call the macro in order to execute it.

Suppose the following macro definition is stored in the external file C:sasfilesprtlast.sas:

%macro prtlast;
   %if &syslast ne _NULL_ %then %do;
      proc print data=&syslast (obs=5);
         title "Listing of &syslast data set";
      run;
   %end;
   %else
      %put No data set has been created yet.;
%mend;

You could submit the following code to access, compile, and execute the Prtlast macro. The PROC SORT step is included in this example in order to create a data set that the Prtlast macro can print.

%include 'c:sasfilesprtlast.sas' /source2; 


proc sort data=sasuser.courses out=bydays;
      by days;
run;

%prtlast 

The following messages are written to the SAS log when this code is submitted. Notice that the macro definition is written to the log because SOURCE2 was specified in the %INCLUDE statement.

Table 12.1. SAS Log

Here is the output that the code generates.

To save the Printit macro definition to the Sasuser.Mymacs catalog, perform these steps:

If you store your macros in a SAS catalog, you might want to view the contents of a particular catalog to see the macros you have stored there. You can use the Explorer window to view the contents of a SAS catalog by navigating to the catalog and double clicking it. You can also use the CATALOG procedure to list the contents of a SAS catalog. The CONTENTS statement of the CATALOG procedure lists the contents of a catalog in the procedure output.

You can use PROC CATALOG to view all of the macros that are stored in the temporary Work.Sasmacr catalog, as follows:

proc catalog cat=work.sasmacr;
      contents;
      title "Default Storage of SAS Macros";
quit;

This PROC CATALOG step produces results that are similar to the output shown below. The macros that are actually listed will be the macros that have been compiled during the current SAS session.

If you store a macro definition in a SOURCE entry of a SAS catalog, you can use the CATALOG access method in a FILENAME statement in conjunction with the %INCLUDE statement to insert the macro definition into a SAS program.

Suppose you have stored the following macro definition as a SOURCE entry in the SAS catalog Sasuser.Mymacs:

%macro prtlast;
   %if &syslast ne _NULL_ %then %do;
      proc print data=&syslast(obs=5);
         title "Listing of &syslast data set";

      run;
   %end
   %else
      %put No data set has been created yet.;
%mend;

You can use the CATALOG access method along with the %INCLUDE statement to compile the macro Prtlast. Then you can reference the macro later in the program.

filename prtlast catalog 'sasuser.mymacs.prtlast.source'; 
%include prtlast; 
proc sort data=sasuser.courses out=bydays;
      by days;
run;
%prtlast 

You can also use the CATALOG access method to reference multiple SOURCE entries as long as the entries are stored in the same SAS catalog.

Suppose you have two macros, named Prtlast and Sortlast, that are stored in a SAS catalog.

Catalog Entry: Sasuser.Mymacs.Prtlast.Source

%macro prtlast;
   %if &syslast ne _NULL_ %then %do;
      proc print data=&syslast(obs=5);
      title "Listing of &syslast data set";
      run;
   %end;
   %else
     %put No data set has been created yet.;
%mend;

Catalog Entry: Sasuser.Mymacs.Sortlast.Source

%macro sortlast(sortby);
   %if &syslast ne _NULL_ %then %do;

      proc sort data=&syslast out=sorted;
         by &sortby;
      run;
   %end;
   %else
     %put No data set has been created yet.;
%mend;

You can use the CATALOG access method in conjunction with the %INCLUDE statement to compile both macros. Then you can call the macros later in the program. In this example, assume that the macros have the same names as the SOURCE entries in which they are stored:

filename prtsort catalog 'sasuser.mymacs'; 
%include prtsort(prtlast) / source2; 
%include prtsort(sortlast) / source2; 


data current(keep=student_name course_title begin_date location);
   set sasuser.all;
   if year(begin_date)=2001;
   diff=year(today())-year(begin_date);
   begin_date=begin_date+(365*diff);
run;


%sortlast(begin_date) 
%prtlast 

This code produces the following output:

An autocall library can be either

The method for creating an autocall library depends on the operating environment that you are using.

To create an autocall library in a directory-based operating system such as Windows, UNIX, or OpenVMS, create a directory in which to store macro definitions. Each macro definition in this directory will be a separate file that has the extension .sas and that has the same name as the macro that it contains.

Suppose you want to save the macro Prtlast in an autocall library. In a directory-based operating system, the first step is to create a directory that will hold your macro source files. You can use the Save As window to create the directory, and to save the macro definition in that directory. With the Prtlast definition in an active code editing window, select File

SAS provides several macros in a default autocall library for you. Some of the macros in the autocall library that SAS provides are listed here.

You might be familiar with SAS functions such as TRIM and LEFT. The macros that SAS supplies look like macro functions, but they are in fact macros. One of the useful things about these macros is that in addition to using them in your SAS programs, you can see their source code.

The macro definition for the Lowcase macro is shown below. Notice that the comments that are included in this macro provide information about using the macro. All of the macros that SAS provides in the autocall library include explanatory comments so that they will be easy for you to understand and use.

%macro lowcase(string);
%******************************************************;
%*                                                    *;
%* MACRO: LOWCASE                                     *;
%*                                                    *;
%* USAGE: 1) %lowcase(argument)                       *;
%*                                                    *;
%* DESCRIPTION:                                       *;
%*     This macro returns the argument passed to      *;
%*     it unchanged except that all upper-case        *;
%*     alphabetic characters are changed to their     *;
%*     lower-case equivalents.                        *;
%*                                                    *;
%* E.g.:   %let macvar=%lowcase(SAS Institute Inc.);     *;
%* The variable macvar gets the value                 *;
%*   "sas institute inc."                             *;
%* NOTES:                                             *;
%*     Although the argument to the %UPCASE macro     *;
%*     function may contain commas, the argument to   *;
%*     %LOWCASE may not, unless they are quoted.      *;
%*     Because %LOWCASE is a macro, not a function,   *;
%*     it interprets a comma as the end of a parameter. *;
%******************************************************;
%sysfunc(lowcase(%nrbquote(&string)))
%mend;

Remember that an autocall library is either a SAS catalog, an external directory, or a partitioned data set. This is true both for the default autocall library that SAS supplies and for autocall libraries that you create.

In order to access a macro definition that is stored in an autocall library, you must use two SAS system options, as follows:

Both the MAUTOSOURCE and SASAUTOS system options can be set either at SAS invocation or with an OPTIONS statement during program execution.

The MAUTOSOURCE system option controls whether the autocall facility is available.

The SASAUTOS system option controls where the macro facility looks for autocall macros.

Unless your system administrator has changed the default value for the SASAUTOS system option, its value is the fileref Sasautos, and that fileref points to the location where the default autocall library was created during installation. The Sasautos fileref can refer to multiple locations that are concatenated.

Generally, it is a good idea to concatenate any autocall libraries that you create yourself with the default autocall library in the value of the SASAUTOS system option. Otherwise, the new autocall library will replace the default or existing libraries in the value of SASAUTOS, and the autocall facility will have access to only the new autocall library.

Suppose you want to access the Prtlast macro, which is stored in the autocall library C:Mysasfiles. You also want to make sure that the default autocall library (which the fileref Sasautos points to) is still available to the autocall facility. You would submit the following code:

options mautosource sasautos=('c:mysasfiles',sasautos);
%prtlast

When the autocall facility is in effect, if you invoke a macro that has not been previously compiled, the macro facility automatically

The autocall facility does not search for a macro in the autocall library if the macro has already been compiled during the current SAS session. In that case, the session-compiled macro is executed.

Remember that when a macro is compiled, it is stored in the temporary SAS catalog Work.Sasmacr by default. You can also store compiled macros in a permanent SAS catalog. Then you can use the Stored Compiled Macro Facility to access permanent SAS catalogs that contain compiled macros.

There are several advantages to using stored compiled macros:

Two SAS system options affect stored compiled macros: MSTORED and SASMSTORE. The MSTORED system option controls whether the Stored Compiled Macro Facility is available.

The SASMSTORE system option controls where the macro facility looks for stored compiled macros.

The MSTORED and SASMSTORE system options can be set either at SAS invocation or with an OPTIONS statement during program execution.

To create a permanently stored compiled macro, you must

There are several restrictions on stored compiled macros.

An alternative to saving your source program separately from the stored compiled macro is to use the SOURCE option in the %MACRO statement to combine and store the source of the compiled macro with the compiled macro code. The SOURCE option requires that the STORE option and the MSTORED option be set. The %MACRO statement below shows the correct syntax for using the SOURCE option.

%macro macro-name<(parameter list)> /STORE SOURCE; 

The source code that is saved by the SOURCE option begins with the %MACRO keyword and ends with the semicolon following the %MEND statement.

Suppose you want to store the Words macro in compiled form in a SAS library. This example shows the macro definition for Words. The macro takes a text string, divides it into words, and creates a series of macro variables to store each word.

Notice that both the STORE option and the SOURCE option are used in the macro definition so that Words will be permanently stored as a compiled macro and the macro source code will be stored with it, as follows:

libname macrolib 'c:storedlib';
options mstored sasmstore=macrolib;


%macro words(text,root=w,delim=%str( ))/store source; 
   %local i word;
   %let i=1;
   %let word=%scan(&text,&i,&delim);
   %do %while (&word ne );
      %global &root&i;
      %let &root&i=&word;
      %let i=%eval(&i+1);
      %let word=%scan(&text,&i,&delim);
       %end;
   %global &root.num;
      %let &root.num=%eval(&i-1);
%mend words;

If the Sasmacr catalog does not exist in the Macrolib library, it is automatically created. You can list the contents of the Macrolib.Sasmacr catalog to verify that the compiled macro was created, as follows:

proc catalog cat=macrolib.sasmacr;
   contents;
   title "Stored Compiled Macros";
quit;

Here is the output from the PROC CATALOG step if no other compiled macros are stored in Macrolib.Sasmacr.

In order to access a stored compiled macro, you must

Only one permanent catalog containing compiled macros can be accessed at any given time.

The following program calls the Words macro. Assume that the Words macro was compiled and stored in an earlier SAS session.

libname macrolib 'c:storedlib';
options mstored sasmstore=macrolib;


%words(This is a test)
%put Number of Words (wnum): &wnum;
%put Word Number 1 (w1): &w1;
%put Word Number 2 (w2): &w2;
%put Word Number 3 (w3): &w3;
%put Word Number 4 (w4): &w4;

Here is a portion of the messages that are written to the SAS log when this code is submitted.

Table 12.2. SAS Log

If you use the SOURCE option of the %MACRO statement to store your macro source code along with the stored compiled macro, you can use the %COPY statement to access the stored source code.

Suppose you submitted the program below to create a stored compiled macro named Words.

libname macrolib 'c:storedlib';
options mstored sasmstore=macrolib;

%macro words(text,root=w,delim=%str( ))/store source;
   %local i word;
   %let i=1;
   %let word=%scan(&text,&i,&delim);
   %do %while (&word ne );
      %global &root&i;
      %let &root&i=&word;
      %let i=%eval(&i+1);
      %let word=%scan(&text,&i,&delim);
       %end;
   %global &root.num;
       %let &root.num=%eval(&i-1);
%mend words;

The %COPY statement writes the source code for the Words macro to the SAS log, for example:

%copy words/source;

The partial SAS log below shows the source code of the Words macro.

Table 12.3. SAS Log

The Stored Compiled Macro Facility can be used in conjunction with the Autocall Facility and with session-compiled macros. When you submit a macro call such as %words, the macro processor searches for the macro Words as

%INCLUDE file-specification </SOURCE2>;

FILENAME fileref

     CATALOG 'libref.catalog.entry-name.entry-type';

%INCLUDE fileref;

FILENAME fileref CATALOG 'libref.catalog';

%INCLUDE fileref(entry-1);

%INCLUDE fileref(entry-2);

PROC CATALOG CATALOG=libref.catalog;

     CONTENTS;

QUIT;

OPTIONS MAUTOSOURCE | NOMAUTOSOURCE;

OPTIONS SASAUTOS=library-1;

OPTIONS SASAUTOS=(library-1,…,library-n);

OPTIONS MSTORED | NOMSTORED;

OPTIONS SASMSTORE=libref;

%MACRO macro-name<(parameters-list)> /STORE SOURCE

     <DES='description'>;

     text

%MEND <macro-name>;