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.

Preference Etiquette

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, application authors 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.

Loading Preference Values at Application Startup

IDL provides the following mechanisms for loading preference values when an IDL application starts:

  • Specifying a preference file via the -pref command line option.
  • Providing an idl.pref file located in the same directory as the IDL DLL file (Windows only).
  • Specifying individual preference values specified as command line options.
  • Specifying individual preference values via the values of corresponding system environment variables.
  • Modifying the 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; do 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.

Specifying Preferences at the Command Line

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.

Providing an idl.pref File (Windows Only)

The option to provide 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:

  • IDL_WINRT_FILE allows you to specify the name of a save file to be run when IDL starts up
  • IDL_WINRT_FILE_TYPE allows you to specify the licensing mode of a runtime application
  • IDL_WINRT_ICON allows you to specify the name of an icon file to use with a runtime application

These preferences are honored only when the idlrt.exe executable is in use.

Specifying Individual Preference Files

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.

Using Environment Variables

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.

Modifying the Default Preferences File

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.

Examples

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. 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.