The HELP procedure gives the user information on many aspects of the current session. The specific area for which help is desired is selected by specifying the appropriate keyword. If no arguments or keywords are specified, the default is to show the current nesting of procedures and functions, all current variables at the current program level, and open files. Only one keyword can be specified at a time.
Examples
To see general information on the current session, enter:
HELP
To see information on the structure definition of the system variable !D, enter:
HELP, !D, /STRUCTURES
Syntax
HELP, Expression1, ..., Expressionn, /BREAKPOINTS, /BRIEF, /DEVICE, /DLM, /FILES, /FULL, /FUNCTIONS, /HEAP_VARIABLES, /KEYS, /LAMBDA, /LAST_MESSAGE, LEVEL=value, /MEMORY, /MESSAGES, NAMES=string_of_variable_names, /OBJECTS, OUTPUT=variable, /PATH_CACHE, /PREFERENCES, /PROCEDURES, /RECALL_COMMANDS, /ROUTINES, /SHARED_MEMORY, /SOURCE_FILES, /STRUCTURES, /SYSTEM_VARIABLES, /TRACEBACK
Arguments
Expression(s)
The arguments are interpreted differently depending on the keyword selected. If no keyword is selected, HELP displays basic information for its parameters. For example, to see the type and structure of the variable A, enter:
HELP, A
Note: Normally, providing an object reference as an argument to HELP prints information about the object heap variable referred to by the object reference. If the argument is an instance of an object class that overloads the IDL_Object::_overloadHelp method, the value returned by that method will be printed.
Keywords
Note that the use of some of the following keywords causes any arguments to HELP to be ignored and HELP provides other types of information instead. If the description of the keyword does not explicitly mention the arguments, the arguments are ignored.
BREAKPOINTS
Set this keyword to display the breakpoint table which shows the program module and location for each breakpoint.
BRIEF
If set in conjunction with one of the following keywords, BRIEF produces very terse summary style output instead of the output normally displayed by those keywords:
|
DLM
HEAP_VARIABLES
LAMBDA
MESSAGES
OBJECTS |
PREFERENCES
ROUTINES
SOURCE_FILES
STRUCTURES
SYSTEM_VARIABLES
|
DEVICE
Set this keyword to show information about the currently selected graphics device. This information is dependent on the abilities of the current device, but the name of the device is always given. Arguments to HELP are ignored when DEVICE is specified.
DLM
Set this keyword to display all known dynamically loadable modules and their state (loaded or not loaded).
FILES
Set this keyword to display information about file units. If no arguments are supplied in the call to HELP, information on all open file units (except the special units 0, -1, and -2) is displayed. If arguments are provided, they are taken to be integer file unit numbers, and information on the specified file units is given.
For example, the command:
HELP, /FILES, -2, -1, 0
gives information below about the default file units:
Unit Attributes Name
-2 Write, Truncate, Tty, Reserved <stderr>
-1 Write, Truncate, Tty, Reserved <stdout>
0 Read, Tty, Reserved <stdin>
The attributes column tells about the characteristics of the file. For instance, the file connected to logical file unit 2 is called “stderr” and is the standard error file. It is opened for write access (Write), is a new file (Truncate), is a terminal (Tty), and cannot be closed by the CLOSE command (Reserved).
FULL
By default, HELP filters its output in an attempt to display only the information likely to be of use to the IDL user. The filtering applied depends on the type of information being requested. By default:
- Function Keys: Under UNIX, undefined function keys are not displayed. Under Windows, all function keys are displayed.
- Structure Definitions and Objects: Built-in IDL structure definitions (widget event structures, for example) are not displayed if they have not yet been used in the current IDL session. Structures and objects that have had their definition hidden using the STRUCT_HIDE procedure are not displayed.
- Pointers and Object References: The reference count for heap variables is displayed.
- Functions and Procedures: Functions and procedures compiled with the COMPILE_OPT HIDDEN directive are not displayed.
- Floating-point Values: By default, for floating-point inputs (FLOAT, DOUBLE, COMPLEX, DOUBLE COMPLEX), HELP truncates the output to six digits for single precision and eight digits for double precision. If the FULL keyword is specified, HELP outputs the value with its full precision (eight digits for single precision and 17 digits for double precision).
Specify the FULL keyword to see all available information on a given topic without any filtering.
FUNCTIONS
Normally, the ROUTINES or SOURCE_FILES keywords produce information on both functions and procedures. If FUNCTIONS is specified, only output on functions is produced. If FUNCTIONS is used without either ROUTINES or SOURCE_FILES, ROUTINES is assumed.
HEAP_VARIABLES
Set this keyword to display help information for all the current heap variables.
KEYS
Set this keyword to show current function key definitions as set by DEFINE_ KEY. Under UNIX, definitions for those function keys that are currently programmed to perform a function are displayed. Under Windows, definitions for all function keys are displayed. (Under UNIX, use the FULL keyword to display every available key, whether or not it is currently defined.)
If no arguments are supplied, information on all function keys is displayed. If arguments are provided, they must be scalar strings containing the names of function keys, and information on the specified keys is given.
LAMBDA
Set this keyword to display the list of currently-defined Lambda routines.
LAST_MESSAGE
Set this keyword to display the last error message issued by IDL.
LEVEL
By default, HELP displays information for variables in the scope of the currently executing routine. To change this behavior, set this keyword to a scalar integer indicating the scope in which the variables for displaying help should be found. The level value can be either absolute or relative to the current scope, as shown in the following table:
|
Value |
Meaning |
|
0 |
Level 0 always refers to the frame for the currently executing routine
|
|
< 0 |
Negative levels are a relative specification and refer to the frames of active routines relative to the currently executing routine. Level -1 is the direct caller of the current routine, -2 is the caller of the caller of the current routine, and so forth. If you specify a level that is deeper than the current call stack, SCOPE_VARFETCH clips the value not to go past $MAIN$.
|
|
> 0 |
Positive levels are an absolute specification and refer directly to the specified frame. Level 1 is $MAIN$, level 2 is the routine called from $MAIN$, and so forth. If you specify a level that is past the currently executing routine, SCOPE_VARFETCH clips the value to the level of the current routine.
|
For more information on scope level, see SCOPE_VARFETCH.
MEMORY
Set this keyword to see a report on the amount of dynamic memory (in bytes) currently in use by the IDL session; the maximum amount of dynamic memory allocated since the last call to HELP, /MEMORY; and the number of times dynamic memory has been allocated and deallocated. Arguments to HELP are ignored when MEMORY is specified.
MESSAGES
Set this keyword to display all known message blocks and the error space range into which they are loaded.
NAMES
A string used to determine the names of the variables whose values are to be printed. A string match (equivalent to the STRMATCH function with the FOLD_CASE keyword set) is used to decide if a given variable will be displayed. The match string can contain any wildcard expression supported by STRMATCH, including “*” and “?”.
For example, to print only the values of variables beginning with “A”, use the command HELP, NAMES='a*'. Similarly, HELP, NAMES='?' prints the values of all variables with a single-character name.
NAMES also works with the output from the following keywords:
|
DLM
HEAP_VARIABLES
LAMBDA
MESSAGES
OBJECTS |
PREFERENCES
ROUTINES
SOURCE_FILES
STRUCTURES
SYSTEM_VARIABLES
|
OBJECTS
Set this keyword to display information on defined object classes. If no arguments are provided, all currently-defined object classes are shown. If no arguments are provided, and the information you are looking for is not displayed, use the FULL keyword to prevent HELP from filtering the output. If arguments are provided, the definition of the object class for the heap variables referred to is displayed.
Information is provided on inherited superclasses and all known methods. A method is known to IDL only if it has been compiled in the current IDL session and called by its own class or a subclass. Methods that have not been compiled yet will not be shown. Thus, the list of methods displayed by HELP is not necessarily a complete list of all possible method for the object class.
If called within a class’ method, the OBJECTS keyword also displays the instance data of the object on which it was called.
OUTPUT
Set this keyword equal to a named variable that will contain a string array containing the formatted output of the HELP command. Each line of formatted output becomes a single element in the string array.
Note: The OUTPUT keyword is primarily for use in capturing HELP output in order to display it someplace else, such as in a text widget. This keyword is not intended to be used in obtaining programmatic information about the IDL session, and is formatted to be human readable. The format and content of this text is not guaranteed to remain static from release to release and may change at any time, without warning. If you find yourself using OUTPUT for a non-display purpose, consider using the STRUCTURE keyword to the SIZE function.
PATH_CACHE
Set this keyword to display a list of directories currently included in the IDL path cache, along with the number of .pro or .sav files found in those directories. See PATH_CACHE for details.
PREFERENCES
Set this keyword to display information about the current status of IDL’s preferences. IDL preferences are internal values used to configure certain aspects of the IDL environment. They serve as the initial values for many IDL system variables, as well as controlling other aspects of the user's environment.
Used by itself, the PREFERENCES keyword provides the following information:
- The path of the command-line preference file, if any.
- The path of the distribution preference file.
- The path of the user preference file.
- The number of preferences that are currently in a pending state. A preference is said to be pending if a new value has been set for it (PREF_SET) but not yet committed (PREF_COMMIT).
- The name and effective value of each preference and the source from which it is derived. In descending order of priority, the sources are command line, environment variable, user preference file, distribution preference file, and IDL default value.
Use PREFERENCES in conjunction with BRIEF for a terse display of the above. Use it with the FULL keyword in order to see the full information for each preference. In FULL mode, HELP displays the information above, as well as:
- A description of its purpose.
- Its category.
- If the preference serves as the initial value of a system variable, the name of the variable associated with the preference.
- When changes to the preference take effect.
- Values other than the effective value that are known for the preference. Because IDL preferences can have values from more than one source, the source with the highest priority is used as the effective value.
PROCEDURES
Normally, the ROUTINES or SOURCE_FILES keywords produce information on both functions and procedures. If PROCEDURES is specified, only output on procedures is produced. If PROCEDURES is used without either ROUTINES or SOURCE_FILES, ROUTINES is assumed.
RECALL_COMMANDS
Set this keyword to display the saved commands in the command input buffer. By default, IDL saves the last 20 lines of input in a buffer from which they can be recalled for command line editing. Arguments to HELP are ignored when RECALL is specified.
The number of lines saved can be changed by assigning the desired number of lines to the IDL_RBUF_SIZE preference. For more information, see IDL_RBUF_SIZE.
ROUTINES
Set this keyword to show a list of all compiled procedures and functions with their parameter names. Keyword parameters accepted by each module are shown to the right of the routine name. If no arguments are provided, and the information you are looking for is not displayed, use the FULL keyword to prevent HELP from filtering the output.
SHARED_MEMORY
Set this keyword to display information about all current shared memory and memory mapped file segments mapped into the current IDL process via the SHMMAP procedure.
SOURCE_FILES
Set this keyword to display information on procedures and functions written in the IDL language that have been compiled during the current IDL session. Full path names (relative to the current directory) of compiled .pro files are displayed. If no arguments are provided, and the information you are looking for is not displayed, use the FULL keyword to prevent HELP from filtering the output.
STRUCTURES
Set this keyword to display information on structures or object references. If no arguments are provided, all currently-defined structures are shown (use the FULL keyword to display all built-in structure definitions as well). If arguments are provided, the structure definition for those expressions is displayed. It is often more convenient to use HELP, /STRUCTURES instead of PRINT to look at the contents of a structure variable because it shows the names of the fields as well as the data.
Tip: If a single argument is provided to HELP, and it is a structure, then HELP will automatically display the structure information without having to set the STRUCTURES keyword.
SYSTEM_VARIABLES
Set this keyword to display information on all system variables. Arguments are ignored.
TRACEBACK
Set this keyword to display the current nesting of procedures and functions.
Version History
|
Original |
Introduced |
|
5.6 |
Added SHARED_MEMORY keyword
|
|
6.0 |
Added PATH_CACHE keyword
|
|
6.1 |
Added LEVEL keyword
|
|
6.2 |
Added PREFERENCES keyword
Deprecated ALL_KEYS and CALLS keywords
|
|
8.0 |
Print reference count for objects and pointers (with /FULL). Automatically set /STRUCTURES for a single-argument of type structure.
|
|
8.4 |
Added LAMBDA keyword
|
See Also
PRINT