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:
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//cwavec/cwavec.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);
}
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:
cwavec_wavevars.c—The C function that calls PV‑WAVE and accesses PV‑WAVE variables directly.This program is available online in the directory:
$WAVE_DIR/demo/interapp/cwavec_wavevars
The C program must be compiled and linked with PV‑WAVE to produce a single executable program, as explained in the README.md. It is because your program is linked with PV‑WAVE as a single executable that your program can “share” PV‑WAVE variables.
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 cwavec_wavevars, enter:
cwavec_wavevars
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.
 |
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:
cwavefor, have PV‑WAVE perform some calculations, and produce a plot. You can find the following listed file in:
$WAVE_DIR/demo/interapp/cwavefor/cwavefor.f
PROGRAM EXAMPLE_175
C
C Variables for array calculations
C
integer*4 action, numcmds, istat, cwavefor
character *30 cmds(5)
C
C In order to initialize stdin and stdout
C correctly so that output goes to your
C terminal, make the following call:
C
C Access PV‑WAVE in non-interactive mode
C
action=2
numcmds = 5
C
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
C
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
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.
C
action=3
istat = cwavefor(action, 0, cmds, 30)
stop
end
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:
cwavefor_wavevars.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.)The C and FORTRAN code described in this example is available online in the directory:
$WAVE_DIR/demo/interapp/cwavefor_wavevars
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 README.md. It is because your program is linked with PV‑WAVE as a single executable that your program can “share” PV‑WAVE variables.
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 cwavefor_wavevars, enter:
cwavefor_wavevars
The output from this example is shown in Figure 2-1: Output Graphics.
How to Link Applications to PV‑WAVE
PV-WAVE leverages CMake for linking C and FORTRAN applications to PV-WAVE. For details on using CMake, see the README.md in each of the example directories.
