XML Model Data
One of the supported textual Model File format is the Extensible Markup Language XML Model Data format. The advantages of using this format are:
Cross-platform data format,
Availability of free and commercial parsers,
Simple view from web browsers,
Commercial structure editors and viewers, and
Industry standard format with wide 3rd party support.
An XML Model Data file contains a single tree structure of data in a Project Model. It always starts with an XML header:
<?xml version="1.0"?>
which is followed by the top level <Project Model> element.
This top level tag indicates the root of the data tree. It has the following attributes from the Project Model:
NAME: the name of the Project Model.
DATE: creation date of the Model File.
TIME: creation time of the Model File.
SIMULATOR: the name of the simulator and option, if any, and its version in brackets [ ].
DESCRIPTION: the description and the option, if any, of the simulator.
ORGANIZATION: the company and the group information.
GENERATOR: SansGUI and its version in brackets [ ] for identification purposes.
CREATOR: the licensed user of SansGUI with license number in brackets [ ].
The top level <ProjectModel> and </ProjectModel> tags encapsulate the following second level elements -- CaseParameter, SimulatorObject, ReferenceObject, and ComponentObject.
The <CaseParameters> element contains a list of the third level <Case> elements. Each <Case> tag contains exactly one attribute, NUMBER, indicating its 1-based case number.
The <Case> and </Case> tags encapsulate a fourth level <Parameter> element which has case parameter bindings listed as its attributes. The first case should contain all the bindings and the following cases contains only overriding values. When the value of a parameter is not overridden in a case, the binding value of its previous case should be used.
Each Project Model contains at least one case, even though there may be no parameter defined by the user.
The <SimulatorObjects> element contains a third level <Class> element, the simulation control class in the Project Model. Because the XML Model Data is for an external process simulator, the class shown here is the simulation developer defined class derived from the SimControl.XProc class.
The <Class> tag contains two attributes:
NAME: the full name path of the class.
VERSION: the schema version of the class.
Inside the <Class> and </Class> pair, exactly one fourth level <Object> element is contained for the simulation control object of the Project Model.
The <Object> tag has a NAME attribute, for the object name, followed by the values of the attributes defined in the class by the simulation developer. See XML Object Data and XML Data Values below for more details.
The simulation control object may contain logged attributes. The internal code, defined by the simulation developer, of the logged attributes are listed as <LoggedAttribute> elements inside the <Object> element.
The <ReferenceObjects> element contains all the reference classes as <Class> elements in the third level. The classes are listed by the name order as shown in the Tree View in the SansGUI environment. Each class has two attributes, NAME and VERSION, as described in the <SimulatorObjects> tag. Within each class, all the objects derived from the class are listed as the fourth level elements <Object>.
Each <Object> tag has a NAME attribute, for the name of the object. It is followed by the values of attributes defined in the class. See XML Object Data and XML Data Values below for more details.
Some reference object (such as a Collection object) may contain logged attributes. The internal code, defined by the simulation developer, of the logged attributes are listed as <LoggedAttribute> elements inside the <Object> element.
Similar to <SimulatorObjects> and <ReferenceObjects> tags, the second level <ComponentObjects> tag contains the third level <Class> elements in which lists of the fourth level <Object> elements may exist to represent the component objects in the Project Model. The <Class> tag has NAME and VERSION attributes as described previously. The <Object> tag contains the NAME of the object followed by all the non-port attributes with values of the named object.
Different from reference objects, component objects may have ports explicitly defined with port attributes. The port attributes of a particular port are listed in a fifth level <Port> tag with the port NUMBER leading them. Each <Port> element represents an explicitly defined port; therefore, there may be more than one <Port> elements.
Also different from the objects in <SimulatorObjects> and <ReferenceObjects>, the component objects do not have any <LoggedAttributes>. They may exist only in parts or links derived from component objects.
Following the <Port> elements, <Part> and <Link> are the other two types of the fifth level elements that may exist inside the <Object> tag of the component object. The <Part> tag contains two attributes -- SERIAL and PATH:
SERIAL: the serial number of the part, unique in all parts. It is the serial number of the part's parent assembly times 65536 plus the part number in that assembly. There is a space indentation before the SERIAL field in each part line.
PATH: the name of the part with its full assembly path.
Between the <Part> and </Part> tags, there is a sixth level <Override> element which may contain overriding values of certain attributes found in the part. The overriding values are shown as the values of the attributes in the <Override> element. Also in the sixth level after the <Override> element, there may be <LoggedAttribute> elements indicating the values of these attributes are to be logged during the simulation run.
Similar to <Part> elements, the fifth level <Link> elements describe the contents of Links with an <Override> and, optionally, <LoggedAttribute> elements. The <Link> tag, however, has six attributes:
SERIAL: the serial number of the part, unique in all parts. It is the serial number of the part's parent assembly times 65536 plus the part number in that assembly. There is a space indentation before the SERIAL field in each part line.
PATH: the name of the part with its full assembly path.
PART1: the assembly path of the beginning part, from which the user started to create the link.
PORT1: the port number in PART1 used to attach to the link.
PART2: the assembly path of the ending part, to which the user completed the creation of the link.
PORT2: the port number in PART2 used to attach to the link.
The following is a list of all the tags used in SansGUI XML Model Data files. The leading number in parentheses (n) represent the levels (1-based) of the tags. The built-in attributes names are in upper-case letters. For clarity, only the attribute names are shown. Attributes defined by the simulation developers are listed (not shown) after the built-in attributes. The internal attribute codes are used as their names in the tags. The ellipses (...) show attribute-value pairs for parameter bindings, object values, and overriding values of parts and links.
(1) <ProjectModel NAME DATE TIME SIMULATOR
DESCRIPTION ORGANIZATION
GENERATOR CREATOR>
(2) <CaseParameters>
(3) <Case NUMBER>
(4) <Parameter ...>
(4) </Parameter>
(3) </Case>
(2) </CaseParameters>
(2) <SimulatorObjects>
(3) <Class NAME VERSION>
(4) <Object NAME ...>
(5) <LoggedAttribute> </LoggedAttribute>
(4) </Object>
(3) </Class>
(2) </SimulatorObjects>
(2) <ReferenceObjects>
(3) <Class NAME VERSION>
(4) <Object NAME ...>
(5) <LoggedAttribute> </LoggedAttribute>
(4) </Object>
(3) </Class>
(2) </ReferenceObjects>
(2) <ComponentObjects>
(3) <Class NAME VERSION>
(4) <Object NAME ...>
(5) <Port NUMBER ...>
(5) </Port>
(5) <Part SERIAL PATH>
(6) <Override ...>
(6) </Override>
(6) <LoggedAttribute> </LoggedAttribute>
(5) </Part>
(4) </Object>
(4) <Object NAME ...>
(5) <Link SERIAL PATH
PART1 PORT1 PART2 PORT2>
(6) <Override ...>
(6) </Override>
(6) <LoggedAttribute> </LoggedAttribute>
(5) </Link>
(4) </Object>
(3) </Class>
(2) </ComponentObjects>
(1) <ProjectModel>
All the objects derived from the same class are listed as <Object> elements within the <Class> tag. Although line breaks are not significant in XML files, SansGUI uses the Append Line Break flag defined in the attributes in the class schema to start a new line in order to make the file more readable by the human eyes. The NAME of the object leads all the data values without a line break. The data values of an object are written in the following manners:
Values in an object are listed in the order of the class attribute. They are listed in the format of <AttributeCode>="<Value>" as the attributes in the <Object> tag, where <AttributeCode> is the internal code of the attribute defined in the class schema and <Value> is the actual value of in the object. The value is always quoted by a pair of double quotes which turn the value into a string in XML.
<AttributeCode>="<Value>" bindings are separated by blank spaces as required by XML.
A new line character is appended to the data value line each time when the associated attribute has the Append Line Break flag set.
Values of port attributes in component objects are printed behind all other object values in <Port> tags. The format is the same as <AttributeCode>="<Values>".
Data values in XML Model Data are written as following:
All values are listed as strings enclosed by a pair of double quotes (""). It does not matter whether the original value is a string or not.
Due to XML limitations, any ampersand (&) in a string value is changed into a hyphen (-) and angle brackets (<>) are changed into underscores (_).
Multiple strings in an array attributes are quoted by single quotes ('') with the entire array attribute value quoted by double quotes ("").
When a string is enclosed by double quotes (in cell attributes), all the double quote characters inside the string are converted to single quotes ('). When a string is enclosed by single quotes (in array attributes), all the single quote characters in the string are converted to hyphens (-).
A string of three question marks (???) is used to identify uninitialized (but allowed) data values.
If a variable has an associated unit of measure, the value will be converted to the unit specified by the simulation developer before printed out.
Vectors and matrices are enclosed by pairs of brackets [ ], as in the GUI controls.
Strings are always enclosed by double quotation marks ("). All the double quotes in the string are converted to single quotes (').
Masked strings are printed without the input mask literals.
Encrypted strings are decrypted before printed. Therefore, there is no advantage of using encrypted strings in an external process simulator.
The names of object references are printed as is, without any enclosing characters.
URL / File name enclosing brackets < > are removed due to XML limitations.
On-off switches have integer values 0 and 1 for the off and on states, respectively. The integers are then turned into XML string values.
Tri-state switches have integer values -1, 0 and 1, for the negative, neutral, and positive states, respectively. The integers are then turned into XML string values.
Enumerated items have 0-based integer values associated with the items selected by the user. The integers are then turned into XML string values.
Date values are printed as a string in the format of "yyyy/mm/dd", where yyyy is the year, mm is the month, and dd is the day.
Time values are printed as a string in the format of "hh:mm:ss", where hh is the hour in 24 hour format, mm is the minute, and ss is the second.
Quality values are enclosed by pairs of brackets [ ], as in the GUI controls.
In general, an array of data is printed with 10 data values per line. The entire values in the array are enclosed by a pair of double quotes ("") shown as one single string.
|
|
SansGUI Modeling and Simulation Environment Version 1.2
Copyright © 2000-2003 ProtoDesign, Inc. All rights reserved.