SAS Functions and CALL Routines under Windows

MODULE Function: Windows

Calls a specific routine or module that resides in an external dynamic link library (DLL).

Category:	External Routines
Windows specifics:	all

Syntax
Details
See Also

Syntax

CALL MODULE(<cntl>,module,arg-1,arg-2. . . ,arg-n);

num=MODULEN(<cntl>,module,arg-1,arg-2...,arg-n);

char=MODULEC(<cntl>,module,arg-1...,arg-2,arg-n);

Note:

The following functions permit vector and matrix arguments; you can use them within the IML procedure. [cautionend]

CALL MODULEI <cntl>,modulearg-1,arg-2. . . ,arg-n);

num=MODULEIN(<cntl>,module,arg-1,arg-2. . .,arg-n)

char=MODULEIC(<cntl>,module,arg-1,arg-2. . .,arg-n);

cntl

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 MODULE function and to the requested DLL routine before and after the DLL routine is called. You can use this option to help diagnose problems that are 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 MODULE function generates is "Invalid argument to function," which is usually not enough information to determine the cause of the error.
Sx	uses x as a separator character to separate field definitions. You can then specify x in the argument list as its own character argument to serve as a delimiter for a list of arguments that you want to group together as a single structure. Use this option only if you do not supply an entry in the SASCBTBL attribute table. If you do supply an entry for this module in the SASCBTBL attribute table, you should use the FDSTART option in the ARG statement in the table to separate structures.
H	provides brief help information about the syntax of the MODULE routines, the attribute file format, and the suggested SAS formats and informats.

For example, the control string '*IS/' specifies that parameter lists be printed and that the string '/' is to be treated as a separator character in the argument list.

module

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 dynamic link library (DLL) and it must be externally callable. For example, the value 'KERNEL32,GetProfileString' specifies to load KERNEL32.DLL and to invoke the GetProfileString routine. Note that while the DLL name is not case sensitive, the routine name is based on the restraints of the routine's implementation language, so the routine name is case sensitive.

If the DLL supports ordinal-value naming, you can provide the DLL name followed by a decimal number, such as 'XYZ,30' .

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

You can specify module as a SAS character expression instead of as a constant; most often, though, you will pass it as a constant.

arg-1, arg-2, ...arg-n

are the arguments to pass to the requested routine. Use the proper attributes for the arguments (numeric arguments for numeric attributes and character arguments for character attributes).

CAUTION:: Be sure to use the correct arguments and attributes.
Using incorrect arguments or attributes for a DLL function can cause SAS, and possibly your operating system, to fail.

Details

The MODULE functions execute a routine module that resides in an external (outside SAS) dynamic link library with the specified arguments arg-1 through arg-n.

The MODULE call routine does not return a value, while the MODULEN and MODULEC functions return a number num or a character char, respectively. Which routine you use depends on the expected return value of the DLL function that you want to execute.

MODULEI, MODULEIC, and MODULEIN are special versions of the MODULE functions that permit vector and matrix arguments. Their return values are still scalar. You can invoke these functions only from PROC IML.

Other than this name difference, the syntax for all six routines is the same.

The MODULE function builds a parameter list by using the information in arg-1 to arg-n and by using a routine description and argument attribute table that you define in a separate file. Before you invoke the MODULE routine, you must define the fileref of SASCBTBL to point to this external file. You can name the file whatever you want when you create it.

This way, you can use SAS variables and formats as arguments to the MODULE function and ensure that these arguments are properly converted before being passed to the DLL routine.