Functions and CALL Routines under OpenVMS

MODULE Function: OpenVMS

Calls a specific routine or module that resides in an image that can be shared.

Category:	External Files
OpenVMS 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. [cautionend]

CALL MODULEI <cntl>,module, arg-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 image routine before and after the shared image 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 shared image, and the routine name or ordinal value, separated by a comma. The routine name has to be externally callable. For example, the following C language link options file contains externally callable routines:

SYMBOL_VECTOR=(RTN_a=PROCEDURE, RTN_b=PROCEDURE)
RTN_a.O
RTN_b.O

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

You do not need to specify the shared image 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 (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, you can cause SAS and possibly your operating system to crash.

Details

The MODULE functions execute a routine module that resides in an external (outside SAS) shared image with the specified arguments arg-1 through arg-n. A shared image is an executable file that is created when using the /SHAREABLE qualifier with the LINK command. For more information about shared images, see OpenVMS Linker Utility Manual.

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 image 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 image routine.