SYSTEM

The SYSTEM function runs an external command or program. It accepts the command in the form of a string and returns the exit code from the program, which is a 32 bit unsigned value. SYSTEM can be used for example to execute a program which contains additional tests and then check for success or failure by examining the return code.

All commands are executed using the Windows Command Processor, cmd.exe. If the Command Processor is unable to start the specified command line for any reason, then it returns an exit code of 1.

The process is launched inside a Job Object, a mechanism that allows a process and all of its children to be monitored and controlled, and allows them to be easily terminated if the user wants to stop a test function from running. The result of this is that any process that is left running — for example a process that is launched in the background — is terminated when the main program returns and the SYSTEM function completes.

SYSTEM( STRING command )

Examples

GLOBAL MeasureFrequency()(INT result)
  INT result;

  SET TXEN := 1;  // Enable transmitter

  result := SYSTEM("MeasureFrequency.exe 900000 1100000");

  SET TXEN := 0;  // Disable transmitter

  IF result > 0 THEN
    PRINT("Incorrect frequency detected\n");
  END;
END;

This executes a program called 'MeasureFrequency', which is assumed to return zero as its exit code if the frequency is between the two values passed in or non-zero if it falls outside.

It can be useful to construct the system command at run time, using string concatenation, e.g.:

DeleteFile(STRING filename)(INT result)
  result := SYSTEM("del " + "\"" + filename + "\"");
END;

Note that the filename above might contain spaces, so it is enclosed in double quotes which have been escaped.

Escaping

The command is executed by the Windows Command Processor, cmd.exe, which assigns some characters special meanings, specifically double quotes ("), less than (<), greater than (>), ampersand (&) and pipe (|). To pass these characters as literal characters to a command, they must be escaped using the circumflex (^) character.

This can get confusing since some escaping is already required within XJEase strings. For example, double quotes are used to enclose arguments containing spaces and must be escaped within an XJEase string with a backslash. In order for a double quote to be passed into a program and not be interpreted as enclosing an argument, it must be escaped with a circumflex, but it still needs the XJEase backslash too.

Example

This example prints various special characters out using the command processor's echo command, demonstrating how they need to be escaped:

result := SYSTEM("echo Special characters: ^&^|^<^>^\"");

Special characters: &|<>"

Redirection

Output from the command can be redirected to a file using the standard redirection operator:

result := SYSTEM("dir /b >filelist.txt");

There is a known issue when redirecting output from a script, e.g. Python or Perl. Normally the script file type (.py or .pl) is associated with the script interpreter and can be invoked directly. However, redirecting output from the script does not work in this case. Instead, the interpreter must be specified on the command-line:

result := SYSTEM("python myscript.py >output.txt");
result := SYSTEM("perl myscript.pl >output.txt");

Note that the interpreter needs to be on the path for this to work.