Chapter Contents


SAS Macro Language: Reference

Writing Portable Macros

If your code runs in two different environments, you have essentially doubled the worth of your development effort. But portable applications require some planning ahead of time. For more details on any host-specific feature of the SAS System, refer to the SAS documentation for your host environment.

Using Portable SAS Language Functions with %SYSFUNC

You can use the %SYSFUNC macro function to access SAS language functions to perform most host-specific operations, such as opening or deleting a file. You can find more information on these and other functions in the description of %SYSFUNC in Chapter 13.

Using %SYSFUNC to access portable SAS language functions can save you a lot of macro coding (and is therefore not only portable but also more efficient). Portable SAS Language Functions and Their Uses lists some common host-specific tasks and the functions that perform those tasks.

Portable SAS Language Functions and Their Uses
Task SAS Language Function(s)
assign and verify existence of fileref and physical file FILENAME, FILEREF, PATHNAME
open a file FOPEN, MOPEN
verify existence of a file FEXIST, FILEEXIST
list available files FILEDIALOG
get information about afile FINFO, FOPTNAME, FOPTNUM
write data to a file FAPPEND, FWRITE
read from a file FPOINT, FREAD, FREWIND, FRLEN
close a file FCLOSE
delete a file FDELETE
open a directory DOPEN
return information about a directory DINFO, DNUM, DOPTNAME, DOPTNUM, DREAD
close a directory DCLOSE
read a host-specfic option GETOPTION
interact with the File Data Buffer (FDB) FCOL, FGET, FNOTE, FPOS, FPUT, FSEP
assign and verify librefs LIBNAME, LIBREF, PATHNAME
get information about executed host environment commands SYSRC

Note:   Of course, you can also use other functions, such as ABS, MAX, and TRANWRD, with %SYSFUNC. A few SAS language functions are not available with %SYSFUNC; see Chapter 13 for more details.  [cautionend]

Example Using %SYSFUNC

The following program deletes the file identified by the fileref MYFILE:

%macro testfile(filrf);
   %let rc=%sysfunc(filename(filrf,physical-filename));
   %if &rc = 0 and %sysfunc(fexist(&filrf)) %then
      %let rc=%sysfunc(fdelete(&filrf));
   %let rc=%sysfunc(filename(filrf));
%mend testfile;


Using Portable Automatic Variables with Host-specific Values

The portable automatic macro variables are available under all host environments, but the values are determined by each host. Portable Automatic Macro Variables with Host-specific Results lists the portable macro variables by task. The "Type" column tells you if the variable can be changed (Read/Write) or can only be inspected (Read Only).

Portable Automatic Macro Variables with Host-specific Results
Task Automatic Macro Varible Type
list the name of the current graphics device on DEVICE=. SYSDEVIC Read/Write
list of the mode of execution (values are FORE or BACK). Some host environments allow only one mode, FORE. SYSENV Read Only
list the name of the currently executing batch job, userid, or process. For example, on UNIX, SYSJOBID is the PID. SYSJOBID Read Only
list the last return code generated by your host environment, based on commands executed using the X statement in open code, the X command in display manager, or the %SYSEXEC (or %TSO or %CMS) macaro statements.

The default value is 0.

SYSRC Read/Write
list the abbreviation of the host environment you are using. SYSSCP Read Only
list a more detailed abbreviation of the host environment you are using. SYSSCPL Read Only
retrieve a character string that was passed to the SAS System by the SYSPARM= system option. SYSPARM Read/Write

Examples Using SYSSCP and SYSSCPL

The macro DELFILE uses the value of SYSSCP to determine the platform that is running SAS and deletes a file with the TMP file extension (or file type). FILEREF is a macro parameter that contains a filename. Because the filename is host-specific, making it a macro parameter enables the macro to use whatever filename syntax is necessary for the host environment.

%macro delfile(fileref);
   %if  /* Unix */sysscp=HP 800 or &sysscp=HP 300 %then
            %sysexec rm &fileref..TMP;

   %else %if            /* VMS */sysscp=VMS %then
            %sysexec %str(DELETE &fileref..TMP;*);
   %else %if  /* PC platforms */sysscp=OS2 or &sysscp=WIN %then
            %sysexec DEL &fileref..TMP;

   %else %if  /* CMS */sysscp=CMS %then
            %sysexec ERASE &fileref  TMP A;
%mend delfile;

Here is a call to the macro DELFILE in a PC environment that deletes a file named C:\SAS\SASUSER\DOC1.TMP:


In this program, note the use of the portable %SYSEXEC statement to carry out the host-specific operating system commands.

Now, suppose you know your macro application is going to run on some flavor of Microsoft Windows. It could be Windows NT, Windows 95, or Windows 3.1. Although these host environments use similar host environment command syntax, some terminology differs between them, different system options are available, and so on. The SYSSCPL automatic macro variable provides information about the name of the host environment, similar to the SYSSCP automatic macro variable. However, SYSSCPL provides more information and enables you to further tailor your macro code. Here is an example using SYSSCPL.

%macro whichwin;  /* Discover which OS is running. */
   %if &sysscpl=WIN_32S %then
         %let flavor=32-bit version of Windows;
         %let term=directory;

   %else %if &sysscpl=WIN_95 %then
         %let flavor=Windows 95;
         %let term=folder;

   %else %if &sysscpl=WNT_NT %then
         %let flavor=Windows NT;
         %let term=folder;

   %else %put *** You must be running a 16-bit version of Windows. ***;
%mend whichwin;
%macro direct;  /* Issue directions to the user. */
   %put This program is running under &flavor;
   %put Please enter the &term your SAS files are stored in:;
   .   more macro code
%mend direct;

Example Using SYSPARM

Suppose the SYSPARM= system option is set to the name of a city. That means the SYSPARM automatic variable is set to the name of that city. You can use that value to subset a data set and generate code specific to that value. Simply by making a small change to the command that invokes SAS (or to the configuration SAS file), your SAS job will perform different tasks.

/* Create a data set, based on the value of the */
/* SYSPARM automatic variable. */
/* An example data set name could be MYLIB.BOSTON. */
data mylib.&sysparm;
   set mylib.alltowns;
      /* Use the SYSPARM SAS language function to */
      /* compare the value (city name) */
      /* of SYSPARM to a data set variable. */
   if town=sysparm();

When this program executes, you end up with a data set that contains data for only the town you are interested in--and you can change what data set is generated before you start your SAS job.

Now suppose you want to further use the value of SYSPARM to control what procedures your job uses. The following macro does just that:

%macro select;
   %if %upcase(&sysparm) eq BOSTON %then
         proc report ... more SAS code;
            title "Report on &sysparm";

   %if %upcase(&sysparm) eq CHICAGO %then
         proc chart ... more SAS code;
            title "Growth Values for &sysparm";
   .  /* more macro code */
%mend select;


The value of the SYSPARM automatic macro variable is the same as the value of the SYSPARM= system option, which is equivalent to the return value of the SAS language function SYSPARM. The default value is null. Because you can use the SYSPARM= system option at SAS invocation, you can set the value of the SYSPARM automatic macro variable before your SAS session begins.

SYSRC Details

The value of the SYSRC automatic macro variable contains the last return code generated by your host environment. The code returned is based on commands you execute using the X statement in open code, the X command in display manager, or the %SYSEXEC macro statement (as well as the nonportable %TSO and %CMS macro statements). Use the SYSRC automatic macro variable to test the success or failure of a host environment command.

Note:   While supported on all host environments in that it does not generate an error message in the SAS log, the SYSRC automatic macro variable is not useful under all host environments. For example, under some host environments, the value of this variable is always 99, regardless of the success or failure of the host environment command. Check the SAS companion for your host environment to see if the SYSRC automatic macro variable is useful for your host environment.  [cautionend]

Macro Language Elements With System Dependencies

Several macro language elements are host-specific, including the following:

any language element that relies on the sort sequence
An expression that compares character values uses the sort sequence of the host environment. Examples of such expressions include %DO, %DO %UNTIL, %DO %WHILE, %IF-%THEN, and %EVAL.

For example, consider the following program:

%macro testsort(var);
   %if &var < a %then %put *** &var is less than a ***;
   %else %put *** &var is greater than a ***;
%mend testsort;

     /* Invoke the macro with the number 1 as the parameter. */

On EBCDIC systems, such as MVS, CMS, and VSE, this program causes the following to be written to the SAS log:

*** 1 is greater than a ***

But on ASCII systems (such as OS/2, OpenVMS, UNIX, or Windows), the following is written to the SAS log:

*** 1 is less than a ***

The names and number of function keys are different on each operating system.

The MSYMTABMAX system option specifies the maximum amount of memory available to the macro variable symbol tables. If this value is exceeded, the symbol tables are stored in a WORK file on disk.

The MVARSIZE system option specifies the maximum number of bytes allowed for any macro variable stored in memory. If this value is exceeded, the macro variable is stored in a WORK file on disk.

The default delimiters that the %SCAN and %QSCAN functions use to search for words in a string are different on ASCII and EBCDIC systems. The default delimiters are
ASCII systems blank . < ( + & ! $ * ) ; ^ - / , % |
EBCDIC systems blank . < ( + | & ! $ * ) ; ¬ - / , % | ¢

The %SYSEXEC, %TSO, and %CMS macro statements enable you to issue an host environment command.

On some host environments, the %SYSGET function returns the value of host environment variables and symbols.

The SYSPARM= system option can supply a value for the SYSPARM automatic macro variable at SAS invocation. It is useful in customizing a production job. For example, to create a title based on a city as part of noninteractive execution, the production program might contain the SYSPARM= system option in the SAS configuration file or the command that invokes SAS. See SYSPARM Details for an example using the SYSPARM= system option in conjunction with the SYSPARM automatic macro variable.

The SASMSTORE= system option specifies the location of stored compiled macros.

The SASAUTOS= system option specifies the location of autocall macros.

Host-Specific Macro Variables

Some host environments create unique macro variables. Host-specific Macro Variables for MVS, Host-specific Macro Variables for OpenVMS, and Host-specific Macro Variables for the Macintosh list some commonly used host-specific macro variables. Additional host-specific macro variables may be available in future releases. See your SAS companion for more details.

Host-specific Macro Variables for MVS
Variable Name Description
SYS99ERR SVC99 error reason code
SYS99INF SVC99 info reason code
SYS99MSG YSC99 text message corresponding to the SVC error or info reason code
SYS99R15 SVC99 return code
SYSJCTID value of the JCTUSER field in the JCT control block
SYSJMRID value of the JMRUSEID field in the JCT control block
SYSUID the TSO userid associated with the SAS session

Host-specific Macro Variables for OpenVMS
Variable Name Description
VMSSASIN value of the SYSIN= system option or the name of the noninteractive file that was submitted

Host-specific Macro Variables for the Macintosh
Variable Name Description
SYSSTNAM step name
SYSETIME elapsed time
SYSFRMEM free memory available
SYSBFTRY number of attempts to access data in a host buffer used for SAS files
SYSBFHIT number of successful attempts to access data in a host buffer
SYSXRDS number of reads to external files
SYSXWRS number of writes to external files
SYSXBRD number of bytes read from external files
SYSBWR number of bytes written to external files
SYSXOPNS number of opens for external files
SYSSRDS number of reads to SAS files
SYSSWRS number of writes to SAS files
SYSSBRD number of bytes read from SAS files
SYSSBWR number of bytes written to SAS files
SYSSOPNS number ofopens for SAS files

Naming Macros and External Files for Use with the Autocall Facility

When naming macros that will be stored in an autocall library, you should consider the following:

Chapter Contents



Top of Page

Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.