XTCE12 — Derived Issue: Update integer 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 integer alarm definitions

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

Some aspects of the IntegerParameterType 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.

Also, some of the XSD types used in the Integer parameters are also used by the Float parameters. As a result, that parameter type will also be updated to the extent appropriate.

The creation of the new NumericContextAlarmListType occurred in a previous resolution. For this resolution, first the IntegerParameterType has updated documentation.

The current state of the proposal shows the complexType IntegerParameterType as such:

<complexType name="IntegerParameterType">
<complexContent>
<extension base="xtce:IntegerDataType">
<sequence>
<element name="DefaultAlarm" type="xtce:NumericAlarmType" minOccurs="0"/>
<element name="ContextAlarmList" type="xtce:NumericContextAlarmListType" minOccurs="0"/>
</sequence>
</extension>
</complexContent>
</complexType>

Add documentation elements to the schema changing the form of the definition to:

<complexType name="IntegerParameterType">
<annotation>
<documentation xml:lang="en">Describe an integer parameter type. Several are supported. Calibrated integer to integer relationships should be described with this data type. Use the integer data encoding to define calibrators. Joins float as one of the numerics. See IntegerDataEncoding and IntegerDataType.</documentation>
</annotation>
<complexContent>
<extension base="xtce:IntegerDataType">
<sequence>
<element name="DefaultAlarm" type="xtce:NumericAlarmType" minOccurs="0">
<annotation>
<documentation xml:lang="en">Default alarm definitions are those which do not adjust definition logic based on the value of other parameters. Other parameters may participate in the determination of an alarm condition for this parameter, but the definition logic of the alarm on this parameter is constant. If the alarming logic on this parameter changes based on the value of other parameters, then it is a ContextAlarm and belongs in the ContextAlarmList element.</documentation>
</annotation>
</element>
<element name="ContextAlarmList" type="xtce:NumericContextAlarmListType" minOccurs="0">
<annotation>
<documentation xml:lang="en">Context alarm definitions are those which adjust the definition logic for this parameter based on the value of other parameters. A context which evaluates to being in effect, based on the testing of another parameter, takes precedence over the default alarms in the DefaultAlarm element. If the no context alarm evaluates to being in effect, based on the testing of another parameter, then the default alarm definitions from the DefaultAlarm element will remain in effect. If multiple contexts evaluate to being in effect, then the first one that appears will take precedence.</documentation>
</annotation>
</element>
</sequence>
</extension>
</complexContent>
</complexType>

Next update the documentation content for the complexType NumericContextAlarmListType. The current proposed content of this type is:

<complexType name="NumericContextAlarmListType">
<sequence>
<element name="ContextAlarm" type="xtce:NumericContextAlarmType" maxOccurs="unbounded"/>
</sequence>
</complexType>

Add documentation such that the definition appears as:

<complexType name="NumericContextAlarmListType">
<annotation>
<documentation xml:lang="en">An ordered collection of numeric alarms associated with a context. A context is an alarm definition on a parameter which is valid only in the case of a test on the value of other parameters. Process the contexts in list order. Used by both FloatParameterType and IntegerParameterType. See NumericContextAlarmType.</documentation>
</annotation>
<sequence>
<element name="ContextAlarm" type="xtce:NumericContextAlarmType" maxOccurs="unbounded">
<annotation>
<documentation xml:lang="en">A contextual alarm definition for the parameter that uses this type that is valid when a test against the value of one or more other parameters evaluates to true.</documentation>
</annotation>
</element>
</sequence>
</complexType>

Next update the documentation content for the complexType NumericContextAlarmType. The current proposed content of this type is:

<complexType name="NumericContextAlarmType">
<annotation>
<documentation xml:lang="en">Context alarms are applied when the ContextMatch is true. Context alarms override Default alarms</documentation>
</annotation>
<complexContent>
<extension base="xtce:NumericAlarmType">
<sequence>
<element name="ContextMatch" type="xtce:ContextMatchType"/>
</sequence>
</extension>
</complexContent>
</complexType>

Add documentation such that the definition appears as:

<complexType name="NumericContextAlarmType">
<annotation>
<documentation xml:lang="en">Describe a parameter dependent context, that when evaluates to true, enables the use of this alarm definition. See ContextMatchType and NumericAlarmType.</documentation>
</annotation>
<complexContent>
<extension base="xtce:NumericAlarmType">
<sequence>
<element name="ContextMatch" type="xtce:ContextMatchType">
<annotation>
<documentation xml:lang="en">Contains the evaluation criteria for a parameter dependent test, that when evaluates to true, enables this alarm definition.</documentation>
</annotation>
</element>
</sequence>
</extension>
</complexContent>
</complexType>

The previous definition of the complexType AlarmRangesType gets updated documentation. The current proposed definition of AlarmRangesType is:

<complexType name="AlarmRangesType">
<annotation>
<documentation xml:lang="en">Contains five ranges: Watch, Warning, Distress, Critical, and Severe each in increasing severity. Normally, only the Warning and Critical ranges are used and the color yellow is associated with Warning and the color red is associated with Critical. The ranges given are valid for numbers lower than the min and higher than the max values. These ranges should not overlap, but if they do, assume the most severe range is to be applied. All ranges are optional and it is quite allowed for there to be only one end of the range. Range values are in calibrated engineering units.</documentation>
</annotation>
<sequence>
<element name="WatchRange" type="xtce:FloatRangeType" minOccurs="0"/>
<element name="WarningRange" type="xtce:FloatRangeType" minOccurs="0"/>
<element name="DistressRange" type="xtce:FloatRangeType" minOccurs="0"/>
<element name="CriticalRange" type="xtce:FloatRangeType" minOccurs="0"/>
<element name="SevereRange" type="xtce:FloatRangeType" minOccurs="0"/>
</sequence>
</complexType>

Replace the definition above with a new complexType that has additional annotation:

<complexType name="AlarmRangesType">
<annotation>
<documentation xml:lang="en">Describe up to six ranges where either less severe ranges are a subset of more severe ranges (outside), or more severe ranges are a subset of less severe ranges (inside). In both forms, the undefined least severe range is normal. Range values are in calibrated engineering units. See FloatRangeType.</documentation>
</annotation>
<complexContent>
<extension base="xtce:BaseAlarmType">
<sequence>
<element name="WatchRange" type="xtce:FloatRangeType" minOccurs="0">
<annotation>
<documentation xml:lang="en">A range of least concern. Considered to be below the most commonly used Warning level.</documentation>
</annotation>
</element>
<element name="WarningRange" type="xtce:FloatRangeType" minOccurs="0">
<annotation>
<documentation xml:lang="en">A range of concern that represents the most commonly used minimum concern level for many software applications.</documentation>
</annotation>
</element>
<element name="DistressRange" type="xtce:FloatRangeType" minOccurs="0">
<annotation>
<documentation xml:lang="en">A range of concern in between the most commonly used Warning and Critical levels.</documentation>
</annotation>
</element>
<element name="CriticalRange" type="xtce:FloatRangeType" minOccurs="0">
<annotation>
<documentation xml:lang="en">A range of concern that represents the most commonly used maximum concern level for many software applications.</documentation>
</annotation>
</element>
<element name="SevereRange" type="xtce:FloatRangeType" minOccurs="0">
<annotation>
<documentation xml:lang="en">A range of highest concern. Considered to be above the most commonly used Critical level.</documentation>
</annotation>
</element>
</sequence>
<attribute name="rangeForm" type="xtce:RangeFormType" default="outside">
<annotation>
<documentation xml:lang="en">A value of outside specifies that the most severe range is outside all the other ranges: -severe -critical -distress -warning -watch normal +watch +warning +distress +critical +severe. A value of inside "inverts" these bands: -green -watch -warning -distress -critical severe +critical +distress +warning +watch. The most common form used is "outside" and is the default.</documentation>
</annotation>
</attribute>
</extension>
</complexContent>
</complexType>

Next, in the complexType ChangeAlarmRangesType, there is a documentation update and also two attribute schema type updates. The current proposed definition for the ChangeAlarmRangesType is:

<complexType name="ChangeAlarmRangesType">
<annotation>
<documentation xml:lang="en">ChangeAlarmRanges are used to trigger alarms when the parameter value's rate-of-change is either too fast or too slow. The change may be with respect to time (the default) or with respect to samples (delta alarms) - the changeType attribute determines this. The change may also be ether relative (as a percentage change) or absolute as set by the changeBasis attribute. The alarm also requires the spanOfInterest in both samples and seconds to have passed before it is to trigger. For time based rate of change alarms, the time specified in spanOfInterestInSeconds is used to calculate the change. For sample based rate of change alarms, the change is calulated over the number of samples specified in spanOfInterestInSeconds.</documentation>
</annotation>
<complexContent>
<extension base="xtce:AlarmRangesType">
<attribute name="changeType" type="xtce:ChangeSpanType" default="changePerSecond"/>
<attribute name="changeBasis" type="xtce:ChangeBasisType" default="absoluteChange"/>
<attribute name="spanOfInterestInSamples" type="positiveInteger" default="1"/>
<attribute name="spanOfInterestInSeconds" type="decimal" default="0"/>
</extension>
</complexContent>
</complexType>

The updated definition is:

<complexType name="ChangeAlarmRangesType">
<annotation>
<documentation xml:lang="en">Describe an alarm when the parameter value's rate-of-change is either too fast or too slow. The change may be with respect to time (the default) or with respect to samples (delta alarms). Use the changeType attribute to select the type: changePerSecond (time) or changePerSample (delta). The change may also be ether relative (as a percentage change) or absolute as set by the changeBasis attribute. (Delta alarms are typically absolute but percentage is conceivable). The alarm also requires the spanOfInterest in both samples and seconds to have passed before it is to trigger. For time based rate of change alarms, the time specified in spanOfInterestInSeconds is used to calculate the change. For sample based rate of change alarms, the change is calculated over the number of samples specified in spanOfInterestInSamples. A typical delta alarm would set: changeType=changePerSample, changeBasis=absoluteChange, spanOfInterestInSamples=1. A typical time based version would set: changeType=changePerSecond, changeBasis=percentageChange, and spaceOfInterestInSeconds=1. To set the ranges use maxInclusive, the following definition applies: | Normal.maxInclusive | &lt;= | Watch.maxInclusive | &lt;= | Warning.maxInclusive | &lt;= | Distress.maxInclusive | &lt;= | Critical.maxInclusive | &lt;= | Severe.maxInclusive |. And it is further assumed the absolute value of each range and sampled value it taken to evaluate the alarm. See NumericAlarmType.</documentation>
</annotation>
<complexContent>
<extension base="xtce:AlarmRangesType">
<attribute name="changeType" type="xtce:ChangeSpanType" default="changePerSecond"/>
<attribute name="changeBasis" type="xtce:ChangeBasisType" default="absoluteChange"/>
<attribute name="spanOfInterestInSamples" type="xtce:PositiveLongType" default="1"/>
<attribute name="spanOfInterestInSeconds" type="double" default="0"/>
</extension>
</complexContent>
</complexType>

The last step for this resolution is to update the documentation for the complexType NumericAlarmType. The current state of this definition in the proposed XSD is:

<complexType name="NumericAlarmType">
<annotation>
<documentation xml:lang="en">Alarms associated with numeric data types</documentation>
</annotation>
<complexContent>
<extension base="xtce:AlarmType">
<sequence>
<element name="StaticAlarmRanges" type="xtce:AlarmRangesType" minOccurs="0">
<annotation>
<documentation xml:lang="en">StaticAlarmRanges are used to trigger alarms when the parameter value passes some threshold value</documentation>
</annotation>
</element>
<element name="ChangeAlarmRanges" type="xtce:ChangeAlarmRangesType" minOccurs="0"/>
</sequence>
</extension>
</complexContent>
</complexType>

Update the definition to the following to enhance the documentation:

<complexType name="NumericAlarmType">
<annotation>
<documentation xml:lang="en">Describe alarm conditions specific to the numeric data types, extends the basic AlarmType with StaticAlarmRanges and ChangeAlarmRanges. See FloatParameterType and IntegerParameterType.</documentation>
</annotation>
<complexContent>
<extension base="xtce:AlarmType">
<sequence>
<element name="StaticAlarmRanges" type="xtce:AlarmRangesType" minOccurs="0">
<annotation>
<documentation xml:lang="en">StaticAlarmRanges are used to trigger alarms when the parameter value passes some threshold value.</documentation>
</annotation>
</element>
<element name="ChangeAlarmRanges" type="xtce:ChangeAlarmRangesType" minOccurs="0">
<annotation>
<documentation xml:lang="en">ChangeAlarmRanges are used to trigger alarms when the parameter value changes by a rate or quantity from a reference.</documentation>
</annotation>
</element>
</sequence>
</extension>
</complexContent>
</complexType>