Contents

NativeServices.RunCommand

Method

RunCommand

ModuleNativeServices
LibraryCore
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, default false): Whether or not to return a row per line of output. Cannot be used with InterpretAsJson .

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:

InterleavedMerge output on both streams as it is produced within the limits of buffering, i.e. mimic the same behavior as before.
AutoReturn only standard output unless there is none whatsoever in which case return standard error.
BeforeStandard error comes before standard output (with an extra new-line in between to separate).
AfterStandard error comes after standard output (with an extra new-line in between to separate).
NeverOnly ever return standard output.
OnlyOnly ever return standard error (i.e. throw away standard output).
OnFailureReturn just standard error if and only if the exit code is non-zero, otherwise return just standard output.

Case is not significant.

From v5.1.

This parameter is implemented for Windows only; it is allowed but ignored for other platforms, apart from Android where it must not be given.
InterpretAsJson  (boolean; optional, default false): 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 with SplitLines.

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.

Timeout is not supported on Android. It is not an error to specify the parameter but the value will be ignored.

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.

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, default false): If true , the execution of the command will be considered successful, irrespective of the exit code returned. If false , any non-zero exit code will be interpreted as a failure and this method will return an error.

AsUser (string; optional; default 1E.Client service user) Windows only: The "domain\user" (down-level logon) account name that the Agent will attempt to impersonate on the local machine.

If this parameter is absent the command will be executed in the Tachyon Agent process's user context.

It is not an error if the specified user is not currently logged on (and this includes accounts that are not even defined). In this case execution is deemed successful but the method does nothing and returns no data.

The specified user must be currently logged on and running explorer.exe (Windows Explorer).

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.

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.

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
  • Solaris Intel
  • Solaris Sparc
  • Android
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.