XTCE12 — Derived Issue: Update enumerated alarm definition types

This new issue is derived from existing issues because it is not possible to attach more than 1 resolution to an issue.

Update alarm type for enumerated alarm definitions

This is the third resolution for the alarm definition issue. The overall resolution is broken up into several smaller resolutions for ease of review.

Some aspects of the EnumeratedParameterType complexType have already been updated in previous issue resolutions. This update is based on the XSD as it exists post-ballot 13. As a result, some of the intended changes were already implemented.

The first step is to update the complexType for EnumerationAlarmLevelType. This gets a documentation element update and a rename of the "enumerationValue" attribute to "enumerationLabel" to be more clear to the user.

<complexType name="EnumerationAlarmLevelType">
<annotation>
<documentation xml:lang="en">Describe an alarm level and its enumeration label to trigger from. See EnumeratedAlarmType and EnumeratedParameterType.</documentation>
</annotation>
<attribute name="alarmLevel" type="xtce:ConcernLevelsType" use="required">
<annotation>
<documentation xml:lang="en">Defines six levels: Normal, Watch, Warning, Distress, Critical and Severe. Typical implementations color the "normal" level as green, "warning" level as yellow, and "critical" level as red. In the case of enumeration alarms, the "normal" is assumed by implementations to be any label not otherwise in an alarm state.</documentation>
</annotation>
</attribute>
<attribute name="enumerationLabel" type="string" use="required">
<annotation>
<documentation xml:lang="en">The enumeration label is the engineering/calibrated value for enumerated types.</documentation>
</annotation>
</attribute>
</complexType>

Next, update the documentation element in the "EnumerationContextAlarmType" complexType to be more descriptive.

<complexType name="EnumerationContextAlarmType">
<annotation>
<documentation xml:lang="en">Describe a context that when true the alarm condition may be evaluated. See ContextMatchType and EnumerationAlarmType.</documentation>
</annotation>
<complexContent>
<extension base="xtce:EnumerationAlarmType">
<sequence>
<element name="ContextMatch" type="xtce:ContextMatchType">
<annotation>
<documentation xml:lang="en">Describe a context in terms of a parameter and value that when true enables the context alarm definition.</documentation>
</annotation>
</element>
</sequence>
</extension>
</complexContent>
</complexType>

Next, update the documentation element in the "EnumerationAlarmListType" complexType to be more descriptive.

<complexType name="EnumerationAlarmListType">
<sequence>
<element name="EnumerationAlarm" type="xtce:EnumerationAlarmLevelType" maxOccurs="unbounded">
<annotation>
<documentation xml:lang="en">Describe an alarm state for an enumeration label where the label is engineer/calibrated value. Note that labels may represent multiple raw/uncalbrated values.</documentation>
</annotation>
</element>
</sequence>
</complexType>

The "EnumerationAlarmType" complexType also gets an update to the documentation annotation. It is significantly expanded from the original text.

<complexType name="EnumerationAlarmType">
<annotation>
<documentation xml:lang="en">Describe alarm conditions specific to the enumeration data type, extends the basic AlarmType with an EnumerationAlarmList. The alarms are described using the label (engineering/calibrated value) of the enumerated parameter. Enumeration labels may represent several raw/uncalibrated values, so as a result, a single alarm definition here may represent multiple raw values in the enumerated parameter. It is not necessary to define an alarm for raw/uncalibrated values that do not map to an enumeration. Implementations should implicitly define this as an alarm case, of which the manifestation of that is program/implementation specific. See EnumeratedParameterType.</documentation>
<appinfo>An additional check needs to be performed to ensure that the enumeration values in the alarms are valid enumeration values for the Parameter</appinfo>
</annotation>
<complexContent>
<extension base="xtce:AlarmType">
<sequence>
<element name="EnumerationAlarmList" type="xtce:EnumerationAlarmListType" minOccurs="0">
<annotation>
<documentation xml:lang="en">List of alarm state definitions for this enumerated type.</documentation>
</annotation>
</element>
</sequence>
<attribute name="defaultAlarmLevel" type="xtce:ConcernLevelsType" default="normal">
<annotation>
<documentation xml:lang="en">Alarm state name for when no enumeration alarms evaluate to true. This defaults to "normal", which is almost always the case. Setting it to another alarm state permits a form of "inverted logic" where the alarm list can specify the normal states instead of the alarm states.</documentation>
</annotation>
</attribute>
</extension>
</complexContent>
</complexType>

Also a relatively minor change to the "EnumerationContextAlarmListType" complexType annotation documentation to expand upon the descriptions.

<complexType name="EnumerationContextAlarmListType">
<annotation>
<documentation xml:lang="en">Describe an ordered collection of context enumeration alarms, duplicates are valid. Process the contexts in list order. See EnumerationContextAlarmType.</documentation>
</annotation>
<sequence>
<element name="ContextAlarm" type="xtce:EnumerationContextAlarmType" maxOccurs="unbounded">
<annotation>
<documentation xml:lang="en">Describe the alarm matching context criteria and the alarm definition itself.</documentation>
</annotation>
</element>
</sequence>
</complexType>

Lastly, update the complexType EnumeratedParameterType to introduce annotation to the alarm definition elements. Replace the existing EnumeratedParameterType with the revised definition below:

<complexType name="EnumeratedParameterType">
<complexContent>
<extension base="xtce:EnumeratedDataType">
<sequence>
<element name="DefaultAlarm" type="xtce:EnumerationAlarmType" minOccurs="0">
<annotation>
<documentation xml:lang="en">Describe labels for this parameter that should be in an alarm state. The default definition applies when there are no context alarm definitions or all the context alarm definitions evaluate to false in their matching criteria.</documentation>
</annotation>
</element>
<element name="ContextAlarmList" type="xtce:EnumerationContextAlarmListType" minOccurs="0">
<annotation>
<documentation xml:lang="en">Describe labels for this parameter that should be in an alarm state when another parameter and value combination evaluates to true using the described matching criteria.</documentation>
</annotation>
</element>
</sequence>
</extension>
</complexContent>
</complexType>