Programmer Guide > Creating an OPI Option > Creating An Option
  
Creating An Option
The Option developer must create two shared objects. The first is the Option Table, which contains information regarding the number of functions, the number of procedures, the names of the functions and the names of the procedures and the feature name and version. The second shared object contains the actual code for the routines described in the Option Table.
Option development consists of the following steps:
*Create a new Option directory structure. This can be done using a template that Rogue Wave has provided.
*Modify the template files for the new Option
*Develop the Option code
*Define the Option table
*Build the new Option
*Test the new Option
Step 1: Create a New Option Directory Structure
To begin, copy the option-templates directory tree in the main Rogue Wave directory (the directory to which the RW_DIR environment variable/logical points). Give the new directory a name that follows the naming convention outlined in the section "Main Directory Requirements".
For example, to create the new Option directory tree for the SAMPLE Option, enter the commands shown at the system prompt:
UNIX
% cd $RW_DIR
% cp -r option-templates sample-1_0
Windows
> cd %RW_DIR%
> xcopy option-templates sample-1_0
The new Option directory structure contains a number of files needed to build the Option. Some of these files must be modified for the new Option. The procedure for modifying the template files is described in the next step. The following tables list the files that were copied from the template directory tree:
Table 15-2: UNIX Platform Files
Files
Used for:
Makefile
Controls the building of an Option.
buildmachine
Defines a build machine for a given UNIX platform.
init.mkinc
Common macros, variables for Makefile.
src/Makefile
Controls the building of the source files.
src/option_info.h
The Option definition template.
src/option_table.c
The Option Table definition.
src/option_routines.c
The Option user routines template.
src/option_rs6000.exp
The exported symbols for the Option Table (AIX only).
src/option_rs6000.imp
The imported symbols for the Option (AIX only).
src/depend.mkinc
Dependencies target for make.
src/flags.mkinc
Defines cc, ld flags based on platform.
src/axposf.mkcfg
specific make flags.
src/hps700.mkcfg
HP-UX specific make flags.
src/rs6000.mkcfg
RS6000/AIX specific make flags.
src/sgi.mkcfg
SGI/IRIX specific make flags.
src/solaris.mkcfg
SPARC/Solaris specific make flags.
src/linux.mkcfg
Linux specific make flags.
bin/Makefile
Controls the building of the Option shareable libraries.
lib/Makefile
Controls the compilation of the PV‑WAVE procedures.
Table 15-3: Windows Platform Files
Files
Used for:
makefile.nt
Controls the building of an Option.
src\makefile.nt
Controls the building of the source files.
src\option_info.h
The Option definition template.
src\option_table.c
The Option Table definition.
src\option_routines.c
The Option user routines template.
src\option_table.def
The module definition file for the Option Table.
src\option_routines.def
The module definition file for the Option.
Step 2: Modify the Template Files
Next you need to modify some of the files that were copied from the template directory. In general, you will change generic names given in the template files to the name of your Option. The following tables list the files that you need to modify and tell you exactly what modifications to make to each file.
Table 15-4: UNIX Platform Files to Modify
Files
Modification
Makefile
Change the ROOTNAME variable to the name of your Option directory.
buildmachine
Define a build machine for the supported platform(s).
init.mkinc
Change the ROOTNAME variable to the name of your Option directory.
src/Makefile
Change the ROOTNAME variable to the name of your Option directory.
src/option_info.h
src/option_routines.c
src/option_rs6000.imp
Add (or delete) the IMPORTed PV‑WAVE routines used in your Option (AIX only).
bin/Makefile
Change the ROOTNAME variable to the name of your Option directory.
lib/Makefile
Change the ROOTNAME variable to the name of your Option directory.
Table 15-5: Windows Platform Files to Modify
Files
Modification
makefile.nt
Change the ROOTNAME variable to the name of your Option directory.
src\makefile.nt
Change the ROOTNAME variable to the name of your Option directory.
src\option_info.h
src\option_routines.c
src\option_routines.def
Define the EXPORTed Option routines, and the IMPORTed PV‑WAVE routines used in your Option.
Step 3: Develop the Option Code
The template file option_routines.c is available for developing the Option procedures in C. If you have a limited number of Option routines written in C, it is recommended that you place them in the option_routines.c file.
If you want to split your Option routines into several separate files, you have to modify the appropriate build files:
(UNIX) src/Makefile
(WIN) src\makefile.nt
 
note
Windows platforms require the LibMain function to be defined in one of the files containing the Option routine code.
AIX/RS6000 platforms require a list of the Option procedures and/or functions to be defined in the set_sys_table function defined in the option_routines.c file (for details, refer directly to the file src/option_routines.c).
If PV‑WAVE procedure files are part of your Option, they should be placed in the lib subdirectory. That is because PV‑WAVE automatically appends all option directories located in the directory pointed to by the RW_DIR environment variable/logical and that contain the subdirectory lib to the !Path system variable. The template Makefile is available in the lib subdirectory to create PV‑WAVE compiled files (.cpr) from PV‑WAVE procedure files.
Step 4: Define the New Option Table
The Option Table needs to contain information regarding the number of functions and procedures in the Option, the names of the functions and procedures in the Option, the feature name, and version of the Option.
This information must be entered into a template file, option_info.h, located in src subdirectory. Just open this file and fill in the required information as indicated in the comments. Here is a sample of the file with some additional notes:
/* Option Feature Identifier: Place the string between the double
   quotes. Leave this string blank for unlicensed options. */
static char feature[] = ””;
/* Option Version Identifier: Replace the 0.0 with the
   option's version */
static double version = 0.0;
/* Option Functions: Enter the number of option functions and
   the option function names below. Enter one name per string
   in the ”function_names” array. Function names must be in
   upper case and listed in alphabetical order. */
static int nm_functions = 0;
static char * function_names[] = {
};
/* Option Procedures: Enter the number of option procedures
   and the option procedure names below. Enter one name per
   string in the ”procedure_names” array. Procedure names
   must be in upper case and listed in alphabetical order. */
static int nm_procedures = 0;
static char * procedure_names[] = {
};
Step 5: Build the New Option
The procedure for building an Option, as explained in this section, is platform dependent.
To build the Option shareable libraries for UNIX platforms use:
% cd $RW_DIR/<Option_Dir_Name>
% gmake all TARGARCH = '<platform name>'
The log file BuildLog.<platform> contains the results of the build.
 
note
The UNIX Makefiles are written for gmake, the FSF GNU version of make.
To build the Option shareable libraries for Windows platforms use:
Z:\VNI> cd <Option_Dir_Name>
$ nmake all -f makefile.nt
 
note
The environment variables/logicals RW_DIR and WAVE_DIR must be set before building the Option. Refer to the PV‑WAVE User’s Guide if you any questions about these variables.
Step 6: Test the New Option
Place the tests written for the new Option in a test subdirectory.
Version 2017.1
Copyright © 2019, Rogue Wave Software, Inc. All Rights Reserved.