RunConsoleProcess - call other applications

Analytica User GuideIntegration with data and applicationsRunConsoleProcess - call other applications

This feature is available in Analytica Enterprise and Optimizer.

RunConsoleProcess(«program», cmdline, stdIn, block, curDir)

This function starts another Windows application -- also known as a "console process". The application or program can be a simple one with no graphical user interface, or it can interact directly with the user. RunConsoleProcess() can provide data as input to the program and return results generated by the application.

The «program» parameter contains text to specify the directory path and name of the program. It can feed input to the program via command line parameters in «cmdLine», via the «stdIn» parameter, piped to the StdIn input channel of the program, or via a data file created with WriteTextFile(). Normally, when the program completes, RunConsoleProcess() returns a result (as text) any information the program writes to «stdOut». Analytica can also use ReadTextFile() to read any results the program saves as a data file.

Required parameter

«program»

Text to specify the directory path and name of the Windows application (program) to run. A relative path is interpreted relative to Analytica’s CurrentDataFolder. If it cannot find or launch the application, it gives an error message.

Optional parameters

cmdline

Text given input to the program as command line parameters. (It is separated from the «program» parameter to protect against a common type of virus attack.)

stdIn

Text to be piped to the StdIn input channel of the program.

block

If you omit «block» or set it to True (1), RunConsoleProcess() blocks — that is, after calling the process, Analytica stops and waits until the console process terminates and returns a result before it resumes execution. While blocked, Analytica still notices Windows events. If you press Control + Break (or Control + .) before the process terminates, it kills the process, and ends further computation by Analytica, just as when Analytica is computing without another process.

If you set «block» to False (0), RunConsoleProcess() spawns an independent process that runs concurrently with Analytica. Within Analytica, it returns empty text. Analytica and the spawned process each continues running independently until it terminates. If you press Control+Break (or Control+), it interrupts and stops further computations by Analytica, but has no effect on the spawned process. An unblocking process might continue running even after you exit Analytica. Unblocking processes are useful when you want to send data to another application for display, such as a special graphing package or GIS, or for saving selected results. It is difficult for Analytica to get any results or status back from an unblocking process. If you need results back it is usually best to use a blocking process.

curDir

The directory the process should use as its default directory to read and write files. If omitted, it uses the application’s own directory as the default.

priority

Sets the priority that Windows should give the spawned process relative to the Analytica process. The default (0) is the same priority as the Analytica process. Setting it to +1 or +2 raises its priority, taking more of the CPU for the process. -1 or -2 lowers the priority, letting other processes (including Analytica) use more of the CPU.

showErr

Controls the display of error messages from a blocking process. By default, if the process writes anything to «stdErr», Analytica displays 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, it ignores anything in «stdErr». Analytica always ignores any error in an unblocking process, which is assumed to control the display of its own errors.

RunConsoleProcess() fully supports Intelligent Arrays. If any parameter is passed an array, it runs a separate process for each element of the array. It runs multiple blocking processes sequentially. It runs multiple non-blocking processes concurrently.

Examples

Run a VB Script

Suppose the Visual Basic program 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 identifies the program 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 returns the text value "Hello World".

To send data to the StdIn of the process, include the optional parameter «stdIn»:

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

where MyDataToSend is an Analytica variable that gives a text value.

To run a batch file

Suppose the directory C:\Try contains a data file named data.log and a batch file named DoIt.bat containing:

#DoIt.bat — dump the log

Type data.log

This batch file assumes it is run from the directory C:\Try so does not mention the directory of data.log. From Analytica, you call:

RunConsoleProcess("C:\Windows\System32\Cmd.exe", "Cmd /C DoIt.bat", CurDir: "C:\Try")

Or you can run it directly:

RunConsoleProcess("DoIt.bat", "DoIt.bat", CurDir: "C:\Try")