.. highlightlang:: us

.. index:: auto_CalculateNCFormula

.. _auto_calculatencformula:

auto_CalculateNCFormula
=======================

.. us.tag  auto_CalculateNCFormula ENGLISH New5603

:ref:`auto_CalculateNCFormula` adds a calculated channel to an NC file.

.. function::  ssError = auto_CalculateNCFormula(ssNCFile, oFormula)
               ssError = auto_CalculateNCFormula(ncid, oFormula)

.. us.return

**Return Value**

*ssError* is an empty string (``""``), if the formula could be calculated or a
string with an error message.

.. us.params

**Parameters**

.. uparam:: ssNCFile

   *ssNCFile*

.. uparam:: ncid

   *ncid*

.. uparam:: oFormula

   *oFormula* is an object (see example) with the following elements

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

      * - Element
        - Default Value
        - Description
      * - ssFormula
        - required
        - Is the formla text. Example: (speed * torque) / 9549.3. 
          See :ref:`defining-formulas`.
      * - ssOutputName
        - required
        - Is the formual channel name
      * - ssUnit
        - ``""``
        - Is the unit text.
      * - ssDescription
        - ``""``
        - Is a formula description.
      * - ssOnlyIf
        - ``""``
        - Name of a condition. 
      * - ssFormat
        - ``""``
        - Number format: Format description, e.g. %g or %.2lf. 
      * - ssUseSIUnits
        - ``"0"``
        - If set to the value "1", the variables will be 
          converted to SI units, before the formula is evaluated. The result will
          be converted to the specified unit in *ssUnit*. 
      * - rsDeleteICFile
        - TRUE (1)
        - If set to 0 the formula, created in the temp directory will not be 
          deleted.

.. us.comment

**Comment**

See :ref:`formula-interpreter` for more information about how to define a formula.
All channel names used in the formula must exist in the NC file. The formula
may contain function calls. See :ref:`formula-location-identifier` for a list of
valid functions. The formula will not be registered. It will only be calculated
ones. 

**Example**

.. include:: ../include/test_auto_CalculateNCFormula.ic

.. us.history

**History**

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

   * - Version
     - Description
   * - R2014.3
     - New

.. seealso::
   :ref:`overview-automation`,
   :ref:`auto_ImportData`,
   :ref:`defining-formulas`,
   :ref:`obj_create`

:sub:`id-681772`