wave_assign_num, _string, _struct
Assigns data to an existing PV‑WAVE variable.
note | Any Wave Variable Handle (WVH) or Wave Structure Definition Handle (WSDH) returned from such PV-WAVE OPI interface routines as wave_get_WVH(), wave_wsdh_from_WVH() or wsdh_element() must be freed by the calling routine via wave_free_WVH or wave_free_WSDH or resource leaks will develop. |
C Usage
long wave_assign_num(wave_variable, type, ndims, dims, data, make_copy)
long wave_assign_string(wave_variable, ndims, dims, data, make_copy)
long wave_assign_struct(wave_variable, ndims, dims, wsdh, data, make_copy)
WVH wave_variable;
long type;
long ndims;
long dims[OPI_MAX_ARRAY_DIMS];
long make_copy;
WSDH wsdh;
char *data;
FORTRAN Usage
INTEGER*4 LF_WAVE_ASSIGN_NUM(l_wvh, l_type, l_ndims, l_dims, value)
INTEGER*4 LF_WAVE_ASSIGN_STRING(l_wvh, l_ndims, l_dims, c_value)
INTEGER*4 LF_WAVE_ASSIGN_STRUCT(l_wvh, l_ndims, l_dims, l_wsdh, s_value)
INTEGER*4 l_wvh, l_type, l_ndims, l_wsdh
INTEGER*4 l_dims(L_OPI_MAX_ARRAY_DIMS)
INTEGER*1 value
CHARACTER*(*) c_value
64-bit UNIX FORTRAN Usage
INTEGER*8 LF_WAVE_ASSIGN_NUM(l_wvh, l_type, l_ndims, l_dims, value)
INTEGER*8 LF_WAVE_ASSIGN_STRING(l_wvh, l_ndims, l_dims, c_value)
INTEGER*8 LF_WAVE_ASSIGN_STRUCT(l_wvh, l_ndims, l_dims, l_wsdh, s_value)
INTEGER*8 l_wvh, l_type, l_ndims, l_wsdh
INTEGER*8 l_dims(L_OPI_MAX_ARRAY_DIMS)
INTEGER*1 value
CHARACTER*(*) c_value
Input Parameters
wave_variable—A Wave variable handle for the PV‑WAVE variable to assign.
type—The numerical type of the assignment for wave_assign_num. Must be one of the OPI_TYP_* macros (PARAMETERS) defined in opi_devel.h or opi_devel.f.
ndims—The number of dimensions you want the PV‑WAVE variable to have, and also indicates the number of elements in dims[] (the number of elements used in dims). For example, if ndims is 2, then the first 2 elements of the dims array must contain the dimensions you want the PV‑WAVE variable to have.
dims—An array containing the dimensions of the PV‑WAVE variable.
data—A pointer to the data you want to assign to the PV‑WAVE variable.
It is declared as a (char *) but the argument you pass must be a pointer to the type of data you are passing as described in the type argument. For the wave_assign_string function, it should be a pointer to a string if you are assigning a scalar string, and it should be a pointer to an array of string pointers if you are assigning an array of strings.
make_copy—If TRUE, then wave_assign_* will make a copy of the data area for use in the PV‑WAVE kernel. If make_copy is FALSE, the PV‑WAVE kernel will use the memory pointed to by data. This means that the memory pointed to by data must be free-able by the PV‑WAVE kernel and must no longer be used outside the kernel.
The FORTRAN LF_WAVE_ASSIGN_* functions will always make a copy of the value argument for use in the PV‑WAVE kernel. Due to the dynamic nature of PV‑WAVE variables, PV‑WAVE must be able to free the memory associated with a PV‑WAVE variable whenever it needs to. Since FORTRAN does not support dynamic allocation of memory, the values of FORTRAN variables must be copied into dynamically-allocated space in PV‑WAVE if they are to used as PV‑WAVE variables.
wsdh—This is a Wave structure definition handle. The structure must already exist in the current PV‑WAVE session. Use the wave_wsdh_from_name or wave_wsdh_from_wvh function to get the Wave structure definition handle of an existing PV‑WAVE structure variable.
Returned Status
OPI_SUCCESS—Successful assignment occurred.
OPI_FAILURE—wave_assign_* considers the arguments to be invalid or inconsistent.
OPI_DO_NOT_PROCEED—Catastrophic errors occurred and execution should not continue. The calling C-code should do its cleaning up (free malloc’s space, free handles, etc.) and return to its caller immediately.
In either of the error cases, PV‑WAVE will have already done its normal error processing which includes printing a message and setting the appropriate system variables.
Discussion
The wave_assign_* functions are wrappers to the function wave_assign. These wrappers give the Options developer access to the PV‑WAVE assignment statement from the C language. These functions can be used to change the type, dimensions and/or contents of an existing PV‑WAVE variable. The PV‑WAVE variable to be modified must already exist within the scope of the current PV‑WAVE procedure or function. It can be a named variable in the currently active PV‑WAVE procedure or function or it can be an unnamed variable. Use the wave_get_WVH function to get a Wave variable handle for a named PV‑WAVE variable. Use the wave_get_unWVH function to get a Wave variable handle for an unnamed PV‑WAVE variable.
Use wave_assign_num to assign numeric values to a PV‑WAVE variable. Use wave_assign_string to assign string values to a PV‑WAVE string variable. Use wave_assign_struct to assign a structure value to a PV‑WAVE variable.
The wave_assign_struct function has an addition argument, stdef. This is the handle of a PV‑WAVE structure definition. The structure definition must already exist in the current PV‑WAVE session. Use the wave_wsdh_from_name or wave_wsdh_from_wvh function to get the handle of an existing PV‑WAVE structure definition.
In all the wave_assign_* functions, the data argument must be a pointer to the data you want to assign to the PV‑WAVE variable. It is declared as a (char *) but the argument you pass will more commonly be a pointer to whatever type of data you are passing. For the wave_assign_string function, it should be a pointer to a string if you are assigning a scalar string and it should be a pointer to an array of string pointers if you are assigning an array of strings.
If the make_copy argument is TRUE, then wave_assign_* will make a copy of the data area for use in the PV‑WAVE kernel. If make_copy is FALSE, the PV‑WAVE kernel will use the memory pointed to by data. This means that the memory pointed to by data must be free-able by the PV‑WAVE kernel and must no longer be used outside the kernel.
Array Indexing in C
PV‑WAVE and C language array indexing is opposite. That is WAVE_ARRAY(i,j,k) is the same as carray[k][j][i]. So, for example, if the PV‑WAVE array is:
WAVEARRAY(2,3,4,5,6,7,8,9)
then the corresponding C array is:
carray[9][8][7][6][5][4][3][2]
The dims array argument to wave_assign_* determines the array dimensions in PV‑WAVE. If you were using wave_assign_num to assign carray[] to the PV‑WAVE variable named WAVEARRAY, then the dims argument to wave_assign_num should have the values:
long dims[] = {2,3,4,5,6,7,8,9};even though PV‑WAVE and C language array indexing is indexed as above.
If the wave_assign_* functions are used to populate an undefined variable (for example a new unnamed variable created using wave_get_unWVH), set ndims=0, dims=NULL to create a scalar variable (ndims=1, dims[0]=1 creates a one dimensional, one element array).
Integer Data Type Size Issues on 64-Bit Platforms
The type codes for OPI_TYP_BYTE, OPI_TYP_SHORT and OPI_TYP_INT32 always correspond to the C types char, short, and int, respectively, regardless of the platform. However on 64-bit platforms there may be differences with the OPI_TYP_LONG data type. On 64-bit UNIX platforms, the C long data type grows to 8 bytes along with the PV-WAVE OPI_TYP_LONG type, so the two remain consistent. However, on 64-bit Windows the C long data type remains at 4 bytes while the OPI_TYP_LONG type grows to 8 bytes. To assign data to a PV-WAVE LONG variable on 64-bit Windows, you must pass in a pointer to an 8-byte value (INT64). The best way to do this is to declare all of your C long variables to be of type OPI_long. This type is declared in the opi_devel.h header file and always matches the size of the OPI_TYP_LONG PV-WAVE data type, regardless of platform.
note | This caveat only applies to data passed into and retrieved from PV-WAVE variables. Return values from, and arguments to, OPI routines declared as type long in the OPI API continue to use the C long type for backwards compatibility. |
