Application Developer Guide > Interapplication Communication for Windows > Accessing Data in PV‑WAVE Variables
  
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 wavevars
*Can 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.0
Copyright © 2017, Rogue Wave Software, Inc. All Rights Reserved.