Chapter Contents
Chapter Contents
Previous
Previous
Next
Next
Programming Statements

Modules with Arguments

In general, the following statements are true about modules with arguments:

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 Also note that, inside the module, the symbols A, B, and D do not exist. Outside the module, the symbols P, Q, X, and Y do not exist.

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: Again note that, inside the module, the symbols A, B, D, and Z do not exist. Outside the module, symbols P, Q, X, and Y do not exist.

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:

  1. IML built-in function
  2. user-defined function module
  3. SAS DATA step function
This means that you should not use a name for a function that is already the name of an IML built-in 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 using 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:

Also note that every module with arguments has its own local table; thus it is possible to have a global and many local tables. A variable can independently exist in one or more of these tables. However, a variable can be commonly shared between the global and any number of local tables when the GLOBAL clause is used.

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 occured 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.

Chapter Contents
Chapter Contents
Previous
Previous
Next
Next
Top
Top

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