wsdh_element
Creates a Wave variable handle for a tag in a PV‑WAVE structure 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 wsdh_element(wsdh, tagname, WVHptr)
WSDH wsdh;
char *tagname;
WVH *WVHptr;
FORTRAN Usage
INTEGER*4 LF_WSDH_ELEMENT(l_wsdh, tagname, l_wvh )
INTEGER*4 l_wsdh, l_wvh
CHARACTER*31 tagname
64-bit UNIX FORTRAN Usage
INTEGER*8 LF_WSDH_ELEMENT(l_wsdh, tagname, l_wvh )
INTEGER*8 l_wsdh, l_wvh
CHARACTER*31 tagname
Input Parameters
wsdh—A Wave structure definition handle.
tagname—The name of the desired tag in the structure.
Output Parameters
WVHptr—A pointer to a Wave Variable Handle for the selected element of the PV-WAVE structure variable.
Returned Status
If the function returns OPI_SUCCESS, then the WVH will be returned in the WVHptr argument. If the function can not allocate enough memory to create the WVH, it will return OPI_DO_NOT_PROCEED. If the function fails because it does not find a tag whose name matches tagname, then it returns OPI_FAILURE and WVHptr is undefined.
Discussion
If tagname is a valid tag name in the structure definition referred to by wsdh, then wsdh_element will create a Wave variable handle that describes this one element of the structure definition. Since one element of a structure definition has all the characteristics of a PV‑WAVE variable (except it has no data area), a WVH is a convenient way to describe it. All the WVH_* functions that return information about a PV‑WAVE variable can also be used to return information about a structure element. wvh_dataptr will return NULL if it is passed a WVH for a structure element since structure elements do not have data areas. Since creating a WVH requires allocating some memory, wsdh_element may fail if the allocation request fails.
