Few commands return a result to their invocation environment (here the invocation environment is the macro).

Command run is one of the few commands really designed to return a value: it executes an external command, for example dir on Windows (ls on Unix), and it captures what is printed on the console to return it as its result.

The following macro is used to run an external command (user is prompted to specify it) and then, to insert at caret position the text which is the result of the external command.

<command name="insertCommandOutput">
  <macro>
    <sequence>
      <command name="run" />
      <command name="insertString" parameter="%_" />
    </sequence>
  </macro>
</command>

Command insertString can insert text at caret position. But how to pass to command insertString what has been returned by command run? The answer is: use variable "%_".

Each time a command (or a sequence, or a choice) is executed inside a macro, the result of the executed command (or construct) is used to assign a predefined variable which referenced as "%_" in command parameters.

When executed command does not return a result, variable "%_" is cleared. A reference in a command parameter to a cleared "%_" is replaced by the empty string.

The sequence and choice constructs, which can be considered as being pseudo-commands, can return results too:

The pass and fail constructs are just tests. They have no effect on "%_". That is, they return the result of the last executed command or construct.