Calling PV-WAVE in a Statically Linked Program

PV-WAVE Foundation > Application Developer Guide > Interapplication Communication for UNIX > Calling PV-WAVE in a Statically Linked Program

Under UNIX, an application written in C or FORTRAN can be linked directly (statically) with the PV‑WAVE object libraries. The user application then passes PV‑WAVE commands to the entry points cwavec (C application) or cwavefor (FORTRAN application) in the PV‑WAVE shareable image.

cwavec: Calling PV-WAVE from a C Program

The routine cwavec, discussed in detail in this section, is the C application entry point to a PV‑WAVE shareable image.

Usage

istat = cwavec(action, numcmds, cmds)

Parameters

action—Specifies how you wish PV‑WAVE to execute. It can have one of the following values:

action=1—Run normally. You are interactively prompted for input and execution continues until you enter the end-of-file character or issue the EXIT command. At this point, cwavec returns with a value of 1. Once cwavec has been called in this mode, it should not be called again.

action=2—Execute the commands supplied by cmds array and return. The return value is the value of the !Error system variable. The cwavec routine can be called repeatedly in this mode.

action=3—It is necessary to wrap up the session by calling cwavec one last time with action=3. This performs any housekeeping required by PV‑WAVE such as closing any open files. The return value for this mode is 1. Once cwavec has been called in this mode, it should not be called again.

numcmds—The number of elements supplied in cmds. This argument is ignored if action=3 or if action=1.

cmds—An array of pointers to strings. If action=2, cmds provides an array of PV‑WAVE commands to execute. This argument is ignored if action=3 or if action=l.

Returned Value

istat—The returned value depends on the action selected.

Discussion

You can choose to communicate with PV‑WAVE in either an interactive mode or by sending an array of commands. Both of these methods automatically initialize PV‑WAVE.

The first parameter is the action parameter. The action parameter may have one of the values listed in Table 2-2: Action Parameter Values:

Action Parameter Values
Value	Meaning
1	Run PV‑WAVE interactively.
2	Execute a sequence of PV‑WAVE commands and return to the program.
3	Exit PV‑WAVE and return to the program.

The third parameter is the name of an array of pointers to strings (i.e., char**) containing the PV‑WAVE commands to be executed. The second parameter specifies the number of elements supplied in the third parameter. The second and third parameters are ignored if the value of the action parameter is 1 or 3.

The status value returned by cwavec depends on the value of the action parameter and in some cases on the value of the action performed. If the value of the action parameter is 1 or 3, cwavec will return 1 as the status. If the value of the action parameter is 2, cwavec will return the value of the PV‑WAVE system variable !Err as the status.

Accessing the Data in PV-WAVE Variables

To access data in PV‑WAVE variables, use the wavevars function, a C function that can be invoked from code linked to PV‑WAVE (either statically or dynamically).

The wavevars calling sequence is:

result = wavevars(&argc, &argv, &argp);

For detailed information about wavevars, see "Using wavevars() to Access PV-WAVE Variables".

You can also use the PV-WAVE Option Programming Interface (OPI) routines to interact with PV-WAVE variables and execute PV-WAVE commands. The OPI routines provide a powerful, handle-based mechanism to retrieve, create, modify, and query PV-WAVE variables from a C application linked with PV-WAVE. You may use all of the routines listed in Creating an OPI Option without creating a full OPI directory structure. The directory structure described in the Programmer Guide is only required if you wish your C application to be a shared object which is dynamically loaded into a PV-WAVE session.

Ending the Session with PV-WAVE

If you are in interactive mode (action=1), enter EXIT at the WAVE> prompt to return to your C application. There is no need to call cwavec with action=3 to end the session. However, if the application has accessed PV‑WAVE in non-interactive mode (action=2), the session must be terminated by a final call to cwavec with action=3.

Running PV‑WAVE from a C Program

To run PV‑WAVE from a C program you must first link the C program with PV‑WAVE. The C program may then invoke PV‑WAVE via the entry point cwavec in the PV‑WAVE shareable object. The C program must pass three parameters to the cwavec entry point. For details on linking the application to PV‑WAVE, see "How to Link Applications to PV‑WAVE".

Example 1

In non-interactive mode, valid PV‑WAVE commands are passed to cwavec as an array of strings. For example, to plot the vector [1, 2, 3, 4, 5] from a C application statically linked to PV‑WAVE, the commands would be:

char *cmds[5];

cmds[0] = "a = indgen(5) + 1";

cmds[1] = "plot, a";

action=2;

status = cwavec(action, 2, cmds);

Example 2

This example shows how to pass a five-element array to PV‑WAVE via cwavec, have PV‑WAVE perform some calculations, and produce a plot.

You can find the following listed file in:

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

#include <stdio.h>

main()

 /* Variables for array calculations

*/

int action, numcmds, istat, cwavec();

char *cmds[5];

/*

 * Access PV-WAVE in non-interactive mode

*/

action=2;

numcmds=5;

/*

 * Send the array of commands to PV‑WAVE. Define the array A

 * Perform matrix multiplication. Print contents of B

 * Display B as a surface.

 * Issue a wait command so you can view result.

 * Call cwavec.

*/

cmds[0] = "A = INDGEN(5) * 4";

cmds[1] = "B = A # A";

cmds[2] = "PRINT, B";

cmds[3] = "SURFACE, B";

cmds[4] = "WAIT, 3.0";

istat = cwavec(action, numcmds, cmds);

/*

 * Since we are done sending commands to PV-WAVE, make a final

 * call to cwavec with action=3 to wrap up the session

*/

action=3;

istat = cwavec(action, 0, cmds);

Compiling and Linking the Example Program

You can use the following commands to compile the example program and link it to PV‑WAVE on a UNIX system:

setenv arch '$WAVE_DIR/bin/arch'

cc -c example.c

make -f $WAVE_DIR/src/pub/quick.mk \
  link MAIN=example OBJ=example.o \
  TARGARCH=$arch

For more information on compiling programs and linking them using the makefile quick.mk, see "How to Link Applications to PV‑WAVE".

Example 3

In this example the C program passes commands to PV‑WAVE to be executed and then accesses the results directly from PV‑WAVE’s variable data space via the wavevars routine.

This example uses one program:

wave_from_c.c—The C function that calls PV‑WAVE and accesses PV‑WAVE variables directly.

On a UNIX system, this program is available online in the directory:

$WAVE_DIR/demo/interapp/cwave

The C program must be compiled and linked with PV‑WAVE to produce a single executable program, as explained in the next section. It is because your program is linked with PV‑WAVE as a single executable that your program can “share” PV‑WAVE variables.

Compiling and Linking the Example Program

You can use the following commands to compile the example program and link it to PV‑WAVE on a UNIX system:

setenv arch '$WAVE_DIR/bin/arch'

cc -c wave_from_c.c

make -f $WAVE_DIR/src/pub/quick.mk \
  link MAIN=wave_from_c OBJ=wave_from_c.o \
  TARGARCH=$arch

For more information on compiling programs and linking them using the makefile quick.mk, see "How to Link Applications to PV‑WAVE".

note	The link operation for this example creates a large executable, because it links in all of PV‑WAVE.

Running the Program

After the program is compiled and linked, it can be run by entering the name of the resulting executable file. For example, if the executable is called wave_from_c, enter:

wave_from_c

The output from this example is shown in Figure 2-1: Output Graphics. The first graphic produced by this example is shown on the left. The second graphic produced is on the right.

Figure 2-1: Output Graphics

cwavefor: Calling PV-WAVE from a FORTRAN Program

The cwavefor routine is the FORTRAN application entry point to a PV‑WAVE shareable image.

Usage

istat = cwavefor(action, numcmds, cmds, cmdlen)

Parameters

action—Specifies how you wish PV‑WAVE to execute. It can have one of the following values:

action=1—Run normally. You are interactively prompted for input and execution continues until you enter the end-of-file character or issue the EXIT command. At this point, cwavefor returns with a value of 1. Once
cwavefor has been called in this mode, it should not be called again.

action=2—Execute the commands supplied by cmds array and return. The return value is the value of the !Error system variable. The cwavefor routine can be called repeatedly in this mode.

action=3—It is necessary to wrap up the session by calling cwavefor one last time with action=3. This performs any housekeeping required by PV‑WAVE such as closing any open files. The return value for this mode is 1. Once cwavefor has been called in this mode, it should not be called again.

numcmds—The number of elements supplied in cmds. This argument is ignored if action=3 or if action=1.

cmds—An array of strings. If action=2, cmds provides an array of PV‑WAVE commands to execute. This argument is ignored if action=3 or if action=l.

cmdlen—The declared length of each string element in the two-dimensional array.

Returned Value

istat—The returned value depends on the action selected, as explained previously.

Discussion

You can choose to communicate with PV‑WAVE in either an interactive mode or by sending an array of commands. These methods automatically initialize PV‑WAVE.

The first parameter is the action parameter. The action parameter may have one of the values shown in Table 2-2: Action Parameter Values.

The third parameter is the name of an array of strings containing the PV‑WAVE commands to be executed. The second parameter specifies the number of elements supplied in the third parameter. The second and third parameters are ignored if the value of the action parameter is 1 or 3.

The status value returned by cwavefor depends on the value of the action parameter and in some cases on the value of the action performed. If the value of the action parameter is 1 or 3, cwavefor will return 1 as the status. If the value of the action parameter is 2, cwavefor will return the value of the PV‑WAVE system variable !Error as the status.

Ending the Session with PV‑WAVE

If you are in interactive mode (action=1), enter EXIT at the WAVE> prompt to return to your FORTRAN application. There is no need to call cwavefor with action=3 to end the session. However, if the application has accessed PV‑WAVE in non-interactive mode (action=2), the session must be terminated by a final call to cwavefor with action=3.

Running PV‑WAVE from a FORTRAN Program

To run PV‑WAVE from a FORTRAN program you must first link the FORTRAN program with PV‑WAVE. The FORTRAN program can then invoke PV‑WAVE via the entry point cwavefor in the PV‑WAVE shareable object. The FORTRAN program must pass four parameters to the cwavefor entry point. For details on linking the application to PV‑WAVE, see "How to Link Applications to PV‑WAVE".

Example 1

In non-interactive mode, valid PV‑WAVE commands are passed to cwavefor as an array of strings. For example, to plot the vector [1, 2, 3, 4, 5] from a FORTRAN application statically linked to PV‑WAVE, the commands would be:

character *50 cmds(5)

cmds(1) = 'a = INDGEN(5) + 1'

cmds(2) = 'plot, a'

action=2

call cwavefor(action, 2, cmds, 50)

Example 2

This example shows how to pass a five-element array to PV‑WAVE via
cwavefor, have PV‑WAVE perform some calculations, and produce a plot. You can find the following listed file in:

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

PROGRAM EXAMPLE_175

C Variables for array calculations

integer*4  action, numcmds, istat, cwavefor

character *30 cmds(5)

C In order to initialize stdin and stdout

C correctly so that output goes to your

C terminal, make the following call:

C Access PV‑WAVE in non-interactive mode

action=2

numcmds = 5

C Send the array of commands to PV-WAVE

C Define the array A

C Perform matrix multiplication

C Print contents of B

C Display B as a surface

C Issue a wait command so user can view result

C Call cwavefor

cmds(1) = 'A = INDGEN(5) *4'

cmds(2) = 'B = A # A'

cmds(3) = 'PRINT, B'

cmds(4) = 'SURFACE, B'

cmds(5) = 'WAIT, 3.0'

istat = cwavefor(action, numcmds, cmds, 30)

C Since we are done sending commands to

C PV-WAVE, make a final call to cwavec

C with action=3 to wrap up the session.

action=3

istat = cwavefor(action, 0, cmds, 30)

stop

end

Compiling and Linking the Example Program

You can use the following commands to compile the example program and link it to PV‑WAVE on a UNIX system:

setenv arch '$WAVE_DIR/bin/arch'

f77 -c examplefor.f

make -f $WAVE_DIR/src/pub/quick.mk \
flink MAIN=examplefor OBJ=examplefor.o \
TARGARCH=$arch

For more information on compiling programs and linking them using the makefile quick.mk, see "How to Link Applications to PV‑WAVE".

Example 3

In this example, the FORTRAN program passes commands to PV‑WAVE to be executed and then accesses the results directly (via a C wrapper) from PV‑WAVE’s variable data space using the C function wavevars.

This example uses two functions:

wave_from_fort.f—The FORTRAN function that calls PV‑WAVE and accesses PV‑WAVE variables directly.

wavevars_fl.c—A C function (wrapper) that allows the FORTRAN program to retrieve and/or modify the values of floating-point arrays in PV‑WAVE’s variable data space. This is accomplished via the wavevars function, which interacts directly with PV‑WAVE’s variable data space. (Direct interaction between a FORTRAN program and wavevars does not work because FORTRAN lacks the C language’s ability to access a common data area by address.)

On a UNIX system, the C and FORTRAN code described in this example is available online in the directory:

$WAVE_DIR/demo/interapp/cwave

The FORTRAN program must be compiled and linked with PV‑WAVE and the C wrapper routine to produce a single executable program, as explained in the next section. It is because your program is linked with PV‑WAVE as a single executable that your program can “share” PV‑WAVE variables.

Compiling and Linking the Example Program

You can use the following commands to compile the example program and link it to PV‑WAVE on a UNIX system:

setenv arch '$WAVE_DIR/bin/arch'

f77 -c wave_from_fort.f

cc -c wavevars_fl.c

make -f $WAVE_DIR/src/pub/quick.mk \
  flink MAIN=wave_from_fort \
  OBJ="wave_from_fort.o wavevars_fl.o" \
  TARGARCH=$arch

For more information on compiling programs and linking them using the makefile quick.mk, see "How to Link Applications to PV‑WAVE".

note	The link operation for this example creates a large executable, because it links in all of PV‑WAVE.

Running the Program

After the program is compiled and linked, it can be run by entering the name of the resulting executable file. For example if the executable is called wave_from_fort, enter:

wave_from_fort

The output from this example is shown in Figure 2-1: Output Graphics.

How to Link Applications to PV‑WAVE

This section explains how to link C and FORTRAN applications to PV‑WAVE on a UNIX workstation.

Using the quick.mk Makefile on a UNIX System

The makefile quick.mk is provided in the <RW_DIR>/src/pub directory and is the preferred method for linking compiled C and FORTRAN objects with PV-WAVE.

For example, to link a compiled program called mywavec to PV‑WAVE, use the following commands from a C shell:

setenv arch `$WAVE_DIR/bin/arch`

make -f $WAVE_DIR/src/pub/quick.mk \ 
  link MAIN=mycwavec OBJ=mycwavec.o \ 
  TARGARCH=$arch

Note the backquotes must be entered exactly as shown.

The quick.mk file contains the generic, architecture-neutral rules for linking with PV-WAVE. Architecture-specific settings, such as compiler paths and flags, linker paths and flags, and required system libraries and directories are specified for each platform in the file <RW_DIR>/src/$arch.mkcfg. You need to edit the file corresponding to your target architecture to match your system before calling quick.mk.

Examples of using quick.mk to link sample C and FORTRAN applications with PV-WAVE are found in the build script located in the <RW_DIR>/demo/interapp/cwave directory.