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.