Changeset 71 for cf-conventions/trunk/docbooksrc/description-of-the-data.xml

Timestamp:

07/14/08 18:34:49 (7 months ago)

Author:

mlaker1

Message:

Version 1.3, ticket #26

Files:

• cf-conventions/trunk/docbooksrc/description-of-the-data.xml (modified) (2 diffs)

cf-conventions/trunk/docbooksrc/description-of-the-data.xml

@@ -110 +110 @@
-              <entry></entry>
-              <entry>1e-2</entry>
-<emphasis role="deletedtext">deci</emphasis><emphasis role="newtext">centi</emphasis>
+centi
-              <entry>c</entry>
-            </row>
@@ -306 +306 @@
-    <title>Flags</title>
-    <para>
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-      <programlisting>
-  byte current_speed_qc(time, depth, lat, lon) ;
-    current_speed_qc:long_name = "Current Speed Quality" ;
+    <emphasis role="newtext">current_speed_qc:standard_name = "sea_water_speed status_flag" ;</emphasis>
-    current_speed_qc:_FillValue = -128b ;
--127b, 127b
+<emphasis role="newtext">0b, 2b</emphasis><emphasis role="deletedtext">-127b, 127b</emphasis>
-    current_speed_qc:flag_values = 0b, 1b, 2b ;
-    current_speed_qc:flag_meanings = "quality_good sensor_nonfunctional 
-               
+
-      </programlisting>
-    </example>
+    <para>
+      <emphasis role="newtext">The <varname>flag_masks</varname> and <varname>flag_meanings</varname> 
+      attributes describe a number of independent Boolean conditions using bit field notation by setting 
+      unique bits in each <varname>flag_masks</varname> value.  <varname>The flag_masks</varname> attribute 
+      is the same type as the variable to which it is attached, and contains a list of values matching unique 
+      bit fields.  The <varname>flag_meanings</varname> attribute is defined as above, one for each 
+      <varname>flag_masks</varname> value.  A flagged condition is identified by performing a bitwise AND
+      of the variable value and each <varname>flag_masks</varname> value; a non-zero result indicates a 
+      <varname>true</varname> condition.  Thus, any or all of the flagged conditions may be <varname>true</varname>, 
+      depending on the variable bit settings. The following example illustrates the use of <varname>flag_masks</varname>
+      to express six sensor status conditions.</emphasis>
+    </para>
+    <example>
+      <title><emphasis role="newtext">A flag variable, using <varname>flag_masks</varname></emphasis></title>
+      <programlisting><emphasis role="newtext">
+  byte sensor_status_qc(time, depth, lat, lon) ;
+    sensor_status_qc:long_name = "Sensor Status" ;
+    sensor_status_qc:_FillValue = 0b ;
+    sensor_status_qc:valid_range = 1b, 63b ;
+    sensor_status_qc:flag_masks = 1b, 2b, 4b, 8b, 16b, 32b ;
+    sensor_status_qc:flag_meanings = "low_battery processor_fault
+                                      memory_fault disk_fault
+                                      software_fault
+                                      maintenance_required" ;</emphasis>
+      </programlisting>
+    </example>
+    <para>
+      <emphasis role="newtext">The <varname>flag_masks</varname>, <varname>flag_values</varname> and 
+      <varname>flag_meanings</varname> attributes, used together, describe a blend of independent Boolean 
+      conditions and enumerated status codes.  The <varname>flag_masks</varname> and <varname>flag_values</varname>
+      attributes are both the same type as the variable to which they are attached.  A flagged condition 
+      is identified by a bitwise AND of the variable value and each <varname>flag_masks</varname> value; 
+      a result that matches the <varname>flag_values</varname> value indicates a <varname>true</varname> 
+      condition.  Repeated <varname>flag_masks</varname> define a bit field mask that identifies a number 
+      of status conditions with different <varname>flag_values</varname>.  The <varname>flag_meanings</varname>
+      attribute is defined as above, one for each <varname>flag_masks</varname> bit field and 
+      <varname>flag_values</varname> definition.  Each <varname>flag_values</varname> and 
+      <varname>flag_masks</varname> value must coincide with a <varname>flag_meanings</varname> value.  
+      The following example illustrates the use of <varname>flag_masks</varname> and <varname>flag_values</varname>
+      to express two sensor status conditions and one enumerated status code.</emphasis>
+    </para>
+    <example>
+      <title><emphasis role="newtext">A flag variable, using <varname>flag_masks</varname> and <varname>flag_values</varname></emphasis></title>
+      <programlisting><emphasis role="newtext">
+  byte sensor_status_qc(time, depth, lat, lon) ;
+    sensor_status_qc:long_name = "Sensor Status" ;
+    sensor_status_qc:_FillValue = 0b ;
+    sensor_status_qc:valid_range = 1b, 15b ;
+    sensor_status_qc:flag_masks = 1b, 2b, 12b, 12b, 12b ;
+    sensor_status_qc:flag_values = 1b, 2b, 4b, 8b, 12b ;
+    sensor_status_qc:flag_meanings =
+         "low_battery
+          hardware_fault
+          offline_mode calibration_mode maintenance_mode" ;</emphasis>
+      </programlisting>
+    </example>
+    <para>
+      <emphasis role="newtext">In this case, mutually exclusive values are blended with Boolean values 
+      to maximize use of the available bits in a flag value.  The table below represents the four binary 
+      digits (bits) expressed by the <varname>sensor_status_qc</varname> variable in the previous 
+      example.</emphasis>
+    </para>
+    <para>
+      <emphasis role="newtext">Bit 0 and Bit 1 are Boolean values indicating a low battery condition 
+      and a hardware fault, respectively. The next two bits (Bit 2 and Bit 3) express an enumeration 
+      indicating abnormal sensor operating modes.  Thus, if Bit 0 is set, the battery is low and if 
+      Bit 1 is set, there is a hardware fault - independent of the current sensor operating mode.</emphasis>
+    </para>
+    <table frame="all"><title><emphasis role="newtext">Flag Variable Bits (from Example)</emphasis></title>
+      <tgroup cols="4" align="left" colsep="1" rowsep="1">
+        <colspec colwidth="50pt"/>
+        <colspec colwidth="50pt"/>
+        <colspec colwidth="50pt"/>
+        <colspec colwidth="50pt"/>
+        <thead>
+          <row>
+            <entry><emphasis role="newtext">Bit 3 (MSB)</emphasis></entry>
+            <entry><emphasis role="newtext">Bit 2</emphasis></entry>
+            <entry><emphasis role="newtext">Bit 1</emphasis></entry> 
+            <entry><emphasis role="newtext">Bit 0 (LSB)</emphasis></entry> 
+          </row>
+        </thead>
+        <tbody>
+          <row>
+            <entry></entry>
+            <entry></entry>
+            <entry><emphasis role="newtext">H/W Fault</emphasis></entry>
+            <entry><emphasis role="newtext">Low Batt</emphasis></entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </table>
+    <para>
+      <emphasis role="newtext">The remaining bits (Bit 2 and Bit 3) are decoded as follows:</emphasis>
+    </para>
+    <table frame="all"><title><emphasis role="newtext">Flag Variable Bit 2 and Bit 3 (from Example)</emphasis></title>
+      <tgroup cols="3" align="left" colsep="1" rowsep="1">
+        <colspec colwidth="50pt"/>
+        <colspec colwidth="50pt"/>
+        <colspec colwidth="100pt"/>
+        <thead>
+          <row>
+            <entry><emphasis role="newtext">Bit 3</emphasis></entry>
+            <entry><emphasis role="newtext">Bit 2</emphasis></entry> 
+            <entry><emphasis role="newtext">Mode</emphasis></entry> 
+          </row>
+        </thead>
+        <tbody>
+          <row>
+            <entry><emphasis role="newtext">0</emphasis></entry>
+            <entry><emphasis role="newtext">1</emphasis></entry>
+            <entry><emphasis role="newtext">offline_mode</emphasis></entry>
+          </row>
+          <row>
+            <entry><emphasis role="newtext">1</emphasis></entry>
+            <entry><emphasis role="newtext">0</emphasis></entry>
+            <entry><emphasis role="newtext">calibration_mode</emphasis></entry>
+          </row>
+          <row>
+            <entry><emphasis role="newtext">1</emphasis></entry>
+            <entry><emphasis role="newtext">1</emphasis></entry>
+            <entry><emphasis role="newtext">maintenance_mode</emphasis></entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </table>
+    <para>
+      <emphasis role="newtext">The "12b" flag mask is repeated in the <varname>sensor_status_qc</varname>
+      <varname>flag_masks</varname> definition to explicitly declare the recommended bit field masks to 
+      repeatedly AND with the variable value while searching for matching enumerated values. An application 
+      determines if any of the conditions declared in the <varname>flag_meanings</varname> list are 
+      <varname>true</varname> by simply iterating through each of the <varname>flag_masks</varname> and 
+      AND'ing them with the variable. When a result is equal to the corresponding <varname>flag_values</varname>
+      element, that condition is <varname>true</varname>. The repeated <varname>flag_masks</varname> enable 
+      a simple mechanism for clients to detect all possible conditions.</emphasis>
+    </para>
-  </section>
-</chapter>