System Preferences are internal values that control various aspects of the environment that IDL presents to its users. Preferences supply initial values for many system variables and control the layout of the IDL Workbench and a variety of other aspects of IDL’s behavior. Preferences can be specified from a variety of sources. They persist between IDL sessions, meaning that once you get them set in a way that satisfies your needs, you can forget them, and IDL will behave in the way you have specified every time you run it.
Preferences are built into the IDL system and are fixed in number and purpose. Each preference has a name that starts with IDL_, and these names are case insensitive.
Note: Preferences that apply only to the IDL Workbench interface are stored separately. You can modify both workbench preferences and many (but not all) IDL system preferences via the IDL Workbench IDL Preferences dialog, but only system preferences are described here and only system preferences can be modified using the IDL PREF_* routines.
IDL system preferences have two data types: string and integer (numeric). The numeric preferences are further specialized:
The complete set of IDL system preferences are documented later in this appendix, starting with General User Environment Preferences. You can view your current preferences from within IDL by using the following command:
HELP, /PREFERENCES
The default display shows the preference names, their values, and the source of those values. For a detailed complete view of their state, add the FULL keyword to the HELP command. See the PREFERENCES keyword for more information on its output.
The value of each system preference can come from a variety of sources. There is a hierarchy to these sources, and IDL will use the value from the source with the highest priority. This value is called the effective value, to reflect the fact that there might be several sources for a given preference, but only one of them is actually used.
A given IDL system preference can come from one of the following sources. These sources are listed in order of priority; the ones at the top will be used in preference to the ones below. The rest of this section describes the sources, listed here in descending order of priority:
You can specify system preference values from the IDL command line. There are two possible forms of this feature. The first form is specifying the preference name and value directly on the command line. For example, the following starts IDL while setting the default graphics device to PostScript:
% idl -IDL_DEVICE ps
The second form is using the -pref command-line option to specify an IDL preference file that IDL reads when it starts. For information on the syntax of this file, see “Understanding Preference Files, above . For example, suppose you had a file named thr.pref containing the following lines, which set parameters used by the IDL thread pool:
IDL_CPU_TPOOL_MAX_ELTS : 1000000
IDL_CPU_TPOOL_MIN_ELTS : 500000
IDL_CPU_TPOOL_NTHREADS : 4
Starting IDL with the following command causes these three preferences from thr.pref to take effect:
% idl -pref=thr.pref
Preferences specified directly on the command line take precedence over those specified within a command-line preference file. The direct form is mainly useful for ad-hoc interactive use of IDL, while the preference file form is of particular interest to those writing stand-alone applications in IDL, especially when using the runtime or virtual machine modes of operation. The use of a command line preference file lets authors of such applications control the values of preferences important to the application in a way that is user-adjustable and not hardwired into the application’s code.
Preferences set at the command line are not written to the current user’s preferences file, and can be modified using the PREF_SET procedure or the IDL Workbench preferences dialog.
Environment variables are an operating-system mechanism by which a table of names and associated values are passed between related processes. A parent process passes a copy of its environment to each child process that it creates. Under UNIX, environment variables are usually set in the user’s shell-initialization files (.cshrc, .login, .profile, .bashrc, etc.). Under Microsoft Windows, the system environment variable dialog is commonly used for this purpose.
Any IDL system preference can have its value defined by an environment variable of the same name. For example, to set the value of the IDL_PATH preference, which supplies the initial value for the !PATH system variable, you would define an environment variable named IDL_PATH.
Note: Although IDL’s preference names are internally case-insensitive, the UNIX environment is case-sensitive. Therefore, you must specify the environment-variable name in uppercase for IDL under UNIX to recognize it. In contrast, the Microsoft Windows environment is case-insensitive, and IDL recognizes any case. A simple rule that will always work is to always use uppercase environment-variable names.
To define an environment variable under Microsoft Windows, use the Environment Variables dialog available through the Windows control panel. Open the dialog by selecting Start > Settings > Control Panel > System > Advanced > Environment Variables.
To define an environment variable under UNIX, enter the following command (given here in ksh/bash format; adjust the command as necessary for your shell):
export IDL_GR_X_RENDERER=1
A preference specified by an environment variable is recognized by any version of IDL running on your system. For this reason, it is often desirable to avoid their use in favor of using a preference file.
A preference whose source is an environment variable can be modified during the current IDL session, using either the PREF_SET procedure or the IDL Workbench preferences dialog. Changes made using either of these methods will be written to the current user’s preferences file, but as long as the environment variable persists it will be the intial source of the preference value each time IDL starts. To alter or remove the environment variable, you must modify it at the source (UNIX shell-configuration file or Windows system dialog).
Every IDL distribution contains an idl.preffile within the pref subdirectory of the resource directory (<IDL_DIR>/resource/pref/idl.pref). The file’s syntax is the same as that of the user preference file. The file serves as a single place where system administrators can establish global defaults for all of their IDL users, without having to edit the preference file for each of those users separately.
For example, IDL uses a thread pool on systems with multiple CPUs in order to carry out numerical operations more quickly. The default is to use the same number of threads as the system has CPUs, in order to use the hardware to best advantage. This default is usually correct for single-user systems, but can be inconvenient at locations where large multi-CPU systems are being shared simultaneously by scientists using IDL for unrelated work. In such a case, the unrelated IDLs battle each other for CPU access and slow down overall system throughput. The system administrator can establish a more productive default by putting a line such as the following in the distribution preference file:
IDL_CPU_TPOOL_NTHREADS : 1
A preference whose source is the distribution preference file can be modified during the current IDL session, using either the PREF_SET procedure or the IDL Workbench preferences dialog. Changes made using either of these methods will be written to the current user’s preferences file, but as long as the distribution preference file contains a value for the preference it will be the intial source of the preference value each time IDL starts.
IDL user preferences are kept in a file named idl.pref. The APP_USER_DIR function is used to determine the location of this file. A distinct and separate user preference file is maintained for each combination of IDL version and operating-system family (UNIX or Microsoft Windows). The path to this file is displayed by the following command:
HELP, /PREFERENCES
Although you are can edit this file directly with any text editor, preferably use the IDL-supplied mechanisms for making changes. The IDL Workbench offers a graphical user interface for managing preferences. See IDL Preferences for more information. You can also use the PREF_SET and PREF_COMMIT procedures for lower-level command-line-based access to the same functionality.
Every IDL preference has a built-in default value. This is the value that IDL will use for the preference if a value is not set by any of the other sources described above. You can use the following command to see the default values for all preferences:
HELP, /PREFERENCES, /FULL
This section provides information on setting and committing changes to IDL system preferences, including details of the routines used to work with preferences, the pending state of changed preferences, and when committed preference changes take effect.
Many, but not all, IDL system preferences can be set by changing values in the IDL Workbench IDL Preferences dialog. Changing a value in the Preferences dialog and clicking Apply is equivalent to setting the preference with the PREF_SET routine with the COMMIT keyword. System preferences that can be set in the Preferences dialog are noted in the indiviual preference descriptions provided in the following topics.
The following routines provide user-level access to the preference system:
Note: Authors of IDL applications should not use these routines in their code to make preference changes. See Using Preference Etiquette for more information.
IDL allows you to change the value of any preference with the PREF_SET procedure. When you set a new value for a preference, the preference enters a pending state. IDL remembers the change, but continues to use the previously active effective value. In order to make a pending preference value take effect, it must be committed. To commit a preference, IDL takes the following steps:
There are two ways to commit a preference:
The pending state is useful for applications that allow users to manipulate preferences. In such an application, the user is typically allowed to make changes, but those changes can be discarded without taking effect if the user clicks the Cancel button. To implement this, an application uses PREF_SET to make the user's changes. If the user confirms the changes by clicking Done, PREF_COMMIT makes them permanent. Otherwise, they can be discarded by use of the RESET keyword. The pending state lifts the burden of tracking a user’s changes from such applications, and greatly simplifies their implementation.
Note: Pending changes are indicated as such in HELP, /PREFERENCES output.
Note: Authors of IDL applications should not use these routines in their code to make preference changes. See Using Preference Etiquette for more information.
Once a new preference value has been committed, its new value is used by the rest of IDL to determine some particular aspect of its operation. This change can take effect at one of three possible times:
The output from the following command describes when changes to each preference take effect:
HELP, /PREFERENCES, /FULL
For information on the output, see the documentation for the PREFERENCES and FULL keywords to HELP.
An IDL system preference file is a simple text file in which each preference is specified on a single line. The line consists of the preference name, followed by a colon (:) character, followed by the preference value. Empty and comment lines are allowed; IDL ignores them.
Note: If you use the API functionality to commit preference changes, IDL overwrites the user preference file accordingly. Doing so removes any comments that you manually added to the file.
Here is a sample preference file:
# Sample IDL preference file
# Author: Exelis Visual Information Solutions
# No user information in SAVE and JOURNAL files
IDL_DATAFILE_USER_COMMENTS : 0
# Suppress information messages (alias used)
IDL_QUIET : on
# Buffer size = 1000 lines
IDL_RBUF_SIZE : 1000
You can give a preference file any name and extension, but you might want to use the .pref extension for clarity.
While you can create and edit preference files using any text editor, in general it is better to modify the user preference file using the API functionality.
The IDL’s preference system routines PREF_SET and PREF_COMMIT provide programmatic control over the values of preferences saved in an individual user’s preference file. In general, as an IDL application author, you should not use these routines in IDL code. Since preference values set in the user preference file persist between sessions, changes made by your application using these routines will affect your end user’s IDL environment even when he or she is running other applications.
Preference files loaded at application startup provide a much more user-friendly mechanism for specifying preference values that apply only to your application. To use this mechanism, create a preference file that contains the preference values you want to have in effect when your application runs, and include the name of the preference file in the command that launches your application via the -pref command-line option.