GUI Control Data Representation

The GUI Control Data Types define the data entered by simulation users during model configuration time. One important feature in this type system is that it allows data to be dynamically typed, meaning that an attribute may be declared as having multiple types given some restrictions. The dynamic typing system provides simulation users with great flexibility and, at times, simplicity in entering model data. For example, a number field in a part may also accept a symbolic parameter so that the numeric value can be assigned in the parent assembly. In this section, we will provide you with the reference information on the data representation for GUI Control Types.

Character Sets

The character sets defined below are used in the Extended Backus-Naur Form (EBNF) syntax rules in the following sections.

<letter> ::= 'A'..'Z' | 'a'..'z'

<digit> ::= '0'..'9'

Identifiers

An identifier represents the name of an entity.

Syntax

<idtail> ::= <letter> <idtail> | <digit> <idtail> |

'-' <idtail> | lambda

where lambda represents an empty string.

Description

From the syntax, we know that <id> must be at least a letter, optionally followed by letters, digits, or hyphens (-).

Example

Valid identifiers: A1, GlobalValue, Global-Value, and S36.

Invalid identifiers: 747, 12PM, -Input, $Money, and ~abc.

Class Names

A class name identifies a class. Because SansGUI supports multiple levels of classes in tree-like structures, the class names can represent the whole class path from the root or merely the name of the class at its given level.

Syntax

<classtail>::= '.' <classID> | lambda

where lambda represents an empty string.

Description

The delimiter for multiple levels of classes is a period (.) and the class name at each level is an identifier.

Example

Corporation and S-Corp are examples of valid class names. Entity.Corporation.S-Corp is an example of a full class path.

Object Names

An object name identifies an object.

Syntax

Description

An object name can be either an identifier, or an identifier prepended with the name of the class from which the object is derived. The delimiter between the class and the object identifiers is an underscore (_).

Example

Entity.Corporation.S-Corp_IL-Corp is an example of an object called IL-Corp, derived from class Entity.Corporation.S-Corp.

Part Names

A part name identifies a part.

Syntax

<partend> ::= <letter> <partend> | <digit> <partend> |

'-' <parttail> | lambda

where lambda represents an empty string.

Description

A part name is similar to an identifier except that there is no restriction on the first character being a letter. A part name can also be prepended with the name of the object from which it is derived. The delimiter between the object and the part names is a colon (:).

Example

Entity.Corporation.S-Corp_IL-Corp:Acme is an example of a part with with full class path and object name in the name string.

Link Names

A link name identifies a link.

Syntax

<linkend> ::= <letter> <linkend> | <digit> <linkend> |

'-' <linktail> | lambda

where lambda represents an empty string.

Description

Link names have the same syntax rules as the part names. A link name is similar to an identifier except that there is no restriction on the first character being a letter. A link name can also be prepended with the name of the link object from which it is derived. The delimiter between the object and the link names is a colon (:).

Example

Transaction.Purchase_Material:Transfer0101 is an example of a link with with full class path and object name in the name string.

Port Numbers

A port number identifies a port in a part.

Syntax

<porttail> ::= <digit> <porttail> | lambda

where lambda represents an empty string.

Description

A port number is represented by an integer number. An at-sign (@) character can be used to indicate a port number. It can be also appended to a part name with the @ delimiter.

Example

Entity.Corporation.S-Corp_IL-Corp:Acme@7 is port number 7 in part Acme. @3 is port number 3, given the proper context within a part.

Parts in Assembly Paths

A part can be identified from the class-object-part hierarchy or from the top-assembly-part hierarchy. At times, accessing it from the assembly hierarchy may be more useful. The assembly path syntax of a part is defined for this purpose.

Syntax

<assmtail> ::= '\' <partID> <assmtail> | lambda

where lambda represents an empty string.

Description

Because an optional class path and an object name can be added to the front of a part name, the part path can be either in a long form (with its class and object names) or a short form (without its class and object names).

Example

Assembly_Generic:TOP\Assembly_Generic:Chair\Support_Leg_MiesStyle:LeftLeg is equivalent to the short form TOP\Chair\LeftLeg and Assembly_Generic:TOP\Engine.Diesel_InLine6:Speedo\Cylinder_Cyl-101:cyl-3 is equivalent to the short form TOP\Speedo\Cyl-3.

The delimiter for different levels of assemblies is the backslash (\) character.

GUI Control Types

Number

All numbers are decimals and may have exponent parts. The syntax for numbers is:

<intnum> ::= '1'..'9' <inttail> | '0'

<inttail> ::= <digit> <inttail> | lambda

<fractail> ::= <digit> <fractail> | lambda

<expon> ::= 'E' <expotail> | 'e' <expotail> | lambda

<expofin> ::= <digit> <expofin> | lambda

where lambda represents an empty string. Three number types are supported in SansGUI:

Integer: When specified in a class attribute, a number entered will be rounded to the nearest integer. Integers are represented as signed quantity in 4 byte (32 bit) storage. The range is from -2147483648 to 2147483647.
Real-Single Precision Floating Point: When specified in a class attribute, a number entered will be stored in a 4 byte (float in C, REAL*4 in Fortran) memory. It has 6 to 7 significant digits.
Real-Double Precision Floating Point: When specified in a class attribute, a number entered will be stored in a 8 byte (double in C, REAL*8 in Fortran) memory. It has 15 to 16 significant digits.

The three number types are mutually exclusive. The type is decided by the simulation developer when the class attributes are defined in the Schema Definition. The Number type can be further specified for:

Matrix: A number field may accept a matrix, if the simulation developer chooses to do so. A matrix is a number array with up to two dimensions. The numbers in a matrix should form a complete rectangle or rows and columns. The values within a matrix are enclosed by a pair of square brackets [] and with the numbers separated by spaces or commas (,). A semi-colon (;) is used to start a new row. After the closing bracket (]), a single quote character (') can be appended for matrix transposition to be done immediately. Matrices are stored as a linear array with row or column major storage order specified in the class by the simulation developer. More on the internal data representation can be found in the SG_VALU Data Structure section in the next chapter. The expected sum of all the elements in the matrix can be specified by the simulation developer for checking against the user entered values.
Vector: A number field may also accept a vector, which is a special case of a matrix with either the number of rows or columns set to 1. A vector can be ended with a single quote character (') for transposition. Vectors are stored as a linear array. In addition to checking the sum of all elements, the vector validation rules include checking of monotonic increasing or decreasing relations among the elements in sequence and strictly monotonic increasing or decreasing (disallowing equality).
Unit Conversion: A measuring unit may be associated with a number field. SansGUI performs unit conversion automatically when processing an input value, displaying the value, storing the value, and passing the value to the simulator. The units are specified in the associated unit object defined by the simulation developer.
Currency Format: When the currency format is requested by the simulation developer, the field will be displayed in a currency format with values rounded to the nearest cent (0.01). When it is declared as an integer, the values will be internally stored in cents.
Verification Rules: The verification rules involved in a number field are:

Rule	Description
Non-Zero Value	The value cannot be zero (0).
Default Value	The specified default value is used.
Minimum Value	The specified minimum value (inclusive) is checked.
Maximum Value	The specified maximum value (inclusive) is checked.
Check Sum	The sum of the vector or matrix is checked against a specified value.
Monotonic Increasing	The values of the elements in a vector should be increasing V(n+1) � V(n).
Monotonic Decreasing	The values of the elements in a vector should be decreasing V(n+1) � V(n).
Strictly Monotonic	Similar to the above but without equality.

String

A string is an array of characters terminated by a NULL (ASCII code 0) character. It can be one of the following three types:

Regular String: A regular string contains an array of arbitrary characters (except for the ending NULL). It can be entered by typing in the string itself, or starting with a double quote (") or a single quote (') character. Entering the end quote for a string is optional. The begin and end quotes will not be included in the value of the string. When a string is entered with a starting double quote character, all the double quote characters in the string are converted to hyphens (-). Same rule applies to a single quote started string.
Masked String: A masked string is filtered by an input mask designed by the simulation developer. The non-masking characters in the input mask are literal characters. The value of the masked string will not contain literal characters. For example, an input mask for telephone numbers "(###)###-####" with an input "(123)456-7890" will yield a masked string "1234567890" internally. The mask characters for input masks are:

Mask Character	Input Characters Allowed
#	<digit> as defined in Character Sets above
?	<letter> as defined in Character Sets above
A	<letter> \| <digit> as defined in Character Sets above
U	<letter> and will convert any lower case letter to upper case
L	<letter> and will convert any upper case letter to lower case
&	any ASCII character
\	escape character for representing the above Mask Characters literally

Encrypted String: The string entered by the user is displayed with asterisks (*) and is encrypted before storing in a Project Model or Object Library. The string is decrypted in the SansGUI Data Object and in the textual Model File. Thus, an encrypted string loses its "secrecy" when it is sent to an external process simulator. An example of using an encrypted string is in a password field.

URL / File

A Uniform Resource Locator (URL), a file name, or a file path can be entered with a starting character < (less than sign). The ending character > (greater than sign) is optional and will be appended if not entered. The value is stored as a regular string without the enclosing < > characters. The file path between the bracket is system dependent. If you have future portability concerns, you should use simple file names in the current working directory. You may also assign relative file names and use forward slashes, such as <myDir/myFile.txt>. Other examples are <myFile.txt>, <C:\Temp\scratch.txt>, <http://sansgui.com>, and <\\alpha\Z\myfile.txt>.

Date / Time

A date field contains day, month and year sub-fields in the GUI control. A time field contains hour, minute, second, and AM/PM sub-fields in the GUI control. Each sub-field is represented by an integer internally.

More on the internal representations can be found in the SansGUI Data Type Funneling section.

On-Off Switch

An on-off switch is represented by an integer with the value 0 for off (unchecked) and 1 for on (checked) states of a check box.

Tri-State Switch

A tri-state switch is represented by an integer with -1, 0, and 1 values for negative (-), 0, and positive (+) states, respectively.

Enumerated Items

Enumerated items are simulation developer defined. The indices of the items are stored as an integer with the base item being 0. The base item is also taken as the default value.

Object Reference

An object reference field allows users to enter the name of a reference object. See Object Names section above for the syntax. It can be only the name of the object, if unambiguous; otherwise, the full name with the deriving class path prepended.

Quality

A quality value is represented by a vector of [<Rank> <ConfidenceFactor>] pair. <Rank> is an integer from -3 to +3 and <ConfidencFactor> is a real number from 0.5 to 1.0, inclusively. They are enclosed by square brackets [] as in vectors. The meanings of the ranks are defined by the simulation developer. Generally, ranks -2, 0, and +2 represents low, neutral and high thresholds and the other ranks stand for the two extremes (-3 and +3) and two in-between ranks (-1 and +1). The confidence factor indicates how much confidence the rank is determined. It cannot be less than 0.5 because it would indicate another rank with a more than 0.5 confidence factor.

Symbolic Parameter

A symbolic parameter can be used as a Cross Field Alias (local binding), an Assembly Parameter (local and subassembly binding), or a Case Parameter (global binding). The syntax for a symbolic parameter is:

<parameter> ::= '{' <id> '}'

A parameter name is enclosed by a pair of {} in the GUI control. The <id> is stored as a string without the enclosing braces. Each parameter name must start with a <letter>. Examples of symbolic parameters are {CriticalTemperature}, {valve-opening}, and {fWidth}.

$C:\FH_Suite\htmlgifs\home.gif$

SansGUI Modeling and Simulation Environment Version 1.2

http://protodesign-inc.com