Previous Application Programming: Distributing Runtime Mode Applications Next

Preferences for Runtime Applications

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.


Note
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 Preferences for a detailed discussion of the preference system.

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

Loading Preference Values at Application Startup

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

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. This option is especially useful if you are creating an application that will be run when a user clicks on the icon for an executable file produced by the IDL Project mechanism.

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 Preferences for a detailed discussion of these options.

Windows Runtime Preferences

Under Microsoft Windows, the IDL Project mechanism allows you to create a .exe file that launches your runtime application. Because this method of launching the application does not lend itself to setting command line options, IDL provides the following Windows-only preference features for use with runtime applications.

Loading an idl.pref File

As described in Loading Preference Values at Application Startup above, when IDL for Windows starts up, if it finds a file named idl.pref in the directory that includes the IDL DLL (usually the bin/bin.platform subdirectory of the IDL or runtime application distribution where platform is your platform-specific bin directory), it loads preference values contained in that file.

Windows-Only Runtime Preferences

There are three Windows-only runtime preferences:

These preferences are honored only when the idlrt.exe executable is in use. Their values are described in detail in Windows Runtime Preferences.

Examples

Suppose you have 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, if you use the IDL Project interface to create an executable file myapp.exe that starts your application, 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.

  IDL Online Help (March 06, 2007)