\index{\$MAIN\$}%
Examines variables and parameters of procedures and the call stack
Using ROUTINE\_NAMES 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. 

ROUTINE\_NAMES uses a notion of the current "call level," which
is the numerical stack depth of the currently executing routine.
At each procedure or function call, the call level becomes one
{\bf deeper}, and upon each RETURN, the call level becomes one
{\bf shallower}.  The call stack always begins at the \$MAIN\$ level.
The current call stack can always be printed by executing \gdlproref{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 {\bf absolute} numbering system, the \$MAIN\$ level
starts at number 1, and becomes deeper with increasing numbers.
In the {\bf 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:

\begin{tabular}{ll}
      VALUE      &  MEANING            \\ \hline
      1 or -N+1  &  \$MAIN\$ level     \\
      2 or -N+2  &  NEXT deeper level  \\
        \ldots   &       \ldots        \\
      N or 0     &  DEEPEST (currently executing) level
\end{tabular}

When called without any keyword ROUTINE\_NAMES returns a string array
containing a list of currently compiled functions and procedures, e.g.:

\gdlcodeexample{routine_names_0}{routine_names}{}

ROUTINE\_NAMES can be invoked in several other ways, which are detailed below
together with keyword descriptions.

%\gdlkeyworddesc{PROCEDURES}
%   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.
%
\gdlkeyworddesc{S-PROCEDURES}
The lists of system procedures is returned, as a string array.
The list does not cover procedures written in GDL itself which
are also part of GDL's routine library (e.g. \gdlproref{WRITE-PNG}).
\gdlcodeexample{routine_names_s_procedures}{}{}

\gdlkeyworddesc{S-FUNCTIONS}
The lists of system functions is returned, as a string array.
The list does not cover functions written in GDL itself which
are also part of GDL's routine library (e.g. \gdlfunref{READ-PNG}).
\gdlcodeexample{routine_names_s_functions}{}{}

\gdlkeyworddesc{LEVEL}
The call level of the calling routine is returned, e.g.:
\gdlcodeexample{routine_names_level}{level}{}

\gdlkeyworddesc{ARG-NAME}
%   NAMES  = ROUTINE_NAMES(ARG0, ARG1, ..., ARGN, ARG_NAME=LEVEL)
The names of variables passed as positional arguments at call level specified
with the ARG\_NAME keyword are returned, as a string array.  
Note that the arguments passed are the actual parameters, not strings containing their names.
All of the arguments 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.
\gdlcodeexample{routine_names_arg_name}{}{arg_name}

\gdlkeyworddesc{VARIABLES}
The names of variables at call level specified with the VARIABLES keyword are returned,
as a string array, e.g.:
\gdlcodeexample{routine_names_variables}{variables}{}

%   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.
%
\gdlkeyworddesc{FETCH}
The value of a variable which name is passed in the first argument (string) 
at call level specified with the FETCH keyword 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:
\gdlcodeexample{routine_names_fetch}{fetch}{}

\gdlkeyworddesc{STORE}
The value specified with the second argument is stored into the variable 
which name is passed in the first argument (string) at
the call level specified with the STORE keyword.  
Note that there is no way to cause the named variable to become undefined.  
The value returned can be ignored.
\gdlcodeexample{routine_names_store}{store}{}

\gdlseealso{\gdlfunref{ROUTINE-INFO}, \gdlfunref{ARG-PRESENT}, \gdlfunref{SCOPE-VARFETCH}}
\gdldisclaimer{Entry based on Craig Markwardt's documentation for ROUTINE\_NAMES:\\
  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.
}
