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 executes a console process specified by the program parameter. 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. [TBD: Use the PATH?]

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.

The function must take care to avoid a deadlock condition when using stdin and stdout/stderr. These streams typically use a finite-sized buffer. Without care, a deadlock condition can occur if the process reads some from stdin, then writes some to stdout, and repeats this pattern (as is very common in Perl scripts, etc). When the stdout buffer fills up, the process will block, waiting for Analytica to pour out the contents, while Analyica may be waiting for the process to drink the remaining stdin text. This means that Analytica must concurrently read out stdout and stderr as it is writing to stdin.