Skip to main content
Previous sectionNext section

$ZF(-1)

Executes an operating system command or program as a child process, synchronously. (Deprecated)

Synopsis

$ZF(-1,program)

Parameters

Argument Description
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(-1) launches the operating system shell.

Description

Note:

$ZF(-1) is a deprecated function. It is described here for compatibility with existing code only. All new code development should use $ZF(-100).

$ZF(-1) permits an InterSystems IRIS process to invoke a program or a command of the host operating system. It executes the program or command specified in program as a spawned child process from the current console. It executes synchronously; it waits for the process to return. $ZF(-1) returns the child process exit status.

$ZF(-1) returns the following status codes:

  • It returns 0 if the child process executed successfully.

  • It returns a positive integer based on the exit status error code issued by the operating system shell. This integer exit status code value is determined by the host operating system. For example, for most Windows command syntax errors, $ZF(-1) returns 1.

  • It returns -1 if the child process could not be forked.

Because $ZF(-1) waits for a response from the spawned child process, you cannot successfully shut down InterSystems IRIS while the child process is executing.

$ZF(-1) 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.

You can use the NormalizeFilenameWithSpaces() method of the %Library.File class to handle spaces in pathnames as appropriate for the host platform.

$ZF(-1) requires the %System_Callout:U privilege. See “Adding the %System_Callout:USE Privilege” in Using the Callout Gateway for details.

If $ZF(-1) is unable to spawn a process, it generates a <FUNCTION> error.

At the Terminal in the Terminal, you can perform operations similar to $ZF(-1) by using an exclamation point (!) or a dollar sign ($) as the first character, followed by the operating system command you wish to execute. The ! or $ command line prefix executes the operating system command, returns results from the invoked process and displays those results at the Terminal. $ZF(-1) does not return operating system command results; it executes the operating system command, then returns the exit status code for the invoked process. For further details, see “Issuing Operating System Commands” in Using the Callout Gateway.

Auditing

An OS command audit record is added to the audit log for each $ZF(-1) call. This record includes information such as the following:

Execute O/S command Directory: c:\182u5\mgr\ 
Command: ls -lt 4002
Copy code to clipboard

$ZF(-1), $ZF(-2), 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(-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(-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(-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.

Examples

The following Windows example executes a user-written program, in this case displaying the contents of a .txt file. It uses NormalizeFilenameWithSpaces() to handle a pathname for $ZF(-1). A pathname containing spaces is handled as appropriate for the host platform. A pathname that does not contain spaces is passed through unchanged. $ZF(-1) returns the Windows shell exit status of 0 if the specified file could be accessed, or 1 if the file access failed:

   SET fname="C:\My Test.txt"
   WRITE fname,!
   SET x=##class(%Library.File).NormalizeFilenameWithSpaces(fname)
   WRITE x,!
   WRITE $ZF(-1,x)
Copy code to clipboard

The following Windows example invokes the Windows operating system SOL command. SOL opens a window that displays the Solitaire game provided with the Windows operating system. Upon closing of the Solitaire interactive window, $ZF(-1) returns the Windows shell exit status of 0, indicating success:

   SET x=$ZF(-1,"SOL")
   WRITE x
Copy code to clipboard

The following Windows example invokes a non-existent Windows operating system command. $ZF(-1) returns the Windows shell exit status of 1, indicating a syntax error:

   WRITE $ZF(-1,"SOX")
Copy code to clipboard

The following Windows example invokes a Windows operating system command, specifying a non-existent network name. $ZF(-1) returns the Windows shell exit error status of 2:

   WRITE $ZF(-1,"NET USE :k \\bogusname")
Copy code to clipboard

See Also