Chapter 10 Storing and Reusing Macro Programs
Saving Macro Programs with the Autocall Facility
Making Autocall Libraries Available to Your Programs
Maintaining Access to the Autocall Macro Programs That Ship with SAS
Defining Filerefs under Windows and Using Them to Identify Autocall Libraries
Explicitly Specifying the Directory Locations of Autocall Libraries on the OPTIONS Statement
Identifying Autocall Libraries That Are Stored in SAS Catalogs
Listing the Names of the Autocall Libraries That Are Defined in the SAS Session
Using the Autocall Facility under UNIX and z/OS Systems
Using the Autocall Facility under UNIX
Using the Autocall Facility under MVS Batch
Saving Macro Programs with the Stored Compiled Macro Facility
Setting SAS Options to Create Stored Compiled Macro Programs
Creating Stored Compiled Macro Programs
Saving and Retrieving the Source Code of a Stored Compiled Macro Program
Encrypting a Stored Compiled Macro Program
As your macro programming skills develop, you will find uses for your macro programs in several different applications. You might want to share these macro programs with your coworkers and make these macro programs available to your batch jobs. You might want to develop your own set of utilities. Since reusability is one of the great features of macro programs, it makes sense that there would be a systematic way to store macro programs in SAS. In fact, there are two ways to store your macro programs in SAS: the autocall facility and the stored compiled macro facility. This chapter describes how to use these two tools.
The autocall facility consists of external files or SOURCE entries in SAS catalogs that contain your macro programs. When you specify certain SAS options, the macro processor searches your autocall libraries when it resolves a macro program reference.
The stored compiled macro facility consists of SAS catalogs that contain compiled macro programs. When you specify certain SAS options, the macro processor searches your catalogs of compiled macro programs when it resolves a macro program reference.
When you store a macro program in an autocall library, you do not have to submit the macro program for compilation before you reference the macro program. The macro processor does that for you if it finds the macro program in the autocall library.
Several SAS products ship with libraries of macro programs that you can reference, or that are referenced by the SAS products themselves.
An advantage of the autocall facility is that the macro programs are portable across all operating systems and releases of SAS.
A minor disadvantage to the autocall facility is that the macro program must be searched for and compiled the first time it is used in a SAS session. This takes resources, although usually it is minimal.
After the macro processor finds your macro program in your autocall library, it submits the macro program for compilation. If there are any macro language statements in open code, these statements execute immediately. The macro program is compiled and stored in the session compiled macro program catalog, SASMACR, just as if you submitted it yourself. SASMACR is in the WORK directory.
The macro program can be reused within your SAS session. When it is, only the macro program itself is executed. Any macro language statements in open code that might have been stored with the macro program are not executed again. The compiled macro program is deleted at the end of the session when the catalog WORK.SASMACR is deleted. The code remains in the autocall library unless you delete the macro program or the autocall library.
The macro programs that you select for your autocall library can be stored as external files or as SOURCE entries in SAS catalogs.
To store macro programs as external files in a directory-based system such as Windows or UNIX, you define the directory and add the macro programs to the directory. Each macro program is stored in an individual file with a file type or extension of SAS. The name given to the file must be the same as the macro program name. (Note that on UNIX platforms, the filename, macro program name, and SAS extension must be in lowercase.)
Under z/OS, macro programs that are stored as external files are saved as members of a partitioned data set. The name of the member should be the same as the name of the macro program.
When storing macro programs in a SAS catalog, make each macro program a separate SOURCE entry. The name of the SOURCE entry should be the same as the macro program name.
Figure 10.1 shows an example of an autocall library where the four macro programs are stored as separate files.
Figure 10.1 A Windows 7 directory containing four autocall macro programs
Figure 10.2 shows a SAS catalog that contains the four macro programs stored as SOURCE entries.
Figure 10.2 A SAS catalog containing four autocall macro programs stored as SOURCE entries
When you want SAS to search for your macro programs in autocall libraries, you must specify the two SAS options, MAUTOSOURCE and SASAUTOS. These options can be specified three ways:
• Add MAUTOSOURCE and SASAUTOS to the SAS command that starts the SAS session.
• Submit an OPTIONS statement with MAUTOSOURCE and SASAUTOS from within a SAS program.
• Submit an OPTIONS statement with MAUTOSOURCE and SASAUTOS from within an interactive SAS session.
Additionally, you can reference them in an AUTOEXEC file or modify the config file so that the autocall library is available when your SAS session starts. For more information, see Documentation in the Knowledge Base, at http://support.sas.com.
The MAUTOSOURCE option must be enabled to tell the macro processor to search autocall libraries when resolving macro program references. By default, this option is enabled. Specify NOMAUTOSOURCE to turn off this option. While not recommended, a reason you might disable MAUTOSOURCE is if you want to save computing resources when you do not intend to use autocall libraries.
options mautosource;
options nomautosource;
The SASAUTOS= option identifies the location of the autocall libraries for the macro processor. On the SASAUTOS= option, specify either the actual directory reference enclosed in single quotation marks or the filerefs that point to the directories. A FILENAME statement defines the fileref.
The syntax of the SASAUTOS= option follows. The first line shows how to specify one library. The second line shows how to specify multiple libraries. The macro processor searches the libraries in the order in which you list them on the SASAUTOS= option.
options sasautos=library;
options sasautos=(library-1, library-2,..., library-n);
Autocall libraries in macro programs come with many SAS products. Chapter 6 describes many of these macro programs that ship with Base SAS. Your SAS session automatically assigns a fileref of SASAUTOS to the macro programs described in Chapter 6. Some applications of these macro programs include changing the case of a macro variable value to lowercase (%LOWCASE) and trimming trailing blanks from a macro variable value (%TRIM).
With MAUTOSOURCE in effect and a typical installation of SAS that assigns the SASAUTOS= option to SASAUTOS, your SAS session automatically has access to these autocall macro programs.
To maintain access to the SASAUTOS autocall library, remember to include the SASAUTOS fileref when specifying references to your own libraries with the SASAUTOS= option. The SASAUTOS fileref is automatically created by SAS when your SAS session starts.
If you omit the SASAUTOS fileref when you issue your SASAUTOS= option, and you have not previously accessed the macro program shipped with SAS that you want to use, you will not have access to that macro program. If you had previously accessed one of the macro programs in the SASAUTOS library before removing SASAUTOS from the SASAUTOS= option, you will still be able to reference that macro program. This is because, on the first reference to that autocall macro program, the macro processor compiles the macro program and makes it available for the duration of the SAS session.
Defining Filerefs under Windows and Using Them to Identify Autocall Libraries
The next statements define two filerefs under Windows with SAS®9 and assigns them to SASAUTOS=. The OPTIONS statement includes these two filerefs plus the SASAUTOS fileref.
filename reports 'c:mymacroprograms epmacs';
filename graphs 'c:mymacroprogramsgraphmacs';
options sasautos=(reports graphs sasautos);
Explicitly Specifying the Directory Locations of Autocall Libraries on the OPTIONS Statement
To specify the same libraries as above without using filerefs, submit the following statement. Note the inclusion of the SASAUTOS fileref.
options sasautos=
('c:mymacroprograms epmacs' 'c:mymacroprogramsgraphmacs'
sasautos);
Identifying Autocall Libraries That Are Stored in SAS Catalogs
An autocall library stored in a SAS catalog requires that you specify the CATALOG access method on the FILENAME statement that identifies the autocall library. The syntax of the FILENAME statement is
filename fileref catalog 'library.catalog';
The next statements reference a user-defined autocall library stored in a SAS catalog under Windows in SAS®9. It also includes the SASAUTOS fileref.
filename mymacs catalog 'books.repmacs';
options sasautos=(mymacs sasautos);
Listing the Names of the Autocall Libraries That Are Defined in the SAS Session
If you want to check what autocall libaries are defined in the current SAS session, submit the following PROC step.
proc options option=sasautos;
run;
Using the Autocall Facility under UNIX and z/OS Systems
Under a directory-based system, all macro programs are stored as individual files in a directory. Each macro program should have a file extension of .sas and a filename identical to the macro program name. Preceding examples use the autocall facility under Windows.
Using the Autocall Facility under UNIX
As with Windows, autocall libraries under UNIX are made up of separate files, each with .sas as the extension. Each macro program is in a separate file. The name of the file is the same as the name of the macro program. Note that the filename and macro program name must be in lowercase on UNIX platforms.
The following example specifies one user-defined autocall library and includes the SASAUTOS reference.
sas -mautosource -sasautos '/mymacroprograms/reports'
-append sasautos sasautos
The next example specifies two user-defined autocall libraries and includes the SASAUTOS reference.
sas -mautosource -sasautos '/mymacroprograms/graphmacs'
-append sasautos '/mymacroprograms/reports'
-append sasautos sasautos
From within a UNIX SAS session, the following line specifies one user-defined autocall library and includes the SASAUTOS reference.
options mautosource sasautos=('/mymacroprograms/reports',
sasautos)
The next OPTIONS statement specifies two user-defined autocall libraries from within a UNIX SAS session, and it includes the SASAUTOS reference.
options mautosource sasautos= ('/mymacroprograms/reports','/mymacroprograms/graphmacs',
sasautos);
Using the Autocall Facility under MVS Batch
Under the MVS operating system, autocall libraries are stored in partitioned data sets. Each macro program is a member in the partitioned data set. The name of the member is the same as the name of the macro program. A JCL DD statement assigns autocall libraries. The following example shows the beginning of the JCL for a batch job that specifies one autocall library. Note that the MAUTOSOURCE option is enabled.
//MYJOB JOB account....
// EXEC SAS,OPTIONS='MAUTOSOURCE'
//SASAUTOS DD DSN=MYMACS.REPORTS,DISP=SHR
The next example shows how multiple macro libraries can be specified.
//MYJOB JOB account....
// EXEC SAS,OPTIONS='MAUTOSOURCE'
//SASAUTOS DD DSN=MYMACS.REPORTS,DISP=SHR
// DD DSN=MYMACS.GRPHMACS,DISP=SHR
An OPTIONS statement can also be submitted from within the SAS program to specify the use of autocall libraries. The following statement specifies one user-defined autocall library plus the SASAUTOS fileref.
options mautosource sasautos=('mymacs.reports' sasautos);
The following statement specifies two user-defined autocall libraries plus the SASAUTOS fileref.
options mautosource sasautos= ('mymacs.reports' 'mymacs.grphmacs'
sasautos);
Macro programs that you want to save and do not expect to modify can be compiled and saved in SAS catalogs using the stored compiled macro facility. When a compiled macro program is referenced in a SAS program, the macro processor skips the compiling step, retrieves the compiled macro program, and executes the compiled code. The main advantage of this facility is that it prevents repeated compilation of macro programs that you use frequently.
A disadvantage of this facility is that the compiled versions of macro programs cannot be moved to other operating systems. The macro source code must be saved and recompiled under the new operating system. Further, if you are moving the compiled macro programs to a different release of SAS under the same operating system, you might also have to recompile the macro programs.
Macro source code is not stored by default with the compiled macro program. You must maintain the macro source code separately. You will not be able to retrieve the code from the compiled version of the macro program.
A convenient place to store your macro program code is in an autocall library. Also, you can save the source code as a SOURCE entry in a catalog if you specify the SOURCE option when compiling your macro program. Another way of saving the macro program code for later retrieval is shown in a later section where the SOURCE option is added to the %MACRO statement when creating a stored compiled macro program. This option stores the macro program code in the same entry as the compiled code, and you can retrieve this code later with the %COPY statement.
You need to set two SAS options, MSTORED and SASMSTORE, before you can compile and store your macro programs.
The MSTORED option instructs SAS that you want to make stored compiled macro programs available to your SAS session.
options mstored;
To turn off the MSTORED option, submit the following OPTIONS statement.
options nomstored;
The value that you assign to the SASMSTORE option is the libref that points to the location of the SAS catalog containing the compiled macro programs. Here is an example of SASMSTORE under Windows in SAS®9:
libname myapps 'c:mymacroprograms';
options mstored sasmstore=myapps;
SAS stores compiled macro programs in a catalog called SASMACR. The SASMACR catalog is stored in the directory specified by the SASMSTORE option. In this example, that directory has the libref of MYAPPS. Do not rename the SASMACR catalog. Use the CATALOG command or PROC CATALOG to view the list of macro programs stored in this catalog.
You can also tell the macro processor to search SASMACR catalogs in multiple locations for a stored compiled macro program by listing the multiple paths on the LIBNAME statement. The following code tells the macro processor to look in the SASMACR catalog in the three locations that are specified within the parentheses.
The order in which you list the paths is the order in which SAS searches for a stored compiled macro program. If you have a macro program with the same name in two locations, the program found in the first of the two paths is the one that executes.
libname myapps ('c:mymacroprograms',
'z:mymacroprograms',
'c:legacymacros'),
options mstored sasmstore=myapps;
Once the SAS options in the previous section are set, macro programs can be compiled and stored in a catalog by adding options to the %MACRO statement. The syntax of %MACRO when you want to compile and store a macro program follows:
%macro macro-name(parameters) / store <source secure
des=“description”>;
macro-program-code
%mend macro-name;
The STORE keyword is required when you want to store a compiled macro program in a catalog. The SOURCE, SECURE, and DES= options are not required.
The SOURCE option tells the macro processor to save a copy of the macro program’s source code, along with the compiled macro program in the same SASMACR catalog. It does not have a separate entry in the catalog and is instead stored in the same MACRO entry as the compiled macro program.
The SECURE option encrypts the compiled macro program and makes it more difficult for someone to obtain portions of the source code. The %COPY statement will not work with secure macro programs. However, it may be possible to see the non-macro code if the catalog entry is viewed within a text editor.
Use the DES= option to save up to 40 characters of text to describe your macro program. SAS displays the descriptive text when you view the contents of the catalog that holds the compiled stored macro programs.
Example 10.1: Creating a Stored Compiled Macro Program
An example of defining a macro program and storing it in a catalog under Windows in SAS®9 follows:
libname myapps 'c:mymacroprograms';
options mstored sasmstore=myapps;
%macro reptitle(repprog) / store des='Standard Report Titles';
title “Bookstore Report &repprog”;
title2 “Processing Date: &sysdate SAS Version: &sysver”;
%mend reptitle;
Figure 10.3 shows the DIR window for the MYAPPS.SASMACR catalog after submitting this program.
Figure 10.3 SAS DIR window for a catalog with one stored compiled macro program
As mentioned earlier, the SOURCE option on the %MACRO statement in conjunction with the STORE option saves a copy of the source code of the compiled macro program. It is not saved as a separate entry that you can retrieve; it is embedded in the same entry as the compiled code. To retrieve a copy of the code, use the %COPY macro language statement. This statement can list the code in the SAS log or save the code to a file. The syntax of the %COPY statement follows. The statement has three options.
%COPY macro-program-name / <library=
outfile= <fileref>
<’external file'>> source ;
By default, if you do not specify a libref with the LIBRARY= option, the macro processor will look in the library specified by the current setting of SASMSTORE.
Example 10.2: Saving the Source Code of a Stored Compiled Macro Program
Example 10.1 is modified in Example 10.2 to save the macro program code along with the compiled macro program.
libname myapps 'c:mymacroprograms';
options mstored sasmstore=myapps;
%macro reptitle(repprog) / store source
des='Standard Report Titles';
title “Bookstore Report &repprog”;
title2 “Processing Date: &sysdate SAS Version: &sysver”;
%mend reptitle;
If you want to view the code in the SAS log, submit the following statement:
%copy reptitle / library=myapps source;
The SAS log shows the results of submitting the %COPY statement.
9 %copy reptitle / library=myapps source;
%macro reptitle(repprog) / store source des='Standard Report Titles';
title “Bookstore Report &repprog”;
title2 “Processing Date: &sysdate SAS Version: &sysver”;
%mend reptitle;
If you want to save the code in a file called REPTITLE_SOURCE.SAS, submit the following %COPY statement.
%copy reptitle / library=myapps source
outfile='c:mymacroprograms eptitle_source.sas';
As mentioned earlier, the SECURE option on the %MACRO statement in conjunction with the STORE option encrypts the compiled macro program. The SECURE and SOURCE options are incompatible on the same %MACRO statement. Therefore, you must save a copy of your macro program code separately from the stored compiled macro program before you store and compile a macro program with the SECURE option.
Example 10.3: Encrypting a Stored Compiled Macro Program
Example 10.2 is modified in Example 10.3 so that the stored compiled macro program is secure and encrypted.
libname myapps 'c:mymacroprograms';
options mstored sasmstore=myapps;
%macro reptitle(repprog) / store secure
des='Standard Report Titles';
title “Bookstore Report &repprog”;
title2 “Processing Date: &sysdate SAS Version: &sysver”;
%mend reptitle;
Resolving Macro Program References When Using the Autocall Facility and the Stored Compiled Macro Facility
The autocall facility and the stored compiled macro facility increase the scope of the tasks that the macro processor can do for you. With these features, instead of explicitly submitting a macro program, you tell the macro processor where and how the macro program is stored. The macro processor understands that it should check these sources after looking within the SAS session for macro programs that were compiled during the session.
If the macro processor finds the macro program in your autocall library, it submits the macro program for compilation. When the macro processor finds the macro program in your SASMACR catalog, it submits for execution the compiled code that is stored in the catalog.
When you make autocall libraries and stored compiled macro programs available to your SAS session by enabling the options described above, the macro processor takes the steps in Figure 10.4 to resolve a macro program reference.
Figure 10.4 How the macro processor resolves calls to macro programs
