Chapter Contents

Previous

Next

CALL MODULE

Category:

Dynamic Link Library

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 and to the requested DLL routine before and after the DLL routine is called. 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, specified as a DLL name and the routine name or ordinal value, separated by a comma. The module must reside in a DLL and must be externally callable.

Note:    The DLL name is not case-sensitive, but the routine name is case-sensitive, as it is based on the restraints of the routine's implementation language.  

Tip:	If the DLL supports ordinal-value naming, you can provide the DLL name followed by a decimal number, such as 'XYZ,30'.
Tip:	You do not need to specify the DLL name if you specified the MODULE attribute for the routine in the SASCBTBL attribute table, as long as the routine name is unique (that is, no other routines have the same name in the attribute file).
Tip:	You can specify module-name as a SAS character expression instead of as a constant; most often, though, you pass it as a constant.
Example:	Specify the value 'KERNEL32,GetProfileString' for module-name to load KERNEL32.DLL and invoke the GetProfileString routine.

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 for a DLL function, 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 (non-SAS-System) dynamic link library (DLL) 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 (or other DLL functions or CALL routines). 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 call DLL routine. The attribute table should contain a description for each DLL 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 DLL routine. If you do not define this fileref, CALL MODULE calls the requested DLL routine without altering the arguments.

For more information on the attribute table, see SAS Language Reference: Concepts.

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

Two DLL CALL routines and four DLL 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. 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 USER32 Dynamic Link Library. Use the following attribute table:

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

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

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

The previous code causes the computer speaker to beep.

See Also

CALL Routine: CALL MODULEI

Functions: MODULEC MODULEIC MODULEIN MODULEN

Chapter Contents

Previous

Next

Top of Page

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