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.

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:

Calling Sequence

LINKIMAGE, Name, Image [, Type [, Entry]]



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.


A string that holds the name of the file containing the code to be dynamically linked.

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.

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.



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 to indicate that the module being loaded contains a device driver.


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


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


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.


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


Specifying The Library Name

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 filename 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 image-name 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:

  1. If LINKIMAGE is called with both the Image argument and DEFAULT keyword, Image is passed to LIB$FIND_IMAGE_SYMBOL as filename, and DEFAULT is passed as image-name. Both are passed directly to the function without any interpretation.
  2. If DEFAULT is not present and Image does not contain a file specification character ( : , [ , < , ; , . ) then it is passed to LIB$CALL_IMAGE_SYMBOL as it's filename argument without any further interpretation.
  3. If DEFAULT is not present and Image contains a file specification character, then IDL examines it and locates the filename part. The filename part is passed to LIB$FIND_IMAGE_SYMBOL as filename and the entire string from Image is passed as image-name.

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.

Linking To The IDL Executable

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.


To add a procedure called MY_PROC, whose entry symbol is also named MY_PROC, and whose file is pointed to by the logical name MY_PROC_EXE:


Under VMS, to add a device driver contained in the file DRA0:[SMITH]XXDRIV.EXE :



The global symbol XX_DEV , which contains the device definition structure, must be defined as universal within the sharable image.

See Also

CALL_EXTERNAL , SPAWN , and the IDL Advanced Development Guide .