Caché ObjectScript Reference
[Back] [Next]
Go to:

Executes an operating system command as a spawned child process and returns immediately.
oscommand Optional — The command or program to be executed as a child process, specified as a quoted string. If you omit oscommand, $ZF(-2) launches the operating system shell.
$ZF(-2) permits a Caché process to invoke a command of the host operating system. $ZF(-2) executes the operating system command specified in oscommand as a spawned child process from the current console. 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 either 0 (on most platforms) or 1 (on OpenVMS platforms). $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 Caché 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 Caché Callout Gateway.
If a pathname supplied in oscommand contains a space character, pathname handling is platform-dependent:
You can use the NormalizeFilenameWithSpaces() method of the %Library.File class to handle spaces in pathnames as appropriate for the host platform.
$ZF(-2) is a privileged operation, which requires the %System_Callout:U privilege. See Adding the %System_Callout:USE Privilege in Using the Caché Callout Gateway for details.
$ZF(-1) and $ZF(-2)
These two functions are in most respects identical. They differ in the following way:
See Also