Adding System Routines with LINKIMAGE

The IDL user level LINKIMAGE procedure makes the functionality of the IDL_SysRtnAdd() function available to IDL programs. It allows IDL programs to merge routines written in other languages 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 is the easiest way to add your system routines to IDL. It does not require linking a separate version of the IDL program with your code the way a direct call to IDL_SysRtnAdd() does, and it does not require writing the extra code required for a Dynamically Loadable Module (DLM). LINKIMAGE is commonly used for simple applications and for testing during the development of a system routine.

If you are developing a larger application, or if you intend to distribute your work, you should package your routines as Dynamically Loadable Modules which are much easier for end-users to install and use than LINKIMAGE calls.

If your IDL application relies on code written other languages and linked using the LINKIMAGE procedure, you must make sure that the routines declared with LINKIMAGE are linked into IDL before any code that calls them is restored. In practice, the best way to do this is to make the calls to LINKIMAGE in your MAIN procedure, and include the code that uses the linked routines in a secondary .SAV file. In this case your MAIN procedure may look something like this:

PRO main

;Link the external code.

LINKIMAGE, 'link_function', 'new.dll'

;Restore code that uses linked code. RESTORE, 'secondary.sav'

;Run your application. myapp

END

In this scenario, the IDL code that calls the LINK_FUNCTION routine (the routine linked into IDL in the LINKIMAGE call) is contained in the secondary .SAV file

'secondary.sav'.

Note: When creating your secondary .SAV file, you will need to issue the LINKIMAGE command before calling the SAVE procedure to link your routine into IDL after you have exited and restarted. The RESOLVE_ALL routine does not resolve routines linked to IDL with the LINKIMAGE procedure. Dynamically Loadable Modules do not have this issue, and are the best way to avoid the problem.