|
|
IDL Reference Guide: IDL Preferences |
|
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 development environment (IDLDE) 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. There are two data types, string and integer (numeric). The numeric preferences are further specialized:
The complete set of IDL 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.
This section of the appendix contains the following information:
The value of each 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 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 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. 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.
If a preference is set at the command-line, IDL considers it to be read-only. IDL uses the value provided for the duration of the current IDL session, but refuses to let you attempt to change it with the PREF_SET procedure. Preferences set at the command line are not written to the current user's preferences file. To alter the preference, you should modify it at the source by restarting IDL with the new value on the command line.
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 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.
If a preference is set by an environment variable, IDL considers it to be read-only. IDL uses the value provided for the duration of the current IDL session, but refuses to let you attempt to change it with the PREF_SET procedure. Preferences set via environment variables are not written to the current user's preferences file. To alter the environment variable, you should modify it at the source (UNIX shell-configuration file or Windows system dialog). Before the change is visible to IDL, you need to exit IDL and restart it.
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:
IDL_CPU_TPOOL_NTHREADS : 1
If a preference is set by the distribution preference file, IDL considers it to be read-only. IDL uses the value provided for the duration of the current IDL session, but refuses to let you attempt to change it with the PREF_SET procedure. Preferences set in the IDL distribution preference file are not written to the current user's preferences file. To alter such a preference, you should modify it at the source by changing the contents of the distribution preference file. You need to exit IDL and restart it before the change is visible to IDL.
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 IDLDE offers a graphical user interface for managing preferences. See Setting 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.
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
For information on the output, see the documentation for the PREFERENCES and FULL keywords to HELP.
This section provides information on setting and committing changes to IDL preferences, including details of the routines used to work with preferences, the pending state of changed preferences, and when committed preference changes take effect.
There are four routines in IDL that 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. |
Unless the current effective value for a preference is read-only, 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:
.reset_session or .full_reset_session executive 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.
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 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 = 50 lines IDL_RBUF_SIZE : 50
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).
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 for details.)
IDL Online Help (March 06, 2007)