.. highlightlang:: none

.. index:: Sequencer-Actions

.. _sequenceractions:

Sequencer Actions
-----------------

Sequences are composed of a list of actions. There are a lot of action types
available which already fulfill recurrent standard task in evaluation
workflows. More specific functionality can be added with script actions.
Actions can be switched on and off manually in the sequencer window which
helps during creation of the workflow. If needed, the on/off swich can be
automated with the "Condition" function. The "Run Mode" function for actions
allows it to loop actions (or even sub sequences) several times in a row (e.g.
to perform the same evaluation for several data files). 

Actions can be copied and pasted via the sequence options menu. Configured
resource files will not be copied within this function, this has to be done
manually (in particular if the destination sequence is in another workspace).

.. index:: Action-Options

Options
=======

The options dialog allows to configure the Condition and the Run Mode of the 
action:

.. image:: S:/uniplot-obj/images/action-options-en.*

.. index:: Action-Condition
.. index:: y^Action_Condition

Condition
=========

If switched on, the action will only run if the Runtime Value fulfills the
comparison.

An activated condition is shown with the purple checkbox background in the
sequence view:

.. image:: S:/uniplot-obj/images/action-condition-en.*

.. index:: Action-RunMode
.. index:: y^Action_RunMode

Run Mode
========

If switched on, the action will run multiple times dependent on the list in
the source Runtime Value. Each element of the list will trigger one action
run. In front of each run, the current element gets written to the destination
Runtime Value. Beside this, a second Runtime Value with the same name +
``_IDX`` will be created automatically which holds the loop number. Additional
lists can be linked to this process by pressing the "Add Link" button.

An activated Run Mode is shown with the orange "LOOP" marker in the sequence
view:

.. image:: S:/uniplot-obj/images/action-runmode-en.*

Run Mode Example
================

Goal of the example is to loop a subsequence inside the workflow. Following
Runtime Values are set from the beginning (this could e.g. be done by an
external software on startup):

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

   * - Name
     - Value
   * - FILE_LIST
     - C:\MyFileA.csv, C:\MyFileB.csv, C:\MyFileC.csv
   * - EXPORT_LIST
     - YES, NO, YES

The Run Mode of the "Run Sequence" action which calls the subsequence will get
the following parameter:

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

   * - Source RV (Main Loop)
     - FILE_LIST
   * - Destination RV (Main Loop)
     - DATAPATH
   * - Source RV (Linked Loop)
     - EXPORT_LIST
   * - Destination RV (Linked Loop)
     - DO_EXPORT

The subsequence will now be called 3 times. During the first run, following 
Runtime Values will get set:

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

   * - Name
     - Value
   * - DATAPATH
     - C:\MyFileA.csv
   * - DATAPATH_IDX
     - 1
   * - DO_EXPORT
     - YES
	 
And during the second run:

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

   * - Name
     - Value
   * - DATAPATH
     - C:\MyFileB.csv
   * - DATAPATH_IDX
     - 2
   * - DO_EXPORT
     - NO

Inside the subsequence, the Runtime Value DATAPATH may now be used as the
input path for a "Data Load" action. DATAPATH_IDX may be used as Slot number
or as Datafile Number in a "Data Exchange" action. DO_EXPORT may be used in a
Condition of a "PDF Export" action.

Standard Parameter Input
========================

Many action parameters can be defined with different input modes:

.. image:: S:/uniplot-obj/images/action-datainputexample-en.*

If its about a file path, you have the option to choose directly from the
workspace folder. This "relative" path definition allows you to forward the
workspace folder within its resource files to other places / PCs without the
need to adapt any file paths. 

The second option is an absolute path anywhere on your PC or network. Keep in
mind that this path may be broken if you move your workspace folder to another
PC.

The third option is to get the path from a Runtime Value, see
:ref:`runtimevalues`.

.. _listofactiontypes:

List of Action Types
--------------------

.. index:: Action Load Document
.. index:: y^Load_Document

Action Load Document
====================

Loads an Uniplot Document file (.ipz). Use in combination with the "Browse for 
File" action to provide User interaction.

.. image:: S:/uniplot-obj/images/action-load-document-en.*

**Parameter:**

DOCUMENT FILE: Path to the .ipz file to be loaded.

.. index:: Action Data Load
.. index:: y^Data_Load

Action Data Load
================

The action assigns a data file on disc to a Data Slot. Use in combination with
the "Browse for File" action to provide User interaction. Data Slots can then
be used by other actions or inside a script. Use in combination with the
``/rv`` parameter in a batch file for automation.

.. image:: S:/uniplot-obj/images/action-data-load-en.*

**Parameter:**

DATA FILE: The path to the datafile on disk. 

TARGET SLOT: The Slot number where the data file will be assigned to.

.. index:: Action Data Exchange
.. index:: y^Data_Exchange

Action Data Exchange
====================

Executes a basic data exchange in the active document.

.. image:: S:/uniplot-obj/images/action-data-exchange-en.*

**Parameter:**

SHOW OPTIONS DIALOG: Opens the data exchange options dialog before executing.

SOURCE DATA SLOT: Slot number with the assigned data file.

EXCHANGE DATA FILE NR: Corresponds to the row number in the manual data exchange 
dialog.

COMMENT: Corresponds to the "Comment" column in the manual data exchange dialog.

RECORD FILTER: Enables the data point filter.

For further information related to the data exchange functionality in Uniplot, 
see :ref:`datadata-exchange-(document)`.

.. index:: Action Snippet
.. index:: y^Snippet

Action Snippet
==============

.. image:: S:/uniplot-obj/images/action-snippet-en.*

Snippets provide a set of basic and often used functionalities. For better 
understanding of the sequence flow, snippets get highlighted in the action list.

**Parameter:**

FUNCTIONALITY:

Following functionalities are available:

* RESET ALL: Resets Slots, Global Object and Runtime Values. Typically used at
  the beginning of a sequence

* ABORT SEQUENCE: Aborts the sequence flow

* CLEAR RVs: Removes all active Runtime Values

* LOG RVs: Writes all Rutime Values to the Uniplot Log. Useful for debugging

* SHUTDOWN: Imediatly closes Uniplot, useful in automated workflows

.. index:: Action Run Script
.. index:: y^Run_Script

Action Run Script
=================

Loads and runs an Uniplot Script file (.ic).

.. image:: S:/uniplot-obj/images/action-run-script-en.*

**Parameter:**

SCRIPT FILE: Path to the .ic file to be executed.

**Script Functions:**

Use following Uniscript functions in
the script for interaction with the sequencer:

::

   Seq_SetRuntimeValue("EXPORT_PDF", "TRUE")

(Creates and) sets the value of a Runtime Value.

::

   Seq_GetRuntimeValue("EXPORT_PDF")

Receives the value of a Runtime Value.

::

   Seq_SetSlotPath(3, "C:\MyFile.csv")

Assignes a data file to Slot (1-100).

   Seq_GetSlotPath(3)

Receives the path of the data file assigned to slot (1-100).

::

   Seq_GetWorkspacePath()

Receives the path to the current workspace folder.

::

   Seq_AbortSequence(bShowAbortDialog)

Aborts the sequence execution after running the script. Shows a notification
dialog if ``bShowAbortDialog`` is ``1``.

.. index:: Action Browse for File
.. index:: y^Browse_for_File

Action Browse for File
======================

Opens a File Dialog and writes the selected path into a Runtime Value. Provides 
User interaction for the workflow. You can for example predefine the path of a 
resource file with the "Set Runtime Values" action and, if temporary needed, 
overwrite it by switching on this action.

.. image:: S:/uniplot-obj/images/action-browse-for-file-en.*

**Parameter:**

FILE FILTER: Filter for the file type in the upcoming dialog.

WINDOW CAPTION: Caption text for the upcoming dialog.

INITIAL BROWSE FOLDER: Start folder in the upcoming dialog.

WRITE PATH TO RUNTIME VALUE: Destination Runtime Value for the path of the
selected file.

ABORT SEQUENCE ON CANCEL: The sequence flow will be aborted if the user presses 
cancel in the upcoming dialog.

ALLOW MULTIFILE SELECT: The User is able to select multiple files in the
upcoming dialog. These file pathes will be stored comma separated in the
destination Runtime Value. In further actions or sub sequence calls, you can
activate the Loop functionality to iterate through the files automatically.

.. index:: Action Run Sequence
.. index:: y^Run_Sequence

Action Run Sequence
===================

Runs another sequence of the current workspace. Useful to structure complex 
workflows. Allows to switch On/Off or assign the Condition and Loop features to 
multiple actions at once. Also allows to reuse specific subsequences in several
workflows.

.. image:: S:/uniplot-obj/images/action-run-sequence-en.*

**Parameter:**

SEQUENCE NAME: Name of the sequence to run. 

Run Sequence actions will be shown with an arrow button in the action list to 
navigate to the linked sequence:

.. image:: S:/uniplot-obj/images/action-subsequence-in-en.*

After navigation, the sequence view will show an arrow to navigate back:

.. image:: S:/uniplot-obj/images/action-subsequence-out-en.*

.. index:: Action Set Runtime Values
.. index:: y^Set_Runtime_Values

Action Set Runtime Values
=========================

Sets a list of Runtime Values. Can e.g. be used for easy switching 
between resource files and controlling of action Conditions/Loops. Can simulate 
the batch start (parameter ``/rv``) from external devices, very helpfull during 
creation of the workflows.

.. image:: S:/uniplot-obj/images/action-set-runtime-values-en.*

**Parameter:**

List of Runtime Values to be created.

The action also allows the creation of different parameter sets for scripts in 
combination with the UniScript function :ref:`Seq_GetRuntimeValue`. To do so,
create a first set of parameters and copy/paste the action several times:

.. image:: S:/uniplot-obj/images/action-setrvexample1-en.*

Now you can switch on the desired set of parameters manually or remote control 
the activation using action conditions. Read the values at the beginning of your 
script:

.. image:: S:/uniplot-obj/images/action-setrvexample2-en.*

.. index:: Action PDF Export
.. index:: y^PDF_Export

Action PDF Export
=================

Exports the active document as an PDF file.

.. image:: S:/uniplot-obj/images/action-pdf-export-en.*

**Parameter:**

EXPORT FOLDER: Destination folder for the exported pdf file.

FILE NAME: Name for the exported pdf file.

PRINT RANGE: Page selection.

OPEN PDF FILE: Opens the PDF file after creation if checked.

Note: You have to configure your PDF Config once after the installation of 
Uniplot, see :ref:`pdf-export`.

.. index:: Action Picture Export
.. index:: y^Picture_Export

Action Picture Export
=====================

Exports the active document as a set of picture files.

.. image:: S:/uniplot-obj/images/action-picture-export-en.*

**Parameter:**

EXPORT FOLDER: Destination folder for the exported picture files.

PICTURE FORMAT: File format of the exported pictures.

RESOLUTION: Resolution of the exported pictures (DPI).

PRINT RANGE: Page selection.

.. index:: Action Synchronize Files
.. index:: y^Sync_Time_Channels

Action Synchronize Files
========================

Automates the UniScript function :ref:`nc_synchronizetime`

Automates the usage of the dialog :ref:`filemore-file-functionssynchronize-data-files`

.. image:: S:/uniplot-obj/images/action-synchronize-files-en.*

**Parameter:**

SHOW SYNC DIALOG: Opens and prefills the dialog 
:ref:`filemore-file-functionssynchronize-data-files`.

.. seealso::
   :ref:`sequencer`

:sub:`id-1715927`