wave_get_WVH

Gets a Wave variable handle for an existing named PV‑WAVE variable.

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_get_WVH(wave_var_name, WVHptr)

char *wave_var_name;

WVH *WVHptr;

FORTRAN Usage

INTEGER*4 LF_WAVE_GET_WVH(wave_var_name, l_wvh)

CHARACTER*31 wave_var_name

INTEGER*4 l_wvh

64-bit UNIX FORTRAN Usage

INTEGER*8 LF_WAVE_GET_WVH(wave_var_name, l_wvh)

CHARACTER*31 wave_var_name

INTEGER*8 l_wvh

Input Parameters

wave_var_name—A string containing the name of an existing PV‑WAVE variable.

Output Parameters

WVHptr—A pointer to a Wave Variable Handle for the variable named by wave_var_name.

Returned Status

OPI_SUCCESS—PV‑WAVE variable successfully found, and WVHptr is returned.

OPI_FAILURE—wave_var_name was not found, and WVHptr is not defined.

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_get_WVH function looks for wave_var_name in the symbol table of the currently active PV‑WAVE procedure or function. If found, a pointer to a Wave variable handle for this variable is returned in WVHptr.

The variable named in wave_var_name must already exist in your PV‑WAVE session.

PV-WAVE system variables use an internal storage mechanism which prevents access via the OPI interface. To access the data in a system variable, use the wave_execute routine to copy the system variable to a normal PV-WAVE variable, which you can then access using the standard OPI interface.

wave_execute("tmp = !ERR");

wave_get_WVH("tmp", &WVHvar);

You may also set the value of non read-only system variables using wave_execute() as well.