IDL’s preference system allows developers, administrators, and individual users to control default values for many aspects of IDL’s environment and configuration. Creators of runtime applications can take advantage of the preference system to customize the environment in which a particular application runs.
Before attempting to use preferences to customize the runtime IDL environment, you should have a clear understanding of how IDL loads and uses preference values. See IDL System Preferences for a detailed discussion of the preference system.
IDL’s preference system routines PREF_SET and PREF_COMMIT provide programmatic control over the values of preferences saved in an individual user’s preferences file. In general, as an 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 wish 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 provides the following mechanisms for loading preference values when an IDL application starts:
-pref command line option.idl.pref file located in the same directory as the IDL DLL file (Windows only).idl.pref file in the resource/pref subdirectory of the application distribution. This method is only useful if you are distributing an IDL distribution to support your application — you should not modify an existing idl.pref file in your end user’s installed IDL distribution.Note: These mechanisms change the value of the specified preference or preferences for the current IDL session only. Values are not written to the user’s preference file.
Of these options the first — specifying a preference file via the -pref command line option — is the most general and user-friendly. By specifying the values for preferences used by your application in a separate, application-specific preferences file, you can both control IDL’s runtime environment and provide your end users with a mechanism to tune the IDL environment themselves. If one of your end users can achieve better performance using a different preference value, all that user needs to do is alter the value in the preference file loaded at startup.
The second option — providing an idl.pref file in the same directory as the IDL DLL — is only available under Microsoft Windows.
There are three Windows-only runtime preferences:
These preferences are honored only when the idlrt.exe executable is in use.
Specifying individual preference values at the command line provides little advantage over specifying the name of a preference file, but may be useful if the number of preferences to be specified is small.
The technique of using environment variables to specify preference values can be useful, but should be used with caution. Setting an environment variable provides a relatively easy way for your end users to override your preference settings without the need to modify the preference file you distribute. Depending on how the value of an environment variable is specified, however, the value may persist between invocations of your application. As a result, end users might experience unexpected behavior in other IDL applications (or in IDL itself) if an environment variable specified for your applications is in effect when the other applications are run.
You should only modify the resource/pref/idl.pref file if you are creating and distributing your own runtime application distribution. See IDL System Preferences for a detailed discussion of these options.
Suppose you created an IDL runtime application named myapp that performs numerous CPU-intensive calculations that could potentially use multiple CPUs on a multiprocessor system. If you want to ensure that your application uses at most two CPUs, you could include the following setting in a preference file named myapp.pref:
IDL_CPU_TPOOL_NTHREADS : 2
On UNIX platforms, you could then invoke your runtime application with a command line something like the following:
idl -rt=/myapp/myapp.sav -pref=/myapp/myapp.pref
On Windows platforms, you could create a preference file containing the following:
IDL_CPU_TPOOL_NTHREADS : 2 IDL_WINRT_FILETYPE: 0 IDL_WINRT_ICON: c:\myapp\myapp.ico
These preference values specify the maximum number of CPUs, the need for a runtime license for your application, and the application icon. If you name the preferences file idl.pref and place it in the bin/bin.platform subdirectory of your application distribution (where platform is your platform-specific bin directory), IDL will load the preferences when a user double-clicks on the application icon.