wave_assign_asarr
Creates a new PV-WAVE ASARR variable or modify an existing PV-WAVE ASARR variable.
C Usage
long wave_assign_asarr(asarr_wvh, new_wvh, key, make_copy)
WVH asarr_wvh
WVH new_wvh
char *key
int make_copy
Input Parameters
asarr_wvh—A PV-WAVE variable handle for a new or existing PV-WAVE ASARR variable.
new_wvh—A WVH for an existing PV-WAVE variable you wish to place in the associative array. This variable must already exist in your PV-WAVE session, either retrieved from PV-WAVE by your C routine or created via the wave_assign_* routines.
key—A string (pointer to an array of characters) containing the key for the new element.
make_copy—If TRUE, then wave_assign_asarr makes a copy of the data area for use in the PV-WAVE kernel. If make_copy is FALSE, the PV-WAVE kernel uses 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. You must set this to TRUE if the data for the variables you are assigning are local to your C routine.
Returned Status
OPI_SUCCESS—Successful assignment occurred.
OPI_FAILURE—The arguments are 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.
Discussion
A PV-WAVE associative array is a container for PV-WAVE variables very much like a LIST, except the elements are accessed via a string key instead of the index value. Elements of a PV-WAVE ASARR are not ordered.
wave_assign_asarr takes a single new_wvh and key combination per call. It must be called iteratively to add multiple, new elements to an associative array.
The PV-WAVE ASARR does not need to exist before wave_assign_asarr is called. If the ASARR does not exist, it is created and the new key-WVH combination added to it. If the ASARR already exists, the new key-WVH combination is added to it. If the key already exists in the ASARR the PV‑WAVE variable associated with it is replaced by the one passed to the wave_assign_asarr routine. There is no way to remove keys from an existing PV-WAVE ASARR variable.
wave_assign_asarr currently supports only the C language interface.
For more information and example usage, see the example OPI in the $WAVE_DIR/demo/interapp/option directory.
For more general information about creating PV-WAVE variables in your C routine, see the documentation for the wave_assign_* routines.
