# RunConsoleProcess

## RunConsoleProcess(program, cmdLine, stdIn, block, curDir, priority, showErr)

RunConsoleProcess lets an Analytica model run a console process -- that is, any Windows program. The program may be very simple with no graphical user interface that takes input from «stdIn» and writing output to stdOut -- or it may interact with the user directly. RunConsoleProcess 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.

## 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 offers considerable flexibility through a number of other optional parameters:

«block»: By default (or if you set «block» to True or 1), RunConsoleProcess blocks -- that is, Analytica waits until the console process terminates and returns a result before it resumes execution. While blocked, Analytica still notices Windows events: If you press Ctrl+break (or Ctrl+.) before the process terminates, it kills the process, and ends further computation by Analytica -- just like what it does when Analytica is computing without another process.

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 each terminate. If you press Ctrl+break (or Ctrl+.), it interrupts any computations by Analytica, but has no effect on the spawned process. An unblocked process is independent, and may continue running even after you exit Analytica. Unblocked 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 hard to get any results or status back to Analytica from an unblocked process. It is usually best to use a blocked process if you need results back.

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 CurrentDataFolder. «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.

## Examples

### VB Script

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.

### Batch File

In this example, a batch file named DoIt.bat is in the directory C:\Try. Also in that directory is a file named data.log. The batch file, DoIt.bat contains the following:

# DoIt.bat -- dump the log
Type data.log

This batch file assumes it is run from the directory C:\Try. The call is:

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")

### Reading Data from a URL

If you want to read data from a URL, you should use the ReadFromURL function. Nevertheless, this example from the past may be illustrative.

To read the contents of a web page given its URL, you can use:

RunConsoleProcess("ReadURL.exe", "ReadURL " & url)

where url is a text string as would appear in the address bar of your browser. You can download the ReadURL.exe program by clicking on the link and saving. The first parameter to RunConsoleProcess may need to be set to the full path where you placed ReadURL.exe unless you put it in your CurrentDataFolder.

A step-by-step example using ReadURL.exe is given here: Retrieving Content From the Web. This example includes the source code for ReadURL.exe, and develops an example that obtains historical stock price data from the Yahoo finance web site.

## History

This function was introduced in Analytica 4.0.