.. highlightlang:: us

.. _nc_varid:

nc_varid
========

.. index:: nc_varid

.. us.tag  nc_varid ENGLISH NC_Var Changed5145

:ref:`nc_varid` returns the ID of a netCDF variable when given its name.

.. function::  varid = nc_varid(ncid, ssName)

.. us.return

**Return Value**

*varid* is the ID of the variable *ssName*. If an error occurs, *varid* is -1.

.. us.params

**Parameters**

.. uparam:: ncid

   Identifies the netCDF file.

.. uparam:: ssName

   *ssName* is the name of the netCDF variable.

**Comment**

In UniPlot 5.14.5 channel names may contain the following special characters:
``.``, ``-``, ``+``, ``$``, ``#``, ``~``, ``!``, ``^``, ``&``, ``%``. To 
avoid problems with the formula interpreter, data exchange or compatibility
problems, the channel name can be used with underscores instead of the special
characters. Example:  A NC-file contains a the channel ``AI50%+m``. 
The following two calls will return the correct, identical *varid*::

   varid = nc_varid(ncid, "AI50%+m"); 
   varid = nc_varid(ncid, "AI50__m"); 

If the NC file contains channel names which only differ in special characters
the function may return different varids. The reason is that the function 
returns the first channel id that matches the channel name. Example: A NC 
file contains the following two channels ``AI50%+m`` (varid 0) and
``AI50%-m`` (varid 1):

The following call will return the *varid* = 1::

   varid = nc_varid(ncid, "AI50%-m"); 

If called with two underscores the function returns the *varid* of ``AI50%+m``,
*varid* = 0::

   varid = nc_varid(ncid, "AI50__m"); 

To avoid problems, all channel names should be unique even if the special 
characters are replaced by underscores. If the NC files are created with 
UniPlot, the channel names which are only different in the special characters
are enumerated, starting with 0. The first channel name will be unmodified.

.. us.history

**History**

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

   * - Version
     - Description
   * - 5.14.5
     - Special characters in channel names

.. seealso::
   :ref:`overview-netcdf-files`,
   :ref:`nc_create`

:sub:`id-576645`