15.2.7 exec (Invoke Subprocess(es))

Description

Invokes subprocess(es) to run program commands.

Synopsis

[Windows]

exec cmd /c cmdname [args ...]

Note: The exec command must be used with cmd /c.

[UNIX]

exec cmdname [args ...]

Options

cmdname: Specify thei name of a command file to invoke. The file names on Windows can also be separated by a slash (/) in addition to the backslash sign (\). When using a backslash sign, the entire file name must be enclosed in braces ({}) so as not to be treated as an escape character.

args ...

Specify the argument to be passed to the command to invoke.

If the last args is "&", the command is executed in background. Generally, the exec command is executed in foreground and waits for the cmdname process to terminate. However, when executed in background, it returns without doing so.

In addition, it is possible to specify a flow control symbol in args.

For Windows, when giving a file by specifying its path, the directory must be separated by backslash sign (\) and the entire file name must be enclosed in braces ({}).

Flow control

Writing the following flow control symbols to args allows manipulation of standard inputs/outputs of commands invoked or information exchange through activation of multiple commands.

Symbol and form	Meaning	Example
\|	Separates individual commands in the pipeline. The standard output of the preceding command will be piped into the standard input of the subsequent command. Three or more commands can be piped in the same way. If "\|&" is used in place of "\|", the standard output as well as standard error output will be piped into the standard input of the subsequent command.	[Windows] exec cmd /c dir \|cmd /c sort [UNIX] exec ls -1 \| grep root
< filename	The content of file specified by filename is read as the standard input of cmdname. (Note 1)	[Windows] exec cmd /c sort < data.txt [UNIX] exec sort < data.txt
<< value	The value (string) specified by value is read as the standard input of cmdname. (Note 1)	[Windows] exec cmd /c sort << $data [UNIX] exec sort << $data
> filename	The standard output of cmdname is overwritten to the file specified by filename. (Note 1) Using ">>" in place of ">" causes it to be appended rather than being overwritten.	[Windows] exec cmd /c dir > data [UNIX] exec ls > data
>& filename	The standard output of cmdname and standard error output are overwritten to the file specified by filename. (Note 1) Using ">>&" in place of ">&" causes it to be appended rather than being overwritten.	[Windows] exec cmd /c dir data >& out [UNIX] exec rm -f data >& out
2> filename	The standard error output of cmdname is overwritten to the file specified by filename. (Note 2) Using "2>>" in place of "2>" causes it to be appended rather than being overwritten.	[Windows] exec cmd /c dir data 2> out [UNIX] exec rm -f data 2> out

Note 1:: If cmdname comprises two or more commands through |, the first command will be used for reading and the last one for writing.

Note 2:: If cmdname comprises two or more commands through |, the standard error output of all commands will be stored in the file specified by filename.

Return Values

When the command is executed in foreground:

The standard output of the cmdname command is returned. The trailing line break code in the output text will be deleted.

When multiple commands are executed through flow control, the standard output of the last command will be returned.

When the standard output is redirected through flow control, a blank string will be returned.

When the command is executed in background:

The process ID of the command invoked is returned.

When multiple commands are executed through flow control, all process IDs separated by blanks will be returned. Due to this, the standard output that is output by an application cannot be obtained as the return value of the exec command.

Other Input/Output Information

In the following conditions, a script detects an exception and will be forcibly terminated. Trap the exception detected with the catch command as required.
- The command is executed in foreground, and
- The command outputs a message to be sent to the standard error output where the standard error output of the command is not redirected, or
- The completion code of the command is other than 0.
Example:
When exception trap with the catch command is not performed.
[Windows]
```
#The application is activated. Standard output is stored to variable "outmsg."
set outmsg [exec cmd /c {c:\usr\bin\appl001.exe}]

#Data output to the standard output by the application is output to the standard output of the job.
puts stdout $outmsg

#When the activation of the application through its execution has been successfully terminated, the processing terminates with completion code "0."
exit 0
```
[UNIX]
```
#The application is activated. Standard output is stored to variable "outmsg."
set outmsg [exec /usr/bin/appl001]

#Data output to the standard output by the application is output to the standard output of the job.
puts stdout $outmsg

#When the activation of the application through its execution has been successfully terminated, the processing terminates with completion code "0."
exit 0
```
Remark:
The following problems occur when the command executed by exec terminates with completion code other than 0 or abnormally, since exception setting with the catch command does not exist:
- "1" is returned as the completion code of the job and the completion code of the command executed is not applied.
- Error message or other information output to the standard error output by the command executed cannot be obtained.
  To prevent the above problems, it is recommended that you trap exceptions with the catch command when executing a command.
When trapping exceptions with the catch command, you can refer to the following information.
- Standard output/standard error output (errorInfo)
- Completion code (errorCode)
Information
Standard output/standard error output information (errorInfo):
When the standard output or standard error output of the command is not redirected, its output string will be stored in the beginning of global variable errorInfo. In errorInfo, the strings that identify execution errors of the exec statement itself will be stored.
Example:
[Windows]
If the application that implements the following specifications (c:\usr\bin\appl001.exe) terminated abnormally:
Specifications:
Write the data of specified date to the standard output
If the specification of date is invalid, output the following message to the standard error output.
"Error in date specification. Specify in yyyymmdd format."
```
if {[catch {
          exec cmd /c {c:\usr\bin\appl001.exe} 010520
    }]} {
      puts "error information START"
      puts $errorInfo
      puts "error information END"
}
```
When the above code is executed, the standard output shows the following information.
```
Error information START
An error in date specification. Specify in yyyymmdd format. <-  appl001 command output
    while executing                                 <- String that indicates execution error
"exec cmd /c {c:\usr\bin\appl001.exe} 010520"                <- of exec statement itself
Error information END
```
[UNIX]
If the ls command is executed by specifying a file (/var/tmp/data) that does not exist:
```
if {[catch {
          exec ls /var/tmp/data
    }]} {
      puts "error information START"
      puts $errorInfo
      puts "error information END"
}
```
When the above code is executed, the standard output shows information as shown below.
```
Error information START
/var/tmp/data: no file or directory exists.                             <- ls command output
    while executing                              <- String that indicates execution error
"exec ls /var/tmp/data"                                            <-  of exec statement itself
Error information END
```
Information
Completion code (errorCode)
In case of a non-zero completion code for a command, the completion code will be stored in global variable errorCode in the form shown below. Also other information is stored in it. See the return value of catch (execute script lines and trap exceptions) for the form of errorCode.
CHILDSTATUS pid exitcode
pid
[Windows]
Numeric characters entered in this field do not have any meaning
[UNIX]
The process ID of the command executed
exitcode
The completion code of the process

Input/output of executed commands

The input and output of executed commands having not been redirected are treated as follows:

Input/ Output	When executed in foreground	When executed in background
Standard input	Read from the standard input of the script process itself.
Standard output	Normally, returned as the return value of the exec command. If exceptions are trapped by the catch command, they are stored in errorInfo.	Written to the standard output of the script process itself.
Standard error output	Treated as an exec command exception. If trapped by the catch command, it is stored in errorInfo.	Written to the standard error output of the script process itself.

Input/ Output

When executed in foreground

When executed in background

Standard input

Read from the standard input of the script process itself.

Standard output

Normally, returned as the return value of the exec command.

If exceptions are trapped by the catch command, they are stored in errorInfo.

Written to the standard output of the script process itself.

Standard error output

Treated as an exec command exception. If trapped by the catch command, it is stored in errorInfo.

Written to the standard error output of the script process itself.

Reference

catch

Cautions

On Windows x64, repeatedly calling the exec command within a single script may cause it to hang up. It is recommended that the number of calls be restricted to 100, more or less.
If it is required to repeatedly call the exec command, split the script file and decrease the number of times to call exec command per script file. The split script files can be executed within the script as arguments to the swotclsh command by the exec command. Below is an example of executing a split script.
Example:
```
exec cmd /c swotclsh {c:\script\part1.swt}
```
If you create a script that calls the exec command multiple times, call the command as many times as specified when testing the operation of the script to make sure all calls are properly performed.
On Windows x64, if a command located in the Windows installation directory\system32 (normally C:\WINDOWS\system32) is specified as the command to be activated by exec, the command located in Windows installation directory\syswow64 will be executed.
Startup of commands or shells whose descendant processes reside
In the following conditions, the command directly executed will not return:
- The command is executed in foreground, and
- The executed command executes a child process, and
- The standard output and standard error output are not redirected.
For this reason, when activating a resident process such as daemon startup shell, activate it in background or redirect it to the standard output and standard error output as shown below.
- Background startup
```
exec rdbstart &
```
- Redirecting the standard output and standard error output to a file
```
exec rdbstart >& /var/tmp/log.txt
```
- Ignoring the standard output and standard error output
```
exec rdbstart >& /dev/null
```
Windows commands whose parameters require particular interpretation
For Windows programs, there are two types of commands. One is general commands that interpret double quotation marks for command options as special characters and the other one is special commands that do not interpret such characters as special characters. When passing parameters to such special commands, the parameters may not be passed properly since scripts themselves interpret double quotation marks.
- Example of parameter interpretation by general commands
  Description in command line
  Interpretaion in command
  "abc"
  abc
  \"abc\"
  "abc"
Special commands interpret the description in the command line as it is.
In order to execute such a command, create a batch file to execute the command and describe statement to execute the batch file by exec.
Arguments beginning with a flow control symbol
Since a character string beginning with a flow control symbol (< > 2>) is interpreted as a flow control symbol when it is specified as an argument, it cannot be passed as a character string. Thus, specify such a character string using either of the following methods.
- Specifying an argument with a space inserted in its top
  Specify the character string as an argument by inserting a space in the top of it so that it can be interpreted as a character string.
  You can insert a space in the top by describing the script as shown below when the character string is stored in a variable (msgtxt).
```
if {[regexp {^<|^>|^2>} $msgtxt] == 1} {
    set msgtxt " $msgtxt"
}
```
- Using a shell script or batch file
  Create a shell script [UNIX] or batch file [Windows] that executes the target command within the script, and call it by using the exec command. If double quotation marks (") are included in the argument character string, they should be replaced with single quotation marks (') beforehand since character string interpretation does not work correctly within the shell script or batch file under this environment.
  Example: Executing the command by specifying a variable (msgtxt) in which arbitrary character string is stored as the argument of the command (usercmd).
  [UNIX]
  "/var/tmp/usercmd_tmp.sh" is a shell script created temporarily. It is deleted after executed.
```
if {[regexp {^<|^>|^2>} $msgtxt all] == 1} {
    regsub {"} $msgtxt {'} msgtxt
    set fd [open /var/tmp/usercmd_tmp.sh w]
    puts $fd "usercmd \"$msgtxt\""
    close $fd
    exec sh /var/tmp/usercmd_tmp.sh
    exec /usr/bin/rm -f /var/tmp/usercmd_tmp.sh
} else {
    exec usercmd $msgtxt
}
```
  [Windows]
  "c:\temp\usercmd_tmp.bat" is a batch file created temporarily. It is deleted after executed.
```
if {[regexp {^<|^>|^2>} $msgtxt all] == 1} {
    regsub {"} $msgtxt {'} msgtxt
    set fd [open {c:\temp\usercmd_tmp.bat} w]
    puts $fd "usercmd \"$msgtxt\""
    close $fd
    exec {c:\temp\usercmd_tmp.bat}
    exec cmd /c del {c:\temp\usercmd_tmp.bat}
}else {
    exec usercmd $msgtxt
}
```

Description in command line	Interpretaion in command
"abc"	abc
\"abc\"	"abc"

Examples

[Windows]

The following example runs the dir command and outputs the command's standard output/standard error output to script's standard output.

if {[catch {
          set outmsg [exec cmd /c dir {c:\tmp\data}]

          # Output dir's standard output (return value from exec) to script's standard
             output.
          puts stdout $outmsg
      }]} {
    # Occurrence of an exception. 
    # Store $errorInfo as initial value in outmsg.
    set outmsg $errorInfo

    # Output dir's output information (except for trailing two lines of errorInfo) to the
       script's standard output.
    regexp {(.*)\n.* \n.*} $errorInfo all outmsg
    puts stdout $outmsg
}

[UNIX]

The following example runs the ls command and outputs the command's standard output/standard error output to script's standard output.

if {[catch {
          set outmsg [exec ls -l /var/tmp/data]

          # Output ls's standard output (return value from exec) to script's standard
             output.
          puts stdout $outmsg
      }]} {
    # Occurrence of an exception. 
    # Store $errorInfo as initial value in outmsg.
    set outmsg $errorInfo

    # Output ls's output information (except for trailing two lines of errorInfo) to the
       script's standard output.
    regexp {(.*)\n.* \n.*} $errorInfo all outmsg
    puts stdout $outmsg
}

Execution Results/Output Format

The result of command execution is displayed on the standard output as shown below.

[Windows]

When c:\tmp\data file exists:

No Drive C volume label.
Volume serial number is 2420-12F3.

Directory c:\tmp
00/12/01  11:37a                    972 data
              One file              972 bytes
                            463,110,144 bytes free area

When c:\tmp\data directory (file) does not exists:

No Drive C volume label.
Volume serial number is  2420-12F3.

Directory c:\tmp 

Cannot find the file.

[UNIX]

When /var/tmp/data file exists:

-rw-rw-r--    1  root  other        0  15:05 Sep. 25  /var/tmp/data

When /var/tmp/data file (directory) does not exist:
```
/var/tmp/data: no file or directory exists.
```