LoadExternalModule
int LoadExternalModule (const char pathname[]);
Purpose
 |
Note This class of functions is deprecated. National Instruments recommends that you instead use the Windows SDK functions LoadLibrary and GetProcAddress to load external modules. These functions allow you to load Windows DLLs, but not compiled object modules or libraries. |
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.
|
Note This function is not supported for 64-bit applications. |
You can compile object and library modules with LabWindows/CVI or with an external compilerexternal compiler. However, depending on which version of the external compiler you use, the call to GetExternalModuleAddr might not succeed, if the module you are loading contains references to symbols that might be implemented differently in the compiler that compiled the module, and the compiler that linked your application. The exact set of symbols can vary between compilers, but they typically do not include the more commonly used functions.
(Linux) Only shared object files (.so) are supported on Linux.
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 obtain pointers to functions in the module by calling GetExternalModuleAddr. Then, you can call the module functions through the function pointers.
- You can call RunExternalModule. This requires that the module contain a function with a pre-defined name and prototype. The function serves as the entry point to the module.
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 Code
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:
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 | ||||||||||||||||
| moduleID | int | 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.
|
Additional Information
Library: Utility Library
Include file: utility.h
LabWindows/CVI compatibility: LabWindows/CVI 3.0 and later