|program||Optional — The operating system command or program to be executed as a child process, specified as a quoted string. If you omit program, $ZF(-2) launches the operating system shell.|
$ZF(-2) is a deprecated function. It is described here for compatibility with existing code only. All new code development should use $ZF(-100).
$ZF(-2) permits an InterSystems IRIS process to invoke a program or a command of the host operating system. $ZF(-2) executes the operating system command specified in program as a spawned child process from the current console. It executes asynchronously; it returns immediately after spawning the child process and does not wait for the process to terminate. Input and output devices default to the null device.
$ZF(-2) does not return the child process exit status. Instead, if the child process was created successfully,$ZF(-2) returns 0. $ZF(-2) returns -1 if a child process could not be forked.
Because $ZF(-2) does not wait for a response from the spawned child process, you can shut down InterSystems IRIS while the child process is executing.
$ZF(-2) closes the parent process principal device (specified in $PRINCIPAL) before executing the operating system command. This is done because the child process executes concurrently with the parent. If $ZF(-2) did not close $PRINCIPAL, output from the parent and the child would become intermingled. When using $ZF(-2) you should redirect I/O in the command if you wish to recover output from the child process. For example:
SET x=$ZF(-2,"ls -l > mydir.txt")
$ZF(-2) with no specified parameters launches the default operating system shell. For further details, see “Issuing Operating System Commands” in Using the Callout Gateway.
If a pathname supplied in program contains a space character, pathname handling is platform-dependent. Windows and UNIX® permit space characters in pathnames, but the entire pathname containing spaces must be enclosed in an additional set of double quote (") characters. This is in accordance with the Windows cmd /c statement. For further details, specify cmd /? at the Windows command prompt.
$ZF(-2) is a privileged operation, which requires the %System_Callout:U privilege. See “Adding the %System_Callout:USE Privilege” in Using the Callout Gateway for details.
An OS command audit record is added to the audit log for each $ZF(-2) call. This record includes information such as the following:
Execute O/S command Directory: c:\182u5\mgr\ Command: ls -lt 4002 - Detached
The Detached keyword indicates the call is $ZF(-2); a $ZF(-1) call does not have this keyword.
$ZF(-2), $ZF(-1), and $ZF(-100)
These three functions are in most respects identical. $ZF(-100) is the preferred function for all purposes, replacing both $ZF(-1) and $ZF(-2).
$ZF(-2) executes using the OS shell. It is asynchronous; it does not suspend execution of the current process. It immediately returns a status value upon spawning the child process. Because it does not await completion of the spawned child process it cannot receive status information from that process. $ZF(-2) sets $ZCHILD if its fifth argument is true.
$ZF(-1) executes using the OS shell. It is synchronous; it suspends execution of the current process while awaiting completion of the spawned child process. It receives status information from the spawned process, which it returns as an exit status code (an integer value) when the spawned process completes. $ZF(-1) does not set $ZCHILD.
$ZF(-100) can be synchronous or asynchronous. It can execute using the operating system shell or not using the shell. It always sets $ZCHILD. Both $ZF(-1) and $ZF(-2) with no specified parameters launch the operating system shell; $ZF(-100) requires a program parameter (and the /SHELL flag) to launch the operating system shell.