SUGI 27 Advanced Tutorials

Paper 17-27
Building and Using Macro Libraries
Arthur L. Carpenter, California Occidental Consultants

ABSTRACT maintenance of the application. All to often

macro definitions become buried within the
While many users take advantage of the SAS® programs that use them. The result is often a
Macro Language, few take full advantage of its proliferation of multiple versions of similar
capabilities to build and maintain libraries of macros in multiple programs, each with its own
macros. Management of large numbers of definition of the macro. Parallel code, two
macros can be problematic. Names and programs or macros that do essentially the same
locations must be remembered, changes must be thing, is an especially difficult problem in large
managed, duplication and variations of individual applications that are maintained by multiple
macros must be monitored, and efficiency issues programmers. Even when there is only one
must be taken into consideration. These programmer, there is a tendency to clone a
problems come even more to the forefront when program ("with slight modifications"). Will each
macros are shared among programmers - version be updated each time a bug is found?
especially in a networked environment. Who makes sure that the update happens? Are
the various versions of the macro documented?
Macro libraries allow you to control and manage These problems are avoided by placing the
the proliferation of your macros. Libraries can definition in a macro library.
consist of a formal use of the %INCLUDE
statement, a group of programs defining macros Macro libraries are used to avoid the problem of
that can be automatically called, or even macro cloning by providing a single location for
collections of macros that were previously all macro definitions. Rather than cloning the
compiled and then stored. macro, it is adapted (generalized) to fit each of
its calling programs and then stored in one of the
Macro libraries are extremely useful, and not libraries. Once in a library, there will only ONE
really all that complicated. If you are not macro definition to maintain, and it can be used
currently using them as part of your macro by as many programs as is needed. Obviously
programming efforts, read on! this requires documentation as well as diligence.
Part of the solution is to place ALL macro
definitions in a common library, which is
KEYWORDS accessible to all programs in the application.
This way no macro definition will be 'buried'
%INCLUDE, autocall, libraries, compiled within a program.
macros, SASMACR catalog, SASAUTOS,
SASMSTORE There are three types of macro libraries;
%INCLUDE, Compiled Stored Macros,
AUTOCALL Macros. Each has its advantages
and disadvantages, and best of all they can be
INTRODUCTION used in conjunction with each other!
The use of macros is essential to an automated It is important to understand the behavior of
and flexible system. This implies that the control these libraries, how they are setup, and how they
of the macro code is very important to the
SUGI 27 Advanced Tutorials

interact with each other. contain any snippet of SAS code. Within the
context of this paper however, we are interested
in building macro libraries and to do this the
%INCLUDE included file would contain a macro definition
e.g. %MACRO and %MEND statements. There
The least sophisticated approach to setting up a are a couple of efficiency issues that the user of
macro library is obtained through the use of include libraries should remember.
%INCLUDE files which store macro definitions.
This was often the only viable type of library in Generally a given file should not contain more
earlier (pre V6) versions of SAS, and not a few than one macro definition, and the macro being
SAS programmers have failed to make the called should not be called from within the
transition to true macro libraries. included code. The first is important because if
the file contains multiple macro definitions, then
Strictly speaking the use of the %INCLUDE all the definitions must be loaded, and compiled,
does not actually set up a macro library. The just to use one of the macros. Of course if all
%INCLUDE statement points to a file and when the macros will eventually be used this does not
the statement is executed, the indicated file (be it really matter. Secondly if the macro call is
a full program, macro definition, or a statement placed within the included code, the code will
fragment) is inserted into the calling program at need to be re-included (and the macro
the location of the call. When using the recompiled) each time the macro is to be used.
%INCLUDE to build a macro library, the
included file will usually contain one or more The greatest disadvantage of using the
macro definitions. %INCLUDE in a large application is tracking
and maintaining the filerefs that point to the
Although you can identify the file to be included individual files. While this is less of a problem in
directly from within the %INCLUDE statement, static systems, it is still non-trivial. This issue
it is usually done indirectly through the use of a virtually goes away with the use of the other
fileref. macro library alternatives discussed below.

filename macdef1
‘c:\mymacros\macdef1.sas’;
........ COMPILED STORED MACROS
%include macdef1;
........
%macdef Macros are always compiled before they are
........ executed and it is possible to store the compiled
code for future use. Compiled macros are stored
One way to build a library or collection of files in a catalog named SASMACR, and by default
that are to be ‘included’, is to place them in one this catalog is stored in the WORK library. Each
central location. This way they will be easier to compiled macro is stored with the entry type of
find and maintain. Some users of include MACRO and with an entry name corresponding
libraries will indicate that these file are to be to the name of the macro. When a macro is
‘included’, and therefore might not be complete called, SAS automatically searches this catalog
programs, by using an extension of INC instead for the compiled version of the macro that was
of SAS. While using an extension of INC in no called. Permanently compiled stored macros are
way hampers the file’s use by SAS, windows also written to a SASMACR catalog, but this
users should be aware that the file will not be catalog is stored in a different (permanent)
marked by a SAS registered icon. library.

As was mentioned above the included file can The ability to store and make use of compiled
SUGI 27 Advanced Tutorials

stored macros is by default turned off. The user Also, since it is not possible to reconstruct the
turns on the abilty to make use of compiled code used to create the compiled macro, the
stored macros with the system option developer must make sure that the code is
MSTORED (NOMSTORED turns it off). The correctly maintained independently from the
library that is to be used to store the permanent SASMACR catalog.
SASMACR catalog is specified by using the
SASMSTORE= option. This highlights a second problem for these
libraries. The compiled macros are all in one
The following OPTIONS statement turns on the location, the SASMACR catalog, however the
use of compiled stored macros and designates code itself could be anywhere. Usually
the PROJSTOR libref as the catalog location. developers that use compiled stored macro
libraries will also have a central location to store
options mstored sasmstore=projstor; the source code. A logical location is in the
same directory as the SASMACR catalog.
Unlike the AUTOCALL libraries discussed next,
you cannot use more than one location reference
with the SASMSTORE option, therefore, if you
do want to search multiple catalogs, you need to
AUTOCALL FACILITY
use either a concatenated libref or a
When a requested macro is not found in a
concatenated catalog.
SASMACR catalog, the AUTOCALL library is
searched. Much like an %INCLUDE file, this
The following designates the two librefs
library contains the macro definitions in the form
PROJSTOR and ALLMSTOR as the locations
of SAS code. When a macro is called, SAS
that are to be searched for the compiled stored
searches for a file with the SAME name as the
macro catalog by concatenating the two
name of the macro in the specified AUTOCALL
locations into a single libref. If the compiled
location. The code in the corresponding file is
macro is in more than one catalog, the definition
then submitted for processing. Since this file
found first will be used (read left to right).
contains the macro definition, the macro is then
libname projstor 'c:\temp'; compiled and made available for execution.
libname allmstor 'f:\junk'; Under Windows this location is a folder and
libname multi (projstor, allmstor);
each macro definition is an individual file. Under
options mstored sasmstore=multi; MVS a PDS is used with each member
corresponding to a macro.
By default the compiled macro is stored in
WORK.SASMACR. You redirect this location By default the ability to make use of the
at compile time through the use of the /STORE AUTOCALL facility is turned on. The
option on the %MACRO statement. For the following code makes sure that the autocall
SASMSTORE definition above, the macro facility is available (MAUTOSOURCE) and
AERPT shown below, will be stored in the specifies the FILEREFs of the locations
PROJSTOR.SASMACR catalog. (SASAUTOS=) that contain the SAS programs
with the macro definitions.
%macro aerpt(dsn, stdate, aelist) / store;
options mautosource
The use of compiled stored macros is not sasautos=(projauto allauto);
without problems. The developer must make
sure that a macro does not exist in more than Although the documentation is not entirely clear
one catalog or if it does (on purpose, of course) on the subject (or sometimes even incorrect, see
that the search order of the catalogs is correct. Carpenter’s Complete Guide to the SAS® Macro
SUGI 27 Advanced Tutorials

Language), be sure that you use filerefs, NOT be compiled at that time and added to the
librefs, to specify the locations of the autocall WORK.SASMACR catalog and the compiled
programs (Burlew, 1998, correctly specifies the macro definition will be used from then on (as
locations with the FILENAME statement). You long as it is not included another time).
can also replace the fileref in the SASAUTOS=
option with a direct reference, however this
approach is less flexible and is not as ‘clean’. MACRO LIBRARY STRUCTURE
Placing your macros in a library will help to
MACRO SEARCH ORDER organize you programs. However in larger
groups, projects, or in organizations with
As these libraries of macros are established it is multiple programmers sharing macros, it
important for both the developer and the user to becomes necessary to organize the libraries
understand the relationship between them. One themselves. In the designations of the locations
of the more important aspects of this relationship of both the Autocall library (SASAUTOS=) and
is the order of locations that SAS searches for a the compiled stored macros (SASMSTORE=)
macro once it is called. shown above there are two locations. By
specifying multiple locations for the libraries it
When a macro is called, the macro facility must becomes possible to organize them into
first find the macro definition before it can be collections of macros. Typically for the work
inserted for execution. Since the macro that I do, I like to arrange the collections
definition can be located in any of several according to how the macros are to be used.
locations, the developer needs to control the Macros that are specific to a task or project will
search. The search for the macro definition uses be placed in the location that will be searched
the following order. first. Then the macros that are more generalized
or are useful to multiple projects are placed in a
1) WORK.SASMACRO location that will be available to users of all
2) Compiled Stored Macros projects. This arrangement allows the developer
3) Autocall Macros to create general tools that are available to
everyone as well as specific macros that apply to
The first time that a macro from the Autocall only one project or task.
library is called it will not be found in any of the
catalogs of compiled macros, but once called it
will be compiled and the compiled code stored MACRO LIBRARY STRATEGY
(in WORD.SASMACR unless otherwise
specified). On successive calls to that macro its The question is then not IF to set up a library,
compiled code definition will be found and the but which macro library setup to use.
search will not extend to the Autocall library a
second time. This process minimizes the The %INCLUDE library and the AUTOCALL
compilation of the macro. library can be set up to in a very similar fashion.
The primary advantage of the AUTOCALL
This is a major advantage over the use of the library is that the developer does not need to
%INCLUDE as a macro library. When a macro manage or work with the individual filerefs, as
definition is brought into the program through these are controlled automatically through the
the %INCLUDE, it will be compiled for each SASAUTOS= system option.
%INCLUDE. Of course if the programmer is
careful, this is not such a bad thing. If the Unless a macro is unusually large or complex, it
%INCLUDE appears only once, the macro will
SUGI 27 Advanced Tutorials

generally takes very little time to locate and appropriate SASMACR catalog. This catalog
compile a macro stored in the AUTOCALL will be in the WORK library unless compiled
library. This suggests that there is not a stored macros are being used and the /STORE
substantial time savings in using the compiled option is present on the %MACRO statement.
stored macro library. Since both libraries require When the macro is then later called, SAS looks
the developer to store and maintain the source for the macro definition in one or more of these
code, there does not seem to be a compelling catalogs and only if the definition is NOT found
reason to adopt one library type over the other. is the AUTOCALL library searched.
For this reason and because everyone already
uses the AUTOCALL facility anyway to get to Suppose the developer is debugging a macro
the SAS supplied autocall macros, the whose definition resides in the AUTOCALL
AUTOCALL library seems to be used much library. She calls the macro for execution, but is
more frequently than the compiled stored macros not satisfied with the results. If she edits the
library. program, saves it back into the AUTOCALL
library, and then re-executes it, the results will be
One strategy that has worked well in limited the same! Her changes will be ignored! Her
situations, combines these two types of libraries. changes are not implemented because the macro
This combined library approach specifies an has not been recompiled! She has updated the
autocall library ( SASAUTOS=). It also turns code, but because the macro has already been
on the compiled stored macro library compiled and resides in the SASMACR catalog,
(MSTORED) and then points the location SAS will never look for the new definition in the
(SASMSTORE=) to the SAME location as the AUTOCALL library. She needs to do one of
autocall library. Since the SASAUTOS= fileref two things after making the change in the macro
and the SASMSTORE= libref both point to the definition. She can:
same directory, the SASMACR catalog will 1) submit the macro definition (%MACRO to
reside in the same location as the source code %MEND), this places the latest definition in the
that defines the macro. Once this is done all the SASMACR catalog.
macros in the autocall directory will ALSO have 2) delete the compiled macro entry from the
the /STORE option. Now we have the best of appropriate SASMACR catalog. The next
both worlds. One source program and a execution of the macro will cause SAS to seek
compiled macro all stored in one easy to find out the AUTOCALL definition, which will then
location. be compiled and re-stored in the SASMACR
catalog.

INTERACTIVE MACRO When your SAS environment includes macro

DEVELOPMENT libraries, you must remember that as you edit
your macro definitions, you must also update the
When developing macros in the interactive appropriate SASMACR catalogs as well. It is
environment, special care must be taken to make not enough to just change the macro definition.
sure that the correct macro definitions are
compiled and stored. If the developer is not The above example illustrates a situation that is
careful it is possible to call a macro without usually not an issue when using a %INCLUDE
using the latest update to the macro definition. library to hold macro definitions. When the
This is not a good thing. %INCLUDE brings in a macro definition, the
definition itself is usually inserted directly into
As was discussed earlier, after a macro definition the code, it is then submitted and compiled - all
is submitted, the compiled code is stored in the in the same operation. Although this may
initially sound like an advantage, it actually is not
SUGI 27 Advanced Tutorials

because the macro must be recompiled each time SUMMARY

the %INCLUDE is executed. This method does
not take full advantage of the ability to save the Macro libraries allow the macro developer to
compiled macro in the SASMACR catalog. store, maintain, and manage large numbers of
macros. The two types of macro libraries
(AUTOCALL and Compiled Stored Macros),
AUTOCALL MACROS SUPPLIED were introduced in V6. These libraries allow the
BY SAS user to avoid the use of the %INCLUDE
statement to bring in macro definitions, while
SAS has supplied a number of macros with the efficiently accessing and utilizing the power of
SAS System e.g. %LEFT, %LOWCASE, and the macro.
%VERIFY. These macros are actually supplied
as macro code, and the code is placed in the Using macro libraries is not difficult nor is it
SAS AUTOCALL library. If you want to make overly complicated. Both styles of libraries are
use of these macros, and you do, you must established through the use of the OPTIONS
include this library in your list of locations search statement, although the AUTOCALL macro
by the autocall facility. facility is available by default.

By default the automatic fileref SASAUTOS is Macro libraries foster an environment that
available. An options statement setting the promotes good macro programming practices by
AUTOCALL options to the defaults would be: making it easier to avoid the use of duplicate
macro definitions. As a result of using these
options mautosource sasautos=sasautos; libraries you will find that it is easier to track and
maintain your macros, and macro programming
If you specify locations for AUTOCALL will become even more fun.
libraries, you need to make sure that the SAS
AUTOCALL library is also specified. Failure to
do this will make ALL of the SAS autocall ABOUT THE AUTHOR
macros unavailable. In the example of the
OPTIONS statement in the AUTOCALL section Art Carpenter’s publications list includes three
of this paper, the SASAUTOS fileref is NOT books Quick Results with SAS/GRAPH®
included and the autocall macros provided with Software, Annotate: Simply the Basics, and
SAS will NOT be available. The OPTIONS Carpenter's Complete Guide to the SAS® Macro
statement should be rewritten as: Language, and numerous papers and posters
options mautosource
presented at SUGI, PharmaSUG, NESUG, and
sasautos=(projauto allauto WUSS. Art has been using SAS since 1976 and
sasautos); has served in various leadership positions in
local, regional, and national user groups.
Notice that the SASAUTOS fileref is listed last.
This allows the user to create macros that will Art is a SAS Certified ProfessionalTM, and
override the default definitions of the macros through California Occidental Consultants he
supplied with SAS. teaches SAS courses and provides contract SAS
programming support nationwide.
SUGI 27 Advanced Tutorials

AUTHOR CONTACT REFERENCES

Arthur L. Carpenter Burlew, Michele M. 1998, SAS® Macro
California Occidental Consultants Programming Made Easy, Cary, NC: SAS
P.O. Box 586199 Institute, Inc., 280pp.
Oceanside, CA 92058-6199
Carpenter, Arthur L., 1998, Carpenter's
(760) 945-0613 Complete Guide to the SAS® Macro Language,
[email protected] Cary, NC: SAS Institute, Inc., 242pp.
www.caloxy.com

TRADEMARK INFORMATION
SAS and SAS Certified Professional are
registered trademarks of SAS Institute, Inc. in
the USA and other countries.
® indicates USA registration.