common/system

System utilities module for the Total Control scripting environment.

This module (path: "sigma/common/system") exposes lightweight host-side helpers
that interact with the desktop OS and the Total Control (TC) runtime. Use it to
execute local shell commands, read the system clipboard, and query TC’s language
and API version. It is framework-agnostic: functions are exported directly and are
not attached to Device objects.

Import path: require("sigma/common/system")

Features

• Run native commands on the host OS and capture stdout/stderr
• Return command output as a single string or as an array of lines
• Optionally filter out empty lines from command output
• Read the desktop clipboard as plain text
• Query the current TC scripting API version (e.g., "2.1.0.20911")
• Query the TC UI language (e.g., "zh", "en")

API

• execCommand(cmd: string, opt?: { outputArray?: boolean, ignoreEmpty?: boolean }): string | string[] | null
  Execute a shell command on the current computer. When outputArray is true,
  returns an array of lines; otherwise returns a single string. When ignoreEmpty
  is true, removes empty lines from the result. Returns null on error and
  sets a descriptive message via lastError().

• TCgetClipboardText(): string | null
  Return the current text contents of the desktop clipboard, or null if the
  clipboard does not contain text or is unavailable.

• TCgetAPIVersion(): string
  Return the TC scripting API version. Useful for feature gating and compatibility checks.

• TCgetLanguage(): string
  Return the TC installation language code, such as "zh" or "en".

Usage Examples

// Import (only this path is supported for this module)
var { execCommand, TCgetClipboardText, TCgetAPIVersion, TCgetLanguage } = require("sigma/common/system");

// 1) Run a command and get a single string
var cmd = java.lang.System.getProperty("os.name").toLowerCase().indexOf("win") >= 0
  ? "cmd /c netstat -a"
  : "sh -c netstat -a";
var out = execCommand(cmd);
if (out == null) {
  print("Command failed: " + lastError());
} else {
  print(out);
}

// 2) Run a command and get an array of non-empty lines
var lines = execCommand(cmd, { outputArray: true, ignoreEmpty: true });
if (!lines) {
  print("Command failed: " + lastError());
} else {
  lines.forEach((line) => print(line));
}

// 3) Read clipboard text
var clip = TCgetClipboardText();
print("Clipboard: " + (clip == null ? "<empty>" : clip));

// 4) Check API version and language
var apiVer = TCgetAPIVersion();
var lang = TCgetLanguage();
print("TC API: " + apiVer + ", language: " + lang);

// Feature gating by version
if (TCgetAPIVersion().startsWith("2.1")) {
  // Use features available in 2.1.x
}

Notes & Caveats

• Import path matters: This documentation applies only to sigma/common/system.
• Shell differences: On Windows, use cmd /c <command>; on macOS/Linux, use sh -c <command>.
• Blocking behavior: execCommand waits for the process to exit. Long-running commands
  will block the script until completion.
• Error reporting: On non-zero exit codes, the function returns null and includes the
  captured stderr in lastError().
• Clipboard format: TCgetClipboardText returns only plain text. Non-text clipboard
  formats will result in null.

Functions

// Get and print the current Total Control API version
var ret = TCgetAPIVersion();
print(ret);

// If it executes successfully, it will return:
2.1.0.20911

// Read and print clipboard contents
var ret = TCgetClipboardText();
print("The contents of the computer clipboard: " + ret);

// Example Output (if clipboard contains the word 'sigma'):
The contents of the computer clipboard: sigma

var ret = TCgetLanguage();
print(ret);

// Example Output:
zh

// Example 1: Get netstat output as a single string
// Cmd command
var cmd = "cmd /c netstat -a";

// Execute this JS API
var output = execCommand(cmd);
print(output);

// Output (truncated example):
TCP    0.0.0.0:135            account:0              LISTENING
TCP    0.0.0.0:445            account:0              LISTENING
...


// Example 2: Get output as an array, removing empty lines
// Cmd command
var cmd = "cmd /c netstat -a";

// Execute this JS API
var output = execCommand(cmd, { outputArray: true, ignoreEmpty: true });
print(output);

// Output:
...TCP    0.0.0.0:135  account:0  LISTENING, TCP    0.0.0.0:445  account:0  LISTENING, ...


// Example 3: Keep empty lines, return as string
// Cmd command
var cmd = "cmd /c netstat -a";

// Execute this JS API
var output = execCommand(cmd, { outputArray: false, ignoreEmpty: true });
print(output);

// Output (string, without empty lines):
TCP    0.0.0.0:135            account:0              LISTENING
TCP    0.0.0.0:445            account:0              LISTENING
...