.. highlightlang:: us

.. index:: nc_open

.. _nc_open:

nc_open
=======

.. us.tag  nc_open ENGLISH NC_open Changed5400 Changed5401

:ref:`nc_open` opens an existing data file.

.. function::  ncid = nc_open(ssFileName)
               ncid = nc_open(ssFileName, nOpenMode)

.. us.return

**Return Value**

If the function succeeds, the return value is the handle of the netCDF file. If
the function fails, the return value is -1.

.. us.params

**Parameters**

.. uparam:: ssFileName

   *ssFileName* is the complete file name.

.. uparam:: nOpenMode

   *nOpenMode* is:

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

      * - Value
        - Meaning
      * - NC_WRITE
        - Opens the file for writing.
      * - NC_NOWRITE
        - Opens the file read-only.

   Falls *nOpenMode* nicht angegeben wird, wird ``NC_WRITE`` verwendet.

.. us.comment

**Comment**

R2012.1 New reference Counter: If a file *ssFileName* is opened multiple times
in one process without invoking :ref:`nc_close` each call of :ref:`nc_open` will
return the identical *ncid*. The parameter *nOpenMode* will be ignored if the
file is already open. :ref:`nc_open` only returns the identical *ncid* if
the file name *ssFileName* is exactly the same for all invokations.

If a process is trying to open an NC file that is already open by another process
with write mode ``NC_WRITE`` it can only be opened in ``NC_NOWRITE`` mode. 

Write protected NC files can only be opened with ``NC_NOWRITE``.

.. us.example

**Example**

::

   ncid = nc_open("d:\\dat\\test.nc", NC_NOWRITE);
   if (ncid == -1) {
       error();
   }
   ...
   nc_close(ncid);

.. us.history

**History**

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

   * - Version
     - Description
   * - R2012.1 (5.40.1)
     - Reference counter added: see comment.
   * - R2012 (5.40.0)
     - Call with only *ssFileName*.

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

:sub:`id-1781578`