.. highlightlang:: us

.. index:: NC_AddFiles

.. _nc_addfiles:

NC_AddFiles
===========

.. us.tag  NC_AddFiles ENGLISH nc.tools New5505 Changed5510 Changed 6011

:ref:`NC_AddFiles` merges NC files into a new NC file by adding data records 
to the destination file. Channels with identical names will be concatenated.

.. function::  oError = NC_AddFiles(svNCAdd, ssNCDest)
    oError = NC_AddFiles(svNCAdd, ssNCDest, svVarNames)
    oError = NC_AddFiles(svNCAdd, ssNCDest, obj)

.. us.return

**Return Value**

Is 0, if no error occurred or an error object, see :ref:`error_create`.

.. us.params

**Parameters**

.. uparam:: svNCAdd

   *svNCAdd* is a vector with NC file names. 

.. uparam:: ssNCDest

   *ssNCDes* is the new NC file name.

.. uparam:: svVarNames

   *svVarNames* is a vector with channel names. 

.. uparam:: obj

   *obj* is an object with the following elements:

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

      * - Name
        - Description
      * - obj.bKeepTimeGaps
        - (BOOL) If TRUE (1), the time channel will not be alterd. If set to FALSE, the 
          time gap will be removed. See comment. Default value is FALSE.
      * - obj.svVarNames
        - (String) Is a vector with channel names. Time channels will be added automatically.
          Default value is "".

.. us.comment

**Comment**

Beginning with R2015.8 data channels which appeared in the second or subsequent
files for the first time but not in the first file will now be added.

The channels must have the identical data type (NC_CHAR or number).

Beginning with R2013.10 data channels from MDF, BLF or Puma Recorder data files
can be concatenated. These files normally contain data with different
sampling rates. The channels with identical sampling rates are generally saved
in one group (dimension).

For each file the time range is determined (t_start and t_end). The time 
channels of the second and all other files is corrected as follows:

   t_offset = t_end[iFile] - t_start[iFile+1] + 0.1;
   t[i] = t[i] + t_offset;
 
A time channel must contain a channel attribute **Type** with the value
**Time Channel**.

The time groups are matched by finding the maximum number of matching channels
in all files. 

The channels are selected by their names. The names in all files must be 
identical. For example, if one MDF file contains the group suffix in the channel
names and the channels in the other file are saved without the group name, the 
function will fail.

The time channels will be added automatically.

.. us.example

**Example**

::

   def _NC_AddFiles(svFiles)
   {
       if (len(svFiles) < 2) {
           return auto_ImportData(svFiles[1]);
       }
       svF = svFiles;
       for (i in 1:len(svFiles)) {
           svF[i] = auto_ImportData(svFiles[i]);
       }
       svFirst = svF[1];
   
       svP = SplitPath(svFiles[1]);
       ssNCDest = sum(svP[1,2,3]) + "Add.nc2";
       oError = NC_AddFiles(svF, ssNCDest);
       if (type(oError) == "error") {
          MessageBoxError("%s\n\nError-No.: %d\n%s", oError.domain, oError.code, oError.message);
          return "";
       }
       return ssNCDest;
   }

**Example**

::

   def test_NC_AddFiles()
   {
      obj= [.];
      obj.bKeepTimeGaps = 1;
      obj.svVarNames = ["Air_pCACDs", "LSU_rLam", "ASMod_dVolEGFld__0_"];
      svNCAdd = "x:\\test-data\\Inca\\" +  ...
          ["IN04N_US06(1).dat.nc2", ....
           "IN04N_US06(1).dat_2.nc2"];
  
      NC_AddFiles(svNCAdd, "T:/Neuer Ordner/aa.nc2", obj);
      NC_Edit("T:/Neuer Ordner/aa.nc2");
   }

.. us.history

**History**

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

   * - Version
     - Description
   * - R2018.11
     - New parameter *obj*.
   * - R2015.8
     - Channels which appeared in the second or subsequent files for the first 
       time but not in the first file will now be added.
   * - R2013.10
     - Data files with different time groups can be concatenated.
   * - R2013.5
     - New.

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

:sub:`id-1284725`