Use IDL_Initialize() function to prepare Callable IDL. As a convenience in simpler situations, the IDL_Init() function may also be used for this purpose.

Note: IDL can only be initialized once for a given process; calling an IDL initialization function more than once for a process will cause an error. If you need to reinitialize an IDL session that is already running, consider using IDL_ExecuteStr(".reset_session");

IDL_Initialize()

The IDL_Initialize() function is the primary function used to prepare Callable IDL for use. This must be the first IDL routine called.

int IDL_Initialize(IDL_INIT_DATA *init_data)

IDL_Initialize() returns TRUE if IDL was successfully initialized, and FALSE otherwise.

init_data

A pointer to an IDL_INIT_DATA structure, used to specify initialization options. If no initialization data is required, a NULL pointer may be passed.

The definition of IDL_INIT_DATA includes the following fields:

typedef struct { 
   IDL_INIT_DATA_OPTIONS_T options;
 
   struct {	/* options & IDL_INIT_CLARGS */
      int argc;
      char **argv;
      } clargs;
      void *hwnd;	/* options & IDL_INIT_HWND */
} IDL_INIT_DATA;

The options field of IDL_INIT_DATA can be set to any combination of the IDL_INIT_* values described below. Most of these values represent boolean options and no other data is required for them. However, a relatively small number of the options require additional information. This extra information is provided via one of the other fields in the IDL_INIT_DATA structure; see below for more information.

IDL_Initialize() always examines the value of the options field of this structure. It will only examine the other fields if a value in options requires it to. Otherwise, those other fields are not used and may safely be left uninitialized. This organization allows NV5 Geospatial Solutions to add additional initialization options to newer versions of IDL without requiring source code changes to older applications that do not require those new features.

The values allowed in the options field of IDL_INIT_DATA are:

IDL_INIT_BACKGROUND

A convenience option, equivalent to setting both the IDL_INIT_NOCMDLINE and IDL_INIT_NOTTYEDIT options.

IDL_INIT_CLARGS

Execution of C programs starts when the main() function is called. Command line arguments are passed to the main() function via the standard argc and argv arguments. Set the IDL_INIT_DATA clargs.argc and clargs.argv fields to these values and set the IDL_INIT_CFLAGS bit in options to pass these command line arguments to IDL for processing. On return, IDL will remove any arguments it understands, and will alter the value of clargs.argc to reflect the count of remaining items.

The argc/argv pair passed must follow the usual convention in which argv[0] is the name under which the program was run, and any additional values are the arguments passed to that program.

IDL_INIT_GUI

Indicates that IDL is being accessed via the IDL Workbench GUI interface rather than using the standard tty based interface.

IDL_INIT_GUI_AUTO (Unix Only)

IDL will try to use the IDL Workbench GUI. If that fails, IDL uses the standard tty interface.

IDL_INIT_HWND (Windows only)

Under Windows, an application calling IDL will usually want IDL to use its main window as its own. This option is used to pass the application’s main window handle to IDL. In addition to setting IDL_INIT_HWND in the options field, you must set the hwnd field to the value of the window handle to use.

IDL_INIT_NOCMDLINE

Indicates to IDL that it is going to be used in a background mode by some other program, and that IDL will not be in control of the user’s input command processing. The main effect of this is that IDL will never prompt for user input from the command line and execution will never stop in such a situation. Instead, IDL will act as if the desired read returned an end of file (EOF) and IDL will instead return to the caller. Another related effect is that XMANAGER will realize that the active command line functionality for processing widget events is not available, and XMANAGER will block to manage events when it is called rather than return immediately.

IDL_INIT_NOTTYEDIT (UNIX Only)

Normally under UNIX, if IDL sees that stdin and stdout are ttys, it puts the tty into raw mode and uses termcap/terminfo to handle command line editing. When using callable IDL in a background process that isn’t doing input/output to the tty, the termcap initialization can cause the process to block (because of job control from the shell) with a message like “Stopped (tty output) idl”. Setting this option prevents all tty edit functions and disables the calls to termcap. I/O to the tty is then done with a simple fgets()/printf(). This option only has meaning when a UNIX tty is in use. It is ignored on non-UNIX platforms, or when the IDL_INIT_GUI bit is set.

IDL_INIT_QUIET

Setting this bit suppresses the display of the startup announcement and message of the day.

IDL_INIT_RUNTIME

Setting this bit causes IDL to check out a runtime license instead of the normal license. IDL_RuntimeExec() is then used to run an IDL application restored from a Save/Restore file.

IDL_Init()

The IDL_Init() function offers a simplified interface to IDL_Initialize().

When possible, callable IDL programs should call IDL_Initialize() to perform the initialization operation. However, IDL_Initialize() requires the IDL_INIT_DATA structure type to be defined. This definition comes from the idl_export.h header file supplied with IDL which can be used from the C or C++ languages, but which is not directly usable from languages such as Fortran. IDL_Init() does not use the IDL_INIT_DATA structure, and is therefore more convenient in such cases.

Note: Most Microsoft Windows applications need to pass their main window handle (HWND) to IDL, which is possible using IDL_Initialize(), but not IDL_Init(). IDL_Init() is therefore primarily of interest in Unix environments.

int IDL_Init(int options, int *argc, char *argv[]);

IDL_Init() returns TRUE if IDL was successfully initialized, and FALSE otherwise.

IDL_Init() is nothing more than a simple convenience wrapper written using IDL_Initialize(). As an aid in understanding the relationship between these two routines, the code that implements it is shown below.

options

A bitmask used to specify initialization options. This is equivalent setting the options field of the IDL_INIT_DATA structure to the desired options value when using the IDL_Initialize() function. Allowed values for options can be found in “Initialization”.

argc, argv

Command line arguments, as passed by the operating system to the program main() function. Setting these arguments to non-NULL values is equivalent to the following 3 steps using IDL_Initialize():

  1. Set the clargs.argc field of the IDL_INIT_DATA structure to the number of items in the argv array, as given by argc.
  2. Set the clargs.argv field of the IDL_INIT_DATA structure to the value of argv.
  3. Set IDL_INIT_CLARGS bit of the options field of that structure.

Example using IDL_Init()

int IDL_Init(int options, int *argc, char *argv[])
{
  IDL_INIT_DATA init_data;
  int r;
   
  init_data.options = options;
  if (argc) {
     init_data.options |= IDL_INIT_CLARGS;
     init_data.clargs.argc = *argc;
     init_data.clargs.argv = argv;
     }
   
  r = IDL_Initialize(&init_data);
  if (argc) *argc = init_data.clargs.argc;
   
  return r;
}

Common Microsoft Windows Initialization Issues

Callable IDL applications intended to run under Microsoft Windows commonly face the following issues:

  • Under Windows, it is usually the case that the use of IDL from another program is non-interactive. By default, IDL assumes an interactive environment in which it is communicating with a user directly. It is necessary to set the IDL_INIT_NOCMDLINE option to change this.
  • Most Microsoft Windows applications have a main window that they wish IDL to use. The window handle for this must be specified to IDL_Initialize().

The function MyAppInitIDL(), shown below, demonstrates how to specify this information to IDL_Initialize(). This function accepts two arguments: options allows the caller to supply any other IDL_INIT_ option values that the program may need, while hwnd allows the specification of a window handle to be used as the application main window.

int MyAppInitIDL(int options, HWND hwnd)
{
   IDL_INIT_DATA init_data;
 
   /* Combine any other IDL init options with NOCMDLINE */
   init_data.options = options | IDL_INIT_NOCMDLINE;
 
/* If we have a non-NULL HWND, tell IDL to use it */
   if (hwnd) {
      init_data.options |= IDL_INIT_HWND;
      init_data.hwnd = hwnd;
   }
 
   return IDL_Initialize(&init_data);
}