SDK Sections 1.1 - 1.3

1.1 Call Arguments

Each component of FRAMES is called with a given set of arguments. The arguments are always as follows.

  1. FUIName (name without extension of files to be read)
  2. RunName (name of temporary files written by a module)
  3. Site# (number of currently executing site)
  4. Module# (module number of currently executing module)
  5. Name (name of currently executing module)

Basically, call arguments allow a component to know which files it can read, write, and which module it is currently executing.  The module currently executing is necessary because many times the same module may be used to simulate multiple media, and different invocations of the same module need to know which invocation is being requested to run. A more complete treatment of arguments is in FRAMES specifications.

1.2 ERR File

The Error(ERR)file is the most important file in FRAMES system.  It is a mechanism used by FRAMES to insure that results that are in error are not mistaken for valid results.  To insure that any error (even an unexpected divide by zero) will be caught, FRAMES requires that every module create an ERR file as the first step in processing for the UI or model.  Only when a UI or model reaches a successful end of processing does it erase ERR file. This is the "guilty until proven innocent" approach to error detection.  The UI or model is assumed to have erred, and only when it reaches a check point (end of program) can it clear this error.  The name of ERR file is RunName from the call argument with an ERR extension.  So if a module was called with "MyTest ~glyph 1 1 MyGlyph" for arguments it would be expected as the first step in process to open the file ~glyph.err and write some error message.  This error message will appear when your module terminates unexpectedly so the "Unexpected error in MyModule" is a good example.

1.3 GID File

The Global Input Data (GID) file contains all the connection and user input data for a FRAMES module.  For example, not only does the GID file contain Bulk Density for a given vadose zone, it also contains which media impacts  that vadose zone as well as which media are impacted by the vadose zone.  All user data is required to be stored in a GID file.  There are two good reasons for doing this. 1) if the user wants to share or copy a simulation to another machine, the only file to copy is the GID file, and 2) a module like the Sensitivity/Uncertainty module has access to all user data for those types of analyses.  So the strict definition of what is required by a FRAMES UI is it must read the GID file for the values associated with the module. It must allow the user to then change those values.  It must write new values to the temporary GID file. The specifications for this format are in FRAMES specifications.

1.3.1 Reading module sections in FRAMES specified files.

All FRAMES files contain sections for each module to read.  This feature allows a module to quickly skip data that it is not concerned with and move to next section.  A module marker consists of two values on a line.  The first is the module name and the second is the number of lines associated with this section.  So the process of reading a file consists of following 

  1. Read marker name, marker number of lines
  2. If marker name matches section module is looking for begin reading data
  3. If marker does not match section module is looking for 
    1. Read marker number of lines from file
    2. If not at end of file go to 1

For example lets assume a module is to read following file and is looking for "MyModule" section.

"FUI",5 
"Param1",0,0,0,0,0,"units",value 
"Param2",0,0,0,0,0,"units",value 
"Param3",0,0,0,0,0,"units",value 
"Param4",0,0,0,0,0,"units",value 
"Param5",0,0,0,0,0,"units",value 
"MyModule",5 
"Param1",0,0,0,0,0,"units",value 
"Param2",0,0,0,0,0,"units",value 
"Param3",0,0,0,0,0,"units",value 
"Param4",0,0,0,0,0,"units",value 
"Param5",0,0,0,0,0,"units",value

It is apparent that module would read first line of data then determine next section is not "MyModule" section and read 5 lines.  Then it would read "MyModule" marker and determine that this is appropriate section and begin reading Param1, Param2, etc.

SDK Introduction - introduction page for Software Developer Kit. 
SDK 1.1-1.3 - Call Arguments, ERR file, GID file and Reading module sections in FRAMES specified files. 
SDK 2.0 - Example of module inclusion 
SDK Tools - Software Development Tools 
Go to Module Specifications for more information on modules.