are intended to make variables that contain flag values self describing.
Status codes and Boolean (binary) condition flags
may be expressed with different combinations of
flag_masks attribute definitions.
attributes describe a status flag consisting of mutually exclusive coded values.
flag_values attribute is the same type as the variable to which
it is attached, and contains a list of the possible flag values.
flag_meanings attribute is a string whose value is a blank
separated list of descriptive words or phrases, one for each flag value.
If multi-word phrases are used to describe the flag values, then the words within
a phrase should be connected with underscores. The following example illustrates
the use of flag values to express a speed quality with an enumerated status code.
Example 3.3. A flag variable, using
byte current_speed_qc(time, depth, lat, lon) ; current_speed_qc:long_name = "Current Speed Quality" ; current_speed_qc:standard_name = "sea_water_speed status_flag" ; current_speed_qc:_FillValue = -128b ; current_speed_qc:valid_range = 0b, 2b-127b, 127b ; current_speed_qc:flag_values = 0b, 1b, 2b ; current_speed_qc:flag_meanings = "quality_good sensor_nonfunctional outside_valid_range" ;
attributes describe a number of independent Boolean conditions using bit field notation by setting
unique bits in each
The flag_masks attribute
is the same type as the variable to which it is attached, and contains a list of values matching unique
bit fields. The
flag_meanings attribute is defined as above, one for each
flag_masks value. A flagged condition is identified by performing a bitwise AND
of the variable value and each
flag_masks value; a non-zero result indicates a
true condition. Thus, any or all of the flagged conditions may be
depending on the variable bit settings. The following example illustrates the use of
to express six sensor status conditions.
Example 3.4. A flag variable, using
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" ;
flag_meanings attributes, used together, describe a blend of independent Boolean
conditions and enumerated status codes. The
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
a result that matches the
flag_values value indicates a
flag_masks define a bit field mask that identifies a number
of status conditions with different
attribute is defined as above, one for each
flag_masks bit field and
flag_values definition. Each
flag_masks value must coincide with a
The following example illustrates the use of
to express two sensor status conditions and one enumerated status code.
Example 3.5. A flag variable, using
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" ;
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
sensor_status_qc variable in the previous
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.
The remaining bits (Bit 2 and Bit 3) are decoded as follows:
Table 3.3. Flag Variable Bit 2 and Bit 3 (from Example)
|Bit 3||Bit 2||Mode|
The "12b" flag mask is repeated in the
flag_masks 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
flag_meanings list are
true by simply iterating through each of the
AND'ing them with the variable. When a result is equal to the corresponding
element, that condition is
true. The repeated
a simple mechanism for clients to detect all possible conditions.