Running an external application from caravan.
============================================

Capabilities of caravan can be enhanced by taking help of external
applications. For example in a wide area network, where  caravan can be used
to create a workflow application with file transfer, it is desirable to
compress the files at source and expand them automatically at destination.
In such situations where you need to do complex processng of data, you can
always find an external utility to do this. Caravan makes it possible to
incorporate these expert capabilities in your application.


Setting up Caravan for running external applications.
====================================================

Among the directories which you can setup through the settings menu, you
will find an entry for "Binary executables:". This is where your helper
applications should be located. Once you set up this folder, just copy
your helper applications here. These are command line utilities like
pkzip, arj etc. which you can run from a console. Also you should
know the command line parameters for these applications.


Using an helper application in caravan script:
===========================================
The syntax for executing a progarm inside caravan script is:

cmd <objname>=<program-name>([parameters]);

An object of name <objname> is created, whose properties indicate the
success or failure of executtion

success: Indicates if program could be executed or not.1 indicattes success.
rc: The return code from program .
output:The console output from program.


example:
<caravan>
cmd x=prg.exe() ;// no parameters
ouput con
if x(success)="1"
 "program was executed successfully\n"
 "return code=";x(rc);"\r\n"
 "program output:\n";x(output);"\r\n"
else
 "error: could not execute\r\n" 
endif
</caravan>


Passing paramenters to the program.

The best way to pass parameters is through var object. Note that this
makes use of the multiple values a property can have in caravan objects.


<caravan>
var pars
pars(val)="myfiles.zip"
pars(val)="newfile"
pars(val)="/add"
cmd x=pkzip.exe(pars(val));// adds "newfile" to pkzip archive "myfiles.zip"
if x(success)<>"1"
"error : could not execute pkzip\n"
endif
</caravan>

One can also pass the parameters in a constant string. But creating the
parameter string dynamically is also possible.

example:
pars(val)="myfiles.zip /add newfile"
cmd x=pkzip.exe(pars(val));
cmd x=pkzip.exe("myfiles.zip /add newfile");
or
cmd x=pkzip.exe("\"myfiles.zip\" \"/add\" \"newfile\"");

Important : Note that the "output" is whatever the program prints on console(stdout/stderr).