LINKIMAGE

The LINKIMAGE procedure merges routines written in other languages with IDL at runtime. 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.

Note: 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.

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:

• Under UNIX, LINKIMAGE uses the dlopen() interface to the dynamic linker.
• Under Windows, LINKIMAGE uses LoadLibrary() to load a DLL.

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.

Examples

To add a procedure called MY_PROC, whose entry symbol is named my_proc, that is contained in the file /home/smith/my_proc.so:

LINKIMAGE, 'MY_PROC', '/home/smith/my_proc.so'

Syntax

LINKIMAGE, Name, Image [, Type [, Entry]] [, /DEVICE] [, /FUNCT] [, /KEYWORDS] [, MAX_ARGS=value] [, MIN_ARGS=value]

Arguments

Name

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

Image

A string containing the full path specification of the dynamically loaded object file. See your system documentation on sharable libraries or DLLs for details.

Type

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.

Entry

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.

Note: Under Microsoft Windows operating systems, only cdecl 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: stdcall, which is used by much of the operating system as well as languages such as Visual Basic, and cdecl, 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 cdecl 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 cdecl function.

Keywords

DEVICE

Set this keyword to indicate that the module being loaded contains a device driver.

FUNCT

Set this keyword to indicate that the module being loaded contains a function.

KEYWORDS

Set this keyword to indicate that the procedure or function being loaded accepts keyword parameters.

MAX_ARGS

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.

MIN_ARGS

Set this keyword equal to the minimum number of non-keyword arguments accepted by the procedure or function.

Version History

Pre 4.0	Introduced
Pre 6.1	Deprecated DEFAULT keyword

See Also

CALL_EXTERNAL, SPAWN