General System Variables

The following system variables contain information about IDL’s configuration.

!CPU

IDL can use multiple system processors to perform some computations in parallel.

The !CPU system variable supplies information about the state of the system processor, and of IDL's use of it. !CPU is read only, and cannot be modified directly. Use the CPU procedure to modify values contained in !CPU.

The !CPU structure is defined as follows:

{ !CPU, HW_VECTOR:0L, VECTOR_ENABLE:0L, HW_NCPU:0L,
  TPOOL_NTHREADS:0L, TPOOL_MIN_ELTS:0L, TPOOL_MAX_ELTS:0L }

where the meaning of the fields as follows:

HW_VECTOR

True (1) if the system supports a vector unit (e.g., Mac Altivec/Velocity Engine). False (0) otherwise.

Note: This value is currently always 0 (False) on platforms other than Mac.

VECTOR_ENABLE

True (1) if IDL will use a vector unit, if such a unit is available on the current system, and False (0) otherwise.

Note: This value is currently always 0 (False) on platforms other than Mac.

HW_NCPU

The number of CPUs contained in the system on which IDL is currently running.

TPOOL_NTHREADS

The number of threads that IDL will use in thread pool computations. The default is to use HW_NCPU threads, so that each thread will have the potential to run in parallel with the others. For numerical computation, there is no benefit to using more threads than your system has CPUs. However, depending on the size of the problem and the number of other programs running on the system, there may be a performance advantage to using fewer CPUs.

If the IDL_CPU_TPOOL_NTHREADS preference has been set, then TPOOL_NTHREADS is initialized with this value at startup. On systems shared by multiple users, you may wish to set this preference so that IDL uses the specified number of threads instead of defaulting to the number of CPUs present in the underlying hardware. See !CPU Settings Preferences for details.

TPOOL_MIN_ELTS

The number of elements in a computation that are necessary before IDL will use the thread pool to perform the work. For fewer than TPOOL_MIN_ELTS, the main IDL thread will perform the work without using the thread pool. It is important not to use the thread pool for small tasks because the overhead of threading will not be offset by the overhead incurred by operation of the pool, and the overall computation will go slower than if threading is not used.

TPOOL_MAX_ELTS

The maximum number of elements in a computation for which IDL will use the thread pool. If this value is 0 (zero) (the default), then no limit is imposed and any computation with at least TPOOL_MIN_ELTS is a candidate for the thread pool. If your computation is too large for the physical memory available on the system, the virtual memory system of the operating system will begin paging. Under such conditions, the performance of the thread pool can be worse than that of a single threaded computation because the threads end up fighting each other for access to memory. TPOOL_MAX_ELTS can be used to prevent this.

Note: The TPOOL_MAX_ELTS, TPOOL_MIN_ELTS, TPOOL_NTHREADS, and VECTOR_ENABLE fields of this system variable take their default values from the !CPU Settings Preferences.

!DEBUG_PROCESS_EVENTS

Set this system variable to 1 to allow IDL to process widget events while the IDL interpreter is stopped within a routine. Set this variable to 0 to disable widget events while stopped within a routine. The default value is 1.

Note: If you are stopped within a $MAIN program, IDL will always process widget events, regardless of the setting of this system variable.

Tip: Usually, you will want to keep !DEBUG_PROCESS_EVENTS = 1. This allows you to use graphics and widget applications while debugging your code. However, if you are debugging an event handler within your widget application, you may want to temporarily set !DEBUG_PROCESS_EVENTS = 0 so that IDL does not make widget event calls back into your event handler.

!DIR

A string variable containing the path to the main IDL directory.

!DIR takes its default value from a preference. See IDL_DIR for details.

!DLM_PATH

Significant portions of IDL’s built in functionality are packaged in the form of Dynamically Loadable Modules (DLMs). DLMs correspond to UNIX sharable libraries or Windows DLLs, depending on the operating system in use. At startup, IDL searches for DLM definition files (which end in the .dlm suffix) and makes note of the routines supplied by each DLM. If a routine is called, IDL automatically loads the DLM. To see a list of the DLMs that IDL knows about, use HELP,/DLM (see the HELP procedure for more information).

!DLM_PATH takes its default value from the IDL_DLM_PATH preference.

If the IDL_DLM_PATH preference is not explicitly defined by the user, IDL supplies a default that contains the directory in the IDL distribution where the supplied DLMs reside. Once !DLM_PATH is expanded, IDL uses it as the list of places to look for DLM definition files. IDL also searches the current working directory for DLM files.

Note: If you change the value of !DLM_PATH then IDL will automatically parse the ".dlm" files within the new directories and add the routines to IDL's internal table of available routines. If your IDL code calls one of these routines then IDL will automatically load the appropriate .dll or .so library, even if that directory is no longer on !DLM_PATH. The only way to clear out the table of available routines is to restart IDL.

Using Path Definition Tokens to Load a DLM Path

Using the <IDL_BIN_DIRNAME> token in the IDL_DLM_PATH preference can be useful for distributing packages of DLMs with support for multiple operating system and hardware combinations. This token is described in The Path Definition String under EXPAND_PATH.

For example, assume that you have your DLMs installed in /usr/local/mydlm, with support for each platform in a subdirectory using the same naming convention that IDL uses for the platform dependent subdirectories underneath the bin directory of the IDL distribution. Setting the IDL_DLM_PATH preference to the following:

"/usr/local/mydlm/<IDL_BIN_DIRNAME>:<IDL_DEFAULT>"

adds the location of the proper DLM for your current system to IDL's !DLM_PATH at startup.

Similarly, the <IDL_VERSION_DIRNAME> token can be useful for distributing packages of DLMs with support for multiple IDL versions, operating systems, and hardware platforms. This token is described in The Path Definition String under EXPAND_PATH.

For example, assume that you have your DLMs installed in /usr/local/mydlm. You create a subdirectory for each supported version of IDL within the mydlm directory. Within each of those subdirectories would be a subdirectory for each operating system and hardware combination supported by that version of IDL. Setting the IDL_DLM_PATH preference to the following:

"/usr/local/mydlm/<IDL_VERSION_DIRNAME>/<IDL_BIN_DIRNAME>:<IDL_DEFAULT>"

adds the location of the proper DLM for your current system to IDL's !DLM_PATH at startup.

!EDIT_INPUT

This system variable determines whether or not the tty-based (non-IDE) command-line version of IDL does command-line editing when reading commands. The default value for !EDIT_INPUT comes from the IDL_EDIT_INPUT preference. See IDL System Preferences for details.

By default, IDL saves the last 20 command lines in a recall buffer. You can change the number of command lines saved in the recall buffer by setting the IDL_RBUF_SIZE preference to the desired number. To preserve backward compatibility with releases of IDL prior to version 6.2, you can also change the number of command lines saved in the recall buffer by setting !EDIT_INPUT equal to the number of lines you would like to save. In order for the change to take effect, IDL must be able to process the assignment statement before providing a command prompt. This means that you must put the assignment statement in the IDL startup file.

!HELP_PATH

A string variable listing the directories IDL will search for online help files. Help files must either be part of an IDL Assistant online help system (controlled by a .adp file), Adobe Portable Document Format (.pdf) files, or HTML (.html or .htm) files. On Windows systems, help files can also be HTML Help (.chm) or Windows Help (.hlp) files.

!HELP_PATH takes its default value from a preference. See IDL_HELP_PATH for details.

If the IDL_HELP_PATH preference is not explicitly defined by the user, IDL supplies a default that contains the directory in the IDL distribution where the supplied help files reside.

To change the value of !HELP_PATH for the duration of an IDL session, set the variable equal to a new string containing the desired path. See Changing the Value of !PATH After IDL Starts for tips that also apply to setting the value of !HELP_PATH.

!JOURNAL

A read-only long-integer variable containing the logical unit number of the file used for journal output.

!MAKE_DLL

The MAKE_DLL procedure and the CALL_EXTERNAL function’s AUTO_GLUE keyword use the standard system C compiler and linker to generate sharable libraries that can be used by IDL in various contexts (CALL_EXTERNAL, DLMs, LINKIMAGE). Variation possible when using these tools between different platforms, operating system versions, and compiler releases. The !MAKE_DLL system variable is used to configure how IDL uses them for the current platform.

The !MAKE_DLL structure is defined as follows:

{ !MAKE_DLL, COMPILE_DIRECTORY:’’, COMPILER_NAME:’’, CC:’’, LD:’’}

where the meaning of the fields as follows:

COMPILE_DIRECTORY

IDL requires a place to create the intermediate files necessary to build a sharable library, and possibly the final library itself. Unless told to use an explicit directory, it uses the directory given by the COMPILE_DIRECTORY field of !MAKE_DLL.

IDL takes the default value of this field from a preference. See IDL_MAKE_DLL_COMPILE_DIRECTORY for details.

COMPILER_NAME

A string containing the name of the C compiler used to build the currently running IDL. This field is not used by IDL, and exists solely for informational purposes and to help the end user decide which C compiler to install on their system.

CC

A string used by IDL as a template to construct the command for using the C compiler. This template uses PRINTF style substitution codes, as described in the following table.

LD

A string used by IDL as a template to construct the command for using the linker. This template uses PRINTF style substitution codes, as described in the following table.

When expanding !MAKE_DLL.CC and !MAKE_DLL.LD, IDL substitutes text in place of the PRINTF style codes described in the following table. These codes are case-insensitive (they can be either upper or lower case).

Note: It is possible to use C compilers other than the one assumed in !MAKE_DLL to build sharable libraries. To do so, you can alter the contents of !MAKE_DLL or use the CC and/or LD keyword to MAKE_DLL and CALL_EXTERNAL. Please understand that a list of all possible compilers and the necessary compiler options is not maintained. This information is available in your compiler and system documentation. It is the programmer’s responsibility to understand the rules for the chosen compiler.

The following table describes the substitution codes for the CC and LD fields:

Code

Meaning

%B %b

The base name of a C file to compile. For example, if the C file is moose.c, then %B substitutes moose.

%C %c

The name of the C file.

%E %e

The name of the linker options file. This file, which is automatically generated by IDL as needed, is used to control the linker. Under UNIX, the system documentation refers to this as an export file, or a linker map file. Microsoft Windows calls it a .DEF file.

%F %f

This substitution code is no longer meaningful, and will be ignored.

%L %l

The name of the resulting sharable library. IDL constructs this name by using the base name (%B) and adding the appropriate suffix for the current platform (.dll, .so, .sl, .exe, etc.).

%O %o

An object file name. IDL constructs this name by using the base name (%B) and adding the appropriate suffix for the current platform (.o, .obj).

%X %x

When expanding !MAKE_DLL.CC, IDL inserts any text supplied via the EXTRA_CFLAGS keyword to MAKE_DLL or CALL_EXTERNAL in place of %X. IDL does not interpret this text. It is the user’s responsibility to ensure that it is meaningful in the command. When expanding !MAKE_DLL.LD, the text from the EXTRA_LFLAGS keyword is substituted. The primary use for this code is to include necessary header include directories and link libraries.

%%

Replaced with a single % character.

!MORE

An integer variable indicating whether IDL should paginate help output sent to a tty device. (This preference has no effect on the IDL Workbench Console view.) Setting !MORE to zero (0) prevents IDL from paginating the output text. A non-zero value (the default) causes IDL to display output text one screen at a time.

!MORE takes its default value from a preference. See IDL_MORE for details.

!PACKAGE_PATH

A string variable listing the directory where IDL packages will be stored and searched for.

!PACKAGE_PATH cannot be set directly and takes its value from a preference. See IDL_PACKAGE_PATH for details.

If the IDL_PACKAGE_PATH preference is not explicitly defined by the user, IDL supplies a default that contains the directory in the IDL distribution where the supplied packages reside.

!PATH

A string variable listing the directories IDL will search for libraries and include files.

Note: The current directory is always searched before consulting !PATH.

!PATH takes its default value from a preference. See IDL_PATH for details.

If you are using the IDL Workbench, your project directories may be added to !PATH.

Note on Path Expansion

When IDL starts, it reads the value of the IDL_PATH preference and builds a value to be stored in !PATH from the specified initialization value. While the initialization value can consist of a normal path string specifying all directories to be included in !PATH, it can also take advantage of several special values that IDL uses to dynamically create the value of !PATH. These values (the “+” symbol and the “<IDL_*>” strings) are described in detail in The Path Definition String under EXPAND_PATH.

Path Caching

By default, as IDL searches directories included in the !PATH system variable for .pro or .sav files to compile, it creates an in-memory list of all.pro and .sav files contained in each directory. When IDL later searches for a .pro or .sav file, before attempting to open the file in a given directory, IDL checks the path cache to determine whether the directory has already been cached. If the directory is included in the cache, IDL uses the cached information to determine whether the file will be found in that directory, and will only attempt to open the file there if the cache tells it that the file exists. By eliminating unnecessary attempts to open files, the path cache speeds the path searching process. If use of the patch cache causes problems, you can disable it either via a keyword to the PATH_CACHE routine or via the IDL_PATH_CACHE_DISABLE preference.

See PATH_CACHE for details.

Changing the Value of !PATH After IDL Starts

Once IDL has started, you can alter the value of !PATH by setting it to a new string value. For example, on a UNIX system, to add a directory to !PATH for the duration of an IDL session, you would use a command like the following:

!PATH = '/usr2/project/idl_files:' + !PATH

Keep the following in mind when changing the value of !PATH by setting its value to a new string:

pathsep = PATH_SEP(/SEARCH_PATH)

!PATH = 'new_path' + pathsep + !PATH

where new_path is the path to the directory you want to add.

pathsep = PATH_SEP(/SEARCH_PATH)

!PATH = EXPAND_PATH('+new_path') + pathsep + !PATH

See EXPAND_PATH for details.

!PROMPT

A string variable containing the text string used by IDL to prompt the user for input. The default is IDL>.

!PROMPT takes its default value from a preference. See IDL_PROMPT for details.

!QUIET

A long-integer variable indicating whether informational messages should be printed (0) or suppressed (nonzero). By default, !QUIET is set to zero.

!QUIET takes its default value from a preference. See IDL_QUIET for details.

!VERSION

A structure variable containing information about the version of IDL in use. The structure is defined as follows:

{ !VERSION, ARCH:'', OS:'', OS_FAMILY:'', OS_NAME:'', $

   RELEASE:'', BUILD_DATE:'', MEMORY_BITS:0, FILE_OFFSET_BITS:0 }

where the meaning of the fields as follows:

ARCH

CPU hardware architecture of the system. The ARCH field will report one of the following strings, depending on the operating system and number of bits used to address memory:

Operating System

Memory Bits

Value of ARCH field

Windows

32

x86

64

x86_64

macOS (Intel)

32

i386

64

x86_64

Linux

32

x86

64

x86_64

OS

The vendor name of the operating system. The OS field will report one of the following strings: linux, darwin, Win32. This is the name of the underlying operating system kernel (not necessarily of the overall operating environment: see OS_NAME). Once an OS name is assigned to a platform, it is not altered in subsequent releases. This makes it safe for use in IDL programs that need to distinguish between platforms. Consider using the OS_FAMILY field before using the OS field, as most programs are mainly concerned with high level platform differences.

OS_FAMILY

The generic name of the operating system (UNIX, Windows). Whenever possible, use this field (rather than OS or OS_NAME) in code that must distinguish between platforms.

OS_NAME

The vendor’s name for the operating system environment, as used by the vendor for casual descriptive and promotional purposes. Vendors change their descriptive environment names from time to time, and the OS_NAME field is updated to reflect this. As a result, restrict your use of this field to descriptive textual uses, and use the OS_FAMILY or OS fields of !VERSION in code that must distinguish between platforms.

RELEASE

IDL version number.

BUILD_DATE

The date and build identifier when the IDL executable was compiled, in the format "MMM DD YYYY (REVISION)", where MMM is the month name, DD is the date (with an extra space for dates less than 10), YYYY is the year, and REVISION is the build identifier. For example: "Feb 29 2016 (306707)".

MEMORY_BITS

The number of bits used to address memory. Possible values are 32 or 64. The number of bits used to address memory places a theoretical upper limit on the amount of memory available to IDL.

FILE_OFFSET_BITS

The number of bits used to position file offsets. Possible values are 32 or 64. The number of bits used to position files places a theoretical upper limit on the largest file IDL can access.

Note: If you need to differentiate between different IDL versions in your code, use !VERSION.OS_FAMILY. At present, two operating system families are supported: UNIX and Windows. For even more detail, you can use !VERSION.OS.