About IDL System Preferences
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:
- A numeric preference can have a minimum and/or maximum value beyond which it is not allowed to be set.
- A numeric preference can be discrete, meaning that the possible values are constrained to be one of a fixed set of values. In most cases, IDL lets you reference these values using case-insensitive mnemonic names called aliases that make them easier to use and remember. For example, many of IDL's preferences are of an integer type called BOOLEAN. Boolean preferences are discrete, with possible values of 1 and 0. The aliases "True", "Yes", and "On" are accepted for the value 1, and "False", "No", and "Off" for 0.
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:
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.
This section of the appendix contains the following information:
Understanding System Preference Sources
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:
Command Line
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:
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. For example, suppose you had a file named thr.pref containing the following lines, which set parameters used by the IDL thread pool:
Starting IDL with the following command causes these three preferences from thr.pref to take effect:
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 Variable
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):
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).
IDL Distribution Preference File
Every IDL distribution contains an idl.pref file 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; for more information, see Understanding Preference Files. 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:
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.
User Preference File
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:
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.
For more information, see Understanding Preference Files.
IDL Default Value
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:
For information on the output, see the documentation for the PREFERENCES and FULL keywords to HELP.
Changing Preference Values
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.
IDL Workbench Preferences Dialogs
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. See IDL Preferences for more on the IDL Workbench Preferences dialog.
Preference Routines
There are four routines in IDL that provide user-level access to the preference system:
- PREF_COMMIT — used to commit preferences or discard pending values. See PREF_COMMIT.
- PREF_SET — used to set the value of a user preference by providing a new value or by setting it to its default value. See PREF_SET.
- PREF_GET — used to obtain detailed information about the status of a preference. See PREF_GET.
- PREF_MIGRATE — used to import preferences from other versions of IDL into the current version. This routine is written in the IDL language, and uses the other three routines above to do the actual work. See PREF_MIGRATE.
Note
Authors of IDL applications should not use these routines in their code to make preference changes. See Using Preference Etiquette for more information.
The Pending State
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:
- PREF_COMMIT — used to commit preferences already in the pending state (see PREF_COMMIT)
- PREF_SET — used with the COMMIT keyword to set and commit a specific preference in a single operation (see PREF_SET)
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.
When Committed Changes Take Effect
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:
- Immediately — in most cases, changes to a preference are reflected in IDL's operation immediately. For example, preferences are used to supply default values for many system variables. Usually, a change to a preference results in the associated system variable changing to the new value as soon as the new preference value is committed.
- On reset or restart — a few preferences do not take effect until the next use of the
.reset_sessionor.full_reset_sessionexecutive commands, or until IDL is exited and restarted. One example of this group is the IDL_DEVICE preference, which specifies the default direct graphics device. Changes to IDL_DEVICE do not cause your current graphics device to be immediately reset. If you later use a reset executive command or restart IDL, however, the new default is used. - On restart — a very small number of preferences only take effect in subsequent IDL sessions. The IDL_DLM_PATH preference is one such preference. Changes to IDL_DLM_PATH are not seen in the current IDL session, but take effect the next time IDL is run.
The output from the following command describes when changes to each preference take effect:
For information on the output, see the documentation for the PREFERENCES and FULL keywords to HELP.
Understanding Preference Files
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: ITT 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 (see Preference Routines).
Using Preference Etiquette
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. (See Command Line Options for IDL Startup (Using IDL) for details.)
