PHENOM Portal Knowledgebase - User contributions [en]

Formatting a CSV for View Import

2024-05-02T18:19:51Z

Dmitry: /* Nested Views */

To bulk import view characteristics, the CSV file should be formatted as described in this article.

== General Column/Data Requirements ==
The following column headers must exist and contain data in each row:
* View_Name
* Characteristic_Name
* Primitive
* Source
* Path
* Measurement

The following columns are optional (for example, the Package columns are only there to specify destination if desired):
* Package_Name
* Package_Description
* Package_Tags
* View_Description
* View_Tags
* Characteristic_Description
* Characteristic_Tags
* Lower_Bound
* Upper_Bound
* Nested_View

The order of the columns is not enforced, it does not have to be in the same order as the suggested format above.

Any additional user-made columns will be ignored and will not interfere with import.

Bulk import can currently import Package, View, and Characteristic elements.

== Column-specific Requirements ==
=== Package Name ===
* Leaving this column blank will default Package to the "Phenom" package.
* Setting this column to an existing Package will default to the first matching Platform Package within the model.
* If there is no matching Package, a new Package will be created within the "Phenom" Package.

=== Package Description ===
Package Description will be imported for new Packages only. Only the first Description for new Packages will be imported.

=== View Name ===
The data in this column for an existing View will be matched to the first View of that name within the model (there should only be one match). If there isn't a matching View, a new View will be created within the "Phenom" Package.

=== View Description ===
View Description will be imported for new Views only. Only the first Description for new Views will be imported.

=== Characteristic Name, Characteristic Description ===
* Characteristic Names must be unique to the View they are imported under.
* The Characteristic must not already exist in the desired View
* Characteristics belonging to different Views may have the same name.

=== Primitive ===
This column isn't case sensitive. Acceptable values: "Char", "Double", "Float", "Long", "Short", "String", "ULong", "UShort", "Octet", "Enumeration".

=== Source, Path, Measurement ===
* Source must exist in the model and must be the Entity/Association projected from the last element in the Path column.
* Path must have valid elements leading up to/ending with the Observable realized by the Measurement.
* Measurement must in the model and realize the Observable at the end of the Path.

''For example: '''AirSystemType''' is projected (through payload) from '''elementID''' which is realized by ''UniqueID_Unbounded_Integer'

=== Lower Bound and Upper Bound ===

* This row must have both a Source and a Path for these values to be valid

=== Nested View ===

* The Nested View must exist in the model and must be the name of a View.
* See Nested Views for changes to other columns

== Tagging New Elements (Optional) ==
Package_Tags, View_Tags, and Characteristic_Tags optional columns can be used to tag new Packages, Views, or Characteristics. Each field can have multiple comma-delimited tags.

The raw CSV must have quotes around fields with commas (Excel normally handles this).

Package_Tags will tag whichever package is chosen - this includes the Phenom package when a package isn't specified in the Package_Name column.

== Nested Views ==
By referencing the name of another view, whether already existing in the model or being added by the same CSV file, in the '''Nested_View''' column, the import can create view sub-structuring or nesting.

In view field rows representing nested views, the '''Source''' and '''Path''' columns represent the perspective path under which the view sub-structure is nested. At the same time, the '''Primitive''', '''Platform_Type''', and '''Measurement''' are not applicable.

By default, all sub-structure nesting view field rows will be inferred to be representing a "private" nesting. This can be made explicit, or toggled off to accomplish a sub-structure import, by using the '''Characteristic_Foreign''' column: if set to "false", the view sub-structure will be private to its nesting view, and an independent import if set to "true".

== Additional Requirements ==
* Data within Package_Name, View_Name, and Characteristic_Name must all begin with a letter, and only contain numbers, letters, or underscores. The data must also not match any of the following reserved words:
** '''IDL Reserved words:'''<p>"and", "begin", "break", "case", "common", "compile_opt", "continue", "do", "else", "end", "endcase", "endelse", "endfor", "endforeach", "endif", "endrep", "endswitch", "endwhile", "eq", "for", "foreach", "forward_function", "function", "ge", "goto", "gt", "if", "inherits", "le", "lt", "mod", "ne", "not", "of", "on_ioerror", "or", "pro", "repeat", "switch", "then", "until", "while", "xor"</p>
** '''OCL Reserved words:'''<p> "abstract", "any", "attribute", "boolean", "case", "char", "component", "const", "consumes", "context", "custom", "default", "double", "emits", "enum", "eventtype", "exception", "factory", "false", "finder", "fixed", "float", "getraises", "home", "import", "in", "inout", "interface", "local", "long", "manages", "module", "multiple", "native", "object", "octet", "oneway", "out", "primarykey", "private", "provides", "public", "publishes", "raises", "readonly", "sequence", "setraises", "short", "string", "struct", "supports", "switch", "true", "truncatable", "typedef", "typeid", "typeprefix", "union", "unsigned", "uses", "valuebase", "valuetype", "void", "wchar", "wstring"</p>
* New Views not already within the model must be unique among elements of type IDLStruct and Enumeration.
* Multidimensional Measurements are supported, however each axis will default to the primitive found within the primitive column (these can be corrected within Phenom later if desired).
* If there are any errors during validation of the CSV file, the model import will not be initiated and a list of errors will be returned. They will be labeled by the row they occur on for convenience.
* There is a 2MB limit in place - if a larger file needs to be imported, it needs to be split up into smaller files.
* In the raw CSV (i.e., as observed from notepad), any field with commas must have surrounding quotes (Excel normally handles this).

Union

2024-02-07T15:30:55Z

Dmitry:

The FACE 3 Technical Standard introduced the ability to document union templates – in PHENOM, these are represented by union [[View|Views]].

== Union Creation ==
Unions cannot be created independently, but rather existing View elements can be converted to be unions. On its [[Data Model Details|Details]] page, a toggle labeled 'Union' is used to change the view element between a union and non-union structure.

Not all views can be changed to be a union type, and so the toggle may be disabled for some view elements in the model. Which views may be transformed into unions is governed by FACE standard rules.

[[File:View_Page_Union_Toggle.png|800px|border|PHENOM views can be converted to unions via a toggle on the Details page.]]

=== Non-Composite (Nesting) Views as Unions ===
For a non-composite view to be converted to a union, three FACE structural requirements must be fulfilled.

First: a union cannot be a “top level” type, but must rather be defined as a sub-type, nested inside the definition of another structure. In a FACE model, this will appear as a template structure that is not housed in its own template node, but is rather defined as a sub-structure in the specification of another template node. In PHENOM, this is represented as a view that is referenced as the type of another view's field - this is what is referred to as "nested attribute". In this case, the field in question should also be marked as "Private", indicating that the nested view is defined in a scope internal to the view in which it is nested.

[[File:Private Union Nesting.png|800px|border|The private nesting of a union view within a top level view.]]

Second: to become a union, a view must have at least one [[View Attribute|attribute]] or field that references an [[Enumerations|enumeration]] as its platform type. In a FACE model, this enumerated field will be selected by the query related to the union template to serve as the discriminant over which the union is switched. In PHENOM, when a user toggles a view to be a union, a drop-down appears next to the switch allowing the selection of the discriminant. This drop-down lists all of the current view's enumeration attributes.

[[File:View Switch Selection.png|800px|border|Selection of an enumeration-based view attribute as a union discriminant.]]

Third: to be eligible for conversion to a union, all of the projections in the view must project the same element. In a FACE model, this is the same rule that applies to all non-composite templates. In PHENOM, this requirement can be satisfied by ensuring that the first element of each attribute's projection path is the same for the selected view.

[[File:Union Projection Uniformity.png|800px|The projected characteristic uniformity among view attributes required of union types.]]

If the union toggle on a given view's page is disabled, it is likely because one of the above requirements is not fulfilled.

=== Assigning Case Literals to Union Fields ===
Once the discriminant of a view has been selected, the attributes of the view can be assigned to the different union cases. Each case is represented by at least one of the literals associated with the discriminant attribute's platform type enumeration. While more than one of the literals can indicate a single case, a given literal can only be associated with at most one case. Only one attribute is allowed to occupy any given case. The view attribute acting as the union's discriminant can also occupy one of the cases.

By expanding a view attribute, a drop-down listing the discriminant enumeration's literals can be used to add literals to that attribute's case. Once selected, the literals of a given attribute's case are shown above the attribute rolename.

[[File:Union Case Selection.png|800px|border|The drop-down listing the discriminant field's enumeration type's literals can be used to select case literals applied to a given field's case. Once selected, they will appear above the relevant field's rolename.]]

=== Composite Views as Unions ===
Composite FACE templates can also be indicated as unions. Mirroring that, in PHENOM, composite views can also be switched to be unions.

Composite unions don't require any additional specifications, such as the indication of an enumeration-based discriminant. Instead, each composition is considered a member of a single case labeled with an integer value corresponding to the compositions index in the composite.

== Union View Export to FACE 3 Queries and Templates ==
Upon exporting a model to the FACE 3 format, PHENOM automatically converts any union views to their appropriate FACE query and template representations.

The template representing any union view is prefixed with the `union` FACE keyword. The discriminant field selected for the view is used as the parameter of the union's switch statement. The view attributes' case literal assignments are converted to case groups in the union template. The union template as a whole is related to a query that reflects the semantics indicated in the view attributes' PHENOM path.

The query and template generated for a given view can be previewed on the view's Details page by expanding the 'Query and Template Preview' section under the attributes listing.

[[File:Union Query Template Preview.png|800px|border|A view of PHENOM's query and template preview for a union view.]]

== Union Structure Code Representation ==
Though interpreted as unions in IDL, the FACE standard dictates C struct and C++/Java class representations of these structures.

Please refer to the [https://publications.opengroup.org/c207 FACE Technical Standard] documents for details on implementing union type structures in code.

Union

2024-02-06T16:28:40Z

Dmitry:

[[File:View_Page_Union_Toggle.png|alt=The toggle to switch a view to a union type on the view element's detail page.|thumb|481x481px|Phenom views can be converted to unions via a toggle on the Details page.]]

The FACE 3 standard introduced the ability to document union templates – in Phenom, these are represented by union [[View|views]].

== Union Creation In Phenom ==
Unions cannot be created independently, but rather existing Phenom view elements can be converted to be unions. On the view element's [[Data Model Details|Details]] page, a toggle labeled 'Union' is used to change view element between a union and non-union structure.

Not all views can be changed to be a union type, and so the toggle may appear disabled for some view elements in a model. Which views may be transformed into unions is governed by FACE standard rules.

=== Non-Composite (Nesting) Views as Unions ===
For a non-composite view to be converted to a union, three FACE structural requirements must be fulfilled.
[[File:Private Union Nesting.png|left|thumb|480x480px|The private nesting of a union view within a top level view.]]
First: a union cannot be a “top level” type, but must rather be defined as a sub-type, nested inside the definition of another structure. In a FACE model, this will appear as a template structure that is not housed in its own template node, but is rather defined as a sub-structure in the specification of another template node. In Phenom, this is represented as a view that is referenced as the type of another view's field - this is what is referred to as "nested attribute". In this case, the field in question should also be marked as "Private", indicating that the nested view is defined in a scope internal to the view in which it is nested.
[[File:View Switch Selection.png|left|thumb|481x481px|Selection of an enumeration-based view attribute as a union discriminant.]]
Second: to become a union, a view must have at least one [[View Attribute|attribute]] or field that references an [[Enumerations|enumeration]] as its platform type. In a FACE model, this enumerated field will be selected by the query related to the union template to serve as the discriminant over which the union is switched. In Phenom, when a user toggles a view to be a union, a drop-down appears next to the switch allowing the selection of the discriminant. This drop-down lists all of the current view's attributes the Platform Type property of which references a platform enumeration element.
[[File:Union Projection Uniformity.png|left|thumb|480x480px|The projected characteristic uniformity among view attributes required of union types.]]
Third: to be eligible for conversion to a union, all of the projections in the view must project the same element. In a FACE model, this is the same rule that applies to all non-composite templates. In Phenom, this requirement can be satisfied by ensuring that the first element of each attribute's projection path is the same for the selected view.

If the union toggle on a given view's page is disabled, is is likely because one of the above requirements is not fulfilled.

==== Assigning Case Literals to Union Fields ====
[[File:Union Case Selection.png|left|thumb|482x482px|The drop-down listing the discriminant field's enumeration type's literals can be used to select case literals applied to a given field's case. Once selected, they will appear above the relevant field's rolename.]]
Once the discriminant of a view has been indicated, the attributes of the view can be assigned to the different union cases. Each case is represented by at least one of the literals associated with the discriminant attribute's platform type enumeration. While more than one of the literals can indicate a single case, only one attribute is allowed to occupy any given case. A given literal is also only allowed to be associated with a single case. The view attribute acting as the union's discriminant can also occupy one of the cases.

The literal assignment UI can be found by expanding a view attribute in Phenom. A drop-down listing the discriminant enumeration's literals found in the view attribute's expanded view is used to add literals to that attribute's case. Once selected, the literals of a given attribute's case are shown above the attribute rolename.

=== Composite Views as Unions ===
Composite FACE templates can also be indicated as unions. Mirroring that, in Phenom, composite views can also be switched to be unions.

Composite unions don't require any additional specifications, such as the indication of an enumeration-based discriminant. Instead, each composition is considered a member of a single case labeled with an integer value corresponding to the compositions index in the composite.

== Union View Export to FACE 3 Queries and Templates ==
[[File:Union Query Template Preview.png|thumb|507x507px|A view of Phenom's query and template preview for a union view.]]
Upon exporting a model to the FACE 3 format, Phenom automatically converts any union views to their appropriate FACE query and template representations.

The template representing any union view is prefixed with the `union` FACE keyword. The discriminant field selected for the view is used as the parameter of the union's switch statement. The view attributes' case literal assignments are converted to case groups in the union template. The union template as a whole is related to a query that reflects the semantics indicated in the view attributes' Phenom paths.

The query and template generated for a given view can be previewed on the view's Details page by expanding the 'Query and Template Preview' section under the attributes listing.

== Union Structure Code Representation ==
Though interpreted as unions in IDL, the FACE standard dictates C struct and C++/Java class representations of these structures.

Please refer to the [https://publications.opengroup.org/c207 FACE Technical Standard] documents for details on implementing union type structures in code.

Union

2024-02-06T16:27:39Z

Dmitry:

[[File:View_Page_Union_Toggle.png|alt=The toggle to switch a view to a union type on the view element's detail page.|frameless|481x481px]]

The FACE 3 standard introduced the ability to document union templates – in Phenom, these are represented by union [[View|views]].

== Union Creation In Phenom ==
Unions cannot be created independently, but rather existing Phenom view elements can be converted to be unions. On the view element's [[Data Model Details|Details]] page, a toggle labeled 'Union' is used to change view element between a union and non-union structure.

Not all views can be changed to be a union type, and so the toggle may appear disabled for some view elements in a model. Which views may be transformed into unions is governed by FACE standard rules.

=== Non-Composite (Nesting) Views as Unions ===
For a non-composite view to be converted to a union, three FACE structural requirements must be fulfilled.
[[File:Private Union Nesting.png|left|thumb|480x480px|The private nesting of a union view within a top level view.]]
First: a union cannot be a “top level” type, but must rather be defined as a sub-type, nested inside the definition of another structure. In a FACE model, this will appear as a template structure that is not housed in its own template node, but is rather defined as a sub-structure in the specification of another template node. In Phenom, this is represented as a view that is referenced as the type of another view's field - this is what is referred to as "nested attribute". In this case, the field in question should also be marked as "Private", indicating that the nested view is defined in a scope internal to the view in which it is nested.
[[File:View Switch Selection.png|left|thumb|481x481px|Selection of an enumeration-based view attribute as a union discriminant.]]
Second: to become a union, a view must have at least one [[View Attribute|attribute]] or field that references an [[Enumerations|enumeration]] as its platform type. In a FACE model, this enumerated field will be selected by the query related to the union template to serve as the discriminant over which the union is switched. In Phenom, when a user toggles a view to be a union, a drop-down appears next to the switch allowing the selection of the discriminant. This drop-down lists all of the current view's attributes the Platform Type property of which references a platform enumeration element.
[[File:Union Projection Uniformity.png|left|thumb|480x480px|The projected characteristic uniformity among view attributes required of union types.]]
Third: to be eligible for conversion to a union, all of the projections in the view must project the same element. In a FACE model, this is the same rule that applies to all non-composite templates. In Phenom, this requirement can be satisfied by ensuring that the first element of each attribute's projection path is the same for the selected view.

If the union toggle on a given view's page is disabled, is is likely because one of the above requirements is not fulfilled.

==== Assigning Case Literals to Union Fields ====
[[File:Union Case Selection.png|left|thumb|482x482px|The drop-down listing the discriminant field's enumeration type's literals can be used to select case literals applied to a given field's case. Once selected, they will appear above the relevant field's rolename.]]
Once the discriminant of a view has been indicated, the attributes of the view can be assigned to the different union cases. Each case is represented by at least one of the literals associated with the discriminant attribute's platform type enumeration. While more than one of the literals can indicate a single case, only one attribute is allowed to occupy any given case. A given literal is also only allowed to be associated with a single case. The view attribute acting as the union's discriminant can also occupy one of the cases.

The literal assignment UI can be found by expanding a view attribute in Phenom. A drop-down listing the discriminant enumeration's literals found in the view attribute's expanded view is used to add literals to that attribute's case. Once selected, the literals of a given attribute's case are shown above the attribute rolename.

=== Composite Views as Unions ===
Composite FACE templates can also be indicated as unions. Mirroring that, in Phenom, composite views can also be switched to be unions.

Composite unions don't require any additional specifications, such as the indication of an enumeration-based discriminant. Instead, each composition is considered a member of a single case labeled with an integer value corresponding to the compositions index in the composite.

== Union View Export to FACE 3 Queries and Templates ==
[[File:Union Query Template Preview.png|thumb|507x507px|A view of Phenom's query and template preview for a union view.]]
Upon exporting a model to the FACE 3 format, Phenom automatically converts any union views to their appropriate FACE query and template representations.

The template representing any union view is prefixed with the `union` FACE keyword. The discriminant field selected for the view is used as the parameter of the union's switch statement. The view attributes' case literal assignments are converted to case groups in the union template. The union template as a whole is related to a query that reflects the semantics indicated in the view attributes' Phenom paths.

The query and template generated for a given view can be previewed on the view's Details page by expanding the 'Query and Template Preview' section under the attributes listing.

== Union Structure Code Representation ==
Though interpreted as unions in IDL, the FACE standard dictates C struct and C++/Java class representations of these structures.

Please refer to the [https://publications.opengroup.org/c207 FACE Technical Standard] documents for details on implementing union type structures in code.

Union

2024-02-06T16:26:44Z

Dmitry: /* Union Structure Representation */

[[File:View Page Union Toggle.png|alt=The toggle to switch a view to a union type on the view element's detail page.|thumb|481x481px|The toggle to switch a view to a union type on the view element's detail page.]]
The FACE 3 standard introduced the ability to document union templates – in Phenom, these are represented by union [[View|views]].

== Union Creation In Phenom ==
Unions cannot be created independently, but rather existing Phenom view elements can be converted to be unions. On the view element's [[Data Model Details|Details]] page, a toggle labeled 'Union' is used to change view element between a union and non-union structure.

Not all views can be changed to be a union type, and so the toggle may appear disabled for some view elements in a model. Which views may be transformed into unions is governed by FACE standard rules.

=== Non-Composite (Nesting) Views as Unions ===
For a non-composite view to be converted to a union, three FACE structural requirements must be fulfilled.
[[File:Private Union Nesting.png|left|thumb|480x480px|The private nesting of a union view within a top level view.]]
First: a union cannot be a “top level” type, but must rather be defined as a sub-type, nested inside the definition of another structure. In a FACE model, this will appear as a template structure that is not housed in its own template node, but is rather defined as a sub-structure in the specification of another template node. In Phenom, this is represented as a view that is referenced as the type of another view's field - this is what is referred to as "nested attribute". In this case, the field in question should also be marked as "Private", indicating that the nested view is defined in a scope internal to the view in which it is nested.
[[File:View Switch Selection.png|left|thumb|481x481px|Selection of an enumeration-based view attribute as a union discriminant.]]
Second: to become a union, a view must have at least one [[View Attribute|attribute]] or field that references an [[Enumerations|enumeration]] as its platform type. In a FACE model, this enumerated field will be selected by the query related to the union template to serve as the discriminant over which the union is switched. In Phenom, when a user toggles a view to be a union, a drop-down appears next to the switch allowing the selection of the discriminant. This drop-down lists all of the current view's attributes the Platform Type property of which references a platform enumeration element.
[[File:Union Projection Uniformity.png|left|thumb|480x480px|The projected characteristic uniformity among view attributes required of union types.]]
Third: to be eligible for conversion to a union, all of the projections in the view must project the same element. In a FACE model, this is the same rule that applies to all non-composite templates. In Phenom, this requirement can be satisfied by ensuring that the first element of each attribute's projection path is the same for the selected view.

If the union toggle on a given view's page is disabled, is is likely because one of the above requirements is not fulfilled.

==== Assigning Case Literals to Union Fields ====
[[File:Union Case Selection.png|left|thumb|482x482px|The drop-down listing the discriminant field's enumeration type's literals can be used to select case literals applied to a given field's case. Once selected, they will appear above the relevant field's rolename.]]
Once the discriminant of a view has been indicated, the attributes of the view can be assigned to the different union cases. Each case is represented by at least one of the literals associated with the discriminant attribute's platform type enumeration. While more than one of the literals can indicate a single case, only one attribute is allowed to occupy any given case. A given literal is also only allowed to be associated with a single case. The view attribute acting as the union's discriminant can also occupy one of the cases.

The literal assignment UI can be found by expanding a view attribute in Phenom. A drop-down listing the discriminant enumeration's literals found in the view attribute's expanded view is used to add literals to that attribute's case. Once selected, the literals of a given attribute's case are shown above the attribute rolename.

=== Composite Views as Unions ===
Composite FACE templates can also be indicated as unions. Mirroring that, in Phenom, composite views can also be switched to be unions.

Composite unions don't require any additional specifications, such as the indication of an enumeration-based discriminant. Instead, each composition is considered a member of a single case labeled with an integer value corresponding to the compositions index in the composite.

== Union View Export to FACE 3 Queries and Templates ==
[[File:Union Query Template Preview.png|thumb|507x507px|A view of Phenom's query and template preview for a union view.]]
Upon exporting a model to the FACE 3 format, Phenom automatically converts any union views to their appropriate FACE query and template representations.

The template representing any union view is prefixed with the `union` FACE keyword. The discriminant field selected for the view is used as the parameter of the union's switch statement. The view attributes' case literal assignments are converted to case groups in the union template. The union template as a whole is related to a query that reflects the semantics indicated in the view attributes' Phenom paths.

The query and template generated for a given view can be previewed on the view's Details page by expanding the 'Query and Template Preview' section under the attributes listing.

== Union Structure Code Representation ==
Though interpreted as unions in IDL, the FACE standard dictates C struct and C++/Java class representations of these structures.

Please refer to the [https://publications.opengroup.org/c207 FACE Technical Standard] documents for details on implementing union type structures in code.

File:Union Query Template Preview.png

2024-02-06T16:25:22Z

Dmitry:

A view of Phenom's query template preview for a union view.

Union

2024-02-06T16:12:34Z

Dmitry:

[[File:View Page Union Toggle.png|alt=The toggle to switch a view to a union type on the view element's detail page.|thumb|481x481px|The toggle to switch a view to a union type on the view element's detail page.]]
The FACE 3 standard introduced the ability to document union templates – in Phenom, these are represented by union [[View|views]]. Though interpreted as unions in IDL, the FACE standard dictates C struct and C++/Java class representations of these structures; please refer to the [https://publications.opengroup.org/c207 FACE Technical Standard] documents for details on implementing union type structures in code.

== Union Creation In Phenom ==
Unions cannot be created independently, but rather existing Phenom view elements can be converted to be unions. On the view element's [[Data Model Details|Details]] page, a toggle labeled 'Union' is used to change view element between a union and non-union structure.

Not all views can be changed to be a union type, and so the toggle may appear disabled for some view elements in a model. Which views may be transformed into unions is governed by FACE standard rules.

=== Non-Composite (Nesting) Views as Unions ===
For a non-composite view to be converted to a union, three FACE structural requirements must be fulfilled.
[[File:Private Union Nesting.png|left|thumb|480x480px|The private nesting of a union view within a top level view.]]
First: a union cannot be a “top level” type, but must rather be defined as a sub-type, nested inside the definition of another structure. In a FACE model, this will appear as a template structure that is not housed in its own template node, but is rather defined as a sub-structure in the specification of another template node. In Phenom, this is represented as a view that is referenced as the type of another view's field - this is what is referred to as "nested attribute". In this case, the field in question should also be marked as "Private", indicating that the nested view is defined in a scope internal to the view in which it is nested.
[[File:View Switch Selection.png|left|thumb|481x481px|Selection of an enumeration-based view attribute as a union discriminant.]]
Second: to become a union, a view must have at least one [[View Attribute|attribute]] or field that references an [[Enumerations|enumeration]] as its platform type. In a FACE model, this enumerated field will be selected by the query related to the union template to serve as the discriminant over which the union is switched. In Phenom, when a user toggles a view to be a union, a drop-down appears next to the switch allowing the selection of the discriminant. This drop-down lists all of the current view's attributes the Platform Type property of which references a platform enumeration element.
[[File:Union Projection Uniformity.png|left|thumb|480x480px|The projected characteristic uniformity among view attributes required of union types.]]
Third: to be eligible for conversion to a union, all of the projections in the view must project the same element. In a FACE model, this is the same rule that applies to all non-composite templates. In Phenom, this requirement can be satisfied by ensuring that the first element of each attribute's projection path is the same for the selected view.

If the union toggle on a given view's page is disabled, is is likely because one of the above requirements is not fulfilled.

==== Assigning Case Literals to Union Fields ====
[[File:Union Case Selection.png|left|thumb|482x482px|The drop-down listing the discriminant field's enumeration type's literals can be used to select case literals applied to a given field's case. Once selected, they will appear above the relevant field's rolename.]]
Once the discriminant of a view has been indicated, the attributes of the view can be assigned to the different union cases. Each case is represented by at least one of the literals associated with the discriminant attribute's platform type enumeration. While more than one of the literals can indicate a single case, only one attribute is allowed to occupy any given case. A given literal is also only allowed to be associated with a single case. The view attribute acting as the union's discriminant can also occupy one of the cases.

The literal assignment UI can be found by expanding a view attribute in Phenom. A drop-down listing the discriminant enumeration's literals found in the view attribute's expanded view is used to add literals to that attribute's case. Once selected, the literals of a given attribute's case are shown above the attribute rolename.

=== Composite Views as Unions ===
Composite FACE templates can also be indicated as unions. Mirroring that, in Phenom, composite views can also be switched to be unions.

Composite unions don't require any additional specifications, such as the indication of an enumeration-based discriminant. Instead, each composition is considered a member of a single case labeled with an integer value corresponding to the compositions index in the composite.

== Union Structure Representation ==

Union

2024-02-06T16:11:36Z

Dmitry:

[[File:View Page Union Toggle.png|alt=The toggle to switch a view to a union type on the view element's detail page.|thumb|481x481px|The toggle to switch a view to a union type on the view element's detail page.]]
The FACE 3 standard introduced the ability to document union templates – in Phenom, these are represented by union [[View|views]]. Though interpreted as unions in IDL, the FACE standard dictates C struct and C++/Java class representations of these structures; please refer to the [https://publications.opengroup.org/c207 FACE Technical Standard] documents for details on implementing union type structures in code.

== Union Creation In Phenom ==
Unions cannot be created independently, but rather existing Phenom view elements can be converted to be unions. On the view element's [[Data Model Details|Details]] page, a toggle labeled 'Union' is used to change view element between a union and non-union structure.

Not all views can be changed to be a union type, and so the toggle may appear disabled for some view elements in a model. Which views may be transformed into unions is governed by FACE standard rules.

=== Non-Composite (Nesting) Views as Unions ===
For a non-composite view to be converted to a union, three FACE structural requirements must be fulfilled.
[[File:Private Union Nesting.png|left|thumb|480x480px|The private nesting of a union view within a top level view.]]
First: a union cannot be a “top level” type, but must rather be defined as a sub-type, nested inside the definition of another structure. In a FACE model, this will appear as a template structure that is not housed in its own template node, but is rather defined as a sub-structure in the specification of another template node. In Phenom, this is represented as a view that is referenced as the type of another view's field - this is what is referred to as "nested attribute". In this case, the field in question should also be marked as "Private", indicating that the nested view is defined in a scope internal to the view in which it is nested.
[[File:View Switch Selection.png|left|thumb|481x481px|Selection of an enumeration-based view attribute as a union discriminant.]]
Second: to become a union, a view must have at least one [[View Attribute|attribute]] or field that references an [[Enumerations|enumeration]] as its platform type. In a FACE model, this enumerated field will be selected by the query related to the union template to serve as the discriminant over which the union is switched. In Phenom, when a user toggles a view to be a union, a drop-down appears next to the switch allowing the selection of the discriminant. This drop-down lists all of the current view's attributes the Platform Type property of which references a platform enumeration element.
[[File:Union Projection Uniformity.png|left|thumb|480x480px|The projected characteristic uniformity among view attributes required of union types.]]
Third: to be eligible for conversion to a union, all of the projections in the view must project the same element. In a FACE model, this is the same rule that applies to all non-composite templates. In Phenom, this requirement can be satisfied by ensuring that the first element of each attribute's projection path is the same for the selected view.

If the union toggle on a given view's page is disabled, is is likely because one of the above requirements is not fulfilled.

==== Assigning Case Literals to Union Fields ====
[[File:Union Case Selection.png|left|thumb|482x482px|The drop-down listing the discriminant field's enumeration type's literals can be used to select case literals applied to a given field's case. Once selected, they will appear above the relevant field's rolename.]]
Once the discriminant of a view has been indicated, the attributes of the view can be assigned to the different union cases. Each case is represented by at least one of the literals associated with the discriminant attribute's platform type enumeration. While more than one of the literals can indicate a single case, only one attribute is allowed to occupy any given case. A given literal is also only allowed to be associated with a single case. The view attribute acting as the union's discriminant can also occupy one of the cases.

The literal assignment UI can be found by expanding a view attribute in Phenom. A drop-down listing the discriminant enumeration's literals found in the view attribute's expanded view is used to add literals to that attribute's case. Once selected, the literals of a given attribute's case are shown above the attribute rolename.

=== Composite Views as Unions ===
Composite FACE templates can also be indicated as unions. Mirroring that, in Phenom, composite views can also be switched to be unions.

Composite unions don't require any additional specifications, such as the indication of an enumeration-based discriminant. Instead, each composition is considered a member of a single case labeled with an integer value corresponding to the compositions index in the composite.

File:Union Case Selection.png

2024-02-06T15:45:14Z

Dmitry:

A view of union case selection in Phenom.

Union

2024-02-06T15:27:35Z

Dmitry: Created page with "The toggle to switch a view to a union type on the view element's detail page. The FACE 3 standard introduced the ability to document union templates – in Phenom, these are represented by union views. Though interpreted as unions in IDL, the FACE standard dictates C struct and C++/Java class representations of these structures;..."

[[File:View Page Union Toggle.png|alt=The toggle to switch a view to a union type on the view element's detail page.|thumb|564x564px|The toggle to switch a view to a union type on the view element's detail page.]]
The FACE 3 standard introduced the ability to document union templates – in Phenom, these are represented by union [[View|views]]. Though interpreted as unions in IDL, the FACE standard dictates C struct and C++/Java class representations of these structures; please refer to the [https://publications.opengroup.org/c207 FACE Technical Standard] documents for details on implementing union type structures in code.

=== Creating a Union ===
Unions cannot be created independently, but rather existing Phenom view elements can be converted to be unions. On the view element's [[Data Model Details|Details]] page, a toggle labeled 'Union' is used to change view element between a union and non-union structure.

Not all views can be changed to be a union type, and so the toggle may appear disabled for some view elements in a model. Which views may be transformed into unions is governed by FACE standard rules.

==== Non-Composite (Nesting) Views as Unions ====
For a non-composite view to be converted to a union, three FACE structural requirements must be fulfilled.
[[File:Private Union Nesting.png|left|thumb|480x480px|The private nesting of a union view within a top level view.]]
First: a union cannot be a “top level” type, but must rather be defined as a sub-type, nested inside the definition of another structure. In a FACE model, this will appear as a template structure that is not housed in its own template node, but is rather defined as a sub-structure in the specification of another template node. In Phenom, this is represented as a view that is referenced as the type of another view's field - this is what is referred to as "nested attribute". In this case, the field in question should also be marked as "Private", indicating that the nested view is defined in a scope internal to the view in which it is nested.
[[File:View Switch Selection.png|left|thumb|481x481px|Selection of an enumeration-based view attribute as a union discriminant.]]
Second: to become a union, a view must have at least one [[View Attribute|attribute]] or field that references an [[Enumerations|enumeration]] as its platform type. In a FACE model, this enumerated field will be selected by the query related to the union template to serve as the discriminant over which the union is switched. In Phenom, when a user toggles a view to be a union, a drop-down appears next to the switch allowing the selection of the discriminant. This drop-down lists all of the current view's attributes the Platform Type property of which references a platform enumeration element.
[[File:Union Projection Uniformity.png|left|thumb|480x480px|The projected characteristic uniformity among view attributes required of union types.]]
Third: to be eligible for conversion to a union, all of the projections in the view must project the same element. In a FACE model, this is the same rule that applies to all non-composite templates. In Phenom, this requirement can be satisfied by ensuring that the first element of each attribute's projection path is the same for the selected view.

File:Union Projection Uniformity.png

2024-02-06T12:02:47Z

Dmitry:

The required projected characteristic uniformity in a union view.

File:Private Union Nesting.png

2024-02-06T12:02:19Z

Dmitry:

The required nesting of a union view in another view.

File:View Switch Selection.png

2024-02-06T12:01:48Z

Dmitry:

The selection of a view discriminant in Phenom.

File:View Page Union Toggle.png

2024-02-06T11:42:39Z

Dmitry:

Location of the toggle which changes a view to a union.

File:Union Type Toggle.png

2024-02-06T11:28:02Z

Dmitry:

The toggle switch which allows changing a view element to a union.