See the following topics:

Starting IDL

The easiest way to start IDL is by launching the IDL Workbench, which is an Eclipse-based graphical user interface.

You can also run IDL in command-line mode, which uses a text-only interface and sends output to your terminal screen or shell window. See Command-line Options for IDL Startup for details.

To launch IDL:

Operating
System

Workbench

Command Line

Windows 64-bit

Start > IDL x.x

Start > IDL x.x IDL Command Line

Mac 64-bit

Double-click on the idl icon in your IDL installation folder

or

Enter idlde at the X11 Terminal window shell prompt

Click on the idl icon in your IDL installation folder

or

Enter idl at the X11 Terminal window shell prompt

Linux 64-bit

Enter idlde at the shell prompt

Enter idl at the shell prompt

 

To launch IDL from the shell prompt, you must first explicitly open a terminal window and set up each IDL user's environment.

Start the IDL Command Line from Windows Explorer

Because the concept of the current directory plays such an important role in IDL, you have the option to open a new command line session from a folder in Windows Explorer. When you do this, the IDL command line opens with the selected folder as IDL's current directory.

 

 

To open the IDL command line from Windows Explorer:

  1. In Windows Explorer, navigate to the folder that you want to set as your current IDL directory.
  2. Right-click the folder name to open a pop-up menu.
  3. From the pop-up, choose "IDL Command Line".

The IDL command line opens with the selected folder as the current directory.

Quitting IDL

To quit IDL from the command line, type EXIT.

Startup Files

A startup file is a Batch File that is executed automatically each time you start IDL. You can specify a startup file in one of two ways:

  • Specify the name of the startup file in the IDL Workbench from the Window > Preferences > IDL menu option.
  • Specify the name of the startup file as the value of the IDL_STARTUP environment variable. Note that this method works whether you use IDL in command-line mode or via the Workbench. If you use the Workbench and you set both the preference and the environment variable, IDL will use the value of the environment variable.

Common uses for startup file include the following:

  • Restoring variable data contained in a SAV file or reading in commonly-used data.
  • Setting common keywords to the DEVICE procedure.
  • Setting up system graphic preferences.
  • Specifying shared or private color maps for PseudoColor devices.

IDL executes startup files as a batch script, one statement at a time. It is not possible to define control blocks (if/then, for/endfor, etc.) or program modules (procedures/functions) in the startup file.

Startup Options

You can add options to the command that starts IDL. If you are starting IDL from the command or shell prompt, append the option flag after the idl or idlde command. (If you are starting IDL on a Windows platform by clicking an icon, modify the Target field of the properties dialog for the IDL icon to include the option flag.)

See Command-line Options for IDL Startup  for a listing of the available startup options.

Environment Variables Used by IDL

When IDL starts, it checks for the presence of a number of environment variables. If one of these environment variables exists, its value is used in one of two ways:

  • As the value for a preference
  • To configure IDL's environment in such a way that it can load and run

Preferences

Preferences are internal values that control various aspects of the IDL environment. While user preference values are usually retrieved from preference files, the value of any preference can be defined by setting an environment variable of the same name. For example, to set the value of the IDL_PATH preference, which supplies the initial value of the !PATH system variable, you would define an environment variable named IDL_PATH.

If an environment variable corresponding to a preference exists, its value will be used as the value of that preference unless the value is explicitly overridden with a value set at the command line when invoking IDL.

Non-preference Environment Variables

IDL checks the following environment variables at startup, but does not use the values as the values of IDL preferences.

DISPLAY

On UNIX platforms, IDL uses the DISPLAY environment variable to choose which X display is used to display graphics.

HOME

IDL uses the value of the HOME environment variable when storing user-specific information in the local file system.

Note: Under Microsoft Windows, the HOME environment variable might not be set in all cases. If it is not set, IDL first attempts to substitute the USERPROFILE environment variable (which usually looks something like C:\Documents and Settings\username where username is the login name of the current user). If USERPROFILE is not set, IDL uses the value of the first of the following it finds: the TEMP environment variable, the TMP environment variable, or the Windows system directory.

IDL_BRIDGE_DEBUG

The IDL export bridges check the value of the IDL_BRIDGE_DEBUG environment variable to enable or disable debugging support. Setting this environment variable to an appropriate value causes the Connectivity bridge to send debugging information that would typically appear in the IDL Output log to stdout. In addition, on Windows systems, debugging information is written with the OutputDebugString() API, whose output can be captured by the Debug Monitor ( DBMON.exe ) tool (provided in the Platform SDK), Visual Studio, or the WinDbg debugger.

When IDL_BRIDGE_DEBUG is enabled, the following debug information is available:

  • Library load errors (on Windows)
  • IDL execution errors
  • Output from the IDL print command

Valid values for the IDL_BRIDGE_DEBUG environment variable are 0 to turn debug output off; 1 to turn it on. All other values will be ignored.

IDLJAVAB_CONFIG

The IDL-Java bridge uses the value of the IDLJAVAB_CONFIG environment variable to locate the IDL-Java bridge configuration file.

IDLJAVAB_LIB_LOCATION

The IDL-Java bridge uses the value of the IDLJAVAB_LIB_LOCATION environment variable to determine which JVM shared library within a given Java version to use.

Note: This only works for command-line IDL. When launching the Workbench the IDL-Java bridge uses the same Java version as the Workbench.

LD_LIBRARY_PATH

On UNIX systems, the Java Connectivity bridges use the value of the LD_LIBRARY_PATH environment variable to determine where IDL's shared library files are located.

PATH

When IDL asks for an operating system resource such as a shell, the executable file for that resource must be located in the operating system's path. While IDL itself does not use the value of the PATH environment variable explicitly, its value does affect IDL's behavior when attempting to launch other applications.

TERM

On UNIX platforms, IDL uses the environment variable TERM to determine the type of terminal in use when IDL is in command-line mode.

Setting Environment Variables

The process used to set environment variables varies depending on the operating system you are using.

UNIX and Mac Systems

On UNIX systems, environment variables are generally specified in a file read by your shell program at startup. Syntax for setting environment variables varies depending on the shell you are using, as does the file you use to specify the variables. If you are unsure how to set environment variables on your system, consult the system documentation or a system administrator.

Microsoft Windows Systems

On Microsoft Windows systems, environment variables are set in the Environment Variables dialog, which is accessible from the System Control panel. Some Windows versions allow you to set environment variables either only for the user you logged in as ("user variables") or for all users ("system variables"). Setting IDL environment variables as user variables means that other users who log on to the computer will not have access to your environment variable values.

Using IDL Help

IDL provides installed, browser-based IDL Help. This topic covers how to open the installed IDL Help from both the command line and in the Workbench, tips for searching, and how to access IDL Help on the internet.

Opening IDL Help

You can start IDL Help in the following ways.

In the IDL Interface

  • Type the "?" command at the IDL prompt to bring up the main help system page.
  • Select Help > Help Contents from the IDL Workbench menu.

Additionally, using the "?" followed by a function name opens the help system inside the topic for that function. For example, typing the following at the IDL prompt:

?ARROW

brings up IDL Help open to the ARROW topic.

On Windows

If the defaults were selected during installation, start IDL Help from the Start> Programs > IDL x.x > Help > IDL Help menu.

On Linux/Mac:

Start IDL Help with the idlhelp command in a terminal window.

Documentation Center

A portion of the IDL Help can also be found on the Documentation Center on the company website.

IDL Documentation Syntax

The following table lists the syntax elements used in the IDL help system for documentation on routines, functions, and objects:

Element

Description

[ ] (Square brackets)

Indicates that the contents are optional. Do not include the brackets in your call.

Brackets are also used when creating and accessing arrays.

[ ] (Italicized square brackets)

Indicates that the square brackets are part of the statement (used to define an array).

Argument

Arguments are shown in italics, and must be specified in the order listed.

KEYWORD

Keywords are all caps, and can be specified in any order. For functions, all arguments and keywords must be contained within parentheses.

/KEYWORD

Indicates a boolean keyword.

Italics

Indicates arguments, expressions, or statements for which you must provide values.

{ } (Braces)
  • Indicates that you must choose one of the values they contain
  • Encloses a list of possible values, separated by vertical lines ( | )
  • Encloses useful information about a keyword
  • Defines an IDL structure (this is the only case in which the braces are included in the call).

| (Vertical lines)

Separates multiple values or keywords.

[, Value1, ... , Valuen]

Indicates that any number of values can be specified.

[, Value1, ... , Value8]

Indicates the maximum number of values that can be specified.

Elements of Syntax

Procedures

IDL procedures use the following general syntax:

PROCEDURE_NAME, Argument [, Optional_Argument]

where PROCEDURE_NAME is the name of the procedure, Argument is a required parameter, and Optional_Argument is an optional parameter to the procedure.

Functions

IDL functions use the following general syntax:

Result = FUNCTION_NAME( Argument [, Optional_Argument] )

where Result is the returned value of the function, FUNCTION_NAME is the name of the function, Argument is a required parameter, and Optional_Argument is an optional parameter. Note that all arguments and keyword arguments to functions should be supplied within the parentheses that follow the function’s name.

Functions do not always have to be used in assignment statements (i.e., A=SIN(10.2)), they can be used just like any other IDL expression. For example, you could print the result of SIN(10.2) by entering the command:

PRINT, SIN(10.2)

Arguments

The “Arguments” section describes each valid argument to the routine. Note that these arguments are positional parameters that must be supplied in the order indicated by the routine’s syntax.

Named Variables

Often, arguments that contain values upon return from the function or procedure (“output arguments”) are described as accepting “named variables”. A named variable is a valid IDL variable name. This variable does not need to be defined before being used as an output argument. Note, however that when an argument calls for a named variable, only a named variable can be used—sending an expression causes an error.

Keywords

The “Keywords” section describes each valid keyword argument to the routine. Keyword arguments are formal parameters that can be supplied in any order.

Keyword arguments are supplied to IDL routines by including the keyword name followed by an equal sign (“=”) and the value to which the keyword should be set. The value can be a value, an expression, or a named variable (a named variable is a valid IDL variable name).

Note: If you set a keyword equal to an undefined named variable, IDL will quietly ignore the value.

For example, to produce a plot with diamond-shaped plotting symbols, the PSYM keyword should be set to 4 as follows:

PLOT, FINDGEN(10), PSYM=4

Note the following when specifying keywords:

  • Certain keywords are boolean, meaning they can only be set to 0 or 1. These keywords are switches used to turn an option on and off. Usually, setting such keywords equal to 1 causes the option to be turned on. Explicitly setting the keyword to 0 (or not including the keyword) turns the option off. In the syntax listings in this reference, all keywords that are preceded by a slash can be set by prefacing them by the slash. For example, SURFACE, DIST(10), /SKIRT is a shortcut for SURFACE, DIST(10), SKIRT=1. To turn the option back off, you must set the keyword equal to 0, as in SURFACE, DIST(10), SKIRT=0.

In rare cases, a keyword’s default value is 1. In these cases, the syntax is listed as KEYWORD=0, as in SLIDE_IMAGE [, Image] [, CONGRID=0]. In this example, CONGRID is set to 1 by default. If you specify CONGRID=0, you can turn it back on by specifying either /CONGRID or CONGRID=1.

  • Some keywords obtain values that can be used upon return from the function or procedure. These keywords are listed as KEYWORD=variable. Any valid variable name can be used for these keywords, and the variable does not need to be defined first. Note, however, that when a keyword calls for a named variable, only a named variable can be used—sending an expression causes an error.

For example, the WIDGET_CONTROL procedure can return the user values of widgets in a named variable using the GET_UVALUE keyword. To return the user value for a widget ID (contained in the variable mywidget) in the variable userval, you would use the command:

  WIDGET_CONTROL, mywidget, GET_UVALUE = userval

Upon return from the procedure, userval contains the user value. Note that userval did not have to be defined before the call to WIDGET_CONTROL.

  • Some routines have keywords that are mutually exclusive, meaning only one of the keywords can be present in a given statement. These keywords are grouped together, and separated by a vertical line. For example, consider the following syntax:

PLOT, [X,] Y [, /DATA | , /DEVICE | , /NORMAL]

In this example, you can choose either DATA, DEVICE, or NORMAL, but not more than one. An example of a valid statement is:

PLOT, SIN(A), /DEVICE

  • Keywords can be abbreviated to their shortest unique length. For example, the XSTYLE keyword can be abbreviated to XST because there are no other keywords in IDL that begin with XST. You cannot shorten XSTYLE to XS, however, because there are other keywords that begin with XS, such as XSIZE.

Properties

The “Properties” section describes each valid property for the routine. Properties are formal parameters that you can supply in any order during the routine's call. In some instances, you can also change the values of properties after you have initially called a routine.

  • Properties are assigned by stating the property name, followed by the "=" sign and finally the value you are assigning.
  • Some properties are Boolean, meaning they can only be set to 0 or 1. Boolean properties can be set during a routine's initial call by explicitly assigning a value or by the alternate "/" syntax. In the following example, both versions of the HIDE syntax have the same effect on the graphic:

result = PLOT(X, Y, /HIDE)

result = PLOT(X, Y, HIDE=1)

Usually, setting such properties equal to 1 causes the option to be turned on. Explicitly setting the property to 0 (or not including the property) turns the option off. In the syntax listings in this reference, all properties that are preceded by a slash can be set by prefacing them by the slash. For example, PLOT(myData, /HIDE) is a shortcut for PLOT(myData, HIDE=1). To turn the option back off, you must set the keyword equal to 0, as in PLOT(myData, HIDE=0) or change the property using the dot syntax.

For more detailed information on setting and changing Properties, see: Modifying Object Properties and Changing Graphics Properties.