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 cmdLine parameter may contain parameters passed to the process over the command line. These two parameters are separated to protect against a common virus attack , rather than lumping them into a single command-line string. The optional stdInTxt text, if specified, will be piped to the stdin of the process.

If the process cannot be launched, an error is issued. The program specified as the first parameter on the command line is interpreted relative to the CurrentDataDirectory. When the remote program runs, it will see its own directory as the current directory unless the curDir parameter is specified, in which case its contents will be used for the current directory.

The priority of the process may optionally be specified. A value of 0 (default) will run the process at the same priority as the Analytica program. A value of –1 or -2 will lower the priority (allowing other programs more of the CPU), and a value of +1 or +2 will raise the priority, dedicating more of the CPU to the process.

By default, the function will block (i.e. wait) until the remote process completes. If the optional block parameters is set to False, the function will return immediately. The behavior in the two cases differs.

Blocking mode: Evaluation of the Analytica expression does not continue until the process terminates. Analytica will continue to field window events, at least periodically, allowing the screen to redraw and watching for CTRL-Break. When the process terminates, the return value is the stream written to StdOut by the process.

Analytica will block (i.e., wait) until the process terminates before proceeding (unless block=FALSE). Therefore, input can also be passed back and forth through data files using, e.g., WriteTextFile and ReadTextFile. Analytica will monitor for windows events such as CTRL-break while it is blocked waiting for the process to complete. If CTRL-break is pressed before the process terminates, the process is "killed" and the computation is aborted.

If the process writes anything to stdErr, it will be displayed as an error message unless the showErr parameters is specified. If showErr=0, then the error is ignored, and if showErr=2 the contents of stdErr is treated as a warning. In non-blocking mode, the showErr parameter is ignored.

Non-blocking mode: In non-blocking mode, returns an empty string.

The function is fully array abstractable, but multiple blocking processes shall be run in sequence, not 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.

Comments


You are not allowed to post comments.