Caché ObjectScript Reference
$ZF(-1)
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Executes an operating system command as a spawned child process and waits for the child process to return.
Synopsis
Windows and UNIX®:
$ZF(-1,oscommand)

OpenVMS:
$ZF(-1,oscommand,outdev,indev)
Parameters
oscommand Optional — The command or program to be executed as a child process, specified as a quoted string. If you omit oscommand, $ZF(-1) launches the operating system shell.
outdev Optional: OpenVMS Only — Output device. Used to specify SYS$OUTPUT for the child process. Uses current SYS$OUTPUT if not specified.
indev Optional: OpenVMS Only — Input device. Used to specify SYS$INPUT for the child process. Uses current SYS$INPUT if not specified.
Description
$ZF(-1) permits a Caché process to invoke a command of the host operating system. It executes the program or command specified in oscommand as a spawned child process from the current console. It waits for the process to return. It returns the child process exit status.
$ZF(-1) returns the following status codes:
Because $ZF(-1) waits for a response from the spawned child process, you cannot successfully shut down Caché 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 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(-1) requires the %System_Callout:U privilege. See Adding the %System_Callout:USE Privilege in Using the Caché Callout Gateway for details.
If $ZF(-1) is unable to spawn a process, it generates a <FUNCTION> error. On OpenVMS systems this may be caused by the child process trying to use the same SYS$INPUT as the parent process, and can be handled by specifying an indev value. The OpenVMS error code may be seen using the SYSLOG utility.
At the programmer prompt in the Caché 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 Caché Callout Gateway.
$ZF(-1) and $ZF(-2)
These two functions are in most respects identical. They differ in the following way:
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)
 
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
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")
 
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")
 
See Also