;+ ; NAME: ; ROUTINE_NAMES (DOCUMENTATION ONLY) ; ; AUTHOR: ; Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 ; craigm@lheamail.gsfc.nasa.gov ; ; PURPOSE: ; Examine variables and parameters of procedures and call stack (OBSOLETE) ; ; CALLING SEQUENCE: ; Various, see USAGE VARIATIONS. ; ; DESCRIPTION: ; ; ROUTINE_NAMES obtains information about routines, and their ; variables and keywords. Using these functions, a subroutine can ; interrogate, and in some cases change, the values and names of ; variables and parameters in its calling routine, or at the $MAIN$ ; level. Some functionality of ROUTINE_NAMES is also in the IDL ; system function ROUTINE_INFO, and other functionality is exclusive ; to ROUTINE_NAMES. ; ; ROUTINE_NAMES has been designated as "OBSOLETE" by RSI, although ; it will probably not disappear soon since their own software ; appears to use it. ; ; ROUTINE_NAMES can be invoked in several different ways, which are ; detailed below, under USAGE VARIATIONS. ; ; ROUTINE_NAMES uses a notion of the current IDL "call level," which ; is the numerical stack depth of the currently executing routine. ; At each procedure or function call, the call level becomes one ; *deeper*, and upon each RETURN, the call level becomes one ; *shallower*. The call stack always begins at the $MAIN$ level. ; The current call stack can always be printed by executing HELP. ; ; When specifying the call level to ROUTINE_NAMES, one can use one ; of two numbering systems, depending on whichever is most ; convenient. In the *absolute* numbering system, the $MAIN$ level ; starts at number 1, and becomes deeper with increasing numbers. ; In the *relative* numbering system, the current (deepest) call ; level is number 0, and becomes shallower with more negative ; numbers. Hence, if the deepest level is N, then the ; correspondence is thus: ; ; VALUE MEANING ; -------------------------------- ; 1 or -N+1 $MAIN$ level ; 2 or -N+2 NEXT deeper level ; ... ... ; N or 0 DEEPEST (currently executing) level ; ; USAGE VARIATIONS: ; ; PROCS = ROUTINE_NAMES( [/UNRESOLVED]) ; PROCS = ROUTINE_NAMES(/PROCEDURES [,/UNRESOLVED]) ; FUNCS = ROUTINE_NAMES(/FUNCTIONS [,/UNRESOLVED]) ; ; The currently compiled procedures and functions are ; returned, respectively, as a string array. Functions ; declared via FORWARD_FUNCTION are also returned. If the ; UNRESOLVED keyword is set then the currently unresolved ; procedures and functions are returned. These are known ; routines which have not yet been compiled. ; ; PROCS = ROUTINE_NAMES(/S_PROCEDURES) ; FUNCS = ROUTINE_NAMES(/S_FUNCTIONS) ; ; The lists of system procedures and functions is returned, ; as a string array. ; ; LEVNUM = ROUTINE_NAMES(/LEVEL) ; ; The call level of the calling routine is returned. ; ; NAMES = ROUTINE_NAMES(ARG0, ARG1, ..., ARGN, ARG_NAME=LEVEL) ; ; The names of variables ARGi at call level LEVEL are ; returned, as a string array. Note that ARGi are the ; actual parameters, not strings containing their names. ; ARGi must be parameters that have been passed to the ; calling procedure. Variables that are unnamed at the ; specified call level will return the empty string. ; [IDL v5.0 and above only] ; ; ; VARS = ROUTINE_NAMES(VARIABLES=LEVEL) ; ; The names of variables at call level LEVEL are returned, ; as a string array. ; ; VARS = ROUTINE_NAMES(PROC, /P_VARIABLES, /P_PARAMETERS) ; VARS = ROUTINE_NAMES(FUNC, /F_VARIABLES, /F_PARAMETERS) ; ; The names of the variables and parameters, respectively, ; defined in compiled procedure PROC, or compiled function ; FUNC, are returned as a string array. ; ; VALUE = ROUTINE_NAMES(NAME, FETCH=LEVEL) ; ; The value of the named variable NAME at call level LEVEL ; is returned. If the value is undefined, then the ; assignment will cause an error. Therefore, the only safe ; way to retrieve a value is by using a variant of the ; following: ; IF N_ELEMENTS(ROUTINE_NAMES(NAME, FETCH=LEVEL)) GT 0 THEN $ ; VALUE = ROUTINE_NAMES(NAME, FETCH=LEVEL) ; ; DUMMY = ROUTINE_NAMES(NAME, VALUE, STORE=LEVEL) ; ; The value VALUE is stored into the named variable NAME at ; call level LEVEL. Note that there is no way to cause the ; named variable to become undefined. The value returned ; in DUMMY can be ignored. ; [IDL v5.2 and earlier: new variables cannot be created] ; [IDL v5.3 and later: new variables can be created] ; ; SEE ALSO: ; ; ROUTINE_INFO, ARG_PRESENT, DXDEBUG (Markwardt Debug Library) ; ; MODIFICATION HISTORY: ; Written, 20 Jul 2000 ; Documented differences between IDL versions, 21 Sep 2000, CM ; ; ; $Id: routine_names.pro,v 1.2 2001/03/25 18:10:43 craigm Exp $ ; ;- ; Copyright (C) 2000, Craig Markwardt ; This software is provided as is without any warranty whatsoever. ; Permission to use, copy, modify, and distribute modified or ; unmodified copies is granted, provided this copyright and disclaimer ; are included unchanged. ;- forward_function routine_names end