wave_execute
Executes a PV‑WAVE command.
C Usage
long wave_execute(any_wave_cmd)
char *any_wave_cmd;
FORTRAN Usage
INTEGER*4 LF_WAVE_EXECUTE(any_wave_cmd)
CHARACTER*(*) any_wave_cmd
64-bit UNIX FORTRAN Usage
INTEGER*8 LF_WAVE_EXECUTE(any_wave_cmd)
CHARACTER*(*) any_wave_cmd
Input Parameters
any_wave_cmd—A string containing a PV‑WAVE command to be executed.
Returned Status
OPI_SUCCESS—Successful.
OPI_FAILURE—Errors occurred but execution can continue.
OPI_DO_NOT_PROCEED—Errors occurred: cease execution. 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 has already done its normal error processing which includes printing a message and setting the appropriate system variables.
Discussion
The wave_execute function takes the string argument it is given and treats it as a PV‑WAVE statement. The statement will be compiled and interpreted as if it were the argument to a PV‑WAVE EXECUTE function at the current interpreter position.
The purpose of this function is to give your C function the ability to use all PV‑WAVE functionality from C code without having to write a separate interface to every piece of PV‑WAVE functionality. For example, suppose your C function needs the transpose of a PV‑WAVE variable that was passed as an argument to the function. If you have access to the PV‑WAVE TRANSPOSE function, you do not have to write your own transpose routine inside the C code of your function.
For example, suppose your code has some related PV‑WAVE system variables and you want to change the value of a system variable without requiring that the system variable be an argument to your function. You can use wave_execute to assign a new value to a PV‑WAVE system variable.
note | wave_execute happens in the context of the currently active PV‑WAVE procedure or function. It knows about only those variables that are in the scope of the currently active PV‑WAVE procedure or function. Between the time wave_execute was called and when it returns, many PV‑WAVE context changes could have occurred. But when wave_execute returns, you are again in the context of the PV‑WAVE procedure or function that was active when wave_execute was called. If you use wave_execute in a cwavec or cwavefor application, you must call either cwavec or cwavefor at least one time before using wave_execute. |
