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.
OPI Variable Handling
OPI consists of C and FORTRAN callable functions that can be used to:
get information about existing PV‑WAVE variablescreate new PV‑WAVE variablesmodify existing PV‑WAVE variablesallow existing PV‑WAVE variables to be used as parameters to other PV‑WAVE functionalityThese 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). |
Use of Opaque Handles
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.WSDH—Wave structure definition handle. This handle gives the Option developer access to all elements of a PV‑WAVE structure definition. 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. |
FORTRAN Variable Handling
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.
All FORTRAN-callable functions have names beginning with LF_. Their C-callable equivalent has the same name but without the LF_ prefix.
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.
FORTRAN Specifics for 64-Bit Platforms
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 INTEGER*4 function and parameter declarations must be changed to INTEGER*8 for use on 64-bit UNIX platforms. |
Include Files
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.
typedef’s and extern declarations needed by the OPI functions. Just #include this in your program.
The file opi_devel.f lists FORTRAN type declarations and PARAMETER statements needed by the FORTRAN OPI functions. Copy the needed statements from this file into your program.
These files are located in:
(UNIX) $WAVE_DIR/wave/src/priv
(WIN) %WAVE_DIR%\wave\src\priv
Examples
For examples showing the use of these functions, see the files in:
(UNIX) $WAVE_DIR/wave/demo/interapp
(WIN) %WAVE_DIR%\wave\demo\interapp
