Accessing the Operating System Using SPAWN
SPAWN is a very flexible command. It can create an interactive command interpreter (shell, for UNIX users) process, or simply issue a single command and return. Under UNIX, in this second case, the command can either be passed to a shell for processing, or it can be executed directly as a child process of PV-WAVE.
Under Windows, SPAWN can create a new Command window, or simply issue a single command and return.
This section discusses SPAWN as it is used to issue commands and capture output. For detailed information on how to use SPAWN to execute and transfer data to and from a child process (external program), see
"Interapplication Communication Using SPAWN".
Using SPAWN to Issue Commands
The SPAWN procedure spawns a child process to execute a given command. It has the form:
SPAWN [, command [, result]]
The command parameter is a string containing the command to be issued and can be either a scalar or an array.
note | The way in which it is treated depends on whether the Noshell keyword is specified. For more information on Noshell, see
"Avoiding the Shell under UNIX". |
If the result parameter is not present, the output from the child process simply goes to the standard output (usually the terminal). Otherwise, the output from the child process is placed into a string array (one line of output per array element) and assigned to result.
Interactive Use of SPAWN
If SPAWN is called without arguments, it starts an interactive shell (UNIX) or Command window (Windows). While you use the shell or command interpreter process, PV-WAVE is suspended. When you exit the child process, control returns to PV‑WAVE, which resumes at the point where it left off. The PV-WAVE session remains exactly as you left it.
UNIX Example
The following statements demonstrate the interactive use of SPAWN in a UNIX environment.
WAVE> SPAWN
%date
Fri Aug 26 13:55:00 MDT 1988
%exit
WAVE>
Windows Example
An example of using SPAWN in a Windows environment is:
; At this point, a Command window appears, and you can enter a
; command, such as the date command.
WAVE> SPAWN
D:\vni\wave> date
The current date is: Fri 07/16/1993
Enter the new date: <mm-dd-yy>
; The exit command exits the Command window and returns you to
; the PV-WAVE session.
D:\vni\wave> exit
WAVE>
note | Using SPAWN in this manner is equivalent to using the $ command. The difference is that $ can only be used interactively, while SPAWN can be used interactively or in PV-WAVE programs. |
UNIX Shells
The most common UNIX shells are the Bourne shell (
/bin/sh), the C shell
(
/bin/csh), and the Korn shell (
/bin/ksh). Rather than force you to use a given shell, PV-WAVE follows the UNIX convention of using the shell specified by the UNIX environment variable
SHELL. If
SHELL does not exist, the Bourne shell is used. The UNIX environment is discussed in
"Manipulating Environment Variables" in this chapter.
Under UNIX, the interactive form of SPAWN is provided primarily for users of the Bourne shell. Shells that offer process suspension (e.g., /bin/csh) offer a more convenient and efficient way to get the same effect.
Avoiding the Command Prompt Window (Windows)
As previously mentioned, SPAWN creates a command prompt window and passes the command to it, instead of creating a child process to directly execute the command. This is the default because the command prompt window provides useful actions such as wildcard expansion and argument processing. Although this is usually desirable, creating a command prompt window process has the drawback of being slower. However, to avoid starting the command prompt use the Noshell keyword.
When SPAWN is called and Noshell is present and non-zero, the command is executed as a direct child process, avoiding the extra overhead of starting a command prompt window. This is faster, but since no command prompt window breaks the command into separate arguments, you have to do it. Every Windows program is called with a series of arguments. When you issue a command prompt window command, you separate the arguments with white space (blanks and tabs). The command prompt window then breaks up the command into an array of arguments, and calls the command (the first word), passing it the array of arguments.
Thus, if you use Noshell to avoid using a command prompt window, you have to break up the arguments yourself. In this case, 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:
WAVE> SPAWN, 'dir c:\reports /a:h'
To issue this command without a shell, write it as:
WAVE> SPAWN,['dir' 'c:\reports' '/a:h'], /Noshell
Non-interactive Use of SPAWN
If SPAWN is called with a single argument, that argument is taken as a command to be executed. In this case, PV-WAVE starts a child process and passes the command to it. The argument should be a scalar string. The child process executes the command and exits, at which point PV-WAVE resumes operation. This form of operation is very convenient for executing single commands from PV-WAVE programs. For example, it is sometimes useful to delete a temporary scratch file. SPAWN can be used as shown in the following program fragment.
UNIX Example
; Open the scratch file. Use the Get_Lun keyword to allocate a
; file unit.
OPENW, Unit, 'scratch.dat', /Get_Lun
; PV-WAVE commands that use the file go here.
. . .
; Deallocate the file unit and close the file.
FREE_LUN, Unit
; Delete the file using SPAWN.
SPAWN, Cmd + 'scratch.dat'
Windows Example
; Open the scratch file. Use the Get_Lun keyword to allocate a
; file unit.
OPENW, Unit, 'scratch.dat', /Get_Lun
; PV-WAVE commands that use the file go here.
. . .
; Deallocate the file unit and close the file.
FREE_LUN, Unit
; Delete the file using SPAWN.
SPAWN, 'ERASE scratch.dat'
note | The Delete keyword to the OPEN procedure is a more efficient way to handle this job. The previous examples serve only to demonstrate the use of the SPAWN procedure. |
Avoiding the Shell under UNIX
As previously mentioned, SPAWN creates a command prompt window and passes the command to it, instead of creating a child process to directly execute the command. This is the default because the command prompt window provides useful actions such as wildcard expansion and argument processing. Although this is usually desirable, creating a command prompt window process has the drawback of being slower. However, to avoid starting the command prompt use the Noshell keyword.
When SPAWN is called and Noshell is present and non-zero, the command is executed as a direct child process, avoiding the extra overhead of starting a shell. This is faster, but since no shell breaks the command into separate arguments, you have to do it. Every UNIX program is called with a series of arguments. When you issue a shell command, you separate the arguments with white space (blanks and tabs). The shell then breaks up the command into an array of arguments, and calls the command (the first word), passing it the array of arguments.
Thus, if you use Noshell to avoid using a shell, you have to break up the arguments yourself. In this case, 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:
WAVE> SPAWN, 'ps ax'
which uses the UNIX ps command to show running processes on the computer. To issue this command without a shell, write it as:
WAVE> SPAWN, ['ps', 'ax'], /Noshell
Capturing Output
By default, any output generated by the spawned command is sent to the standard output, which is usually the terminal. It is possible to capture this output in a string array by calling SPAWN with a second argument. If this second argument, called result, is present, all output from the child process is put into a string array, one line of output per array element, and is assigned to result.
UNIX Example
For example, the following statements can be used to give a simplistic count of the number of users logged onto the computer:
; Issue the command; catch the result in a string array.
SPAWN, Cmd, Users
; Count how many lines of output cue back. Under UNIX, this is the
; number of users logged in.
N = N_ELEMENTS(Users)
; Give the result.
PRINT, 'There are ', N, ' users logged on.'
Windows Example
For example, the following statements can be used to capture the current environment variable settings in a variable:
; Issue the command; catch the result in a string array.
SPAWN, 'set', vars
; List the environment variables in the PV-WAVE Console window.
PRINT, vars
Version 2017.0
Copyright © 2017, Rogue Wave Software, Inc. All Rights Reserved.