Documentation for the Dictionary Editor of the FRAMEwork System (FRAMES)


Title Page
Legal Notice
Table of Contents
Introduction
Requirements
Design
Quality Assurance and Testing
 

Design of the FRAMES Dictionary Editor

All information about a dictionary is stored in an ASCII file with a .DIC file extension. When the Dictionary Editor changes information about a dictionary, it is actually manipulating the dictionary's .DIC file. This section describes the format for dictionary files, using privileges and variables, manipulating dictionary files, and publishing dictionary files to a server. In-depth information about dictionaries can be found in a separate dictionary document.

Formatting Dictionary Files

Each dictionary is stored in an ASCII file. The file can reside anywhere on the system. Dictionaries can be created outside the Dictionary Editor using any kind of text editor. However, dictionaries created outside the Dictionary Editor must register their dictionary with the editor (see Opening a Dictionary below) to be recognized by the system.

When creating a dictionary within the FRAMES 2.0 Dictionary Editor, a .DIC file extension is automatically assigned to the dictionary file. FRAMES 2.0 does not require that a dictionary contain a .DIC file extension; however, the Dictionary Editor only recognizes .DIC file extensions as dictionaries.

The file format of a dictionary is as follows:

Line 1 - Description of dictionary fields
Line 2 - [Variable Count],[name],[description],[privilege]
Line 3 - Description of variable fields
Line 4 on -
[Name],[Description],[Dimension],[Data Type],[Scalar],
[Minimum],[Maximum],[Measure],[Unit],[Stochastic],
[Preposition],[Index 1],[Index 2], Y [Index 6]

While many of these items will be familiar to most module or system developers, the privilege, data type, scalar, minimum and maximum, measure and unit, stochastic, preposition, and index items are used in specific manners within FRAMES, as described in the subsections below.

In general, all information in FRAMES 2.0 is stored in datasets, and datasets must use variables to store their information correctly. A variable defines what type of data is going to be added, how the data are retrieved (in a list or a single value), the type of units (if any), and other variables needed to select a particular value with a set of information.

To add a variable to a dictionary, the user opens the Dictionary Editor and selects a dictionary. Clicking on the "New Variable" button brings up an input box. The user enters the name of the new variable. After confirmation, the new variable will appear on the list of associated variables.

To delete a variable from a dictionary, the user opens the Dictionary Editor and selects a dictionary. A list of all the variables belonging to the selected dictionary appears on the right. The user highlights a variable from the list and clicks on the "Delete Variable" button. After confirmation, the Dictionary Editor removes the variable from the list.

Privileges

Each dictionary contains a privilege property field that describes the dictionary's scope. A dictionary's scope is determined by who created the dictionary (system developer or module developer) and by the context of its use within FRAMES. System developer dictionaries are created and used by FRAMES 2.0 and should only be modified by individuals with appropriate access privileges. For example, a module developer will not have access privileges to change any information in a system developer dictionary but will have access privileges to view and reference system developer dictionaries.

The privilege field also describes the context of dictionary use. A dictionary may be interpreted as a model input dictionary or a boundary condition dictionary. A model input dictionary informs FRAMES that a specific module will use the dictionary, whereas a boundary condition dictionary informs FRAMES that the dictionary will be used as global information for all modules.

To make changes to system developer dictionaries and system modules, the user must first log in as a system developer. The log in form is accessed via the File menu.

Data Type

Data can be stored in four different ways:

  • logical - [true|false]
  • float - [0.01549|87| -32.223]
  • integer - [1|546|-97]
  • string - ["Name"| "123"].

Scalar

The scalar field describes a true or false value used to identify retrieval method. Data can be retrieved as single values or a list of values. If the scalar value is false, then a single value will be returned. If the scalar value is true, then a list of values will be returned. If the scalar value is set to true, the last indexing variable must be self-referencing. FRAMES will not provide any checks for this condition. It is up to the user to know and maintain this protocol.

Minimum and Maximum

When defining a variable, restraints can be placed on the data to indicate acceptable values. These restraints are accomplished through the minimum and maximum fields. Minimum and maximum values mean different things for different data types:

  • logical values - no effect
  • float values - [min > = float > = max]
  • integer values - [min > = integer > = max]
  • string values - [min > = length of string > = max].

In addition, as shown in the table below, there are special cases for some minimum and maximum values.

Special Cases of Minimum and Maximum Values

Minimum Maximum Meaning
0 *blank 0 > = value = MAX
*blank 0 MIN > = value > 0
0 0 MIN > value > = MAX
* Cannot be represented within the Framework Development Environment.
User must use text editor to make changes.

Measure and Unit

Data within a variable can specify the type of measure/unit. This ability allows FRAMES 2.0 to automatically convert between mediums without addition input from the user. All data associated with a variable within a dictionary must use the same unit of measure. For example, it is not possible for a single variable in a dictionary to treat some values as seconds and others as nanoseconds. See the documentation for the Conversion Editor for additional information.

Stochastic

Stochastic is a true or false value that signifies whether a variable's data can be modified. If the stochastic flag is set to true, the variable's data cannot not be modified.

Preposition

The preposition of a variable is used to describe, in English, how a variable is used in communication with other variables. Typical prepositions for a variable include the "for," "at," or "is" prepositions.

Index

Variables have the capability to reference other variables to set and retrieve data. Currently in FRAMES 2.0, a variable has a limit of referencing up to six other variables. Variables can only reference other variables with a dimension less than two (meaning that a variable can only reference against a list or singular value). The order in which indexing variables are defined is used to identify how to store and retrieve data. Each indexing variable acts as a filter over the data in question. If more than one indexing variable exists, the data can be thought of as going through multiple filters until only one solution remains.

When adding an indexing variable, the starting variable depends on other data to add or retrieve data from its location in a dataset. To add an indexing variable using the Dictionary Editor, the user selects a variable and clicks the "Add Index" button, which brings up a form. The user then selects the variable to reference and clicks the "Add Index Variable" button.

To delete an indexing variable using the Dictionary Editor, the user selects a variable and then an associated indexing variable and clicks on the "Del Index" button. On confirmation, the Dictionary Editor will remove the idexing variable.

Because the order of indexing variables is important to adding and retrieving data, the Dictionary Editor includes the ability to "promote" and "demote" an indexing variable up or down in the list. To promote an indexing variable, the user selects the variable and associated indexing variable and clicks the "Up" button. To demote an indexing variable, the user selects the variable and associated indexing variable and clicks the "Down" button.

Manipulating Dictionaries

Dictionaries themselves can also be manipulated from the Dictionary Editor, including adding a dictionary and deleting a dictioary. Dictionaries can be added in two ways: by creating an entirely new dictionary and by opening a dictionary that already exists but has not been added to the list. In both cases, FRAMES uses system files to store information about the dictionary.

To add a new dictionary, the user selects the appropriate node under system developer or model developer (for boundary condition or model input dictionaries, respectively) to select privilege, then clicks on the "New Dictionary" button. On the Open File form, the user enters a name that does not already exist. On confirmation, the Dictionary Editor will prompt the user to create the file. On confirmation, the Dictionary Editor creates a new file, which should appear in both the list and in the tree beneath the current selected node.

To open an existing dictionary, the user selects the appropriate node under system developer or model developer (for boundary condition or model input dictionaries, respectively) to select privilege, then clicks on the "Open Dictionary" button. On the Open File form, the user selects a dictionary that has not already been added to the list and opens the file. The Dictionary Editor adds the new dictionary to the list and tree beneath the current selected node.

To delete a dictionary, the user selects the appropriate node under system developer or model developer (for boundary condition or model input dictionaries, respectively) to select privilege, highlights the dictionary of interest, then clicks on the "Delete Dictionary" button. On confirmation, the Dictionary Editor deletes the selected dictionary unless that dictionary has been referenced by another dictionary or is used by any module its connection scheme.

Publishing Dictionaries Using the Linkage Server

The Linkage Server is an online database for publishing and retrieving FRAMES modules and dictionaries . FRAMES automatically checks for the latest version when a user attempts to publish a dictionary to the Linkage Server. If the Linkage Server's version is newer, a message box prompts the user for confirmation to overwrite the online dictionary.

To publish a dictionary to the Linkage Server from the Dictionary Editor, the user selects a dictionary from the list of available dictionaries and clicks the "Publish Online" button. To download a dictionary from the Linkage Server, the user selects the Linkage Server from the Tools menu, bringing up the Linkage Server Updates form. Modules appear at the left, with associated dictionaries beneath them. Icons associated with a dictionary or module in the Linkage Server Updates form define the relationship between files on the computer where FRAMES is residing and files on the Linkage Server database. The user selects a dictionary from the Linkage Server Updates form and clicks the "Update Dictionary" button. The Linkage Server downloads the dictionary into FRAMES.


Battelle Logo
Home | Security and Privacy | Contact Us