Incorporating a Module into the FRAMEwork System (FRAMES)
Title Page
Legal Notice
Table of Contents
Introduction
Example
STEP 1
STEP 2
STEP 3
STEP 4
STEP 5
APPENDIX A
APPENDIX B
APPENDIX C
APPENDIX D
Introduction
One of the most powerful features about the FRAMEwork System (FRAMES) is its ability to accomodate a wide range of models and databases. This document describes how a model developer can incorporate a model into FRAMES 2.0. Additional documentation describes how a database owner can incorporate a database into FRAMES.
The following step-by-step instructions assume that the developer has a model developed in some programming language (FORTRAN, C++, C, Java, or Visual Basic), which will be used to incorporate the model. The instructions also assume that the developer is comfortable making use of the Application Programming Interface (API) of FRAMES 2.0. FRAMES 2.0 should also be installed on the same computer as the model, in the directory specified in the installation instructions. For modelers that prefer to use a wrapper and additional coding to incorporate a model into FRAMES, separate coding guidelines are available.
The process for incorporating a model into FRAMES 2.0 has been simplified from the process for FRAMES 1.X. FRAMES 1.X required each model developer to match a file specification that incorporated both format and data content. Thus, each developer in effect had to recode the specification. While workable, this approach increased code maintenance and made correct file specification critical. Unfortunately, many problems arise when different individuals make slightly different interpretations of the specification.
In FRAMES 2.0, the file format is separated from the data being stored through a collection of function and subroutines in an API. This API provides developers with all the resources needed to incorporate a component without having to be a slave to the details of the file format. In FRAMES 2.0, the "what" of what is being stored is different from the "how" it is stored.
Another aspect that makes FRAMES 2.0 easier to incorporate a model is the fact that a general user interface can be implemented from the model input description. In FRAMES 1.X, there was not enough information about model inputs to create a user interface. In FRAMES 2.0, the model inputs have enough detailed information to allow a single program [the Data Client Editor (DCE)] to query the user for a set of values. This functionality is made possible because FRAMES 2.0 keeps track of all inputs needed by the model and the inter-relationships between the models.
Models can be incorporated into FRAMES using one of two methods, both with advantages and disadvantages from a software maintenance point of view. One method leaves the legacy model as is and wraps the executable in a pre- and post-processor that create the native file information needed by the model. The other method modifies the original model to use the API functions to replace existing read and write statements. The advantage of the wrapped executable approach is that the testing and use of legacy of the model is not disturbed. The developer would still need to test the pre- and post-processors but the model itself would not need to be retested. The disadvantage of this approach is that the data items needed in the model have two representations that must be synchronized. For example the pre-processor needs to understand and read the input parameters and write them in the native file format. So all the detailed logic of when parameters are needed and where they occur in the input file need to be known to both the legacy model and the pre-processor. A similar situation exists for the post-processor.
Using the API functions to replace existing read and write statements requires that the model be retested within FRAMES, but greatly simplifies the design and maintenance process in the long-term. The following sections describe this type of model integration. Those modelers who decide to wrap legacy models in pre- and post-processors instead should refer to separate coding guidelines.
Utilizing the API, the model incorporation process encompasses five steps: 1) add units and measures, 2) define model inputs and boundary conditions, 3) develop an invocation for the model, 4) provide a description of the model, and 5) categorize the model. An example also walks the modeler through this process.
