Launching Module
The Launching module starts an executable program when the module’s Launch input is pulsed. This module is only available in the VIP.
Module icon
Overview
A setup register allows you to specify the name of the program and any command line parameters you wish. The Launching module can launch as many instances of the program as computer resources will allow.
Inputs
Source 1 to Source
4
This input is used as part of the command line that runs a program. You can link it to a numeric, Boolean or text output register. This input is optional; if you leave it unlinked the module will continue to operate.
NOTE: See “Detailed Module Operation” for how the Source input is incorporated into the command line.
Enable
This input enables or disables the Launching module by setting it on or off respectively. If you disable a Launching module, pulses on the Launch inputs are ignored. Linking this input is optional; if you leave it unlinked, the module will be enabled by default.
Launch
When this input is pulsed, the Launching module launches the program specified in the RunCommand setup register. This input must be linked for the module to operate.
Setup registers
RunCommand
This register specifies the command to be launched when the Launch input is pulsed.
Launch Mode
NOTE: Although you can select interactive, it is recommended that you only use not interactive due to operating system limitations. Contact Technical Support for more information.
Output registers
Event
All events produced by a Launching module are written into this register.
Possible events and their associated priority numbers are shown in the following table:
| Event priority group | Priority | Description |
|---|---|---|
| Setup Change | 10 | Input links, setup registers or labels have changed. |
| Information | 25 | Pulse received on Launch input; program launch successful; program launch not successful. |
The Event output register stores the following information for each ION event: time stamp, priority, cause, effect, and any values or conditions associated with the cause and effect.
Responses to special conditions
The following table summarizes how the module behaves under different conditions.
| Condition | Response of output registers |
|---|---|
| If Source is not linked | The module will operate normally but, if used, the Value variable will be not available. |
| If Source is not available | The module will operate normally but the Value variable will be N/A. |
| If the Enable input is off | The module will ignore pulses on the Launch input. |
| When the Virtual Processor is started | The module will assess inputs; if there is a pulse on the Launch input, it will attempt to start the program specified in the RunCommand setup register. |
| If RunCommand has an invalid command and the Launch input is pulsed | The module will write an event indicating that the command failed to execute. |
Detailed module operation
When the Launch input is pulsed, the Launching module attempts to execute the command entered in the RunCommand setup register. For the program to successfully run, the executable file must be in the location specified, and the syntax of the command specified in the RunCommand register must be correct.
If you do not use the Source input, the command specified in the RunCommand register behaves just as if you typed it on a DOS command line. To test your RunCommand entry, open a Command prompt window, then type in the command exactly as you typed it in the RunCommand setup register.
NOTE: The Launching module can only start the program. If the program does not quit on its own, you have to do it manually.
RunCommand Syntax
If the directory in which the program resides is in your PATH variable, you can specify just the name of the program. For example:
cmd.exe
If the directory in which the program resides is not in your PATH variable, you must include the program's full path name. For example:
d:\apps\myprogram.exe
The program can be on a local drive or in a directory on another computer on the network if the directory is shared. If it is shared, you will be able to see that computer and directory in Windows Explorer. You can either map a network drive to the directory, or reference it with the computer name. For example:
f:\networkdir\myprogram.exe
or
\\COMPUTERNAME\DIR\myprogram.exe
If the program you want to launch accepts command line parameters, you can include them as part of the RunCommand text. For example, if you want to run a program and have it open a specific data file, you might type:
d:\apps\myprogram.exe
-Fdatafile.txt
Incorporating the Source Input
When entering the command line into the RunCommand setup register, you can include the Source input values. You can do this by linking the Launching module’s Source inputs (to other modules’ output registers) and incorporating the %V1, %V2, %V3 or %V4 variables in the RunCommand line. When the Launch input is pulsed, the variables will be replaced with the values contained in the registers that you linked to the Source inputs to. This way, you can include dynamic values in your command line for programs that can accept command line parameters. For example, you might link a Source input to an output register that reports the voltage on phase A and have the Launching module start a pager program that pages you and reports what the voltage is.
Value variables are identified in the command line by a % sign before the variable name (variable names are V1 to V4 — this corresponds to Source inputs #1 to #4). The following example displays the value of Source input #1 at the end of your message:
d:\commapps\page.exe 555-4712 %V1
If you fail to include the % sign before the variable name, it will not be replaced with the value on the Source input.
Following is the syntax used to display data appearing at Source inputs #1 to 4:
Source
#1:%V1
Source #2:%V2
Source #3:%V3
Source #4:%V4
If you want the actual text "%V1" to appear in the command line (rather than replaced by the value), you must insert an additional % sign in front of it. For example, to produce the following command line:
d:\commapps\page.exe 555-4712 TotalHD %Value=25
the RunCommand setup register would look like this:
d:\commapps\page.exe 555-4712 TotalHD %%Value=%V1