RunConsoleProcess

Function RunConsoleProcess

Declaration:

RunConsoleProcess(
  program: Atomic Text,
  cmdLine: Optional Atomic Text,
  stdIn: Optional Atomic Text,
  block: Optional Atomic Boolean, /* default TRUE */
  curDir: Optional Atomic Text, /* default process directory */
  priority: Optional Atomic Number, /* default 0 = normal, same as Ana */
  showErr: Optional Numeric) /* defaults to 1=err msg */

RunConsoleProcess lets an Analytica model run a console process -- that is, any Windows program that can run without a graphical user interface. It passes the path and application name in the program parameter. It can feed input to the program via command line parameters in cmdLine, or as input data given as text to the stdIn parameter, which is piped to the StdIn input channel of the console process. Normally, when the process completes, RunConsoleProcess will return a result (as text) any information the program writes to stdOut. Analytica can also send data to a console process via a data files created with WriteTextFile or receive a data file created by the process using ReadTextFile.

RunConsoleProcess offers considerable flexibility through a number of other optional parameters:

block: By default RunConsoleProcess blocks -- that is, Analytica waits until the console process terminates and returns a result before it continues execution. While blocked, Analytica will monitor for Windows events such as CTRL-break. If you press CTRL-break before the process terminates, it aborts the computation and kills the process, returning [what?].

If you pass False (0) to block, RunConsoleProcess does not wait for the process to terminate. It immediately returns an empty text. Analytica and the spawned process both continue running. If you press CTRL-break, it will stop Analytica, but not the spawned process [Lonnie, is that true?]. It is not advisable for Analytica to try to read a file created by the console process because there is no way to know whether it has completed. [Is there any way for Analytica to get information from the spawned process in non-blocking mode?]

The program and cmdLine parameters are separated, rather than lumped together as one parameter, to protect against a common virus attack.

curDir: Any relative directory path specified in the program parameter is interpreted relative to Analytica's CurrentDataDirectory. curDir specifies the directory the spawned process should use as its default directory to read and write files. If curDir is not specified, it uses its own directory as its default .

Errors: Analytica will give an error message if RunConsoleProcess cannot find or launch the specified program.

priority defines the priority Windows should give the spawned process relative to the Analytica process. The default (0) is to run the new process at the same priority as the Analytica program. A value of –1 or -2 lowers the priority, allowing other programs more of the CPU. A value of +1 or +2 raises the priority, dedicating more of the CPU to the process.

showErr: By default, in blocking mode, if the process writes anything to stdErr, Analytica will display it as an error message when the process terminates. If showErr=2 it shows any text in stdErr as a warning message. If showErr=0, and always in non-blocking mode, it ignores anything in stdErr.

RunConsoleProcess fully supports Intelligent Arrays: If any parameter is passed an array, it will run a separate process for each element of the array. It will run multiple blocking processes in sequence, one after another. It will run multiple non-blocking processes concurrently.

Example

Suppose the file HelloWorld.vbs is in your model directory and contains:

WScript.Echo "Hello World"

Your call to RunConsoleProcess might look like:

RunConsoleProcess( "C:\Windows\System32\CScript.exe",
                "CScript /Nologo HelloWorld.vbs" )

The first parameter is the program (usually an EXE) that will be launched. If there are spaces in the path name, there is no need to worry about quoting them. The second parameter is the command line as it might appear on a command prompt. This expression will evaluate to the string "Hello World".

If you need to send data to the StdIn of the process, include an optional parameter:

RunConsoleProcess( "C:\Windows\System32\CScript.exe",
                "CScript /Nologo HelloWorld.vbs"       
                StdIn: MyDataToSend)

where MyDataToSend evaluates to a text string.