92 Rate this article:

No rating

INTERNAL: Miscellaneous Notes on Running Non-interactive IDL Development or IDL Runtime Application Sessions on Windows

Anonym Tuesday, December 24, 2013

This help article is a collection of miscellaneous topics related to running IDL applications non-interactively on Windows.

CONTENTS
1.) idl.exe
2.) idlrt.exe
3.) IDL batch script program
4.) IDL_PATH preference
5.) !PATH IDL system variable
6.) The -arg and -args IDL startup command line switches
7.) The -e IDL session startup command line switch
8.) Example commands to automatically launch an IDL program when IDL is launched
9.) Useful references on the Exelis VIS web-based IDL Help pages on the Documentation Center

1.) idl.exe

The “idl.exe” starts a command line IDL development session on Windows. Also is useful for running non-interactive IDL development sessions. IDL development sessions (idl.exe, like the IDL Workbench environment (idlde.exe))are capable of compiling and running IDL source code program files (*.pro),taking interactive commands, or running IDL batch script files. IDL development sessions can also restore and run pre-compiled IDL application *.sav files. Requires an IDL development license. Default location on Windows:

C:\ProgramFiles\exelis\idl83\bin\bin.x86_64\idl.exe (64-bit IDL 8.3)
C:\ProgramFiles\exelis\idl83\bin\bin.x86\idl.exe (32-bit IDL 8.3)

A special syntax is needed to launch IDL from a command shell, to automatically call/run an IDL program, and then to pass that IDL program command arguments. For example, if you could run a procedure called "myapp", which takes one command argument, from an IDL> command prompt like this:

IDL> myapp, 9.99

Then to launch myapp automatically when idl.exe is launched, you might launch "idl.exe" with the "-e" command line switch, issuing a Windows shell command like this:

idl.exe -e "myapp, 9.99"

Or if you needed to pass "myapp" an argument that could not be easily represented in a string, you might create a wrapper program that, for example, acquires data from a file and then passes that to myapp as a variable. Then you might call that program instead of "myapp", for example:

idl.exe -e "mywrapper, 'C:\path\to\mydata.dat'"

You could also run "myapp" from an IDL batch script which in essence is just a text file that contains a list of IDL commands, in the format that you would enter commands at an IDL> command prompt. For example:

    ; file: mybatchscript.pro
    data = fltarr(100, 30)
    openr, 1, 'C:\path\to\mydata.dat'
    readu, 1, data
    close, 1
    myapp, data
    exit ; Exit IDL session after running this batch script
    ; endfile

Then you might launch IDL with the batch script like this:

idl.exe "c:\path\to\mybatchscript.pro"

Note that if you will be needing to launch a precompiled IDL application *.sav file program in IDL Runtime (RT) mode, using "idlrt.exe", then neither the"-e" mechanism or using IDL batch scripts is available for IDL runtime sessions. In this case, if you will need to be able to provide one or more command line input arguments to an IDL RT application session, you could instead use the "-args" command line switch that is available to both idl.exe and idlrt.exe. For example, the code for"mywrapper.pro" might look like:

    pro mywrapper, filename
      args = command_line_args(count=cnt)
      ; If not given a command statement parameter then
      ; use a value passed via the -args command line switch
      if n_elements(filename) eq 0 then $
        filename = args[0]
      data = fltarr(100, 30)
      openr, 1, filename
      readu, 1, data
      close, 1
      myapp, data
    end

You could then test the source code program like this:

idl.exe -e "mywrapper" -args "C:\path\to\mydata.dat"

After compiling and saving the program to "mywrapper.sav" in addition to calling the program as above using idl.exe, you could also run the program inIDL RT mode like this:

idlrt.exe "c:\path\to\mywrapper.sav" -args "C:\path\to\mydata.dat"

A couple of other ways to bring data dynamically into an IDL program is to use the IDL "GETENV" function to read IDL session shell environment variable strings or reading data from files.

[ back to top ^ ]

2.) idlrt.exe

The “idlrt.exe” command starts an IDL runtime (RT) session (Windows), which is only capable or loading and running IDL application save (*.sav) files (which are precompiled binary versions of IDL programs (similar to the concept of Java class files). IDL Runtime sessions cannot compile or execute IDL source code program (*.pro) files, including IDL batch script programs. Minimally requires and IDL RT license; can also use an IDL development license. Default location on Windows:

C:\ProgramFiles\exelis\idl83\bin\bin.x86_64\idlrt.exe (64-bit IDL RT 8.3)
C:\ProgramFiles\exelis\idl83\bin\bin.x86\idlrt.exe (32-bit IDL RT 8.3)

Note that neither the "-e" mechanism or using IDL batch scripts is available for use with IDL runtime sessions.

Using the "-args" command line switch (used in conjunction with the IDL routine "COMMAND_LINE_ARGS") to "idlrt.exe" is also available to provide dynamic startup parameter data, for example:

idlrt.exe "c:\path\to\mywrapper.sav" -args "C:\path\to\mydata.dat"

as well as other mechanisms like using GETENV or reading data from files.

Note that if licensing is unavailable for "idlrt.exe", then execution will default to an IDL Virtual Machine (VM) session. IDL VM is a unlicensed, limited execution mode of IDL RT which requires user interaction to dismiss a displayed IDL VM splash screen, in order to continue with program execution. Because of the interaction requirement, IDL VM is not suitable for running non-interactive IDL programs sessions.

[ back to top ^ ]

3.) IDL batch script program

An IDL batch script program is a text file containing an list of IDL commands in the form of commands that could be entered interactively at an IDL> command prompt. For example:

    ; File: mybatchscript.pro
    data = fltarr(100, 30)
    openr, 1, 'C:\path\to\mydata.dat'
    readu, 1, data
    close, 1
    myapp, data
    exit ; Exit IDL session after running this batch script
    ; End file

Note that IDL batch scripts do not have a PRO or FUNCTION statement designation or an END statement, and cannot be compiled. IDL batch scripts can be run from and IDL> command prompt by using the "@" character, for example:

IDL> @C:\Users\joeuser\mybatchscript.pro

Or from a Windows command prompt as an argument to idl.exe, for example (notice the absence of the "@" in this case):

idl.exe "C:\Users\joeuser\mybatchscript.pro"

Additionally, an IDL batch script program can also be automatically launched using the"-e" command line switch to idl.exe, for example:

idl.exe -e "@C:\Users\joeuser\mybatchscript.pro"

[ back to top ^ ]

4.) IDL_PATH preference

“IDL_PATH” is an IDL preference that specifies one or more directory path locations from which to automatically find, resolve and execute a IDL routine based on the file name prefix of the *.pro or application *.sav file. If this IDL preference is not explicitly defined, then the IDL session's default library and examples directory IDL program search path be implied.

Note that when customizing this preference, be sure that the token string"<IDL_DEFAULT>" is included in the IDL_PATH definition along with the added custom path(s) to allow IDL to find the default IDL library *.pro and *.sav file routines.

A custom IDL_PATH preference setting can be persisted to an IDL user's personal IDL preference file (for example: C:\Users\joeuser\.idl\idl\pref-10-idl_8_3-windows\idl.pref) by doing one of the following:

a.) Add this new directory location to the IDL_PATH in preference via the IDL Workbench Preferences dialog.

b.) Use the IDL command "PREF_SET" with the "/COMMIT" keyword setting (/COMMIT causes the change to be recognized immediately by IDL; note even with the/COMMIT setting, some IDL preferences will not be recognized un till after the IDL session is restarted). Again be sure to include the string "<IDL_DEFAULT>" in a customized definition for this preference. For example:

PREF_SET, 'IDL_PATH','<IDL_DEFAULT>;C:\Users\joeuser\myidllibdir', /COMMIT

Note that no spaces are used before or after the ";" character to separate multiple path settings.

A custom IDL_PATH preference may also be defined without persisting the change to the user's idl.pref file.

c.) Define an "IDL_PATH" Windows environment variable that include the IDL default program search path and custom path(s). This can be set globally for the user or Windows system. IDL Preferences that are defined via a Windows environment variable supersedes settings made via the IDL Workbench Preferences dialog (a) or via the PREF_SET procedure in IDL.

Note that when setting a Windows User or System variable via the Windows Environment Variable dialog, no quote characters are used in the path definitions. Note also that no spaces should be included before or after the ";" character that separates multiple paths for this preference.

Or IDL_PATH may be defined locally within a command prompt shell or Windows batch(*.bat) script that is launching the IDL or IDL RT session. For example (notice"<" and ">" must be escaped with a "^" character when used with the Windows SET command at a Windows command prompt or in a Windows batch script.

    SET IDL_PATH=^<IDL_DEFAULT>^;C:\path\to\myidllibdir
    CD "C:\Program Files\exelis\idl83\bin\bin.x86_64"
    idl.exe -e "myapp, 'my string'"

The advantage of setting the IDL_PATH environment variable locally in the shell that will launch the IDL session, as opposed to setting the value globally as a System or User environment variable via the Windows Environment Variable setting dialog (or using PREF_SET or using the IDL Workbench Preferences dialog),is that the IDL_PATH setting can be easily customized to that particular IDL session instance. Setting IDL_PATH via a shell environment variable to the IDL session is that the change is local to the current shell environment (not global) and is not persisted to the user's idl.pref file.

d.) Using the "-IDL_PATH" IDL session startup preference switch can define the IDL_PATH preference for the current IDL session. Note that setting the IDL_PATH preference in this way will override other IDL_PATH preference definition mechanisms. Setting IDL_PATH via the-IDL_PATH command line switch to an IDL session is not persisted to the user's idl.pref file (notice that unlike item (c) above, the "<"and">" characters don’t need to be escaped in this context). For example:

idl.exe -IDL_PATH "<IDL_DEFAULT>;C:\path\to\myidllibdir" -e "myapp, 'mystring'"

idlrt.exe -IDL_PATH "<IDL_DEFAULT>;C:\path\to\myidllibdir" -args myapp "mystring"

[ back to top ^ ]

5.) !PATH IDL system variable

“!PATH“ is an IDL system variable that derives its underlying initial value from the IDL_PATH preference. IDL users will typically manage the IDL program search path via the IDL_PATH preference mechanism. However, advanced users may manage the value of !PATH directly, keeping in mind possible changes that can be introduced by subsequent changes to the IDL_PATH preference and to changes to !PATH caused by the IDL Workbench Projects automatic path management mechanism. IDL_PATH and !PATH do not use the exact same path specification syntax. See documentation for details.

[ back to top ^ ]

6.) The -args or -arg IDL startup command line switches

These command line switches allow a user to pass global command line argument strings to the IDL session. IDL programs running in such an IDL session may access the command line argument string(s) through the use of the IDL "COMMAND_LINE_ARGS" function.

Note that the idl.exe and idlrt.exe programs are unable to directly accept unknown command line arguments outside of the context of the -arg or -args command line switches. For example, the following commands are NOT valid:

idlrt.exe "C:\Users\joeuser\myapp.sav" "my string" 1.234 <<<NOT VALID>>>

idl.exe -e "mywrapper" "C:\path\to\mydata.dat" <<<NOT VALID>>>

The -args switch allows you to pass multiple strings and must be used at the end of the IDL session launch command. The -arg switch allow you to pass a single command line argument string and may be used within an IDL session launch command. For example:

idlrt.exe "C:\Users\joeuser\myapp.sav" -args "my string" 1.234

idl.exe -arg "C:\path\to\mydata.dat" -e "mywrapper"

[ back to top ^ ]

7.) The -e IDL session startup command line switch

Command line IDL "-e" switch to execute an IDL command, similar to executing the command at an IDL> command prompt, for example:

idl.exe -e "myapp, 'my string'"

The IDL session will automatically exit after executing the given command. Note that in order for IDL to automatically resolve the program "myapp" from the source code file "myapp.pro" or save file "myapp.sav", without having to explicitly compile the *.pro file (in an IDL development session) or resolve the *.sav file (in an IDL development or runtime session), then the directory containing the program file should be included in the IDL_PATH preference setting.

The "-e" command line switch can only be used in the context of a development IDL session. The "-e" command line switch is not valid in the context of a licensed IDL Runtime session. For example, although not documented syntax, the following command used in conjunction with myapp.sav in the IDL search path, would attempt to launch a development session of IDL:

idlrt.exe -e "myapp" <<< LAUNCHES A DEVELOPMENT IDL SESSION >>>

[ back to top ^ ]

8.) Example shell commands from above that automatically launch a specified IDL program when the IDL session is executed

a.) IDL development session with automatic execution of IDL command:

idl.exe -e "myapp, 9.99"

idl.exe -e "myapp, 'my string'"

idl.exe -e "mywrapper" -args "C:\path\to\mydata.dat"

idl.exe -IDL_PATH"<IDL_DEFAULT>;C:\path\to\myidllibdir" -e "myapp, 'mystring'"

b.) IDL runtime session execution of application IDL save file:

idlrt.exe "C:\Users\joeuser\myapp.sav"

idlrt.exe "C:\Users\joeuser\myapp.sav" -args "my string" 1.234

idlrt.exe -IDL_PATH "<IDL_DEFAULT>;C:\path\to\myidllibdir" -args myapp "mystring"