LoadExternalModule

LoadExternalModule (const char pathName[]);

Purpose

Loads an external object module file.

You do not need to list the file in your project or load it as an instrument module.

The file can be an object file (.obj), a library file (.lib), or a DLL import library (.lib). You cannot load a DLL directly. You can compile object and library modules with LabWindows/CVI or with an external compilerexternal compiler.

Linux Only shared object files (.so) are supported.

All files must conform to the rules for loadable compiled modulesloadable compiled modules.

By loading external object modules, you can execute code that is not in your project and not in a loaded instrument module. You can load the external modules only when you need them and unload them when you no longer need them.

After you load a module, you can execute its code in one of two ways:

You can use LoadExternalModule on a source file (.c) that is part of the current project or on a source file that you load as the program for an instrument module. This allows you to develop your module in source code form and test it using the LabWindows/CVI debugging capabilities. After you finish testing your module and compile it into an external object or library file, you must change the pathname in the call to LoadExternalModule in your application source code. You do not have to make any other modifications to load the module.

Avoid calling LoadExternalModule on a file in the project when you plan to link your program in an external compiler. The LabWindows/CVI Utility Library does not know the locations of symbols in executables or DLLs linked in external compilers. To provide this information, select Build»External Compiler Support in the Workspace window and use the Other Symbols section to create an object module that contains a table of symbols you want to find using GetExternalModuleAddr. If you use this method, pass the empty string "" to LoadExternalModule for the module pathname.

If successful, LoadExternalModule returns an integer module ID that you can pass to RunExternalModule, GetExternalModuleAddr, and UnloadExternalModule. If unsuccessful, LoadExternalModule returns a negative error code.

Differences Between DLLs and Objects or Libraries

An important difference exists between loading an object or static library module and loading a DLL through an import library. DLLs are prelinked; that is, when you load a DLL, the loader does not need to resolve any external references. Object and static library modules, on the other hand, have unresolved external references. LoadExternalModule resolves them using symbols defined in the project or exported by object, static library, or import library modules that you have already loaded using LoadExternalModule. This is true even when you call LoadExternalModule in a DLL. LoadExternalModule does not use symbols in a DLL to resolve external references unless those symbols have been exported in the import library.

If you want to load an object or library module from a DLL and have the external references resolved using symbols in the DLL that have not been exported through the import library, you must call LoadExternalModuleEx rather than LoadExternalModule.

Using LoadExternalModule on Source Files from the Interactive Window

When you load a source file using LoadExternalModule from the Interactive window, you must enable either the Force loaded instrument drivers into Interactive window or Force project files into Interactive window options in the Environment dialog box, depending on whether the source file is in the project or is loaded as an instrument driver. To access the Environment dialog box, select Options»Environment in the Workspace window.

Example

void (*funcPtr) (char buf[], double dval, int *ival);
int module_id;
int status;
char buf[100];
double dval;
int ival;
char *pathname;
char *funcname;
pathname = "EXTMOD.OBJ";
funcname = "my_function";
module_id = LoadExternalModule (pathname);
if (module_id < 0)

FmtOut ("Unable to load %s\n", pathname);

else {

funcPtr = GetExternalModuleAddr (module_id, funcname, &status);
if (funcPtr == NULL)

FmtOut ("Could not get address of %s\n", funcname);

else

(*funcPtr) (buf, dval, &ival);

}

Parameters

Input
Name Type Description
pathName const char [] Relative or absolute pathname of the module to load.

If pathname is a simple filename, such as module.obj, LoadExternalModule takes the following steps to find the file:

  1. First looks for the file in the project list.
  2. Then looks for the file in the directory that contains the currently loaded project.

If pathname is a relative pathname with one or more directory paths (such as dir\module.obj), LoadExternalModule creates an absolute pathname by appending the relative pathname to the directory that contains the currently loaded project.

If pathname is for a DLL import library, LoadExternalModule finds the DLL using the DLL name embedded in the import library and the standard Windows DLL search algorithm.

Linux You must pass the absolute path of the .so file, or the .so file must be in one of the paths specified in the system file /etc/ld.so.conf. Make sure to run the ldconfig command to update the /etc/ld.so.conf file if you add a path.

Return Value

Name Type Description
module_id integer ID of the loaded module.

You can pass this value to RunExternalModule, GetExternalModuleAddr, GetExternalModuleAddrEx, UnloadExternalModule, and ReleaseExternalModule.

If LoadExternalModule is successful, the value is greater than or equal to zero. If LoadExternalModule fails, the value is one of the following return codes.

Code Description
-1 Out of memory.
-2 File not found.
-4 Invalid file format.
-6 Invalid pathname.
-7 Unknown file extension.
-8 Cannot open file.
-26 Module already loaded with different calling module handle. Occurs when one of the following is true:

  • You call LoadExternalModuleEx to load the same module as a previous call to LoadExternalModuleEx, but the callingModuleHandle parameters differ.
  • You call LoadExternalModule to load the same module as a previous call to LoadExternalModuleEx in which the callingModuleHandle referred to a DLL.
  • You call LoadExternalModuleEx to load the same module as a previous call LoadExternalModule and the callingModuleHandle parameter in this call refers to a DLL.
-28 Module you loaded in Borland mode within the LabWindows/CVI development environment contains uninitialized global variables that are also defined in other modules.