Skip to main content

1E 23.11 (SaaS)

NativeServices.RunCommand

Method

RunCommand

Module

NativeServices

Library

Core

Action

Execute a command-line.

Parameters

CommandLine (string): The entire command line to run, including the CLI arguments.

WorkingDirectory(string; optional): The path of the current directory when the command is executed.

SplitLines(boolean; optional, defaultfalse): Whether or not to return a row per line of output. Cannot be used withInterpretAsJson.

TrimTrailingWhitespace(boolean; optional, default true): Whether or not to discard trailing whitespace characters from output row(s). New in v5.1 in a hotfix.

IncludeErrorOutput (string; optional, default "Interleaved" for backwards compatibility): How to handle output from the standard error stream with respect to the Output value. One of:

Interleaved

Merge output on both streams as it is produced within the limits of buffering, i.e. mimic the same behavior as before.

Auto

Return only standard output unless there is none whatsoever in which case return standard error.

Before

Standard error comes before standard output (with an extra new-line in between to separate).

After

Standard error comes after standard output (with an extra new-line in between to separate).

Never

Only ever return standard output.

Only

Only ever return standard error (i.e. throw away standard output).

OnFailure

Return just standard error if and only if the exit code is non-zero, otherwise return just standard output.

Note

Case is not significant.

Warning

This parameter is implemented for Windows only; it is allowed but ignored for other platforms.

InterpretAsJson (boolean; optional, defaultfalse): If specified and has value true, assume that the output of the command is JSON and deserialize it. The return value is then the table produced. Cannot be used withSplitLines.

TimeoutSecs (integer; optional, default 3600): If the command does not terminate within the specified number of seconds, return anyway. A value of 0 means an eternal timeout, i.e. none. A negative value is illegal.

TimeoutKill (boolean; optional, default false): If a timeout has been reached, attempt to kill the command execution sub-process. The method terminates even if killing the command fails for some reason, i.e. the method never hangs. Do not specify if there is no timeout.

Warning

Try to avoid using TimeoutKill if possible, and instead let the sub-process die in its own time. For example, consider the effect of killing an install partway through.

IgnoreExitCode(boolean, optional, defaultfalse): Iftrue, the execution of the command will be considered successful, irrespective of the exit code returned. Iffalse, any non-zero exit code will be interpreted as a failure and this method will return an error.

Return values

ExitCode (int): The exit code from the command (or the attempt to run the command if the command is not defined). This will only be non-zero if IgnoreExitCode is true.

Warning

Many Windows programs set a zero exit code even on failure.

LineNumber (int): The line number of the output, starting at 0. This is only returned if SplitLines is true.

Output (string): The output that the command sends to standard output and standard error, combined.

Warning

If there is no (captured) output from the program whatsoever, the return value from this method is completely empty. There is not a single row with an empty Output value, as might be expected.

Examples

Running as the Tachyon.Agent user (LocalSystem usually) 

NativeServices.RunCommand(CommandLine:"ping 127.0.0.1", SplitLines:true, IgnoreExitCode:true);

NativeServices.RunCommand(CommandLine:@cmdRun, SplitLines:true, WorkingDirectory:@fileDir, TimeoutSecs: 10, TimeoutKill: true);

AsUser example 

@users = Users.GetLoggedOnUsers();
@users = select * from @users where SessionState='Active';

NativeServices.RunCommand(CommandLine:"c:\\windows\\notepad.exe", AsUser:@users.Account);

Platforms

  • Windows

  • Linux

  • MacOS

Notes

If the Agent is shut down while a command is running (with or without a timeout specified), the command subprocess is detached from the Agent (so that Agent shutdown is not blocked), and the Tachyon instruction's status is set to "execution failed" because Tachyon cannot know the ultimate fate of the command. It is up to the user to decide whether to resubmit the instruction or not when the Tachyon Agent resumes.

By default, a long-running instruction will time out. "Long running" is 3600 seconds, i.e. 1 hour. This is to prevent a hanging command from completely blocking the Tachyon Agent, because the Agent has an exclusivity feature for safety such that even if the Agent runs with multiple workers then executing a command prevents any other worker from running an instruction in parallel. (This is because instructions that follow the command might depend on that command having run to completion.) A command hanging indefinitely would completely block the Agent, including any instructions to kill the hanging command's process. If a command really must be run to completion, set TimeoutSecs to 0 to indicate no timeout.

Because the Tachyon Agent has multiple workers and so can run a number of instructions in parallel, it is possible that conflicting commands could run at the same time, e.g. each attempting to install software. (Software packages can only usually be installed one at a time.) If this is likely to be a problem, the Agent's "Exclusivity" setting (in its configuration file) should be set to true which will ensure that only one RunCommand can run at any time across all workers, causing other RunCommand instances to be temporarily suspended. By default Exclusivity= false. Exclusivity was introduced in a 1E Client 4.1 hotfix; prior to then RunCommand instances would block, equivalent to Exclusivity=true.

In this section: