./toolbox
which_routine.pro

Last modification date:

Wed Sep 28 13:27:11 2016

which_routine

function which_routine(name, unresolved=variable)

Search for any file in the IDL !path that contains the user-supplied IDL routine (procedure or function) name.

If the returned string has non-zero length, the routine has been compiled (resolved in IDL lingo) otherwise, it has not. Any unresolved files that contain this routine are also returned in the unresolved keyword value. If both the returned string and the resolved keyword values have zero length, then the routine could not be found in the !path.

This is the code behind which. It was originally all in which but was split so that other code could make use of this functionality (e.g. driving a browser to the appropriate reference manual location, finding and summarizing the help information for a routine).

Restrictions: The IDL !path is searched for file names that are simply the module (in IDL documentation, "module" and "routine" are used interchangeably) name with a ".pro" suffix appended to them. A module stored inside a file whose name is different than the module name (followed by a ".pro") will not be found UNLESS that module happens to be the currently-resolved module! E.g., if the module "pro test_proc" lives in a file named "dumb_name.pro", then it will not be found:

 IDL> a=which_routine('test_proc',unresolved=unresolved)
 IDL> print, strlen(a), strlen(unresolved)
          0           0
 

 IDL> .run dumb_name
 % Compiled module: TEST_PROC.
 IDL> print,which_routine('test_proc')
 /hvc/robishaw/dumb_name.pro
 

Notes: First, all currently-compiled procedures and functions are searched. Then the remainder of the IDL !path is searched.

MODIFICATION HISTORY:

• 30 May 2003 Written by Tim Robishaw, Berkeley
• 17 Feb 2004 Fixed oddity where user tries to call a function as if it were a procedure, thus listing the module in both the Compiled Functions and Compiled Procedures list.
• 14 Jun 2005 Split code into which_routine function for use elsewhere in GBTIDL and which. Reformatted comments for use with idldoc.

Returns

String containing the file name from which the resolved (compiled) version of name was found. This is a zero-length string if name has not been resolved (compiled) yet.

Examples

You haven't yet resolved (compiled) the routine (module) DEFROI. Let's look for it anyway:

 IDL> a=which_routine('defroi',unresolved=unresolved)
 IDL> print,strlen(a)
        0
 IDL> print, unresolved
 /usr/local/rsi/idl/lib/defroi.pro
 

For some reason you have two modules with the same name. (This can occur in libraries of IDL routines such as the Goddard IDL Astronomy User's Library; an updated version of a routine is stored in a special directory while the old version is stored in its original directory.) Let's see which version of the module ADSTRING we are currently using:

 IDL> a=which_routine('adstring.pro',unresolved=unresolved)
 IDL> print,a
 /hvc/robishaw/idl/goddard/pro/v5.4+/adstring.pro
 IDL> print,unresolved
 /hvc/robishaw/idl/goddard/pro/astro/adstring.pro
 

Version

$Id$

Parameters
name in, required string	The procedure or function name to search for.

Keywords
unresolved out variable	The paths to files that likely contain this name but are not the currently compiled version containing name.