| Programming Statements |
Modules with Arguments
In general, the following statements are true about modules with arguments:
- You can specify arguments as variable names.
- If you specify several arguments, you should use commas to separate them.
- If you have both output variables and input variables, it is good practice to list the output variables first.
- When a module is invoked with either a RUN or a CALL statement, the arguments can be any name, expression, or literal. However, when using arguments for output results, you should use variable names rather than expressions or literals.
When a module is executed with either a RUN or a CALL statement, the value for each argument is transferred from the global symbol table to the local symbol table. For example, consider the module MOD2 defined in the following statements. The first four statements are submitted in the global environment, and they define variables (A, B, C, and D): the values of these variables are stored in the global symbol table. The START statement begins definition of MOD2 and lists two variables (X and Y) as arguments. This creates a local symbol table for MOD2. All symbols used inside the module (X, Y, P, Q, and C) are in the local symbol table. There is also a one-to-one correspondence between the arguments in the RUN statement (A and B) and the arguments in the START statement (X and Y). Also note that A, B, and D exist only in the global symbol table, whereas X, Y, P, and Q exist only in the local symbol table. The symbol C exists independently in both the local and global tables. When MOD2 is executed with the statement run mod2(A,B);, the value of A is transferred from the global symbol table to X in the local table. Similarly, the value of B in the global table is transferred to Y in the local table. Because C is not an argument, there is no correspondence between the value of C in the global table and the value of C in the local table. When the module finishes execution, the final values of X and Y in the local table are transferred back to A and B in the global table.
> proc iml;
> a=10;
> b=20;
> c=30;
> d=90;
> start mod2(x,y); /* begin module */
> p=x+y;
> q=y-x;
> y=100;
> c=25;
> finish mod2; /* end module */
NOTE: Module MOD2 defined.
> run mod2(a,b);
> print a b c d;
A B C D
10 100 30 90
The PRINT statement prints the values
of variables in the global symbol table.
Notice that after the module is executed, the following conditions exist:
- A is still 10.
- B is changed to 100 since the corresponding argument Y was changed to 100 inside the module.
- C is still 30. Inside the module, the local symbol C was set equal to 25, but there is no correspondence between the global symbol C and the local symbol C.
- D is still 90.
Defining Function Modules
Functions are special modules that return a single value. They are a special type of module because modules can, in general, return any number of values through their argument list. To write a function module, include a RETURN statement that assigns the returned value to a variable. The RETURN statement is necessary for a module to be a function. You invoke a function module in an assignment statement, as you would a standard function.The symbol-table logic described in the preceding section also applies to function modules. The following is an example of a function module. In this module, the value of C in the local symbol table is transferred to the global symbol Z.
> proc iml;
> a=10;
> b=20;
> c=30;
> d=90;
> start mod3(x,y);
> p=x+y;
> q=y-x;
> y=100;
> c=40;
> return (c); /* return function value */
> finish mod3;
NOTE: Module MOD3 defined.
> z = mod3(a,b); /* call function */
> print a b c d z;
A B C D Z
10 100 30 90 40
Note the following about this example:
- A is still 10.
- B is changed to 100 because Y is set to 100 inside the module, and there is a one-to-one correspondence between B and Y.
- C is still 30. The symbol C in the global table has no connection with the symbol C in the local table.
- Z is set to 40, which is the value of C in the local table.
In the next example, you define your own function ADD for adding two arguments:
> proc iml;
> reset print;
> start add(x,y);
> sum=x+y;
> return(sum);
> finish;
NOTE: Module ADD defined.
> a={9 2,5 7};
A
9 2
5 7
> b={1 6,8 10};
B
1 6
8 10
> c=add(a,b);
C
10 8
13 17
Function modules can also be called inside each other. For example, in the following statements, the ADD function is called twice from within the first ADD function:
> d=add(add(6,3),add(5,5));
> print d;
D
19
Functions are resolved in this order:
- IML built-in function
- user-defined function module
- SAS DATA step function
Using the GLOBAL Clause
For modules with arguments, the variables used inside the module are local and have no connection with any variables of the same name existing outside the module in the global table. However, it is possible to specify that certain variables not be placed in the local symbol table but rather be accessed from the global table. Use the GLOBAL clause to specify variables you want shared between local and global symbol tables. The following is an example of a module that uses a GLOBAL clause to define the symbol C as global. This defines a one-to-one correspondence between the value of C in the global table and the value of C in the local table.
> proc iml;
> a=10;
> b=20;
> c=30;
> d=90;
> start mod4(x,y) global (c);
> p=x+y;
> q=y-x;
> y=100;
> c=40;
> d=500;
> finish mod4;
NOTE: Module MOD4 defined.
> run mod4(a,b);
> print a b c d;
A B C D
10 100 40 90
Note the following about this example:
- A is still 10.
- B is changed to 100.
- C is changed to 40 because it was declared global. The C inside the module and outside the module are the "same."
- D is still 90 and not 500, since D independently exists in the global and local symbol tables.
Nesting Modules with Arguments
For nested module calls, the concept of global and local symbol tables is somewhat different. Consider the following example:
> start mod1 (a,b);
> c=a+b;
> d=a-b;
> run mod2 (c,d);
> print c d;
> finish mod1;
NOTE: Module MOD1 defined.
> start mod2 (x,y);
> x=y-x;
> y=x+1;
> run mod3(x,y);
> finish mod2;
NOTE: Module MOD2 defined.
> start mod3(w,v);
> w=w#v;
> finish mod3;
NOTE: Module MOD3 defined.
The local symbol table of MOD1 in effect becomes the global table for MOD2. The local symbol table of MOD2 is the global table for MOD3. The distinction between the global and local environments is necessary only for modules with arguments. If a module (say, A) calls another module (say, B) which has no arguments, B shares all the symbols existing in A's local symbol table.
For example, consider the following statements:
> x=457;
> start a;
> print 'from a' x;
> finish;
> start b(p);
> print 'from b' p;
> run a;
> finish;
> run b(x);
P
from b 457
ERROR: Matrix X has not been set to a value.
Error occurred in module A
called from module B
stmt: PRINT
Paused in module A.
In this example, module A is called from module B. Therefore, the local symbol table of module B becomes the global symbol table for module A. Module A has access to all symbols available in module B. No X exists in the local environment of module B; thus no X is available in module A as well. This causes the error that X is unvalued.
Copyright © 2009 by SAS Institute Inc., Cary, NC, USA. All rights reserved.