LINKIMAGE merges routines written in other languages with IDL at run-time. Each call to LINKIMAGE defines a new system procedure or function by specifying the routine's name, the name of the file containing the code, and the entry point name. The name of your routine is added to IDL's internal system routine table, making it available in the same manner as any other IDL built-in routine. LINKIMAGE can also be used to add graphics device drivers.
CAUTION: Using LINKIMAGE requires intimate knowledge of the internals of IDL, and is not for use by the novice user. We recommend use of CALL_EXTERNAL, which has a simpler interface, instead of LINKIMAGE unless your application specifically requires it. To use LINKIMAGE, you should be familiar with the material in the IDL Advanced Development Guide .
LINKIMAGE uses the dynamic linking interface supported by the operating system to do its work. Programmers should be familiar with the services supported by their system in order to better understand LINKIMAGE:
dlopen()interface to the dynamic linker in all cases except for HP-UX (which uses
shl_load()) and AIX (which uses
LoadLibrary()to load a 32-bit, Win32 DLL.
FindSymbol()to load shared libraries.
NOTE: Modules must be merged via LINKIMAGE before other procedures and functions that call them are compiled, or the compilation of those routines will fail. Note that because routines merged via LINKIMAGE are considered built-in routines by IDL, declaring the routine with the FORWARD_FUNCTION statement will not eliminate this restriction.
A string containing the IDL name of the function, procedure or device routine which is to be merged. When loading a device driver, Name contains the name of the global (also called "universal" under VMS) DEVICE_DEF structure in the driver. Upon successful loading of the routine, a new procedure or function with the given name will exist, or the new device driver will be loaded.
Under VMS, the full interpretation of this argument is discussed in VMS LINKIMAGE and LIB$FIND_IMAGE_SYMBOL . Under other operating systems, this argument contains the full path specification of the dynamically loaded object file. See your system documentation on sharable libraries or DLLs for details.
An optional scalar integer parameter that contains 0 (zero) for a procedure, 1 (one) for a function, and 2 for a device driver. The keyword parameters DEVICE and FUNCT can also be used to indicate the type of routine being merged. The default value is 0, for procedure.
An optional string that contains the name of the symbol which is the entry point of the procedure or function. With some compilers or operating systems, this name may require the addition of leading or trailing characters. For example, some Unix C compilers add a leading underscore to the beginning of a function name, and some Unix FORTRAN compilers add a trailing underscore.
If Entry is not supplied, LINKIMAGE will provide a default name by converting the value suppled for Name to lower case and adding any special characters (leading or trailing underscores) typical of the system.
Under Microsoft Windows operating systems, only
functions can by used with LINKIMAGE. Attempting to use routines with other calling conventions will yield undefined results, including memory corruption or even IDL crashing.
The Windows operating system has two distinct system defined standards that govern how routines pass arguments:
, which is used by much of the operating system as well as languages such as Visual Basic, and
, which is used widely for programming in the C language. These standards differ in how and when arguments are pushed onto the system stack. The standard used by a given function is determined when the function is compiled, and can be controlled by the programmer. LINKIMAGE can only be used with
functions. Unfortunately, there is no way for IDL to know which convention a given function uses, meaning that LINKIMAGE will quietly accept an entry point of the wrong type. The LINKIMAGE user is responsible for ensuring that Entry is a
This keyword is ignored on non-VMS platforms. Under VMS, it is a string containing the default device, directory, file name, and file type information for the file that contains the sharable image. See VMS LINKIMAGE and LIB$FIND_IMAGE_SYMBOL for additional information.
Set this keyword equal to the maximum number of non-keyword arguments the procedure or function accepts. If this keyword is not present, the maximum number of parameters is not checked when the routine is called.
NOTE: It is a very good idea to specify a value for MAX_ARGS. Passing the wrong number of arguments to an external routine may cause unexpected results, including causing IDL to crash. By forcing IDL to check the number of arguments before passing them to the linked routine, you will avoid parameter mismatch problems.
The VMS implementation of LINKIMAGE uses the system runtime library function LIB$FIND_IMAGE_SYMBOL to perform the dynamic linking. This function has a complicated interface in which the name of the library to be linked is given in two separate arguments. We encourage VMS users wishing to use LINKIMAGE to read and fully understand the documentation for LIB$FIND_IMAGE_SYMBOL in order to understand how it is used by IDL. The following discussion assumes that you have a copy of the LIB$FIND_IMAGE_SYMBOL documentation available to consult as you read.
LIB$FIND_IMAGE_SYMBOL uses an argument called
to specify the name of the sharable library or executable to be loaded. Only the actual file name itself is allowed, meaning that none of the file specification punctuation characters (
) are allowed. Filename can also be a logical name, in which case its translated value is the name of the file to be loaded. The translation of such a logical name is allowed to contain additional file specification information. VMS uses this information to find the file to load, using SYS$SHARE as the default location if a location is not specified via a logical name. Alternatively, the user can also supply the optional
argument, which is used as a "default filespec" to fill in the parts of the file specification not contained in filename. IDL uses the following rules, in the order listed, to determine how to call LIB$FIND_IMAGE_SYMBOL:
.) then it is passed to LIB$CALL_IMAGE_SYMBOL as it's filename argument without any further interpretation.
This means that although LIB$CALL_IMAGE_SYMBOL has a complicated interface, the LINKIMAGE user can supply a simple file specification for Image and it will be properly loaded by IDL. Full control of LIB$CALL_IMAGE_SYMBOL is still available for those who require it.
LINKIMAGE routines invariably need to call functions supplied by the IDL program. In order to do this, you must link your sharable library with IDL. This requires you to supply the linker with the path (file specification) of the IDL program. The VMS linker in turn includes the path you specify in the resulting library. This can be inconvenient because a library linked this way can only run with the exact IDL executable that it was linked with. This means that you cannot move your IDL installation or keep multiple installations for use with your library. The standard VMS solution to this problem is to use a logical name instead of an actual path. For example, IDL users frequently use the logical name IDL_EXE to point at their IDL executable. To make this process easier and less trouble prone, IDL defines this logical name in the users process logical table when it starts running. Therefore, you can always link with the IDL_EXE logical and know that it will refer to the IDL executable you are actually running when the LINKIMAGE call is made.