HELP
An object that spawns a child process, either
directly or through a command shell.

USE
Use Execute Program to communicate with
programs external to HP VEE.  Communication
to the external program is handled through
the operating system mechanism of stdin and
stdout.

Use Execute Program to run any executable
user written program or operating system
commands.

In general, you need to add or modify
transactions to accomplish useful results.
To add a transaction, select Add Trans in the
object menu.  To edit a transaction,
double-click on the transaction and complete
the resulting dialog box.

LOCATION
I/O ==> Execute Program

OBJECT MENU

* Config - Allows you to view and edit the
formatting configuration for data transmitted
to and from the spawned process.

* Add Trans - Adds a transaction to the end
of the list.

* Insert Trans - Inserts a transaction before
the currently highlighted transaction.

* Cut Trans - Cuts (deletes) the currently
highlighted transaction, but saves it in the
transaction "cut-and-paste" buffer.

* Copy Trans - Copies the currently
highlighted transaction to the transaction
"cut-and-paste" buffer.

* Paste Trans - Pastes a transaction,
previously "cut" or "copied" to the buffer,
in the position before the currently
highlighted transaction.

OPEN VIEW PARAMETERS

* Shell - The operating system shell to
communicate with.  If the Shell field is set
to none, the first token in the Pgm with
params field is assumed to be the name of an
executable file.  Each token after the first
is assumed to be a command-line parameter.
The executable is spawned directly as a child
process of HP VEE.  All other things being
equal, Execute Program operates fastest when
Shell is set to none.

If the Shell field specifies a shell, HP
VEE spawns a process corresponding to the
specified shell.  The string contained in the
Pgm with params field is passed to the
specified shell for interpretation.
Generally, the shell spawns additional
processes.

* Wait for child exit - If Wait for child
exit is set to Yes, HP VEE performs the
following tasks:

1.  Spawns a child process.

2.  Executes all transactions specified in
the Execute Program object.

3.  Closes all pipes to the child process
(thus sending an EOF to the child).

4.  Waits until the child process
terminates before activating the sequence
output pin of the Execute Program object.

If Wait for child exit is set to No, HP
VEE performs the following tasks:

1.  Checks to see if a child process
corresponding to the Execute Program object
is active.  If one is not already active, HP
VEE spawns one.

2.  Executes all transactions specified in
the Execute Program object.

3.  Activates the sequence output pin of
the Execute Program object.  The child
process remains active and the corresponding
pipes still exist.

All other things being equal, Execute
Program operates fastest when Wait for child
exit is set to No.

* Pgm with params - The program you want to
run.

Here are examples of what you typically
type into the Pgm with params field:

To run a custom C program (Shell field set
to none):

MyProg -optiona -optionb

To run a shell command (Shell set to ksh):

ls -t *.dat

To run a program using one of the shell
dependent features, you could set Shell to sh
and enter the command into the Shell command:
line:
MyProg *.dat

This forces the shell to pass as command
line parameters all the files that end in
".dat".

A maximum of 256 parameters may be passed.

NOTES
If you use shell-dependent features in the
Pgm with params field, you must set a shell
in the Shell field to achieve the desired
result.  Common shell-dependent features are:
* Standard input/output redirection (< and
>).
* File name expansion using wildcards (*, ?,
and [a-z]).
* Pipes (|).

When sending input to a shell command such
as sort or wc, you must include an EXECUTE
CLOSE WRITE PIPE transaction after the data
has been written to the command.  Closing the
write pipe will let the command know that it
has received all of the data to process.

When reading an arbitrary amount of data
back from a shell command such
as ls or grep, use a READ ...  ARRAY 1D TO
END:  (*) transaction.  It will continue to
read data until the pipe reading data from
the shell is closed.

EXAMPLE
Here is a simple C program to read a number
from stdin, add one to it, and send it back
to HP VEE by way of stdout.  The stdout
buffering must be turned off.  This is done
in one of two ways.  The first way is with
the "setbuf(stdout,NULL)" statement, which
turns buffering off.  The second technique is
to leave the stdout buffering on, then use
the "fflush(stdout)", command to flush the
output buffer back to HP VEE.
<ex smaller>
#include <stdio.h>
main ()
{
     int c; double val; setbuf(stdout,NULL);
     /* turn stdout buffering off */ while
     (((c=scanf("%lf",&&val)) !=EOF) && c >
     0) {
       /* read a value */
       fprintf(stdout,"%g\n",val+1;
       /* add one to the input value */
       fflush(stdout);
       /* force output back to main pgm */ }
     exit(0); }

SHORT CUTS

You can quickly add a data terminal by
placing the cursor over the input or output
terminal display area and then pressing
[CTRL-A].  Each press of [CTRL-A] adds an
additional data terminal.

You can quickly delete a data terminal by
placing the cursor over the terminal view
area and then pressing [CTRL-D].

To quickly insert a transaction, place the
cursor on a transaction.  Press [CTRL-O] to
insert a transaction over the transaction
where you placed the cursor.

To quickly delete ("kill") a transaction,
place the cursor on that transaction and
press [CTRL-K].

To paste a transaction from the "kill"
buffer press [CTRL-Y].

To quickly move to the next or previous
transaction, press [CTRL-N] or [[CTRL-P]]
respectively.

SEE ALSO
HP BASIC/UX, From StdIn, To/From Named Pipes,
and To StdOut.

"Using Transaction I/O" in Using HP VEE,
chapter 12.
