exelisvis.com / Docs Center / Libraries / Markwardt / ROUTINE_NAMES

Libraries

ROUTINE_NAMES

ROUTINE_NAMES

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 $

Notes


This page has no user notes yet. Be the first one!


This information is not subject to the controls of the International Traffic in Arms Regulations (ITAR) or the Export Administration Regulations (EAR). However, it may be restricted from transfer to various embargoed countries under U.S. laws and regulations.
© 2014 Exelis Visual Information Solutions