The Developer Environment
This section contains information the developer needs to develop in PV-WAVE.
The Directory Structure
The developer must be able to develop Options for UNIX, Windows, and other platforms that support explicit loading.
To facilitate this goal, we recommend that for each Option the developer set up a directory structure containing some common files and some operating system specific files.
note | The Option directory structure must be located in the RW_DIR directory. This is the PV-WAVE installation directory. |
The directory structure of an Option called SAMPLE is shown in Figure 14-1: Option Directory Structure.
 |
Makefiles
Makefiles can be set to be platform dependent, so that building the shared libraries is done according to the operating system specific flags and include files. We advise you to place them under the Option main directory, here sample-1_0.
The bin Directory
The name SAMPLE is used by the LOAD_OPTION command to choose the appropriate shared library. The shared libraries are located in the bin directory:
sample-1_0/bin/bin.hps700
sample-1_0/bin/bin.solaris
sample-1_0\bin\bin.i386nt
The src Directory
The directory sample-1_0/src contains the source code for the Option.
The lib Directory
If an Option requires PV‑WAVE code (for example, for keyword processing), it should be located in the lib subdirectory.
Main Directory Requirements
The main Option directory must be named according to the following naming convention. The directory name is used to locate the Option.
<OptionName>-<Version>_<Release>
where:
<Option_Name>—The name of the Option. <Version>—The major version number of the Option.<Release>—The minor version number of the Option.For the example Option described in this chapter, the main directory name is sample-1_0.
Required Files
Under the main Option directory, you must have the files:
bin/bin.<platform_name>where the platform names are the same as the platform names used for the main PV‑WAVE executable.
For example, bin/bin.hps700 or bin/bin.i386nt.
Assume that you are building an Option that will run under HP-UX and SunOS. The required directory structure for the Option is shown in Figure 14-2: Option Directory Structure.
 |
The shared library files:
option_routines.xx
option_table.xx
are explicitly loaded when the LOAD_OPTION command is invoked.
option_table.xx—Contains a PV‑WAVE kernel table that describes the content of the Option: the number of functions, the number of procedures, the feature and version for the license manager, the names of the functions, and the names of the procedures. In this particular example (the Option called SAMPLE), the file option_table.xx returns the fact that this Option has three functions and two procedures, named respectively:PLUS_TWO (function)
PLUS_THREE (function)
PLUS_FOUR (function)
ADD_TWO (procedure)
ADD_THREE (procedure)
option_routines.xx—Contains the actual code for the these functions and procedures. This code contains OPI wrapper calls that implement the functions and procedures of the module.The filename extension for the shared library files is operating system dependent. Table 14-1: Operating System Filename Extensions lists the filename extensions for the operating systems that Rogue Wave supports:
Operating System | Shared Library Filename Extension |
|---|---|
HP-UX | .sl |
Linux | .so |
Solaris | .so |
AIX | .so |
Windows | .dll |
note | AIX requires that the file option_table.o be placed in the bin/bin.rs6000/object directory. |
Option Example
This section presents an example of an Option and describes the flow of control and data through the different components associated with the Option.
This example does not present all of the OPI features available to an Option developer. The example is based on the IMSL C/Stat/Library normality_test function as it might be implemented with OPI.
The user enters the following at the PV‑WAVE command line:
x = SIN(DINDGEN(1000))
norm = IMSLS_NORMALITY_TEST(x, /Double)
IMSLS_NORMALITY_TEST is a PV‑WAVE Option function (contained in a .pro file). The purpose of this function is to prepare parameters for the PV‑WAVE Option system functions for this IMSL C/Stat/Library function. The Option system functions are named:
OPT_FLOAT_IMSLS_NORMALITY_TEST, and
OPT_DOUBLE_IMSLS_NORMALITY_TEST
IMSLS_NORMALITY_TEST checks the keyword parameters, makes sure the positional parameters are the correct type and, in this case, calls:
value = OPT_DOUBLE_IMSLS_NORMALITY_TEST(x, n_observations)
Up until this point the data and control flows have been identical to past versions of PV‑WAVE. At this point the PV‑WAVE kernel will convert the list of PV‑WAVE variables passed to OPT_DOUBLE_IMSLS_NORMALITY_TEST to a list of Wave variable handles (WVH).
Inside of OPT_DOUBLE_IMSLS_NORMALITY_TEST, Wave variable handles (WVH) and Wave structure definition handles (WSDH) are used by the OPI C or FORTRAN functions to access PV‑WAVE variables and PV‑WAVE structure definitions.
In the example, the function definition for OPT_DOUBLE_IMSLS_NORMALITY_TEST is as follows:
WVH opt_double_imsls_normality_test(int argc, WVH *argv);
When OPT_DOUBLE_IMSLS_NORMALITY_TEST is called in the example the parameters will have the following values:
argc =2;
WVH *argv = { <WVH for the PV-WAVE variable ”x”>,
<WVH for the PV-WAVE variable ”n_observations”>
};
The following assignment statements will get a C pointer to the data associated with the first two PV‑WAVE handles:
x = (double *) wvh_dataptr(argv[0]);
n_observations = (int *) wvh_dataptr( argv[1]);
These pointers are then passed to the imsls_d_normality_test function in the C/Stat library. The return value from this function is a scalar double. For the purpose of the example the variable name of the return value will be result.
result = imsls_d_normality_test(n_observations, x);
To return result to the PV‑WAVE kernel the Option must create an unnamed PV‑WAVE variable, assign result to this variable, then return the unnamed variable’s WVH. The following functions accomplish this task:
status = wave_get_unWVH(return_value);
status = wave_assign_num(return_value, TYP_DOUBLE, 0, NULL, $
(char *) result, FALSE);
return(return_value);
At this point control returns to the IMSLS_NORMALITY_TEST PV‑WAVE Option function. The unnamed variable, with the WVH name return_value, has been assigned to the PV‑WAVE variable value.
IMSLS_NORMALITY_TEST now returns value to the original assignment statement, as entered at the PV‑WAVE command line:
norm = IMSLS_NORMALITY_TEST(x, /Double)
