System Preferences are internal values that control various aspects of IDL and supply initial values for system variables. Preferences can be specified from a variety of sources and persist between IDL sessions.
Each preference has a name that starts with IDL_.
IDL system preferences have two data types: string and integer (numeric).
The numeric preferences can have a minimum and/or maximum value beyond which it is not allowed to be set. In addition, a numeric preference can be discrete, meaning that the possible values are constrained to a fixed set of values. In most cases, IDL lets you reference these discrete values using aliases. For example, many of IDL’s preferences are of an integer type called BOOLEAN, 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, 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, values, and the source. For a detailed view, add the FULL keyword to HELP.
Note: Preferences that apply only to the IDL Workbench interface are stored separately. You can modify both workbench preferences and many IDL system preferences via the IDL Workbench Preferences dialog, but only system preferences are described here and only system preferences can be modified using the PREF_GET and PREF_SET routines.
Understanding System Preference Sources
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.
Command Line
You can specify system preference values from the IDL command line. There are two possible forms. 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 example, suppose you had a file named thread.pref containing the following lines:
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 preferences to take effect:
% idl -pref=thread.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. Using 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.
IDL Bin Directory
Your IDL installation may include an idl.pref file within your <IDL_DIR>/bin/bin.<arch> directory. This preference file is typically used by other applications that install IDL, and want to set the IDL_PREF_DIR preference to enforce a specific subdirectory to be used for their application's preferences.
Note: This preference file is ignored if you specify a command-line preference file.
Environment Variable
Any IDL system preference can have its value defined by a system or user 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.
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.
Note: You should always use uppercase when specifying environment-variable names.
IDL Distribution Preference File
Every IDL distribution contains an idl.preffile within the pref subdirectory of the resource directory (<IDL_DIR>/resource/pref/idl.pref). The file serves as a single place where system administrators can establish global defaults for all of their IDL users.
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:
HELP, /PREFERENCES
Although you can edit this file directly, to avoid mistakes use either the IDL Workbench dialog or the PREF_SET procedure.
IDL Default Value
Every IDL preference has a built-in default value. You can use the following command to see the default values for all preferences:
HELP, /PREFERENCES, /FULL
Changing Preference Values
IDL Workbench Preferences Dialogs
Many IDL system preferences can be set in the IDL Workbench 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.
Preference Routines
The following routines provide user-level access to the preference system:
- PREF_COMMIT: Used to commit preferences or discard pending values.
- PREF_SET: Used to set the value of a user preference.
- PREF_GET: Used to obtain information about a preference.
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 previous value until the new value is committed. To commit a preference, IDL takes the following steps:
- Writes a user preference file.
- Updates its internal state to make the pending values current.
- Notifies the IDL internals of the changed preference.
To commit a preference you can either use PREF_COMMIT or PREF_SET with the COMMIT keyword.
The pending state is useful for applications that allow users to change preferences, but may want to cancel such changes or commit all of the changes at once.
Note: Pending but uncommitted changes are indicated in the HELP, /PREFERENCES output.
When Committed Changes Take Effect
Once a new preference value has been committed, the effects of the new value can occur:
- Immediately: Usually, a change to a preference results in the associated system variable changing immediately.
- On reset: Some preferences do not take effect until the next use of the .reset_session or .full_reset_session executive commands. One example of this group is the IDL_DEVICE preference, which specifies the default direct graphics device.
- On restart: A few preferences only take effect in subsequent IDL sessions. For example, 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:
HELP, /PREFERENCES, /FULL
Preference Files
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. IDL quietly ignores empty and comment lines (with the hash character).
Here is a sample preference file:
# Sample IDL preference file
# 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
Note: If you use PREF_SET or PREF_COMMIT to commit preference changes, IDL overwrites the user preference file and removes any user comments. In general it is better to modify the user preference file using the built-in routines or dialogs.