SPAWN
The SPAWN procedure spawns a child process to execute a command or series of commands. The result of calling SPAWN depends on the platform on which it is being used:
- Under UNIX, the shell used (if any) is obtained from the SHELL environment variable. The NOSHELL keyword can be used to execute a command directly as a child process without starting a shell process.
- Under Windows, a Command Shell is opened. The NOSHELL keyword can be used to execute the specified command directly without starting an intermediate command interpreter shell.
Note: See Using SPAWN Without a Shell Under UNIX for notes on executing commands without using a shell process under UNIX. See Execution Directory under Microsoft Windows for a caution regarding Windows network paths.
If SPAWN is called without arguments, an interactive command interpreter process is started, in which you can enter one or more operating system commands.
By default, IDL waits for the child process started by SPAWN to finish before it continues. It is possible to have IDL instead continue execution in parallel with the child process. The syntax for this depends on the operating system on your system:
- Under UNIX, include an ampersand (&) at the end of your shell command.
- Under Windows, specify the NOWAIT keyword to SPAWN.
Note: For Windows-7, there is an OS limitation that results in the need to restrict the number of characters on the command argument to SPAWN. If a command argument exceeds 8192 characters, the command is ignored.
Examples
See Additional Examples for more information on using SPAWN.
Example 1: Interactive use of SPAWN
To spawn a shell process from within IDL, enter the command:
SPAWN
To execute the UNIX ls command and return to the IDL prompt, enter:
SPAWN, 'ls'
To execute the UNIX ls command and store the result in the IDL string variable listing, enter:
SPAWN, 'ls', listing
Syntax
SPAWN [, Command [, Result] [, ErrResult] ]
Keywords (all platforms): [, COUNT=variable] [, EXIT_STATUS=variable] [ ,/NOSHELL] [, /NULL_STDIN] [, PID=variable] [, /STDERR] [, UNIT=variable {Command required, Result and ErrResult not allowed}]
UNIX-Only Keywords: [, /NOTTYRESET] [, /SH]
Windows-Only Keywords: [, /HIDE] [, /LOG_OUTPUT] [, /NOWAIT]
Arguments
Command
A string containing the commands to be executed.
If Command is present, it must be specified as follows:
- On UNIX, Command is expected to be scalar unless used in conjunction with the NOSHELL keyword, in which case Command is expected to be a string array where each element is passed to the child process as a separate argument.
- On Windows, Command can be a scalar string or string array. If it is a string array, SPAWN glues together each element of the string array, with each element separated by whitespace.
If Command is not present, SPAWN starts an interactive command interpreter process, which you can use to enter one or more operating system commands. While you use the command interpreter process, IDL is suspended. Under Windows, an interactive command shell window is created for this purpose. UNIX spawn does not create a separate window, but runs on the user’s current tty, using the default shell (as specified by the SHELL environment variable). The SH keyword can be used to force use of the Bourne shell (/bin/sh).
Note: Using SPAWN in this manner is equivalent to using the IDL $ command. The difference between these two is that $ can only be used interactively while SPAWN can be used interactively or in IDL programs
Result
A named variable in which to place the output from the child process. Each line of output becomes a single array element. If Result is not present, the output from the child shell process goes to the standard output (usually the terminal).
Note: Result will be an empty string if the NOWAIT keyword is specified (Windows) or if Command ends in an ampersand (&) (UNIX).
ErrResult
A named variable in which to place the error output (stderr) from the child process. Each line of output becomes a single array element. If ErrResult is not present, the error output from the child shell process goes to the standard error file.
Note: See the STDERR keyword for another error stream option.
Note: ErrResult will be an empty string if the NOWAIT keyword is specified (Windows). If Command ends in an ampersand (&) (UNIX), ErrResult may contain an error string generated by the shell.
Keywords
COUNT
If Result is present and this keyword is also specified, COUNT specifies a named variable into which the number of lines of output is placed. This value gives the number of elements placed into Result.
EXIT_STATUS
Set this keyword to a named variable in which the exit status for the child process is returned. The meaning of this value is operating system dependent:
- Under UNIX, it is the value passed by the child to exit(2), and is analogous to the value returned by $? under most UNIX shells.
- Under Windows, it is the value returned by the Windows GetExitCodeProcess() system function. If the NOWAIT keyword is set, EXIT_STATUS returns 0.
If the UNIT keyword is used, this keyword always returns 0. In this case, use the EXIT_STATUS keyword to FREE_LUN or CLOSE to determine the final exit status of the process.
HIDE
This keyword is only available on Windows platforms.
If HIDE is set, the command interpreter shell window is minimized to prevent the user from seeing it.
LOG_OUTPUT
This keyword is only available on Windows platforms.
Normally, IDL starts a command interpreter shell, and output from the child process is displayed in the command interpreter’s window. If LOG_OUTPUT is set, the command interpreter window is minimized (as with HIDE) and all output is diverted to the workbench log window. If the Result or ErrResult arguments are present, they take precedence over LOG_OUTPUT.
NOSHELL
Set this keyword to specify that Command should execute directly as a child process without an intervening shell process.
- UNIX – When using the NOSHELL keyword under UNIX, you must specify Command as a string array in which the first element is the name of the command to execute and the following arguments are the arguments to be passed to the command. See Using SPAWN Without a Shell Under UNIX for notes on executing commands without using a shell process.
- Windows – Use this keyword to start the specified Command directly, without the use of an intervening command shell. This is useful for Windows programs that do not require a console, such as Notepad.
Many common DOS commands (e.g. DIR) are not distinct programs, and are instead implemented as part of the command interpreter. Specifying NOSHELL with such commands results in the command not being found. In such cases, the HIDE keyword might be useful.
NOTTYRESET
This keyword is only available on UNIX platforms.
Some UNIX systems drop characters when the tty mode is switched between normal and raw modes. IDL switches between these modes when reading command input and when using the GET_KBRD function. On such systems, IDL avoids losing characters by delaying the switch back to normal mode until it is truly needed. This method has the benefit of avoiding the large number of mode changes that would otherwise be necessary. Routines that cause output to be sent to the standard output (e.g., I/O operations, user interaction and SPAWN) ensure that the tty is in its normal mode before performing their operations.
If the NOTTYRESET keyword is set, SPAWN does not switch the tty back to normal mode before launching the child process assuming instead that the child will not send output to the tty. Use this keyword to avoid characters being dropped in a loop of the form:
WHILE (GET_KBRD(0) NE 'q') SPAWN, command
This keyword has no effect on systems that don’t suffer from dropped characters.
NOWAIT
This keyword is only available on Windows platforms.
If this keyword is set, the IDL process continues executing in parallel with the subprocess. Normally, the IDL process suspends execution until the subprocess completes.
NULL_STDIN
If set, the null device is connected to the standard input of the child process. The null device is either /dev/null (under UNIX) or NUL (under Windows).
PID
A named variable into which the Process Identification number of the child process is stored.
Note: This number is the PID of the forked shell process, not the PID of the actual command that is executed within that child shell. For example, on Unix, if you do the following:
SPAWN,'xeyes &',PID=p & print,'shell PID=',p
The shell prints:
[1] 28989
IDL prints:
shell PID= 28962
The "28962" is the process ID of the forked shell process, while the "28989" is the process ID of the "xeyes" command within that shell process.
SH
This keyword is only available on UNIX platforms.
Set this keyword to force the use of the Bourne shell (/bin/sh). Usually, the shell used is determined by the SHELL environment variable.
STDERR
If set, the child’s error output (stderr) is combined with the standard output and returned in Result. STDERR and the ErrResult argument are mutually exclusive. You should use one or the other, but not both.
UNIT
If UNIT is present, SPAWN creates a child process in the usual manner, but instead of waiting for the specified command to finish, it attaches a bidirectional pipe between the child process and IDL. From the IDL session, the pipe appears as a logical file unit. The other end of the pipe is attached to the child process standard input and output. The UNIT keyword specifies a named variable into which the number of the file unit is stored.
Once the child process is started, the IDL session can communicate with it through the usual input/output facilities. After the child process has done its task, the CLOSE procedure can be used to kill the process and close the pipe. Since SPAWN uses GET_LUN to allocate the file unit, FREE_LUN should be used to free the unit.
If UNIT is present, Command must be present, and neither Result or ErrResult are allowed.
Using SPAWN Without a Shell Under UNIX
When a Unix program is run, its name and arguments are provided to it as an array of strings, one string per argument. The first string is the name of the program, and the remainder (if any) are the arguments. C programmers will recognize this as the standard (argc, argv) arguments passed to the main() function when the program is run. When you execute a command via a Unix shell, one of the operations that the shell carries out for you is to split the command and arguments apart on whitespace boundaries (blanks and tabs) to create this array of arguments. It then runs the program for you, using one of the Unix system exec() functions.
By default, SPAWN creates a shell process and passes the command to this shell instead of creating a child process to directly execute the command. Use of a shell is the default because the shell provides useful facilities such as wildcard expansion and argument processing (described above). Although this is usually desirable, it has the drawback of being slower than necessary, and of using an additional process for the shell.
When SPAWN is called with the NOSHELL keyword set, the command is executed as a direct child process, avoiding the extra overhead of starting a shell. This is faster, but since there is no shell, you must specify the arguments in the standard form required by Unix programs. When you specify the NOSHELL keyword, the Command argument should be a string array. The first element of the array is the name of the command to use, and the following elements contain the arguments.
For example, consider the command,
SPAWN, 'ps ax'
that uses the UNIX ps command to show running processes on the computer. To issue this command without a shell, you would write it as follows:
SPAWN, ['ps', 'ax'], /NOSHELL
Execution Directory under Microsoft Windows
SPAWN attempts to use IDL’s current working directory as the current directory for the spawned process. However, Microsoft Windows does not support the specification of a UNC path as the current directory for a Command Shell. Issuing a SPAWN command when IDL’s current working directory is set to a UNC path will cause Windows to generate an error that looks something like:
CMD.EXE was started with '\\host\dir' as the current directory path. UNC paths are not supported. Defaulting to Windows directory.
If your application requires that you be able to use SPAWN when IDL’s current working directory is set to a directory on a Windows network, consider mapping the UNC path to a Windows drive letter and setting that to be IDL’s working directory.
If your SPAWN command contains a directory name with spaces and you are using the < or > redirect tokens in a DOS window, you may receive an error. If so, you can create a temporary environment variable containing the command as follows:
setenv, 'MYARG="C:\test dir\ins" < "C:\test dir\refs" > ^
"C:\test dir\outs"'
SPAWN, '%MYARG%'
Additional Examples
Example 2: Noninteractive use of SPAWN
It is sometimes useful to create a temporary scratch file, removing the file when it is no longer needed. SPAWN could be used as shown below to manage the removal of the scratch file.
OPENW, UNIT, 'scratch.dat', /GET_LUN
;...IDL commands go here.
;Deallocate the file unit and close the file.
FREE_LUN, UNIT
;Use the !VERSION system variable to determine the proper file
;deletion command for the current operating system.
CASE !VERSION.OS OF
'Windows': CMD = 'DEL'
ELSE: CMD = 'rm'
ENDCASE
;Delete the file using SPAWN.
SPAWN, CMD + ' scratch.dat'
END
Note: The DELETE keyword to the OPENR/OPENU/OPENW procedure or the FILE_DELETE procedure more efficiently handles this job. The above example should serve only to demonstrate use of the SPAWN procedure.
Version History
|
Original |
Introduced |
|
Pre-6.2 |
Deprecated FORCE, MACCREATOR, NOCLISYM, NOLOGNAME, and NOTIFY keywords |