ITP/Server will start an external program and wait for the program to terminate. The command RunCommand will fail if the external program terminates with a non-zero return-code. The output of the command can be captured into both the ITP/Document Processor's logs and into script variables for further processing.
RunCommand
CmdLine(<text>)
LogStdOut(True or False)
LogStdErr(True or False)
UnicodeOutput(True or False)
CollectOutput(True or False);
CmdLine: Required.
The command line that will be executed.
LogStdOut: Optional.
If this parameter is set to True, all output written by the command to its 'standard output' channel is added to the ITP/Document Processor's log. The log level for the ITP/Server should be at least three (Extended info).
If this parameters is omitted or set to False, no output is written to the logs.
Note
Most commandline tools buffer their output into blocks before writing it to the 'standard output' channel. It is therefore possible that lines are broken into multiple parts when written to the log.
LogStdErr: Optional.
If this parameter is set to True, all output written by the command to its 'standard error' channel is added to the ITP/Document Processor's log. The log level for the ITP/Server should be at least three (Extended info).
If this parameter is omitted or set to False, no output is written to the logs.
Note
Most command line tools write their error messages to the 'standard error' channel.
UnicodeOutput: Optional
If this parameter is set to True, all output of the command is interpreted as Unicode text.
If this parameter is omitted or set to False, the output is treated as single-byte text in the local code page of the system.
CollectOutput: Optional
If this parameter is omitted or set to True, all output written to the 'standard output' channel and 'standard error' channel are captured and made available to the script in the variables _stdout and _stderr, after the RunCommand completes.
If this parameter is set to False, the channels are not captured and the variables _stdout and _stderr are empty.
It is possible to use RunCommand/StartProgram to execute scripts, e.g., batch and vbs files, by using the appropriate script processor to execute these scripts. For example, to run a CMD file:
RunCommand
CmdLine("cmd /c c:\scripts\do_work.cmd par > c:\logs\out.txt");
Note that this command redirects the 'standard output' channel to the file c:\logs\out.txt. Therefore the variable _stdout will not capture anything and be empty when the command completes.
The _stdout and _stderr variables will by default only capture the first 100 lines of output. If there is more output the variable will end with the line '...TRUNCATED...'. The number of lines can be changed by adding the setting
CaptureLineLimit=100
to the [Configuration] section of the dp.ini of your ITP/Server setup. Replace 100 with the required number of lines, or 0 to remove any limitation.
Warning
If the program generates an excessive amount of output (in the order of hundreds of megabytes) the ITP/Document Processor can shut down if it runs out of memory to store the text. In such a scenario it is recommended to write the output to disk and preprocess it with external tools before reading it into the ITP/Server script.
Logging to the ITP/Document Processor's log file, whenever LogStdOut or LogStdErr are enabled, is never truncated. This logging is subject to the normal log rotation schedule.
Note
Some applications can (appear to) hang when their output is captured. The following is a list of programs with known issues. Disable capturing when calling these programs: