Function RunConsoleProcess

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 in a typescript console, called on one line, taking input from stdIn and writing output to stdOut, with no graphical user interface. It gives the path and name of the application 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 resumes execution. While blocked, Analytica monitors for Windows events such as CTRL-break. If you press CTRL-break before the process terminates, it aborts the computation and kills the process, and returns [what??].

If you pass False (0) to block, RunConsoleProcess will not wait for the process to terminate: It immediately returns an empty text to Analytica. Analytica and the spawned process both continue running concurrently until they terminate. If you press CTRL-break, it will stop Analytica, but not the spawned process [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. [How can Analytica 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 type of 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 .

priority defines the priority that Windows should give the spawned process relative to the Analytica process. The default (0) runs 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.

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

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 runs multiple blocking processes in sequence, one after another. It runs 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 file) to be launched. You don't need to worry about quoting any spaces in the path name. 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 StdIn:

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

where MyDataToSend evaluates to a text.