.. highlightlang:: us

.. index:: auto_LoadDataset

.. _auto_loaddataset:

auto_LoadDataset
================

.. us.tag  auto_LoadDataset ENGLISH Changed5514

:ref:`auto_LoadDataset` loads a 1D, 2D, or 3D dataset from a data file opened
with the function :ref:`auto_ImportData`.

.. function::  hData = auto_LoadDataset(ssDiagram, ssYName)
    hData = auto_LoadDataset(ssDiagram, ssXName, ssYName)
    hData = auto_LoadDataset(ssDiagram, ssXName, ssYName, ssZName)
    hData = auto_LoadDataset(hLayer, ssYName)
    hData = auto_LoadDataset(hLayer, ssXName, ssYName)
    hData = auto_LoadDataset(hLayer, ssXName, ssYName, ssZName)

.. us.return

**Return Value**

*hData* is a handle of the new dataset (see example).

.. us.params

**Parameters**

.. uparam:: ssDiagram

   *ssDiagram* is the name of the diagram in which the dataset should be
   displayed.

.. uparam:: hLayer

   *hLayer* is the diagram handle (see :ref:`PageGetLayerHandle`). 

.. uparam:: ssXName

   *ssXName* is the channel name with the x-coordinates. Check the channel name
   spelling in the dialog box :ref:`fileimport-data`.

.. uparam:: ssYName

   *ssYName* is the channel name with the y-coordinates. Check the channel name
   spelling in the dialog box :ref:`fileimport-data`.

.. uparam:: ssZName

   *ssZName* is the channel name with the z-coordinates. Check the channel name
   spelling in the dialog box :ref:`fileimport-data`.

.. us.comment

**Comment**

Notes for curve style files: For 1D and 2D datasets the curve style will be
copied from the curve style file. A counter for each diagram is used to select
the curve style. The first dataset added to the diagram will use the curve style
with index 1. The second dataset will use curve style with index 2 and so on. To
set the counter for a diagram call :ref:`auto_SetDatasetStyle`.

.. us.example

**Example**

If the function is called with only one variable name, a 1D dataset will be
created. Example::

   auto_LoadDataset("Diagram 1", "Signal")

If the function is called with two variables, a 2D diagram will be
created. Example::

   auto_LoadDataset("Diagram 1", "Speed", "Torque")

If the function is called with three variables, a 3D dataset
(contour map) will be created. Example::

   auto_LoadDataset("Diagram 1", "Speed", "Torque", "be")

The following example shows how a dataset is scaled.
The function :ref:`auto_LoadDataset` returns a value (Handle),
which can be used to access the dataset::

   hData = auto_LoadDataset("Diagram 1", "Speed", "Torque")
   if (hData != 0) {
       yscale = 2.0;
       yoffset = 1.0;
       XYSetScaleOffset(hData, [1,0,yscale, yoffset]);
   }

**History**

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

   * - Version
     - Description
   * - R2013.14
     - New first parameter *hLayer*.

.. seealso::
   :ref:`overview-automation`,
   :ref:`auto_LoadTemplate`,
   :ref:`auto_SetTemplate`, 
   :ref:`auto_LoadMatrixDataset`,
   :ref:`auto_LoadCompressorMap`,
   :ref:`PageGetLayerHandle`,
   :ref:`GetParent`

:sub:`id-404676`