An IDL runtime mode application is a program or set of programs written to use IDL’s data analysis and display capabilities in a stand-alone mode, without access to the IDL Workbench, the IDL command line, or the ability to compile IDL .pro files. All IDL code for a runtime mode application must be pre-compiled and provided in the binary SAVE file format. If a runtime mode application presents a user interface, it must be exposed via the IDL widget toolkit functionality, since no access to the IDL command line or command output log is provided to the user.

Runtime mode applications are generally intended for users who do not have an IDL development license, although users who do have a development license can execute runtime mode applications as well. Typically, a runtime mode application is distributed along with an IDL distribution hierarchy containing all of the files necessary to run the application. (The exception is an application written to be run in the IDL Virtual Machine, which is installed separately from the IDL application itself.)

IDL applications written to run with an IDL development license (one that allows the application to compile .pro files and access to the IDL command line) can be distributed to other IDL users. Distributing applications that run with an IDL development license can be as simple as providing the application files to the end user along with instructions describing how to install the files and configure the application.

This section describes the process of packaging an application written entirely in IDL so that it can be distributed to end users who do not have an IDL development license. Much of the information in this section is relevant whether or not your application end users have an IDL development license, but the assumption is that your end user will not have such a license.

To create and distribute an IDL runtime application, do the following:

  1. Refer to Limitations of Runtime Applications.
  2. Create your application using an IDL development license. Test the application using the type of license you expect your end user to have.
  3. If your application uses Callable IDL, see Callable IDL Applications for information on creating a runtime distribution.
  4. Decide on a licensing option (see below) and obtain licenses for your application.
  5. Create an application distribution: If your IDL application will be run in an installation with an IDL development license, you do not need to create an IDL distribution. Just package your application files (either .pro files or .sav files, and any necessary data files) and distribute them to your users along with instructions describing how to install and launch the application. If your application will be run by users who do not already have an IDL installation, or who do not have the proper IDL version, you can create and distribute a runtime application distribution using the MAKE_RT procedure.
  6. Create invocation and use instructions for your application (see below for details).
  7. Create an installer, if desired, and installation instructions for your application. Installation of your application on the end user’s machine can be performed manually by the user, or it can be automated using an installer. There are a number of commercial applications available to help you build installers. In order to avoid conflicts with existing versions of IDL, you should warn your users NOT to install your application in the same directory as IDL x.x, where IDL x.x is the version used by your application.NV5 Geospatial Solutions’ Professional Services Group can create installation packages for your application. Contact your sales representative for additional information.

Licensing Options for Runtime Mode Applications

Free Runtime License (IDL Virtual Machine)

The IDL Virtual Machine is a runtime version of IDL that can execute IDL SAVE files without an IDL license. Users install the IDL Virtual Machine with the IDL Installer available on an IDL distribution CD-ROM or from the IDL download website.

Purchased Runtime Licenses

You can purchase runtime mode licenses from IDL. Runtime mode licenses provide a way to include a licensed IDL installation with your IDL application or Callable IDL application.

When you distribute a licensed version of IDL with your application, you provide users with IDL functionality, but do not provide access to the IDL command line, the IDL Workbench, or the ability to compile IDL .pro files. Runtime licenses are appropriate for:

  • Vertical-market packages developed in IDL but appear to the user as standalone applications.
  • Software designed for use by operators or technicians who do not need programmatic access to IDL’s full range of analytical tools.
  • Situations in which the you do not want end users to be able to modify functions written in the IDL language.
  • Organizations with existing investments in IDL code, where some mixture of distributable and development IDL licenses may be cost-effective.

If your users need access to the full scope of IDL’s features or advanced analytical tools outside the scope of your application, you might choose to distribute your application with an IDL development license. Contact your sales representative to purchase copies that you can distribute.

Runtime Licensing

A runtime license allows you to run an IDL application that cannot display the IDL Workbench or IDL command line, and cannot compile .pro files. This type of licensing offers developers who have smaller customer bases the opportunity to buy single distribution licenses as needed, paying a small fee for each license. The license is either a node-locked license running on the machine that has the application (you will need to obtain information about your customer’s machine), or a floating license running on a license server machine.

When using runtime licensing, you can create a single unlicensed distribution that you can distribute to all your customers, you purchase a license for each customer and provide that license along with the information necessary for the customer to license your application. To create a license for a user that does not have Internet access, contact Technical Support.

Ensuring Your License is Used

To ensure your application will run with your runtime license and not in the IDL Virtual Machine, add code similar to the following to your application before preparing the application distribution:

isVM = LMGR(/VM)

IF isVM THEN BEGIN

   void = DIALOG_MESSAGE(['Please contact the author', $

      'for licensing instructions'])

   RETURN

ENDIF

Obtaining and Installing Runtime Licenses

Runtime applications are licensed as node-locked licenses or floating licenses. If you purchased a runtime license, you will receive an e-mail from NV5 Geospatial Solutions with a license activation code. To activate a node-locked license, see the installation and licensing documentation that came with your software entitlements. To activate a floating license, see the Flexera license server installation and administration documentation that came with your software entitlements.

Custom Features

You can request to have your own custom feature license added to your runtime license. Using a custom feature license allows you to specify that your application will only run if the custom feature license is present. Contact your sales representative for information on adding custom features to your runtime license.

Embedded Licensing

An embedded license allows your application to run without an external IDL license. The application can be distributed to multiple users and will run on any system supported by IDL. Licensing an IDL application with an embedded license is the simplest form of licensing for end users.

To create applications with embedded licenses, purchase an IDL Developer’s Kit license from NV5 Geospatial Solutions. The Developer’s Kit license gives your copy of IDL the ability to add an embedded license to your application’s SAVE file.

Note: Licenses for Callable IDL applications are embedded directly in the application code.

Optional Features

When you purchase an IDL Developer’s Kit license, you can request to include one or more optional features in the license. Optional feature licenses control access to additional-cost IDL modules, such as the IDL DataMiner.

When your application attempts to use an additional-cost IDL module, IDL first checks if a license for the module is included in your application’s embedded license. If a license for the module is not included in the embedded license, IDL checks for node-locked or floating licenses available to that product installation. If a license for the module is not available, the user will not be able to use the features of that module.

Starting a Runtime Application

You must provide your end users with instructions describing how to start your application. You may choose to provide users with the name and location of your application executable along with a launch command to execute, or (if you are using an installer for your application) with shell scripts, shortcuts, or Start menu items.

The application startup process differs depending on whether you are supplying an IDL runtime distribution (created using the IDL Project interface or the make_rt script) or are relying on your user to install a full (if potentially unlicensed) IDL distribution. The following sections describe the process for each of these situations.

Using an IDL Runtime Distribution

If you use the MAKE_RT procedure to create a runtime distribution, specifying a SAVE file for your application, application launch scripts for your application are created automatically. (You may need to modify the launch scripts.) If you do not use MAKE_RT, you can still create application launch scripts based on generic scripts included in the IDL distribution.

Using an Existing IDL Distribution

If you are relying on your end user to install an IDL distribution (licensed or not) before running your application, you can either give your users instructions based on the following information or create scripts to launch your application. The specifics depend on your end user’s platform.

Windows

To start a runtime application if you are not providing a runtime IDL distribution, either change directories to IDL_DIR\bin\bin.platform directory (where IDL_DIR is the main IDL directory and platform is the platform-specific bin directory) or ensure that this directory is included in the Windows PATH environment variable. Do one of the following:

  • If your application runs in the IDL Virtual Machine, enter the following:
    • idlrt -vm=<path><filename>
  • If your application uses a runtime license, enter the following:
    • idlrt <path><filename>

    where <path> is the path to the SAVE file, and <filename> is the name of the SAVE file.

To simplify startup of your application, you can use the Windows launch script. Alternately, you can create a batch file that changes directories to the IDL bin directory and invokes idlrt with the SAVE file name. Such a batch file might look something like the following (you will need to substitute *** with your installation path):

@ECHO OFF

REM This batch file launches the IDL runtime application myapp

cd c:\Program Files\***\IDLxx\bin\bin.x86

idlrt C:\mydir\myapp.sav

UNIX/Mac

To start a runtime application if you are not providing a runtime IDL distribution, first ensure that the environment variable IDL_DIR is set to the path to the main directory of the IDL installation. When the IDL_DIR environment variable is set, do one of the following:

  • If your application runs in the IDL Virtual Machine, enter the following:
    • idl -vm=<path><filename>
  • If your application uses a runtime license, enter the following:
    • idl -rt=<path><filename>

    where <path> is the path to the SAVE file, and <filename> is the name of the SAVE file.

To simplify startup of your application, you can use the UNIX or Mac launch script. Alternately, you can create a shell script that sets the IDL_DIR environment variable and calls IDL with the correct flag and SAVE file name. Such a script might look something like the following:

#!/bin/sh

# This script launches the IDL runtime application myapp

IDL_DIR=/usr/local/***/idlxx

idl -rt=/mydir/myapp.sav

Specifying Application Preferences at Startup

You can specify the values of IDL preferences in your startup command by including either the -pref command line option or by specifying individual preference values on the command line.

For example, suppose your application is installed in the directory /mydir. To have IDL load the preference values contained in a file named myapp.pref in the same directory when the application starts, you might modify your the UNIX startup script described above to read:

#!/bin/sh

# This script launches the IDL runtime application myapp

IDL_DIR=/usr/local/***/idlxx

idl -rt=/mydir/myapp.sav -pref=/mydir/myapp.pref

Similarly, to force a Windows runtime application to use software rendering, you could explicitly specify the preference value in a batch file that starts the application:

@ECHO OFF

REM This batch file launches the IDL runtime application myapp

cd C:\Program Files\***\IDLxx\bin\bin.x86

idlrt C:\mydir\myapp.sav -IDL_GR_WIN_RENDERER 1

See Preferences for Runtime Applications for details.

What Happens When IDL Runs Your Application

When you launch an IDL runtime application, IDL does the following:

  • IDL restores the specified SAVE file, if one is specified at the command line or when creating the distribution via the IDL Project interface or make_rt script.
  • On Windows, if no SAVE file is specified, IDL restores the SAVE file specified by the IDL_WIN_RT preference.
  • If no SAVE file is specified, restores the file runtime.sav

IDL then calls the main procedure. This is one of the following:

  • A procedure named main in the restored SAVE file
  • A procedure with the same name as the SAVE file

When the main procedure returns, IDL exits.

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.

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.

Preference Example

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.

Limitations of Runtime Applications

IDL applications that run without an IDL development license, whether native IDL or Callable IDL, do not have access to the IDL compiler and thus cannot compile IDL source code from .pro files. As a result, operations that require the compiler will not execute when a development license is not present. This includes IDL applications written to be distributed to users who do not have a development IDL license.

Note: Since runtime applications do not allow code compilation, startup files are not executed.

  • Because the ON_ERROR procedure has the potential to force the IDL interpreter into an idle state when an error is encountered, use the CATCH procedure instead if your application will be distributed to users without a development IDL license.
  • When a SAVE file is executed, IDL’s current working directory will be the directory that contains the SAVE file.
  • Support for the IDL help system is not included in a runtime distribution by default. This means that applications that use the ONLINE_HELP procedure to display IDL help topics will fail unless you explicitly include the required support. If you use the MAKE_RT procedure to create a runtime distribution, you can use the IDL_HELP keyword to include the necessary files. Support for the IDL Assistant help viewer (IDL’s standard help viewer for releases 6.2 thorugh 6.4) is not included in a runtime distribution by default. If your application uses an IDL Assistant help system (that is, if it includes a .adp file), you will need to explicitly include the IDL Assistant help viewer. If you use the MAKE_RT procedure to create a runtime distribution, you can use the IDL_ASSISTANT keyword to include the necessary files.