Functions and CALL Routines

CALL MODULE Routine

Calls an external routine without any return code.

Category:

External Routines

Syntax
Arguments
Details
Comparisons
Examples
	Example 1: Using the CALL MODULE Routine
	Example 2: Using the MODULEIN Function in the IML Procedure
	Example 3: Using the MODULEN Function
See Also

Syntax

CALL MODULE(<cntl-string,>module-name<,argument-1, ..., argument-n>);

Arguments

cntl-string

is an optional control string whose first character must be an asterisk (*), followed by any combination of the following characters:

I	prints the hexadecimal representations of all arguments to the CALL MODULE routine. You can use this option to help diagnose problems caused by incorrect arguments or attribute tables. If you specify the I option, the E option is implied.
E	prints detailed error messages. Without the E option (or the I option, which supersedes it), the only error message that the CALL MODULE routine generates is "Invalid argument to function," which is usually not enough information to determine the cause of the error. The E option is useful for a production environment, while the I option is preferable for a development or debugging environment.
H	provides brief help information about the syntax of the CALL MODULE routine, the attribute file format, and suggested SAS formats and informats.

module-name

is the name of the external module to use.

argument

is one or more arguments to pass to the requested routine.

CAUTION:: Be sure to use the correct arguments and attributes.
If you use incorrect arguments or attributes, you can cause the SAS System, and possibly your operating system, to fail.

Details

The CALL MODULE routine executes a routine module-name that resides in an external library with the specified arguments.

CALL MODULE builds a parameter list using the information in the arguments and a routine description and argument attribute table that you define in a separate file. The attribute table is a sequential text file that contains descriptions of the routines that you can invoke with the CALL MODULE routine. The purpose of the table is to define how CALL MODULE should interpret its supplied arguments when it builds a parameter list to pass to the external routine. The attribute table should contain a description for each external routine that you intend to call, and descriptions of each argument associated with that routine.

Before you invoke CALL MODULE, you must define the fileref of SASCBTBL to point to the external file that contains the attribute table. You can name the file whatever you want when you create it. This way, you can use SAS variables and formats as arguments to CALL MODULE and ensure that these arguments are properly converted before being passed to the external routine. If you do not define this fileref, CALL MODULE calls the requested routine without altering the arguments.

CAUTION:: Using the CALL MODULE routine without a defined attribute table can cause the SAS System to fail or force you to reset your computer.
You need to use an attribute table for all external functions that you want to invoke.

Comparisons

The two CALL routines and four functions share identical syntax:

The MODULEN and MODULEC functions return a number and a character, respectively, while the routine CALL MODULE does not return a value.
The CALL MODULEI routine and the functions MODULEIC and MODULEIN permit vector and matrix arguments. Their return values are scalar. You can invoke CALL MODULEI, MODULEIC, and MODULEIN only from the IML procedure.

Examples

Example 1: Using the CALL MODULE Routine

This example calls the xyz routine. Use the following attribute table:

routine xyz minarg=2 maxarg=2;
arg 1 input num byvalue format=ib4.;
arg 2 output char format=$char10.;

The following is the sample SAS code that calls the xyz function:

data _null_;
   call module('xyz',1,x);
run;

Example 2: Using the MODULEIN Function in the IML Procedure

This example invokes the changi routine from the TRYMOD.DLL module on a Windows platform. Use the following attribute table:

routine changi module=trymod returns=long;
arg 1 input num format=ib4. byvalue;
arg 2 update num format=ib4.;

The following PROC IML code calls the changi function:

proc iml;
   x1=J(4,5,0);
   do i=1 to 4;
      do j=1 to 5;
         x1[i,j]=i*10+j+3;
      end;
   end;
   y1=x1;
   x2=x1;
   y2=y1;
   rc=modulein('*i','changi',6,x2);

Example 3: Using the MODULEN Function

This example calls the Beep routine, which is part of the Win32 API in the KERNEL32 Dynamic Link Library on a Windows platform. Use the following attribute table:

routine Beep
   minarg=2
   maxarg=2
   stackpop=called
   callseq=byvalue
   module=kernel32;
arg 1 num format=pib4.;
arg 2 num format=pib4.;

Assume that you name the attribute table file 'myatttbl.dat'. The following is the sample SAS code that calls the Beep function:

filename sascbtbl 'myatttbl.dat';
data _null_;
   rc=modulen("*e","Beep",1380,1000);
run;

The previous code causes the computer speaker to beep.