.. highlightlang:: us

.. index:: DocExchangeDataFiles

.. _docexchangedatafiles:

DocExchangeDataFiles
====================

.. us.tag  DocExchangeDataFiles ENGLISH DocSet New5110 Changed5156 Changed5403

:ref:`DocExchangeDataFiles` executes a data exchange for a complete document.

.. function::  bool = DocExchangeDataFiles(hDoc, smMatrix)
               bool = DocExchangeDataFiles(hvPage, smMatrix)
               bool = DocExchangeDataFiles(hvPage, smMatrix, oPara)

.. us.return

**Return Value**

.. us.params

**Parameters**

.. uparam:: hDoc

   *hDoc* is a handle of an UniPlot document.  *hvPage* is a vector with 
   page handles.

.. uparam:: smMatrix

   *smMatrix* is a matrix with 7 columns:

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

      * - Column
        - Alias
        - Description
      * - 1
        - DS_FILE_ORIGIN
        - Original data file name. For Excel files the sheet name can be added to the file name in square brackets.
      * - 2
        - DS_FILE_NCNAME
        - Name of the NC file.
      * - 3
        - DS_FILE_ACTION
        - Action string.
      * - 4
        - DS_FILE_STYLEPROPS
        - 2D style attributes.
      * - 5
        - DS_FILE_STYLEPROPS3D
        - 3D style attributes.
      * - 6
        - DS_FILE_COMMENT
        - Comment string.
      * - 7
        - DS_FILE_RECORDFILTER
        - Record filter: See :ref:`auto_setfilter`

   Valid values for the action string (see example and :ref:`datadata-exchange-(page)`):

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

      * - Value (String)
        - Description 
      * - ``""``
        - (empty string), Exchange data.
      * - ``"UNCHANGED"``
        - ignore datasets.
      * - ``"SETTOZERO"``
        - set to 0. 
      * - ``"SETSTYLEONLY"``
        - Only style properties will be set. The data points will not be modified.

.. uparam:: oPara

   *oPara* is an object created with :ref:`obj_create`. The object can be used
   to pass parameters. The default values are the last interactive 
   specified values.

   .. list-table::
      :header-rows: 1
  
      * - Element
        - Description
      * - bUpdatePlaceholder
        - If TRUE (1): Dollar placeholders will be updated..
      * - nRecordFilter
        - Value = 1: Use Record Filter specified in Data files, Value = 2:Use 
          Record Filter specified in Datasets (Curve), Value = 3: Do not use 
          Record Filter.
      * - bAutoscale
        - If TRUE (1): All axes will be auto scaled.
      * - bResetDatasetScaling
        - If TRUE (1): Scale factor and offset will be set to default 
          values (1, 0).
      * - bDisplayChannelReplaceDialog 
        - If set to TRUE (1), a dialog box is displayed to replace missing channels
          by valid channels.

.. us.example

**Example**

::

   RegisterCommand("Data", "MyDataExchange", "My Data Exchange");
   UserBar_Add("MyDataExchange");
   def MyDataExchange()
   {
       hDoc = AppGetActiveDocument();
       if (hDoc == 0) {
           MessageBoxError("No active Document");
           return FALSE;
       }
       smF = DocGetDataFileList(hDoc);
       smF[1;DS_FILE_ORIGIN] = "c:/programme/uniplot/samples/TEST4.xls [data]";
       smF[1;DS_FILE_COMMENT] = "This is a comment";
       smF[1;DS_FILE_ACTION] = "";  // Exchange data

       obj = [.];
       obj.nRecordFilter = 1; 
       obj.bAutoscale = TRUE; 

       DocExchangeDataFiles(hDoc, smF, obj);

      PageReplot(DocGetActivePage(hDoc));
       return TRUE;
   }

.. us.history

**History**

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

   * - Version
     - Description
   * - R2015.5
     - New column added: DS_FILE_RECORDFILTER
   * - R2012.3
     - New parameter **oPara**
   * - 5.15.6
     - Can be invoked with a page handle to exchange the data for one or more pages.
   * - 5.11.0
     - New.

.. seealso::
   :ref:`overview-documents`,
   :ref:`DocCreate`,
   :ref:`datadata-exchange-(page)`,
   :ref:`DocGetDataFileList`,
   :ref:`DocSetDataFileList`

:sub:`id-608347`