SAS/IML 13.1 includes a handy function for programmers who write a lot of modules. The PARENTNAME function obtains the name of the symbol that was passed in as a parameter to a user-defined module.

How is this useful? Well, suppose that you want to create a SAS/IML module that prints simple descriptive statistics about a data vector, similar to this call to PROC MEANS:

proc means nolabels data=sashelp.cars N mean std Q1 median Q3;
var MPG_City;
run;

Look at the heading of the table. The heading displays the name of the numerical variable that the statistics summarize. If you want to display this table from within a SAS/IML module, the module somehow needs to discover the name of the data vector that was passed into the module. That is, it needs information from the parent (or calling) environment.

This problem was resolved in SAS/IML 13.1 by introducing the PARENTNAME function. The following SAS/IML statements create a module that prints descriptive statistics for a data vector. The module calls the PARENTNAME function to discover the name of the variable that was passed via the y parameter. The name is used to create a heading for the table:

proc iml;
/* create function that prints simple descriptive statistics */
start DescStats(y);            /* the local variable is "y" */
   varName = ParentName("y");  /* find the name of "y" in calling environment */
   stats = {"N" "Mean" "Std Dev" "Lower Quartile" "Median" "Upper Quartile"};
   N = countN(y);  mean = mean(y);  std = std(y);
   call qntl(quartiles, y, {0.25 0.5 0.75});
   print (N || mean || std || quartiles`)[label=varName colname=stats];
finish;
 
/* test module on a variable from Sashelp.Cars */
use sashelp.cars; read all var {"MPG_City"}; close sashelp.cars;
 
run DescStats( MPG_City );    /* the name of variable passed in is "MPG_City" */

I think this is a very cool feature. The PARENTNAME function returns the name of the variable that was passed in as the y parameter. The call returns the string "MPG_City". That string is then used in the LABEL= option for the PRINT statement. The result is that the table displays the name of the MPG_City variable in the heading.

The PARENTNAME function is used internally by the modules that create standard statistical graphics in SAS/IML. For example, the following statement creates a histogram of the MPG_City variable and labels the horizontal axis with the name of the variable:

call histogram( MPG_City );

What happens if the argument to the DescStats module is a temporary variable? In this case, the PARENTNAME function returns a blank string. Try running the statement call histogram(MPG_City+5) to see the results. If necessary, a programmer can detect that the PARENTNAME function returned a blank string and act accordingly. For example, when the SAS/IML statistical graphics routines encounter a temporary variable, they display "X" or "Y" as the label for the graph axis.