Executing PV‑WAVE Commands Externally

PV-WAVE Foundation > Application Developer Guide > Interapplication Communication for UNIX > Executing PV‑WAVE Commands Externally

The routines waveinit, wavecmd, and waveterm let you start, run, and exit PV‑WAVE from an external program, such as a C or FORTRAN program. The first routine, waveinit, starts PV‑WAVE.; wavecmd sends commands to PV‑WAVE; and waveterm ends the PV‑WAVE session.

note

Keep the following in mind when reviewing this section:

The commands described in this section are only available for PV‑WAVE running on UNIX systems.

The commands described in this section cannot be used with PV‑WAVE in runtime mode.

These routines allow one-way (unidirectional) communication only. That is, PV‑WAVE cannot pass data back to the calling program. If you require data to be passed back to the calling program (bidirectional transfer), then choose another method of interapplication communication.

Compiling the External Program

After these routines have been incorporated into an external program, the program must be compiled with the correct object module. The object module is named callwave.o, and its full pathname is the following, where arch is the machine architecture, such as hps700 or linux64:

$WAVE_DIR/bin/bin.arch/callwave.o

If you are unsure about the architecture, you can get the information by typing the following command:

$WAVE_DIR/bin/arch

Once you know the architecture, you can compile your program. For example, if you were on a Linux64, you would type one of the following commands:

cc -o myprog myprog.c $WAVE_DIR/bin/bin.linux64/callwave.o

or:

f77 -o myprog myprog.f $WAVE_DIR/bin/bin.linux64/callwave.o

note	Compile and link options vary by platform, and are sometimes site specific. Refer to the man page for your compiler for more detailed information on how to compile programs on your system.

Starting PV‑WAVE from External Program with waveinit

The initialization routine waveinit starts PV‑WAVE. The routine first checks the environment variable WAVE_DIR. If WAVE_DIR is defined, the routine uses the path $WAVE_DIR/bin/wave to start PV‑WAVE. When WAVE_DIR is not defined, the routine uses the path /usr/local/bin/wave. The last part of the path (wave) may be set to a symbolic link. When this path (/usr/local/bin/wave) is used, the path /usr/local/lib/wave must also be a valid path. The last part of this path may be set to a symbolic link that points to the main PV‑WAVE directory.

The waveinit function has one output parameter, the name of a file to contain the PV‑WAVE alphanumeric output (not the graphics output). For example, you can specify a character string denoting the filename or you can specify a null string, denoting that no alphanumeric output should be produced. Suppose you have a C program and you do not want to save the output, you can use:

waveinit("");

To write the alphanumeric output to a file (e.g., wave.out), use the following:

waveinit("wave.out");

To do the same thing from a FORTRAN program, you would use the following two commands:

CALL WAVEINIT('');

or:

CALL WAVEINIT('wave.out');

Sending Commands to PV‑WAVE with wavecmd

To send commands to PV‑WAVE, you must use the wavecmd routine. The routine’s single parameter is the string you want to send to PV‑WAVE. For example, to plot a vector [1,2,3,4,5] from a C program you would use:

wavecmd("plot, [1,2,3,4,5]");

From a FORTRAN program:

CALL WAVECMD('PLOT, [1,2,3,4,5]')

The wavecmd routine can be called as many times as required.

Ending the Session with PV‑WAVE with waveterm

When you are finished sending commands to PV‑WAVE, you must call the routine waveterm. This routine terminates the session with PV‑WAVE and closes the necessary files. In a C program, type:

waveterm();

and in a FORTRAN program type:

CALL WAVETERM();

Example: Calling PV-WAVE from a C Program

The following C code sample shows how to pass a 5-element array to PV‑WAVE, have PV‑WAVE perform some calculations, and produce a surface plot.

You can find the following listed file in:

$WAVE_DIR/demo/interapp/wavecmd/example.c

#include <stdio.h>

#include <string.h>

#define MAXSIZE 128

main()

/*

 * Variables for array passing

*/

char buf[MAXSIZE];

char temp[MAXSIZE];

/*

 * Variables for calculations

*/

int i,x[5];

/*

 *Perform some calculations

*/

for (i=0; i< 5; i++) x[i] = i * 4;

/*

 * Start PV‑WAVE sending the alphanumeric

 * output to 'wave.save'.

*/

waveinit("wave.save");

/*

 * Send the commands to PV-WAVE. First, we

 * need to send the array to PV-WAVE.

*/

sprintf(buf,"a=[%d", x[0]);

for (i=1; i< 5; i++) {
sprintf(temp,",%d", x[i]);
strcat(buf, temp);

strcat(buf, "]");

wavecmd(buf);

/*

 * Next, we perform a matrix multiplication.

 * Then we print the newly formed

 * two-dimensional array, as well as display

 * it as a surface.

*/

wavecmd("b = a # a");

wavecmd("print, b");

wavecmd("surface, b");

/*

 * The following WAIT is needed so that the

 * surface will not be deleted as soon as it

 * has been drawn.

*/

wavecmd("wait, 3.0");

/*

 * Since we are done sending commands to

 * PV-WAVE, we must call waveterm.

*/

waveterm();

Example: Calling PV‑WAVE from a FORTRAN Program

The following FORTRAN code fragment shows how you can use PV‑WAVE to manipulate and plot data.

You can find the following listed file in:

$WAVE_DIR/demo/interapp/wavecmd/examplefor.f

PROGRAM TEST

C Start PV-WAVE and send the alphanumeric

C output to 'wavefor.save'.

CALL WAVEINIT('wavefor.save')

C Send my commands to PV-WAVE. First, we

C define a 5-element array. Next, we perform

C a matrix multiplication. Then we print the

C newly formed two-dimensional array and

C display it as a surface.

CALL WAVECMD('A =[110,90,27,48,60]')

CALL WAVECMD('B =A # A')

CALL WAVECMD('PRINT, B')

CALL WAVECMD('SURFACE, B')

C The following WAIT is needed so that the

C surface will not be deleted as soon as it

C has been drawn.

CALL WAVECMD('WAIT, 3.0')

C Since we are done sending commands to

C PV-WAVE, we must call waveterm.

CALL WAVETERM()

END