.. highlightlang:: us

.. index:: auto_LoadDataset_CycleIndex
.. index:: auto_LoadDataset_CycleIndexEx

.. _auto_loaddataset_cycleindex:

auto_LoadDataset_CycleIndex
===========================

.. us.tag  auto_LoadDataset_CycleIndex ENGLISH Changed5514

:ref:`auto_LoadDataset` loads a 2D datasets from a data file opened
with the function :ref:`auto_ImportData` or :ref:`nc_open`. A third channel
must contain an index channel. For each value in the index channel a separate
dataset can be created.

.. function::  hvData = hvData = auto_LoadDataset_CycleIndex(ssDiagram, ssXName, ssYName, ssIndexName, bXSort, rvIndex)
    hvData = auto_LoadDataset_CycleIndexEx(hLayer, ncid, ssXName, ssYName, ssIndexName, bXSort)
    hvData = auto_LoadDataset_CycleIndexEx(hLayer, ncid, ssXName, ssYName, ssIndexName, bXSort, rvIndex)

.. us.return

**Return Value**

*hvData* is a vector of handles of the new datasets (see example). In case of
an error, the first handle is 0. 

.. 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:: ssIndexName

   *ssIndexName* is the channel name with the index values. The function expects
   interger values greater than 0, for example 1, 2, 3, etc.

.. uparam:: bXSort

   If *bXSort* is set to TRUE (1), the x-coordinates for each curve are sorted.

.. uparam:: rvIndex

   *rvIndex* is a vector with index values to create.
   If the value 0 is given, alle datasets are created.

.. uparam:: ncid

   *ncid* Identifies the netCDF file, see :ref:`nc_open`.

.. us.comment

**Comment**

The function creates one dataset (curve) for each index value.
The index value must be greater than 0 and an integer value.
Example [1,1,1,2,2,2,2,3,3]. For this index value three cuves are created.

.. us.example

**Example**

::

   hvData = auto_LoadDataset_CycleIndex("Diagramm 1", "CA", "p_cyl1", "Index", TRUE, [1,2,3])
   if (hvData[1] == 0) {
       MessageBoxError("Cannot create dataset '%s, %s, %s'", "CA", "p_cyl1", "Index");
       return TRUE;
   }

**Example**

::

   auto_AddToUI("Examples", "Example 1: Cycle", "RS_Example_cycleindex");
   
   def RS_Example_cycleindex()
   {
       svFile = auto_GetFileNameDialog(1);
       if (svFile[1] == "DLG_CANCEL") {
           return;
       }
       auto_LoadTemplate(GetRootDirectory() + "samples/automate/Example.ipw");
       auto_SetImportOptions(2);
       auto_ImportData(svFile[1]);
       auto_LoadDataset_CycleIndex("Diagramm 1", "EngSpd", "SAETrq", "Index", TRUE, [1,2,3]);
       auto_LoadDataset_CycleIndex("Diagramm 2", "EngSpd", "SAEPwr", "Index", TRUE, 0);  // alle laden
       auto_ScaleAxes();
       auto_UpdatePage();
   } 

**History**

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

   * - Version
     - Description
   * - R2016.6
     - Documentation added

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

:sub:`id-1627322`