OPI Language Bindings

This section presents an overview of the architecture of an OPI style Option and describes the C and FORTRAN application programming interfaces for OPI style Options. For both C and FORTRAN, this section discusses the background, data types, and OPI functions used to manipulate PV‑WAVE variables and structures from an Option.

These functions can be called from user-written programs, and may be used in conjunction with cwavec, cwavefor, or the PV‑WAVE LINKNLOAD command. These functions make it easier for user-written code to access PV‑WAVE variables and use other PV‑WAVE functionality.

note	OPI variable handling functions are designed to be used with OPI options; however, these functions can be used in any code that calls PV‑WAVE (e.g., via cwavec or cwavefor) and in code called from PV‑WAVE (e.g., via LINKNLOAD).

OPI makes use of opaque handles for elements in the PV‑WAVE internal code that remain hidden from the Option developer. This makes it possible for Rogue Wave to change the underlying implementation in the future without breaking this interface definition. The following abbreviations are used for these handles:

WVH—Wave variable handle. This handle gives Option developers access to everything they need to know about a PV‑WAVE variable. OPI routines that return a Wave Variable Handle (WVH) or take the address of a WVH as an argument need to free the variable with wave_free_WVH or resource leaks will develop.

note

A WSDH is not a PV‑WAVE variable of structure type. Structure definitions exist independently of PV‑WAVE structure variables.

The routines described later in this chapter have been implemented as functions that return a value indicating the success or failure of the function call. The possible return values and their meanings are described for each function. It is extremely important that any code using these functions looks at the returned values and takes the appropriate action. Ignoring the returned value and continuing to execute after an error condition has occurred can result in memory trashing and PV‑WAVE crashes. Ignoring return values that indicate other PV‑WAVE states can result in incorrect PV‑WAVE behavior.

The FORTRAN-callable OPI functions are actually written in C and are part of the PV‑WAVE code base. Basically, these functions take care of all parameter passing differences between C and FORTRAN and then call one of the C-callable OPI functions.

There is not an exact one-to-one correspondence between C-callable and FORTRAN-callable functions due to basic language differences. However, there is no functionality missing from the FORTRAN-callable interface.

Passing and returning string values is the biggest difference between FORTRAN and C. While the C-callable functions can return string values, the FORTRAN-callable functions must pass a string argument which will be filled in with the string value that would be returned by the equivalent C-callable function.

In all the following function descriptions where one or more of the arguments is a string, the string argument is shown to be declared as a CHARACTER*31 FORTRAN type. The maximum length of a PV‑WAVE variable or structure definition name is 31 characters. However, for each string argument passed, FORTRAN also passes the size of the string argument. When filling in a string argument for return to the calling function, these PV‑WAVE functions will not “overfill” the string.

For example, if you pass a CHARACTER*10 as the string argument to be filled by the LF_WVH_NAME function and the PV‑WAVE variable name is longer than 10 characters, you will get only the first 10 characters of the PV‑WAVE variable name. Also, if you pass a CHARACTER*10 variable as the string argument to the LF_WSDH_OFFSET function, the LF_WSDH_OFFSET function still works as expected.

All of the LF_, FORTRAN-callable routines return C long integers. This means that on 64-bit UNIX platforms the return values must be declared as INTEGER*8 values in your FORTRAN code, as opposed to INTEGER*4 values on 32-bit systems. The exception to this is 64-bit Windows, where C long integers remain at 4-bytes.

note	All INTEGER4 function and parameter declarations must be changed to INTEGER8 for use on 64-bit UNIX platforms.

The file opi_devel.h is a C include file containing #define macros,
typedef’s and extern declarations needed by the OPI functions. Just #include this in your program.

The file opi_f_devel.h lists FORTRAN type declarations and PARAMETER statements needed by the FORTRAN OPI functions. Copy the needed statements from this file into your program.