IDL Environment System Variables

IDL can use multiple system processors to perform some computations in parallel. See Multithreading in IDL for additional information.

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


Field	Meaning
HW_VECTOR	True (1) if the system supports a vector unit (e.g. Macintosh Altivec/Velocity Engine). False (0) otherwise. Note - This value is currently always 0 (False) on platforms other than Macintosh.
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 Macintosh.
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 environment variable 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 environment variable so that IDL uses the specified number of threads instead of defaulting to the number of CPUs present in the underlying hardware. See IDL_CPU_TPOOL_NTHREADS for more information.
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 simply 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.

!DIR

!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 such are routine is called, IDL loads the DLM that supplies it into memory. To see a list of the DLMs that IDL knows about, use HELP, /DLM (see HELP for more information).

!DLM_PATH is initialized from the environment variable IDL_DLM_PATH at startup. This initialization is similar to that performed for IDL_PATH, (see !PATH), including recursive path expansion denoted with a leading "+" but not including any use of IDLDE preferences settings. See Environment Variables Used by IDL for details on setting the IDL_DLM_PATH environment variable.

If the IDL_DLM_PATH environment variable is not defined, IDL supplies a default that contains the directory in the IDL distribution where the DLMs supplied by RSI reside. Once !DLM_PATH is expanded, IDL uses it as the list of places to look for DLM definition files.

Since all DLM searching happens once at startup time, it would be meaningless to change the value of !DLM_PATH afterwards. For this reason, it is a read-only system variable and cannot be assigned to. The value of !DLM_PATH is useful because it shows you where IDL looked for DLMs when it started.

Using Path Definition Tokens to Load a DLM Path

Note that using the <IDL_BIN_DIRNAME> token in the IDL_DLM_PATH environment variable 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 dependant subdirectories underneath the bin directory of the IDL distribution. The following line, which might be located in a file executed by a UNIX shell when you log in (.cshrc, .login), will add the location of the proper DLM for your current system to IDL's !DLM_PATH at startup:

(all on a single line). Setting the Windows environment variable IDL_DLM_PATH to a similar string would produce the same result on a Windows system.

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. Within the mydlm subdirectory would be a directory for each supported version of IDL. Within each of those subdirectories would be a subdirectory for each operating system and hardware combination supported by that version of IDL. The following line, which might be located in a file executed by your shell when you log in (.cshrc, .login) will add the location of the proper DLM for your current system to IDL's !DLM_PATH at startup:

(all on a single line). Setting the Windows environment variable IDL_DLM_PATH to a similar string would produce the same result on a Windows system.

!EDIT_INPUT

An integer variable indicating whether keyboard line editing is enabled (when set to a non-zero value) or disabled (when set to zero). By default, !EDIT_INPUT is set equal to one, and line editing is enabled.

By default, IDL saves the last 20 command lines. You can 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. (See Startup Files for more information on startup files.)

!HELP_PATH

A string variable listing the directories IDL will search for online help files. On UNIX systems, help files must be Adobe Portable Document Format (.pdf) files or HTML (.html or .htm) files. On Windows systems, help files can be HTML Help (.chm), Windows Help (.hlp), Portable Document Format (.pdf), or HTML (.html or .htm) files.

!HELP_PATH is initialized from the environment variable IDL_HELP_PATH at startup. This initialization is similar to that performed for IDL_PATH (see !PATH), including recursive path expansion denoted with a leading "+" but not including any use of IDLDE preferences settings. See Environment Variables Used by IDL for details on setting the IDL_HELP_PATH environment variable

If the IDL_HELP_PATH environment variable is not defined, IDL supplies a default that contains the directory in the IDL distribution where the help files supplied by RSI reside.

To change the value of !HELP_PATH for the duration of an IDL session, simply 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). There is a great deal of variation possible in the use of 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 meaning of the fields of !MAKE_DLL are given 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, and can be either upper or lower case.


Field	Meaning
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. If the IDL_MAKE_DLL_COMPILE_DIRECTORY environment variable is set, IDL uses its value to initialize the COMPILE_DIRECTORY field. Otherwise, IDL supplies a standard location. Note - If the directory given by !MAKE_DLL.COMPILE_DIRECTORY does not exist when IDL needs it, IDL automatically creates it for you if possible.
COMPILER_NAME	A string containing the name of the C compiler used by RSI 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.


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`, ...).
%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, any text supplied via the EXTRA_CFLAGS keyword to MAKE_DLL or CALL_EXTERNAL is inserted in place of %X. IDL does not interpret this text. It is the users 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. 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.

!PATH

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

!PATH is initialized from the environment variable IDL_PATH when IDL starts. See Environment Variables Used by IDL for details on setting the IDL_PATH environment variable.

Note on Path Expansion

When IDL starts, it reads the IDL_PATH environment variable (or the default value, if IDL_PATH does not exist) 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. 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:

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

Remember to use the proper path string separator character for your platform. If you are writing a cross-platform application that changes !PATH, you may want to use code that looks something like this:

pathsep = PATH_SEP(/SEARCH_PATH) 
 
!PATH = 'new_path' + pathsep + !PATH

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

You can use the EXPAND_PATH function to generate a path string. This method allows you to specify one or more directories and let IDL figure out whether those directories contain .pro or .sav files. It also allows you to use the "+" character path expansion technique. For example, the following commands add all directories below the new_path directory that contain .pro or .sav files to !PATH:

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>.

!QUIET

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

!VERSION

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


Field	Meaning
ARCH	CPU hardware architecture of the system.
OS	The vendor name of the operating system (for example: AIX, HP-UX, IRIX, linux, MacOS, OSF, sunos, 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 by RSI, it is not altered in subsequent releases. This makes it safe for use in IDL programs that need to distinguish between platforms. RSI recommends that you first 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). RSI recommends that whenever possible this field (rather than OS or OS_NAME) be used 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. For example, on Sun workstations, the name of the operating system kernel (!VERSION.OS) is "sunos", whereas the name of the overall system (!VERSION.OS_NAME) is "Solaris". Vendors change their descriptive environment names from time to time, and RSI updates the OS_NAME field to reflect this. As a result, RSI recommends that IDL users restrict their use of this field to descriptive textual uses, and that the OS_FAMILY or OS fields of !VERSION be used in code that must distinguish between platforms.
RELEASE	IDL version number.
BUILD_DATE	The date the IDL executable was compiled, in the format dictated by ANSI C for the `__DATE__` macro.
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.

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.