[ You are here: XTF -> Tag Reference -> Calling Command-line Tools ]

Calling Command-line Tools

The built-in exec extension element can be used in stylesheets to call external command-line tools. See the Programming Guide for a description and examples.

External Command Extension Element

This element can be used inside any XTF stylesheet to call a command-line program, like this:
<exec:run command  = "CommandName"
          {timeout = "Milliseconds"}
          xsl:extension-element-prefixes="exec">
 
  {<exec:arg>Argument1</exec:arg>}
  {<exec:arg>Argument2</exec:arg>}
      …
 
  {<exec:input>
    XmlOrString
   </exec:input>}
 
</exec:run>
where
exec: is a namespace prefix identifying this particular Saxon extension. The namespace URI for this prefix must be: java:/org.cdlib.xtf.saxonExt.Exec.
command="CommandName" specifies the command-line program to run. In general, this should be an absolute path; if a relative path is given, it will be resolved in an undefined manner.
timeout="Milliseconds" is an optional attribute setting an upper limit, in milliseconds, on the amount of time the external process will be given to finish its work. If this time is exceeded, the process will be forcibly terminated, an a Java exception will be thrown (which terminates stylesheet processing immediately.) If this attribute is not specified, the process will be allowed to run to completion no matter how long it takes.
<exec:arg> is an optional sub-element that can be used repeatedly to specify command-line arguments to be passed to the program. Each argument should be specified in its own <exec:arg> element; in particular, pairs should usually be broken up. For example, to perform the command "ls -al *" one would specify two arguments, the first being "-al" and the second being "*".
<exec:input> is an optional sub-element that specifies the input to be send to the external program (input will be sent to the process stdio stream). If the content of the exec:input element is XML data (for instance, a variable holding one or more elements) then the servlet will automatically serialize the data into standard XML format, with UTF-8 character encoding. If the content is not XML, the string will be sent to the tool verbatim.
This extension element calls an external command-line tool. Internally, this creates a new operating system process, and the servlet thread waits for that process to complete.
If the exec:input element is specified, the entire string of input text (converted from XML to text if necessary) will be fed to the process' stdin stream.

Output from the process' stdout stream will be collected, and the servlet checks if the data begins with an XML header. If so, the value of the exec:run element will be actual XML elements from the data. Otherwise, the value will be one long string, being an exact copy of the output from the external tool.

If the process exits with a non-zero code (or the optional timeout is exceeded) then XTF will throw a Java exception, which causes the stylesheet execution to terminate immediately.