ExternalComm launcher

This article explains how to launch an external application in the ExternalComm module.

Overview

The launcher optional property for the ExternalComm module allows to specify the path to an external executable to launch and its launch arguments. The property specifies an XML file which defines:

• The executable path
• The specification of the arguments to use to launch the executable
• Optionally, the specification of environment variables to use when launching the application

For example:

      <properties>
         <application name="externalComm" >
            <module name="externalComm" >
               <moduleProperty key="network" value="network.xml" />      
               <moduleProperty key="endianness" value="littleEndian" />		
               <moduleProperty key="charAs8Bits" value="true" />		
      <moduleProperty key="launcher" value="launcher.xml" />			 
            </module>
         </application>
      </properties>

Launcher configuration

The launcher.xsd describes the grammar of the launcherXMl file:

• The top level element is a launcher element
• It has a an executable or shell child representing the executable to start

The executable or shell element has the following attributes:

• path (the only mandatory attribute): the path of the executable to start
• redirectIO: true if the IO of the process must be redirected to the Framework logger (will be false by default)
• wait: the time to wait before starting communcating with the process after starting it (no wait by default)
• processDir: the working directory for the process (by default the working directory of the framework JVM process will be used)
• useGlobalEnvVariables: true if the environment variables defined for the framework should be used. See also environment variables declarations for the specification of environment variables for the framework

Launcher arguments

Arguments can be specified for the executable or shell element. The element can have several of the following children elements:

• argument for an argument value
• env for an environment variable value
• propertyArgument for an argument whose value is one property value for the ExternalComm module
• portArgument for an argument whose value is a port for the External Communication network property
• hostArgument for an argument whose value is a host for the External Communication network property

Each the arguments will have the following pattern when starting the application: <name>=<value>

argument element

The argument element specifies the value for an argument and has two attributes:

• key specifies the argument name
• value specifies the argument value

For example:

      <launcher>
         <executable path="PublishAppli.exe">
            <argument key="prop" value="20" />
         </executable/> 
      </launcher>

will start the executable with:

      PublishAppli.exe prop=20

env element

The env element specifies the value for an argument whose value is coming from an environment variable, and has two attributes:

• key specifies the environment variable name
• value specifies the environment variable value

For example:

      <launcher>
         <executable path="PublishAppli.exe">
            <env key="PROP" value="20" />
         </executable/> 
      </launcher>

will start the executable with something having the same result as:

      set PROP=20
      PublishAppli.exe

propertyArgument element

The propertyArgument element specifies the value for an argument whose value is coming from one of the module properties, and has two attributes:

• key specifies the argument name
• property specifies the property name

For example suppose that we have the following properties declaration for the ExternalComm module:

      <properties>
         <application name="externalComm" >
            <module name="externalComm" >
               <moduleProperty key="network" value="network.xml" />      	
               <moduleProperty key="launcher" value="launcher.xml" />		
               <moduleProperty key="theProp" value="20" />		 
            </module>
         </application>
      </properties>

And the launcher declaration:

      <launcher>
         <executable path="PublishAppli.exe">
            <propertyArgument key="prop" property="theProp" />
         </executable/> 
      </launcher>

will start the executable with:

      PublishAppli.exe prop=20

portArgument element

The portArgument specifies the value for an argument whose value is coming from the port of one of the network property channels:

• key specifies the argument name
• channel specifies the channel name

For example suppose that we have the following Network specification for the ExternalComm module:

      <network>
         <channel name="event" type="input" port="8080" >
            <service name="published" />
         </channel>
      </network>

And the launcher declaration:

      <launcher>
         <executable path="PublishAppli.exe">
            <portArgument key="prop" channel="event" />
         </executable/> 
      </launcher>

will start the executable with:

      PublishAppli.exe prop=8080

hostArgument element

The hostArgument specifies the value for an argument whose value is coming from the host of one of the network property channels:

• key specifies the argument name
• channel specifies the channel name

For example suppose that we have the following Network specification for the ExternalComm module:

      <network>
         <channel name="event" type="input" port="8080" host="127.0.0.1" >
            <service name="published" />
         </channel>
      </network>

And the launcher declaration:

      <launcher>
         <executable path="PublishAppli.exe">
            <hostArgument key="prop" channel="event" />
         </executable/> 
      </launcher>

will start the executable with:

      PublishAppli.exe prop=127.0.0.1

Example

Suppose that we want to implement the publishAppli of the first tutorial in CSharp. We will have the following architecture:

Properties configuration

The properties configuration will be:

      <properties>
         <application name="externalComm" >
            <module name="externalComm" >
               <moduleProperty key="network" value="network.xml" />      
               <moduleProperty key="endianness" value="littleEndian" />		
               <moduleProperty key="charAs8Bits" value="true" />		
               <moduleProperty key="launcher" value="launcher.xml" />			 
            </module>
         </application>
      </properties>

Launcher configuration

The launcher configuration will be:

      <launcher>
         <executable path="PublishAppli.exe" redirectIO="true" wait="500ms"/> 
      </launcher>