38.14. $invokeModule

$invokeModule invokes the MODULE (i.e., binds then unbinds it, like MAINEX) named by the first (blank- or tab-delimited) word of moduleOrFileNameAndArgs (or contained in the file named by the same word) with the arguments composing the remainder of moduleOrFileNameAndArgs (arguments are discussed in more detail under the entry for $getCommandLine). It returns FALSE if a bound data section already exists for the MODULE or if the MODULE cannot be invoked (e.g., because the object MODULE cannot be found); if it returns FALSE, it sets msg to an error message describing why it failed.

The first word of moduleOrFileNameAndArgs is assumed to be a file name if it is not a valid MODULE identifier. The file name may contain a device MODULE specification. The first word of moduleOrFileNameAndArgs may be terminated with a comma, in which case MAINEX subcommands are read from cmdFile (see Chapter 21 of the MAINSAIL Utilities User's Guide).

The valid ctrlBits bits are the same as for bind, with the same meanings.

If the call to bind was successful (i.e., if $invokeModule returns TRUE), bindCpuTime is set to the number of CPU time units (see the description of $cpuTimeResolution) used by the call to bind; this time includes the execution of the INITIAL PROCEDURE of the MODULE.

When an unhandled exception causes the INITIAL PROCEDURE of a MODULE invoked with $invokeModule to be aborted, $invokeModule unbinds the MODULE.