VoiceGuide Online Help - Script Module : Run Program

Run Program

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.

If the 'wait' option is selected then VoiceGuide will pause 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 can either be called VGRUNRESULT_LineNumber.TXT or SHLRESLT.TXT

If using multiple lines on your system you should adopt the first naming scheme - 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. This will prevent problems when more then one line tries to execute a Run program module at the same time.

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.

The syntax for the SHLRESLT.TXT file is:

SUCCESS|FAIL
Result Variable

Only one Result Variable can be specified.

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

Wait until program finishes	If the result file contains some data, then the "Success" path is taken. If the result file is empty then the "Fail" path is taken. If the program could not be started then the "Fail' path is taken.
Don't Wait	If the program was started successfully then the "Success" path is taken. If the program could not be started then the "Fail' path is taken.

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.

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.

SHLRESLT.TXT 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.

Windows NT/2000/XP : Can use the NET SEND command (type "net help send" for full command syntax) :

net send someusername "VG call from $RV_CIDNUMBER"

Windows 95/98/ME : need to use a 3rd party message product like Vypress Messenger or RealPopup.

Example 5:

Running batch files (.bat) directly from the Run Program module does not work on some systems. (A combination of PATH and other system settings is the cause).

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.

Example 6 (using old result file format) :

Here is an example of the command line which can be specified in the Run Program module:

C:\MyProgram.exe $RV[Get UserID] $RV[Get CC]

You can still use the v2.9 way of returning results to VoiceGuide. Two examples of the contents of the result file which is expected by VoiceGuide are shown below:

SUCCESS
25

FAIL
2

The second line in the result file will become the value for this module's Result Variable, and the Success or Fail will determine if the Success or Fail path is taken - if none of the Paths match the Result Variable value. The following rules are used when using the old style result files:

if any of the paths match the result exactly then that path will be taken.
If none of the Paths match the Result Variables value exactly, but the Result Variable is non-empty then the "Success" path will be taken.
If the Result Variable is empty, then the "Fail" path will be taken.

Example 7:

Concatenation of sound files can be done using the "shntool" utility.
Eg: to concatenate wav files 1.wav, 2.wav and 3.wav into one file 1_2_3.wav you would run the following command from a "Run Program" module:

command /c shntool join -stdout 1.wav 2.wav 3.wav > 1_2_3.wav

shntool can be obtained from:

http://www.etree.org/shnutils/shntool/
http://shnutils.freeshell.org/shntool/

Example 8:

The Run Program module can be used to run a VB Script or a Java Script in the Windows Script Host, by calling the csript.exe and wscript.exe script interpreters, with the filename of the script to run as an argument. For more information on Windows Scripting Host see:

http://msdn.microsoft.com/scripting/