Functions and CALL Routines under UNIX

CALL MODULE Routine: UNIX

Calls a specific routine or module that resides in a shared executable library.

Category:	External Files
UNIX 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 only within the IML procedure (See the documentation for SAS/IML for more information.): [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 shared library routine before and after the shared library 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. The module can be specified as a shared library and the routine name or ordinal value, separated by a comma. You do not need to specify the shared library 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).

The module must reside in a shared library, and it must be externally callable. Note that while the shared library 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 shared library supports ordinal-value naming, you can provide the shared library name followed by a decimal number, such as 'XYZ,30'.

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 (that is, numeric arguments for numeric attributes and character arguments for character attributes).

CAUTION:: Be sure to use the correct arguments and attributes.
If you use incorrect arguments or attributes for a shared library function, you can cause SAS to crash, or you will see unexpected results.

Details

The MODULE functions execute a routine module that resides in an external (outside SAS) shared 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 shared library 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 shared library routine.

CAUTION:: Using the MODULE function without defining an attribute table can cause SAS to crash, produce unexpected results, or result in severe errors.
You need to use an attribute table for all external functions that you want to invoke.