Previous IDL Reference Guide: System Variables Next

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

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., 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 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 in IDL 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 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.


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. See IDL Preferences for details.

!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 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 takes its default value from a preference. See IDL_DLM_PATH for details.

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.

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

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

An integer variable indicating whether keyboard line editing is enabled (when set to a non-zero value) or disabled (when set to zero). The default value for !EDIT_INPUT comes from the IDL_EDIT_INPUT preference. See IDL 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. (See Startup Files for more information on startup files.)

To understand how IDL processes the request to change the recall buffer's size (either through IDL_RBUF_SIZE or through !EDIT_INPUT), see Support for Obsolete Preference Mechanisms.

!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. See Providing Online Help For Your Application for additional information on creating IDL Assistant online help systems or other online help 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, 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 !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 Table D-26. 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:

Table D-26: Description of CC and LD Field Codes 

Table D-26: Description of CC and LD Field Codes 
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. 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.

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

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:

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

OS

The vendor name of the operating system. The OS field will report one of the following strings: AIX, HP-UX, IRIX, linux, MacOS, 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, 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. 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 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 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.


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.

  IDL Online Help (March 06, 2007)