docs.intersystems.com
Home  /  Application Development: Core Topics  /  ObjectScript Reference  /  ObjectScript Functions  /  $ZF(-100)


ObjectScript Reference
$ZF(-100)
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


Executes an operating system command or program as a child process.
Synopsis
$ZF(-100,flags,program,args)
Parameters
flags A quoted string containing one or more keyword flags. Multiple keyword flags are separated by blank spaces. A keyword flag can take the format /keyword, /keyword=value, or /keyword+=value. Keywords are not case-sensitive. The flags specify how to execute program.
program An operating system command or a program to be executed as a child process, specified as a quoted string. You can specify a full path, or just a program name. The operating system uses its rules, such as a PATH environment variable, to search for the specified program.
args Optional — A comma-separated list of program options and arguments. You can specify a null argument as "". You can use a local array and indirection .args or the args... syntax to specify a variable number of arguments.
Description
$ZF(-100) permits an InterSystems IRIS process to invoke an executable 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. $ZF(-100) allows you to invoke a program or command either synchronously or asynchronously, with or without invoking the operating system shell. $ZF(-100) provides similar functionality to $ZF(-1) and $ZF(-2). Its use is preferable to $ZF(-1) or $ZF(-2), which are both deprecated functions.
You can use a local array and indirection to specify a variable number of args, as shown in the following UNIX® example:
  SET args=2
  SET args(1)="-01"
  SET args(2)="myfile.c"
  SET status = $ZF(-100,"/ASYNC", "gcc",.args)
$ZF(-100) sets $ZCHILD to the PID of the started program.
Keyword Flags
How $ZF(-100) executes depends on the flags string values:
To specify $ZF(-100) with no keyword flags, specify the empty string for this parameter:
  SET status = $ZF(-100,"", "ls", "-l")
I/O Redirection
I/O redirection for /STDIN=filename, /STDOUT=filename, and /STDERR=filename follow UNIX® conventions. On both UNIX and Windows systems:
If /STDIN, /STDOUT, or /STDERR is not specified:
If /STDIN, /STDOUT, or /STDERR specifies a file that cannot be created or opened, the null device is used in place of the file.
If /STDOUT=filename and /STDERR=filename (or /STDOUT+=filename and /STDERR+=filename) specify the same filename, the specified file is only opened or created once. The resulting file handle is duplicated and supplied as both the stdout and stderr file handles given to the process that executes the specified cmd string. $ZF(-100) generates an <ILLEGAL VALUE> error if you specify the same file for /STDOUT and /STDERR, and one is specified +=filename and the other is specified =filename.
Quoting User-Specified Values
By default,$ZF(-100) provides automatic quoting. The /NOQUOTE flag inhibits automatic quoting. If /NOQUOTE is not specified, delimiting double quote characters are supplied as needed. This behavior is shown in the following example:
  DO $ZF(-100,"/LOGCMD","c:\sdelete64.exe","-nobanner","c:\dir1\nested directory\deleteme\")
This logs the following to messages.log; $ZF(-100) quoted the final argument to escape the space in the file path:
06/14/18-14:25:05:988 (3788) 0 $ZF(-100) cmd=c:\sdelete64.exe -nobanner "c:\dir1\nested directory\deleteme\"
06/14/18-14:25:06:020 (3788) 0 $ZF(-100) ret=0
If you specify /NOQUOTE, automatic quoting is suppressed; you must do your own quoting, as needed. If a specified value contains a / character or a blank space, the value must be quoted using doubled double quotes. This is shown in the following example:
  DO $ZF(-100,"/NOQUOTE /LOGCMD","c:\sdelete64.exe","""-nobanner""","""c:\dir2\""")
This logs the following to messages.log:
06/15/18-09:27:38:619 (3788) 0 $ZF(-100) cmd=c:\sdelete64.exe "-nobanner" "c:\dir2\"
06/15/18-09:27:38:650 (3788) 0 $ZF(-100) ret=0
If a filename contains a / character or a blank space, the filename must be quoted using doubled double quotes, as shown in the following example:
  SET status = $ZF(-100,"/stdout=""/home/user/myfile.txt"" /async", "ls", "-l")
The behavior differs on UNIX® and Windows systems:
Double quotes found within a command or command argument are escaped. On Windows these double quotes are escaped by doubling them as "" (as shown in the above examples). On UNIX they are escaped as \".
Return Status Codes
$ZF(-100) returns the following status codes:
$ZF(-100) with the /SHELL parameter 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(-100) requires the %System_Callout:U privilege. See Adding the %System_Callout:USE Privilege in Using the Callout Gateway for details.
If $ZF(-100) is unable to spawn a process, it generates a <FUNCTION> error.
Error Handling
$ZF(-100) generates a <NOTOPEN> error if:
The error is logged in SYSLOG. The operating system error number and message are available from the %SYSTEM.Process.OSError() method.
Auditing
An OS command audit record is added to the audit log for each $ZF(-100) call. This record includes information such as the following:
Command: /Users/myname/IRIS/jlc/bin/clmanager 4002 
Flags: /ASYNC/SHELL
$ZF(-100) , $ZF(-1), and $ZF(-2)
These three functions are in most respects identical. They differ in the following ways:
See Also