Run Program

$run "pgm args" [NOWAIT|NOMONITOR] [NOHIDE]

The $run command spawns and runs the program specified, with the passed arguments. The program should be of a type which can execute reliably and quickly, since the CopiaFacts channel defaults to being effectively suspended while it is running. This command must be used in a $type query question box.

Running a batch file:  When the external program is executed, its current folder is set to the Copia Application Data folder (typically \\server\copia\faxfacts).  Note that if your command line runs a batch file using "CMD /c filename.bat" the operation of CMD.EXE in Windows XP and above does not support the current folder being a UNC path and instead silently changes the current folder of the process to the Windows folder (e.g. C:\WINDOWS). Your batch file, and any relative or absent pathnames, must be written to allow for this. You can change this CMD behavior by modifying the registry as described at http://support.microsoft.com/kb/156276. If you change the current folder in the external process, the value is not retained after your program returns.

The parameters on this command are used as follows:

pgm the program name to be executed. The name must include the file extension if it is .COM, but the file extension is optional for .EXE files. Including the full path may speed the loading of the program, but double-quotes are needed (in the form "") to enclose a pathname containing spaces.  Do not start this parameter with the name of a .CMD or .BAT file, always precede this with CMD /c and read the note above.
args the arguments for the program to be executed. These will normally be of the form "@var1 @var2... @varN". To include quoted values among the arguments, use the form "" to insert a double-quote character.
nowaitthis keyword causes execution to continue in COPIAFACTS while the spawned program runs.
nomonitorthis keyword also causes execution to continue in COPIAFACTS while the spawned program runs, but no further interaction with the program is possible and the options to terminate it do not apply.  It may also continue running after the call ends.
nohidethis keyword causes the window of the program that is run to be made visible.

If the program returns an exit code of 0 to 254, this value is added to the number specified by $next_box. To do this, you must provide a plain numeric infobox reference on the $next_box command, not a state value. An exit code of 255. or a negative exit code, transfers to the $error_exit, if any. The exit code is also saved in a variable named FFRESULT, which is not available in the same infobox as the $run command, only in a subsequent infobox.

The RUNVALUE command can be used to pass a string value back to CopiaFacts.  If a program run from this command is one that you have developed, you can also return a value to COPIAFACTS by sending a Windows message, as described in the RUNVALUE topic.

When the nowait keyword is given, you can determine whether the program has ended by referencing the NOWAIT_ACTIVE system variable, which will contain a non-empty value (the numeric exit code) if the program has terminated.  Until you have checked this variable and it has returned a non-empty value, further $run commands in the same line/thread with nowait will fail.  You can kill a nowait process by assigning a non-empty value to the system variable KILL_NOWAIT.

If the current call ends before a program spawned with nowait terminates, CopiaFacts will attempt to terminate the spawned process.  This does not happen with the nomonitor option.

Example:

Create a .IIF file using an external program and then run it. Use a filename based on the line number for uniqueness.

$type query

$run "writeiif @LINE @input1 @input2"

$next_box @LINE ; run the generated file

$error_exit 999

Run a batch file:

$type query

$run "CMD /c @FFBASE\mybatch.bat @VAR1 @VAR2"

$next_box batchOK

$error_exit 999