RunCommand

KCM Core starts an external program and waits for the program to terminate. The command RunCommand fails if the external program terminates with a non-zero return code. The output of the command can be captured into both the KCM Document Processor logs and into script variables for further processing.

Syntax

RunCommand 
   CmdLine(<Text>) 
   LogStdOut(<Boolean>) 
   LogStdErr(<Boolean>)
   UnicodeOutput(<Boolean>)
   CollectOutput(<Boolean>);

Parameters

CmdLine: Required. The command line that is 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 KCM Document Processor log. The log level for the KCM Core should be at least three (Extended info). If this parameter, is omitted or set to False, no output is written to the logs.

Most command line 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 KCM Document Processor log. The log level for the KCM Core should be at least three (Extended info). If this parameter is omitted or set to False, no output is written to the logs. 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.

You can use RunCommand/StartProgram to execute scripts, such as 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");

This command redirects the "standard output" channel to the file c:\logs\out.txt. Therefore, the variable _stdout does not capture anything and is empty when the command is completed.

The _stdout and _stderr variables are by default only capture the first 100 lines of output. If there is more output, the variable ends with the line "TRUNCATED." The number of lines can be changed by adding the following setting to the [Configuration] section of the dp.ini of your KCM Core setup. Replace 100 with the required number of lines, or 0 to remove any limitation.

CaptureLineLimit=100

If the program generates an excessive amount of output (in the order of hundreds of megabytes), the KCM Document Processor can shut down if it runs out of memory to store the text. In such a scenario, write the output to disk and preprocess it with external tools before reading it into the KCM Core script.

Logging to the KCM Document Processor log file, whenever LogStdOut or LogStdErr is enabled, is never truncated. This logging is subject to the normal log rotation schedule.

Some applications may become unresponsive when their output is captured. Disable capturing when calling the following program:

PsExec.exe (SysInternals PsTools)