Accessing Data in PV‑WAVE Variables
You can access PV-WAVE variables from a dynamically linked C program by calling the function wavevars. Once commands have been sent to PV-WAVE from an external application, you can use the wavevars function to access the results in the external application. wavevars is a C function that can be invoked from code linked to PV-WAVE with either cwavec or LINKNLOAD.
wavevars obtains data directly from PV-WAVE’s variable data space.
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. |
Usage
int argc;
char **argv;
WaveVariable *argp;
result = wavevars(&argc, &argv, &argp);
Parameters
argc—The number of variables returned.
argv—An array of strings, sorted in lexicographic order, corresponding to variable names available at the current scope level of PV-WAVE.
argp—A type WaveVariable array of descriptors defining the type, structure, and dimension of the variables as well as providing a pointer to their actual data. The WaveVariable structure is described in the Discussion section that follows.
Returned Value
result—A C int value which is nonzero if the routine executed successfully, and zero if an error (such as running out of memory) occurred.
Discussion
PV-WAVE variables can be accessed directly from a C function by calling the C function wavevars which is dynamically linked to PV-WAVE. The C function passes three parameters to the wavevars entry point.
The first parameter is the address of an integer variable into which wavevars will return the number of currently-defined PV-WAVE variables (including system variables). The second parameter is the address of an array of pointers to strings (i.e., char**) into which wavevars will return the names of currently-defined PV-WAVE variables. The third parameter is the address of an array of pointers to the C structure WaveVariable into which wavevars will return information regarding the type, structure, dimension, and data of each PV-WAVE variable (including a pointer to the current value of the variable).
WaveVariable is defined as follows in:
%WAVE_DIR%\util\variables\wavevars.h.
This header file must be included in any C function that calls wavevars.
typedef struct WaveVariable {int type;
int read_only;
int numdims;
int dims[8];
int numelems;
void **data;
char name[MAXIDLEN + 1];
} WaveVariable;
note | Although wavevars returns pointers to the data associated with PV-WAVE’s variables, keep in mind that the data pointer associated with a given variable can change after execution of certain PV-WAVE system commands. It’s best to call wavevars immediately before it is needed to obtain information from the external program. |
The wavevars function allocates space to store the information it returns to the caller. When the caller no longer needs the information returned by wavevars, then the free_wavevars() function should be called to free the space. The arguments to free_wavevars() should be identical to those used in the call to wavevars such as:
result = free_wavevars( &argc, &argv, &argp );
and argc must still contain the number of variables returned by the wavevars call.
The WaveVariable structure’s fields are:
int type—The type field indicates the type of the variable. Valid PV-WAVE variable types, together with their C equivalents, are defined in wavevars.h as follows:
TYP_BYTE char;
TYP_INT short;
TYP_INT32 int;
TYP_LONG long;
TYP_FLOAT float;
TYP_DOUBLE double;
TYP_COMPLEX struct { float r, i; } COMPLEX;TYP_DCOMPLEX struct { double r, i;} DCOMPLEX;TYP_STRING char *;
In PV-WAVE, a structure is a collection of data where each field (tag) has a name. The C structure WaveVariable describes a PV-WAVE structure with a type of TYP_STRUCT, where each element of the structure is contained in a list of WaveVariable structures pointed to by the data field, which is described later in this section.
The constant TYP_ARRAY will be bitwise or-ed into the type field if the variable is in fact an array.
int read_only—Many PV-WAVE variables are read-only, and thus if this field is nonzero, it is not permissible to alter the actual variable data. This is often the case with system variables.
int numdims—PV-WAVE variables may be of dimension zero (scalar) to eight. The field numdims indicates the dimensionality of the variable.
int dims[8]—Indicates the size of each dimension of a variable if it is of type array.
int numelems—Corresponds to the total number of data values which are addressable from the data pointer.
void **data—Corresponds to the address of the actual variable data. The data is always stored as a one-dimensional C array regardless of the dimensionality of the PV-WAVE variable.
char name[MAXIDLEN + 1]—Only used when the variable being described is of type structure and represents the structure or tag field name (depending on context).
To access a specific PV-WAVE variable you must search the array of variable names returned by wavevars to find the index associated with that variable. Then use the index to access the correct PV-WAVE variable from the WaveVariable array. The type field in WaveVariable is used to determine a variable’s type. To access the data associated with a PV-WAVE variable it is necessary to use the data pointer and cast it to the correct type. It is then possible to read and/or modify the actual data value(s).
Using wavevars to Retrieve Data from PV-WAVE
An example C program demonstrating the use of wavevars can be found online. You can print the program or view it online using a text editor. The example program is in the file:
%WAVE_DIR%\demo\interapp\win32\wavevars\example.c
The C program retrieves a list of all PV-WAVE variables and prints out their contents. The program demonstrates several important concepts.
The data pointer must be cast to appropriate type.
The data is always stored as a flat one-dimensional array.
PV-WAVE structures are stored recursively.
Building the DLL File
The makefile (called makefile) creates the DLL file used by LINKNLOAD to link the C function to PV-WAVE at runtime. This makefile is in the same directory as the source file example.c. At a Windows’ command prompt, enter the following command to build the DLL:
nmake
note | You must have a supported Windows C compiler on your system for this makefile to execute properly. |
Accessing the External Function with LINKNLOAD
The following PV-WAVE procedure runs the example C program by calling LINKNLOAD. For detailed information on LINKNLOAD, see the
"Using LINKNLOAD to Call External Programs". This procedure is available online in the file:
%WAVE_DIR%\demo\interapp\win32\wavevars\lnl_example.pro
PRO variable
ln = LINKNLOAD('example.dll','printallvars')INFO, ln
END
To run this procedure, start PV-WAVE and type the following command at the WAVE> prompt:
WAVE> lnl_example
The output of this PV-WAVE procedure prints a listing of all currently defined PV-WAVE variables and their values. Finally, the INFO command prints the return value of the LINKNLOAD call.
Using the Option Programming Interface
The Option Programming Interface (OPI), a C-callable or FORTRAN-callable programming interface, was developed to provide greater flexibility and control than wavevars. OPI differs from wavevars in the following ways:
Uses less memory than
wavevarsCan obtain information about a single PV‑WAVE variable at a time.
Can obtain a subset of the information normally returned by
wavevars.
Can create new PV‑WAVE variables.
For detailed information on OPI, see the PV-WAVE Programmer’s Guide.
note | To use OPI effectively with C programs, you should be a C programmer, understand the difference between call-by-reference and call-by-value, and be able to use pointers and the C malloc() function. |
Version 2017.1
Copyright © 2019, Rogue Wave Software, Inc. All Rights Reserved.