|Application Programming: Distributing Runtime Mode 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.
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.
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.)
IDL provides the following mechanisms for loading preference values when an IDL application starts:
-prefcommand line option.
idl.preffile located in the same directory as the IDL DLL file (Windows only).
idl.preffile in the
resource/prefsubdirectory 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.preffile in your end user's installed IDL distribution.
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. 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.
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.
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
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.
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.
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
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
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)