Run Program Module

This module will run the specified program. Result Variables can be used when specifying the program's name and the parameters passed to the program.

Run Program Tab

The Program name and parameters passed to the program are specified here.

Play Tab

If "Wait Until Program Finishes" option is selected, the sound file specified in the Play tab will be played while the started program is executing. The playing of the sound file will be stopped as soon as the the program finishes.

Paths Tab

After reading in the result file, VoiceGuide will rename the file by adding a ".last" to the filename.

Timeout Paths

When used in Run Program module, a Timeout Path can be used to limit the maximum amount of time the module will wait for the called program to finish (when "Wait until program finishes" option is selected). When the timeout is reached the module will close the program it has called, and go the module specified in the Timeout Path. 

Returning data from ran program back to VoiceGuide

There are two ways in which the ran program can return data back to VoiceGuide:

• Calling VoiceGuide's COM/WCF functions. eg: Run_ResultReturn

or:

• Creating a 'Result File' which is then read in by VoiceGuide.

Result Files

If "Wait Until Program Finishes" option is selected, then VoiceGuide will wait until the program completes and afterwards VoiceGuide will look for the result file which can be optionally created by the called program. The file can be created in the script's directory, or in the directory where the program was ran from, or in VoiceGuide's \data\ subdirectory.
The file must be named VGRUNRESULT_LineNumber.TXT

The LineNumber is the ID of the line which is executing the Run Program module, and it can be passed to your program using the $RV_LINEID Result Variable.

The result file can be used to return results back to VoiceGuide. This file should contain the list of the Result Variables that you want VoiceGuide to read in, along with their values.

The syntax for the VGRUNRESULT_LineNumber.TXT file is: 

[Result Variable Name]{Result Variable Value}

Multiple Result Variables can be specified. For Example, the following contents:

[RvName1]{Value1}[RvName2]{Value2}[RvName3]{Value3}[RvName4]{Value4}

Would return 4 Result Variables to VoiceGuide, whose values would be whatever is contained in the curly brackets. All Result Variables must be listed on a single line.

Task Start Modes

VoiceGuide can start the program as a Simple Process, or run it as a Logged In User, or use the Shell to run it.

The default option is set in VG.INI, section [moduleRunProgram], entry: StartTask_Mode

Mode preference can also set during the call by setting this Result Variable: $RV[ini_moduleRunProgram_StartTask_Mode]

Allowed settings are:

simple
logged_in_user
shell
cmd

Example 1:

A custom written utility ReadData.exe to retrieve information about a product has been written and the system has a Get Number Sequence module called Get Data Type which is used to ask caller to select what data is to be retrieved. The ReadData.exe is then called with the information entered in Get Data Type passed as a parameter.

Result File is then be used to return the retrieved data. ReadData.exe writes the following data into the file:

The above will create 3 new Result Variables in VoiceGuide, which can be accessed using:

$RV[Product_Price]
$RV[Product_InStock]
$RV[Product_OnOrder]

whose values are:

1495
7
50

respectively. These Result Variables can then be used is Say Numbers modules to speak out this information to the caller.

Example 2:

The Run Program module can be used to write out data that the caller has entered into a file. The command below will write out the 3 pieces of data gathered in Get Number Sequence modules out into the file output.txt:

command.com /c echo $RV[GetUserId], $RV[GetProductID], $RV[GetOrderAmount] >> c:\output.txt

Use ">" instead of ">>" if you would like to overwrite the output.txt file instead of appending to it.

Always specify the full path of the file to which the output is echoed - if you do not specify the full path sometimes the output file will not be in the scripts' directory.

Note: If writing to same log file from subsequent modules in same script or from multiple lines then it's preferable to use the Run VB Script module to write log files, as the DOS echo command does not handle concurrent writing to the same file well.

Example 3:

Sound Recorder application specifying that it should play the specified sound file and then close afterwards using this command line:

sndrec32 /play /close c:\test.wav

The Media Player application can also be used for this purpose:

mplayer /play /close c:\test.wav

If you are finding that the program does not run as VoiceGuide cannot find it then try specifying the full path to where your program is on your system. For example, the Media Player program on some systems is actually in:

C:\Program Files\Windows Media Player\mplayer2.exe

which would make the actual command line required to be used in the Run Module:

C:\Program Files\Windows Media Player\mplayer2.exe /play /close c:\test.wav 

Example 4:

Send a message to another computer, alerting a particular user of an event. eg. when the caller on the VoiceGuide system is about to be transferred to their extension.

net send someusername "VG call from $RV_CIDNUMBER" 

Example 5:

Running batch files (.bat) : To run a batch file from a Run Program module it is best to create a shortcut (a link) to the batch file and run the shortcut itself. You may need to use the actual name of the file as shown when doing a DIR listing in the DOS Command Prompt window.