WARNING: This server provides a static reference view of the NetKernel documentation. Links to dynamic content do not work. For the best experience we recommend you install NetKernel and view the documentation in the live system .

Endpoint
Name:Exec Accessor
Description:Executes native operating system processes
Id:layer1.ExecProcess
Category:accessor
Identifier Syntax

Exec Accessor is an accessor using Active URI syntax with the following base identifiers:

Base
active:exec
active:exec-stderr

and the following arguments: (for more details on argument passing details see here)

ArgumentRulesTypingDescription
command
Mandatory
Representation (Determinate String Array)Command line to execute.
stdin
Optional
Representation (Binary Stream)Input to stream into command.
stderr
Optional
Defaults to "active:exec-stderr"
IdentifierService to handle error response.
param
Optional
Representation (HDS)additional parameters to control the process.
wd
Optional
IdentifierThe file: URI of the current working directory to use for the process.
Request Verbs

The following verb is supported:

Verb
SOURCE
Response

The following response representations can be returned for SOURCE requests:

SOURCE Representations
Binary Stream

This accessor throws no documented exceptions.

Import Requirements

To use Exec Accessor accessor you must import the module urn:com:1060research:www3:

<import>
  <uri>urn:com:1060research:www3</uri>
</import>

The Exec accessor invokes a host operating system native process and returns its stdout as the response.

command

The command argument is the command line to be executed by the native operating system.

Internally the command is used as a Determinate String Array but if a regular String argument is provided it will be transrepted to this array by splitting the string at whitespace boundaries.

The most convenient way to create an unambiguous list of arguments is to use a String[] like so...

String[] commandline=new String[]{"unzip", "-j", "-o", "-d","modules/*.jar"};
req=context.createRequest("active:exec");
req.addArgumentByValue("command", commandline); 
response=context.issueRequest(req);

stdin

The resource specified by stdin will be requested as a BinaryStreamRepresentation and passed into the executed processes stdin.

stderr

The stderr argument should be the base of an active URI of a service to receive stderr as a BinaryStreamRepresentation. It must have the following grammar:

<grammar>
  <active>
    <identifier>[same as the argument value you supplied eg active:stderrHandler]</identifier>
    <argument name="command" />
    <argument name="stderr" />
  </active>
</grammar>

For example here the stderr argument is given as "active:stderrHandler"

String[] commandline=new String[]{"unzip", "-j", "-o", "-d","modules/*.jar"};
req=context.createRequest("active:exec");
req.addArgumentByValue("command", commandline);
req.addArgument("stderr", "active:stderrHandler"); 
response=context.issueRequest(req);

The following mapping for "active:stderrHandler" would lead to the stderr being directed to the groovy script stderr.gy with the arguments command and stderr

<endpoint>
  <grammar>
    <active>
      <identifier>active:stderrHandler</identifier>
      <argument name="command" />
      <argument name="stderr" />
    </active>
  </grammar>
  <request>
    <identifier>active:groovy</identifier>
    <argument name="operator">res:/resources/stderr.gy</argument>
    <argument name="command">arg:command</argument>
    <argument name="stderr">arg:stderr</argument>
  </request>
</endpoint>

The error handler must complete before the main response of the stdout is returned by the exec accessor.

wd

This may be a file: URI specifying a directory to set as the current working directory for the process. If not set the current working directory of the JVM executing NetKernel is used.

param

The param argument may be used to specify additional control over the process - it has the following form...

<param>
  <ignoreReturnCode />
  <ignoreStderr />
  <mimetype>....</mimetype>
</param>

Where each element is optional and if specified has the following effect:

ignoreReturnCode - if a non-zero return code is returned from the process then the exec accessor will return as normal. By default a non-zero return code results in an Exception being thrown from the active:exec invocation.

ignoreStderr - ignore any stderr that the process may produce.

mimetype - specify the mimetype to use for the response.