exec

Home > Books > NetKernel API and Services Reference > Accessor Listing > Utility and System Accessors > exec

Module

The exec accessor is exported by the urn:org:ten60:netkernel:ext:sys module. Import this module to gain access to the accessor.

Syntax

URI

active:exec

Argument	Rules	Description
command	Mandatory	the native process to be executed
wd	Optional	the working directory for the process, a file: scheme URI, If not specified the working directory is inherited from the boot-up of NetKernel.
stdin	Optional	a resource that should be streamed into the stdin of the process
stderr	Optional	a service to be invoked with the stderr stream from the process
param	Optional	some optional configuration

Example Usage

DPML

<instr>
  <type>exec</type>
  <command>
    <args>
      <arg>cat</arg>
      <arg>-E</arg>
    </args>
  </command>
  <stdin>readme.txt</stdin>
  <target>this:response</target>
</instr>

NetKernel Foundation API

req=context.createSubRequest("active:exec");
req.addArgument("command", [resource representation, aspect, or URI] );
result=context.issueSubRequest(req);

Purpose

The exec accessor provides a flexible mechanism for executing a native process on the local native operating system. It enables the native process to be wrapped and treated as a service within NetKernel.

The streams stdin, stdout and stderr of the invoked process can be harnessed as pipelines to/from NetKernel services or redirected to other operating system native processes.

Usage

The command argument specifies a native operating system command and its arguments (argv) that will be passed to the underlying operating system to execute in a platform specific way. The command argument can either be specified as a string (for example, using the data: scheme) or as an XML fragment with a set of <arg> elements containing the text of each part of the command specification.

The working directory of the executed process defaults to the working directory of the NetKernel process. The wd argument can be used to specify a different directory using a file: URI.

Working with stdin

Any resource can be passed to the process via its stdin stream. The resource must be capable of being serialized to a binary stream.

Working with stdout

By default the exec accessor returns the stdout stream from the native process as its response. The response is generated as a stream such that it may be pipelined into another service without being buffered in memory - this is an important consideration if the amount of data being processed is large. This also also means that the actual execution of the native application only occurs just-in-time when a resource is used (this is analogous to a SAX pipeline) and means that true application pipelines can be composed.

If the native process returns a non-zero return code then it assumed to be an error and an exception is thrown. If you wish to override this default behaviour you can specify an <ignoreReturnCode/> element in the param argument XML fragment.

The default MIME media type of the response is text/plain. This can be overriden by specifying in the param argument XML fragment a first-child <mimetype> element containing the MIME media type as text.

Working with stderr

By default the stderr stream from a process is logged line-by-line into the system log as a warning. This behaviour can be stopped by specifying an <ignoreStderr/> element in the param argument XML fragment. The default behaviour can be overridden by setting a custom stderr handler service URI specified in the stderr argument.

A stderr handler service is invoked with the URI specified on the stderr argument. It is also passed a command argument which is the command string that generated the stderr, and a stderr argument which is the stderr stream. Any response from the stderr handler is ignored, however if it fails its exception will be propagated back to the caller of the exec accessor.

Termination

The exec accessor is valuable for enabling access to the standard Unix system tools which process stdin to stdout such as sed, awk, gzip, etc. It is assumed that these applications will terminate when the stdin file is closed. It is not possible to kill a native system process started with the exec accessor so, for example, a GUI application started with exec will block an initiating NetKernel process until it exits.

Example

A simple native OS pipeline written as a DPML script to compress an XML literal using gzip and then gunzip to expand it again:

<idoc>
  <instr>
    <type>exec</type>
    <command>
      <!-- define command as a string -->
        data:text/plain,gzip%20--stdout</command>
    <stdin>
      <example>document</example>
    </stdin>
    <param>
      <exec>
        <mimetype>application/x-gzip</mimetype>
      </exec>
    </param>
    <target>this:response</target>
  </instr>
  <instr>
    <type>exec</type>
    <command>
      <!-- define command as an XML doc -->
      <args>
        <arg>gunzip</arg>
        <arg>--stdout</arg>
      </args>
    </command>
    <stdin>this:response</stdin>
    <param>
      <exec>
        <mimetype>text/xml</mimetype>
      </exec>
    </param>
    <target>this:response</target>
  </instr>
</idoc>