SCOPE_TRACEBACK

The SCOPE_TRACEBACK function is used to obtain an array containing the current interpreter call stack, which is a list describing the sequence of routine calls that have brought IDL execution to the current point. Each element of the array describes the routine as well as the source file and line number at which it was running at a given interpreter level. See Interpreter Frames, Level, and Variable Scope for more information.

In general, you should strive to write routines that execute properly no matter how they are called or by which routines. As such, your programs should rarely require call-stack information. Code that looks at what routine called it and alters its behavior accordingly can quickly become difficult to understand and maintain, and is generally considered to represent poor programming style. For this reason, avoid using the SCOPE functions.

Syntax

Result = SCOPE_TRACEBACK( [ /STRUCTURE] [, /SYSTEM] )

Return Value

Returns an array containing the current interpreter call stack. Each element of this result corresponds to one routine. Element 0 of the result contains information about the outer main program ($MAIN$), and each subsequent element contains information about the following routine. The final element of the result describes the currently executing caller of SCOPE_TRACEBACK.

If the STRUCTURE keyword is set, the array contains one IDL_TRACEBACK structure per stack frame containing detailed information about that invocation. Otherwise, a string array is returned, each element of which contains the name of the program module, source file name, and line number.

Keywords

STRUCTURE

Set this keyword to return an array of IDL_TRACEBACK structures containing detailed information about the call stack. Each IDL_TRACEBACK structure contains the following fields:

Field	Description
ROUTINE	Name of the routine.
FILENAME	If the routine was compiled from an IDL program file, FILENAME gives the name of the file. If it was restored from an IDL SAVE file, it gives the name of the SAVE file. FILENAME is an empty string if the routine is a built-in system routine.
LINE	If the routine was compiled from an IDL program file, LINE contains the current line number within the file given by FILENAME. It is 0 if the routine is from an IDL SAVE file or is a built-in system routine.
LEVEL	For user-level IDL language routines, the interpreter level of this frame of execution. See the documentation of the SCOPE_LEVEL function for more information on interpreter level. Interpreter levels only apply to routines written in the IDL language and are 0 (zero) or greater. This field is set to -1 for system routines.
IS_FUNCTION	This field is 1 if the routine is a function and 0 (zero) if it is a procedure.
METHOD	This field is 1 if the routine is an object method and 0 (zero) if it is a regular routine.
RESTORED	This field is 1 if the routine was restored from an IDL SAVE file and 0 (zero) otherwise.
SYSTEM	This field is 1 if the routine is a built-in system routine and 0 (zero) if it is a user-level routine written in the IDL language.

SYSTEM

By default, SCOPE_TRACEBACK shows the call stack of IDL routines. Set the SYSTEM keyword to have the function also include any IDL system routines that are currently active within the call chain. Such system routines are present whenever an IDL system routine makes a nested call to the IDL interpreter to run a routine written in the IDL language. For example, WIDGET_CONTROL, WIDGET_EVENT, and any call to an IDL object method all involve such interpreter callbacks.

Version History

6.2	Introduced