.. _sardana-howto-environment-managing:

===============================
Managing environment variables
===============================

The MacroServer stores *variable - value* pairs, called environment
variables, persistently. Macros use them to share configuration (or even
small data) between executions. Sardana built-in macros use a set of
standard variables listed in the
:ref:`Environment Variable Catalog <environment-variable-catalog>`,
and you can also define your own variables. See :ref:`macro-environment`
for the full description of the environment concept, value types
and scopes.

Getting and setting variables
-----------------------------

The most common way of accessing the environment is using the
:ref:`environment macros <sardana-environment-macros>` from Spock
(or any other macro execution client):

* `~sardana.macroserver.macros.env.lsenv` - list environment variables and
  their values
* `~sardana.macroserver.macros.env.senv` - set the value of an environment
  variable (create it if it does not exist)
* `~sardana.macroserver.macros.env.genv` - get the value of an environment
  variable
* `~sardana.macroserver.macros.env.usenv` - unset (remove) one or more
  environment variables
* `~sardana.macroserver.macros.env.dumpenv` - dump the complete environment,
  including internal variables, e.g. for diagnostics
* `~sardana.macroserver.macros.env.load_env` - load environment variables
  from a file

For example:

.. sourcecode:: spock

    Door_demo1_1 [1]: senv ScanDir /tmp/scans
    ScanDir = /tmp/scans

    Door_demo1_1 [2]: genv ScanDir
    ScanDir =
    '/tmp/scans'

    Door_demo1_1 [3]: usenv ScanDir
    Environment variable(s) ScanDir removed

.. important::
    Environment variable names are case sensitive. So, variable ``Foo`` is
    a different variable than ``foo``.

Values are interpreted as Python literals (numbers, strings, lists,
dictionaries, ...); anything that does not evaluate to a Python literal is
treated as a string - see :ref:`sardana-macro-environment_types`.

Door and macro specific variables
---------------------------------

By default a variable is set on the *global* scope: it applies to all doors
and all macros. You can restrict a variable to a specific door and/or to a
specific macro by prefixing its name with the door device name and/or the
macro name, separated by dots:

.. sourcecode:: spock

    # only for macros running on door Door/demo1/2
    Door_demo1_1 [1]: senv Door/demo1/2.Foo Bar

    # only for the ascan macro, on any door
    Door_demo1_1 [2]: senv ascan.Foo Bar

    # only for the ascan macro when run on door Door/demo1/2
    Door_demo1_1 [3]: senv Door/demo1/2.ascan.Foo Bar

Scoped variables override the global ones. Remember to use the Door device
name (not its alias) when defining variables on the door scope. The details
of the scope resolution are explained in :ref:`macro-environment`.

Accessing the environment from macros
-------------------------------------

Inside a macro you can use the `~sardana.macroserver.macro.Macro.getEnv` and
`~sardana.macroserver.macro.Macro.setEnv` :term:`API` to read and write
environment variables::

    @macro()
    def save_position(self, motor):
        position = motor.getPosition()
        self.setEnv("SavedPosition", position)
        self.output("Saved position: %f", position)

See :ref:`sardana-macro-environment` for more details and examples.