Language Reference


EXECUTEFILE Call

CALL EXECUTEFILE (filename <, encoding>);

The EXECUTEFILE subroutine executes SAS/IML statements that are contained in a text file, which is called the source file. The statements in the source file can be SAS/IML statements or global SAS statements such as the TITLE statement. The statements in the source file do not appear in the SAS log.

The first argument to the EXECUTEFILE subroutine is a string literal, a character matrix that contains a valid file name, or a SAS fileref that points to a valid file. The argument can refer to an absolute path such as C:\Temp\commands.sas or a relative path such as .\commands2.sas . Relative paths depend on the current working directory for the SAS session.

The EXECUTEFILE subroutine accepts an optional second argument that specifies the encoding of the source file. You can use this argument when the encoding of the source file is different from the SAS session encoding. If you omit the second argument, an attempt is made to deduce the encoding of the source file automatically. SAS encoding strings and their usage are described in the chapter "Encoding Values in SAS Language Elements" in the SAS National Language Support: Reference Guide. Examples of valid values for the second argument include "UTF-8," "us-ascii," "latin2," and "ms-949."

The following DATA step creates a file called commands.sas in the current working directory:

filename ExeFile "./commands.sas";
data _null_;
   file ExeFile;
   put 'start MySqr(t);   ';
   put '   return( t##2 );';
   put 'finish;           ';
   put 'x = {1 2, 3 4};   ';
run;

The file commands.sas contains SAS/IML statements. It is created in the current working directory, assuming that you have permission to write to that directory. The statements define a matrix (x) and a module named MYSQR. After you use the EXECUTEFILE subroutine to execute the statements in the source file, you can refer to the matrix and call the module, as shown in the following example:

proc iml;
call executefile("commands.sas");
y = MySqr(x);
print x y;

Figure 25.123: Results of Executing SAS/IML Statements from a Source File

x   y  
1 2 1 4
3 4 9 16



Figure 25.123 shows that the statements in the source file were executed. The matrices and the module are available for use in subsequent SAS/IML statements.

In the preceding example, the statements that reference the x matrix are in the same calling environment (scope) as the EXECUTEFILE statement. In the following program, the EXECUTEFILE subroutine is called from inside a module:

proc iml;
start MyMod(a);
   call executefile("commands.sas");
   /* x is defined inside the module, but not outside */
   print x[label="x inside module"];
finish;
call MyMod(1);

show modules names;

Figure 25.124: Modules and Names Known at Main Scope

x inside module
1 2
3 4

Modules:                                                                        
  MYMOD                             MYSQR                                       
                                                                                
                                                                                
 SYMBOL   ROWS   COLS TYPE   SIZE                                               
 ------ ------ ------ ---- ------                                               
  Number of symbols = 0  (includes those without values)                        
                                                                                



Notice in Figure 25.124 that the matrix x is not known outside the module. However, the MYSQR module is known because all modules are defined at the main scope, as discussed in the section Nesting Module Definitions.

The EXECUTEFILE subroutine is similar to the %INCLUDE macro statement for including source code into a SAS program. However, the EXECUTEFILE subroutine parses and runs the source file at run time, whereas the %INCLUDE statement inserts the contents of a source file at parse time. One advantage of the EXECUTEFILE statement is that the name of the file does not need to be known until run time. In fact, the file itself does not need to exist until run time, as demonstrated by the DATA step in this section that creates the source file.

Some SAS/IML statements are not supported by the EXECUTEFILE subroutine. The file should not contain the PROC IML statement, the QUIT statement, or other statements that terminate the IML procedure.

In SAS/IML 14.1, there are differences between the implementation of the EXECUTEFILE statement in PROC IML and in the IMLPlus language:

  • In PROC IML, the source file should not contain the SUBMIT and ENDSUBMIT statements. An alternative is to use the %INCLUDE statement to include SUBMIT blocks.

  • In IMLPlus, filerefs are not supported.

  • In IMLPlus, modules that are defined inside a source file are not recognized by the parser until after the EXECUTEFILE subroutine is run. SAS plans to remove this restriction in a future release.

If a statement in the source file contains an error, an error message appears in the SAS log. However, PROC IML concatenates the source file into a single text string, so the error is always reported as being on "Line 1." For some kinds of errors, the SAS log displays the message NOTE: Paused in module _EXECUTEFILE. If you see this note, submit the RESUME statement to restore program control to the main scope.