Calling PV‑WAVE as a Dynamically Linked Program
An application written in C or FORTRAN can be linked with the PV-WAVE Dynamic Link Libraries (DLLs), creating an application that can execute PV-WAVE commands at runtime. The C or FORTRAN application passes PV-WAVE commands to the entry points cwavec or cwavefor in the PV-WAVE DLL.
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 DLL.
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, as explained previously.
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 shown in Table 2-2: Action Parameter Values.
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.
note | The cwavec connectivity is designed and tested only on specific C compilers. C++ and C# for .NET are not tested nor supported compilers for cwavec functionality. |
Accessing the Data in PV‑WAVE Variables
The wavevars function can be used to access the results generated by PV-WAVE in a user-written application called with cwavec. wavevars is a C function that can be invoked from code linked to PV-WAVE to obtain data from PV-WAVE’s data variable space.
For detailed information on wavevars, see "Accessing Data in PV‑WAVE Variables".
note | See also the section "Using the Option Programming Interface". The Option Programming Interface (OPI) functions allow user-written C code to access PV‑WAVE variables and use other PV‑WAVE functionality. OPI provides greater flexibility and control than wavevars. |
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’s Dynamic Link Library (DLL). The C program may then invoke PV-WAVE via the entry point cwavec in the PV-WAVE DLL. The C program must pass three parameters to the cwavec entry point. A makefile is provided to link the following example programs. The makefile is available online in the same directories as the example program files. For more information, see the following example sections.
Example 1: Execute PV‑WAVE Commands From C Program
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 CL. 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 CL, we make a
* final call to cwavec with action = 3 to wrap up the session.
*/
action = 3;
istat = cwavec (action, 0, cmds);
return 0;
}
cwavefor: Calling PV‑WAVE from a FORTRAN Program
The cwavefor routine is the FORTRAN application entry point to a PV-WAVE DLL.
Usage
istat = cwavefor(action, numcmds, ptr, 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 in the string array pointed to by ptr. 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 the string array pointed to by ptr. This argument is ignored if action=3 or if action=1.
ptr—A pointer to an array of strings. If action=2, ptr provides a pointer to the 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.
Instructions for building and running the examples are in the file:
%WAVE_DIR%\demo\interapp\cwavefor\README.md
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:
[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
ptr = LOC(cmds)
call cwavefor(action, 2, ptr, 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\cwavec.f
C
C Build interface for FORTRAN to call the
C "C" function "CWAVEFOR" that is built into PV-WAVE
C
INTERFACE
INTEGER(C_INT) FUNCTION CWAVEFOR (action, numcmds, ptr, cmdlen)
$ BIND(C)
USE, INTRINSIC :: ISO_C_BINDING
INTEGER(C_INT) :: action
INTEGER(C_INT) :: numcmds
INTEGER(C_INTPTR_T), VALUE :: ptr
INTEGER(C_INT) :: cmdlen
END FUNCTION
END INTERFACE
C
C Variables for array calculations
C
integer*4 action, numcmds, cmdlen, istat
character *30 cmds(5)
C
C Declare pointer to pass the CHARACTER array of commands to
C PV-WAVE
C
pointer (p,VAR)
C
C Access PV-WAVE CL in non-interactinve mode
C
action = 2
numcmds = 5
cmdlen = 30
C
C Send the array of commands to PV-WAVE CL
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'
C
C Set up th pointer and call PV-WAVE
C
p=LOC(cmds)
istat = cwavefor (action, numcmds, p, cmdlen)
C
C Since we are done sending commands to
C PV-WAVE CL, we make a final call to cwavec
C with action = 3 to wrap up the session.
C
action = 3
istat = cwavefor (action, 0, p, cmdlen)
C
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.linknloadfor_wrapper.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 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.
