FieldClassify()
===============

Use ``FieldClassify()`` to attach a user-defined classification code to a
data field in the table definition metadata. This gives cloud applications extra information that can be
used to interpret and provide more details about field values.

.. admonition:: Syntax

   **FieldClassify** (Class_Code)

   - ``Class_Code`` {*String*} = A string that can contain any code, tag, or text schema that you want your cloud application to interpret.
  
CampbellCloud uses hexadecimal classification codes, but that is only one implementation method.
Other cloud platforms may choose different formats and define their own schema.

CampbellCloud Example 
---------------------
The Classification code is used to define metadata such as:

.. list-table::
   :header-rows: 1

   * - CampbellCloud Code
     - Classification
     - Subclassification
     - Units
     - Abbreviation
     - Aggregate Type
   * - 01010105
     - Temperature
     - Air Temperature
     - Degrees Celsius
     - °C
     - Sample
  
An example classification reference is available at
`campbell-m2i.xyz/classifications <https://www.campbell-m2i.xyz/classifications>`_.

CRBasic Example
---------------

.. important::

   * Use one ``FieldClassify()`` per table output processing instruction 
     (e.g., ``Sample``, ``Average``, ``Totalize``).

   * When repetitions (reps) are used, ``FieldClassify()`` takes a single string 
     containing a comma-separated list of values one for each field.

.. _single-field-example:

**Single Field Example:**

.. code-block:: basic

    DataTable (Air_Temperature,1,-1)
      DataInterval (0,5,Sec,10)
      Sample (1,air_temperature_C,IEEE4)
      FieldClassify("&H01000105")
    EndTable

**Multi-Field Example:**
  
.. code-block:: basic

    DataTable (HygroVUE10,1,-1)
      DataInterval (0,5,Sec,10)
      Sample (4,HygroVUE10,IEEE4)
      FieldClassify ("&H01010101,&H02010101,&H01020101,&H0C060302")
    EndTable

FieldClassify() Output
----------------------

``FieldClassify()`` adds a ``class`` value to each field definition in the
data table metadata topic.

In the `single-field example <single-field-example_>`_, the code assigned to
``air_temperature_C`` appears in the field's ``class`` entry in the metadata
JSON output. In the metadata JSON output, ``FieldClassify("&H01000105")``
appears as decimal value ``16777477``.

**Example Output**

:guilabel:`Subscribe` ``cs/v2/metadata/ABCD-EFGH-1234/metadata/Air_Temperature``

.. code-block:: json

    {
      "fields": {
        "key": [
          "type",
          "settable",
          "size",
          "class",
          "stream"
        ],
        "definitions": {
          "air_temperature_C": [
            "xsd:float",
            false,
            1,
            16777477,
            -1
          ]
        }
      }
    }

When a cloud environment receives this classification code, it is the
responsibility of that cloud application to interpret the value and decide
what action to take. ``FieldClassify()`` provides the metadata, but the
meaning and behavior of the code are defined by the receiving system.