.. highlightlang:: us

.. index:: nc_create

.. _nc_create:

nc_create
=========

.. us.tag  nc_create ENGLISH NC_open Changed560 Changed5400 Changed5509

:ref:`nc_create` creates a new netCDF file.

.. function::   ncid = nc_create(ssFileName)
                ncid = nc_create(ssFileName, nCreateMode)

.. us.return

**Return Value**

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

.. us.params

**Parameters**

.. uparam:: ssFileName

   *ssFileName* is the complete file name.

.. uparam:: nCreateMode

   *nCreateMode* is ``NC_CLOBBER`` or ``NC_NOCLOBBER``.

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

      * - Value
        - Description
      * - NC_CLOBBER
        - If the file already exists, a new file will be created, erasing the
          old file's contents.
      * - NC_NOCLOBBER
        - If the file already exists, :ref:`nc_create` returns -1.

   The following attributes can be specified:

   .. list-table::
      :header-rows: 0

      * - Name
        - Value
        - Description
      * - NC_FORMAT_CLASSIC
        - 0x0
        - creates a standard netCDF data file.
      * - NC_FORMAT_PC
        - 0x10000
        - The byte order of the Intel 80x86 will be used. The created files are
          not compatible to the netCDF file format. The advantage of this flag is
          that reading and writing is much faster.
      * - NC_FORMAT_UP
        - 0x20000
        - (Default) UniPlot data file will be created.

   If the UniPlot data file format is used (NC_FORMAT_UP) the following
   attributes can be specified:

   .. list-table::
      :header-rows: 0
  
      * - Name
        - Value
        - Description
      * - NC_ZLIB_COMPRESSION
        - 0x40000
        - A improved data compression is used. Reading and writing is slower, but
          the files are approx. 30 percent smaller.
      * - NC_LZ4_COMPRESSION
        - 0x100000
        - Fast compression, see https://code.google.com/p/lz4/. Currently not
          used. Old UniPlot version cannot read LZ4 compressed files.
      * - NC_REPACKING
        - 0x80000
        - If attributes or channels are removed, the file will automatically 
          shrink. If this flag is not set the free space will be used to new 
          attributes and channels.

   The ``NC_COMPRESSION`` flag (old) is replaced by ``NC_ZLIB_COMPRESSION``.

.. us.example

**Example**

::

   ncid = nc_create("test.nc2");
   ncid2 = nc_create("test2.nc2", NC_CLOBBER | NC_FORMAT_UP);

.. us.history

**History**

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

   * - Version
     - Description
   * - R2013.9
     - ``NC_LZ4_COMPRESSION``.
   * - R2012.0
     - New Parameter *nCreateMode* added.
   * - 5.6.0
     - New file format with new flags ``NC_FORMAT_UP``, ``NC_COMPRESSION``
       and  ``NC_REPACKING`` (see :ref:`overview-netcdf-files`).

.. seealso::
   :ref:`overview-netcdf-files`,
   :ref:`nc_open`,
   :ref:`nc_close`

:sub:`id-1641987`