What is the best way to share SAS/IML functions with your colleagues? Give them the source code? Create a function library that they can use? This article describes three techniques that make your SAS/IML functions accessible to others.
As background, remember that you can define new functions and subroutines in the SAS/IML language, and that these functions are generically called modules. You can use the STORE statement to store modules in a library, and the LOAD statement to load modules from a library.
Option 1: Sharing the raw definitions
To share the module source code, create a file that contains the function definitions. Put the file in a publically accessible location on your network. Your colleagues can use the SAS %INCLUDE statement to insert the definitions into their PROC IML sessions. For example, suppose that you create a file named Func_Defs.sas that contains the following function definitions:
/* contents of Func_Defs.sas */ start func1(x); return(1); finish; start func2(x); return(2); finish; start func3(x); return(3); finish;
Notice that the Func_Defs.sas file does not contain a PROC IML statement. Therefore your colleagues must use the %INCLUDE statement after the PROC IML statement, as follows:
proc iml; %include "C:\<path>\Func_Defs.sas"; y1=func1( 1:3 ); /* call any function in Func_Defs.sas */
The advantage of this approach is its simplicity. A disadvantage is that this approach is monolithic. Suppose there are 100 functions defined in the file. Your colleague's program must parse all 100 functions. All functions are kept in memory, even if he intends to use only one function. This isn't a big deal on modern systems that have plenty of RAM, but it isn't optimally efficient either.
Another disadvantage is that the functions have to be %INCLUDEd (and parsed) by every PROC IML session that wants to use them. The next section shows a more efficient approach that parses the functions once.
Summary: Store definitions. Use %INCLUDE in every PROC IML session that wants to use the functions.
Option 2: Creating a temporary module library
It is not much harder to create a temporary library in compiled form. In this approach, you create a file named Func_TempLib.sas that defines and stores the function definitions, as follows:
/* contents of Func_TempLib.sas */ proc iml; start func1(x); return(1); finish; start func2(x); return(2); finish; start func3(x); return(3); finish; store module=_all_; quit;
Notice that the Func_TempLib.sas file begins and ends a PROC IML session. Therefore it should be included into a SAS session before you start your own PROC IML session. The statements in the file parse the functions, store them (in compiled form) in the default SAS/IML storage library, and then exit PROC IML. Your colleagues can use the %INCLUDE statement to execute the program statements, as follows:
%include "C:\<path>\Func_TempLib.sas"; /* create the library */ proc iml; load module=_all_; y1=func1( 1:3 ); /* call any function in library */
The LOAD statement reads the compiled version of the functions into memory. If you use MODULE=_ALL_, then all modules are read from the storage library. However, if you know that you only intend to use a few functions, you can load just those functions:
load module=(func1 func2);
I call this approach the "temporary library" approach because by default PROC IML stores the library in the WORK directory. This library persists until you end your SAS session. This means that the functions are parsed and stored once, but can be loaded and used by many PROC IML sessions until you exit SAS.
Summary: Use %INCLUDE once, which creates the function library. Use LOAD in any PROC IML session that wants to use the functions. The library vanishes when you exit SAS.
Option 3: Creating a permanent module library
This approach is similar to the previous, except that you create a permanent library of modules. This approach is best when there is a team of programmers that are sharing a common set of functions. You can create a module library in a central location that everyone can access.
For example, suppose your administrator has set up a permanent SAS libref called FUNCLIB. The libref points to a directory on a networked drive that all programmers on your team can access. Create a file named Func_Lib.sas that defines and stores the function definitions in that permanent libref, as follows:
/* contents of Func_Lib.sas */ proc iml; start func1(x); return(1); finish; start func2(x); return(2); finish; start func3(x); return(3); finish; reset storage=FUNCLIB.LIBA; store module=_all_; quit;
The RESET STORAGE statement specifies that the functions should be stored in a library called LIBA, which is in the permanent libref FUNCLIB. A single libref can contain multiple libraries, such as LIBB, LIBC, and LIBD.
When a programmer on the team wants to use a function in FUNCLIB.LIBA, he can use the RESET STORAGE statement prior to loading the modules:
proc iml; reset storage=FUNCLIB.LIBA; load module=_all_; /* or load module=(func1 func2); */
Notice that there is no %INCLUDE statement. The functions are defined and stored one time by a team member who has write permissions to the FUNCLIB libref. The rest of the team simply uses the RESET STORAGE statement so that the LOAD statement loads the functions from the shared library.
Summary: Store modules in a permanent library. Use the RESET STORAGE and LOAD statements to read the functions into any PROC IML session. The function library persists across SAS sessions.
In conclusion, whether you want to use the simple %INCLUDE mechanism or create and maintain permanent libraries that are accessible by many programmers, the SAS/IML language provides options for managing libraries of related functions in PROC IML.
Does your organization maintain a library of SAS/IML functions? Do you have an alternative way to manage it? Let me know in the comments.