``check``, ``logging``: Optional extensions
-------------------------------------------

These sets of messages are optional feature - the SEC node does not need to
support them and should reply with a `ProtocolError` error to indicate this.

Dry run functionality
~~~~~~~~~~~~~~~~~~~~~

.. message:: [request] check <module>:<accessible> [<value>]
             [reply] checked <module>:<accessible> <data-report>
             [reply] error_check <module>:<accessible> <error-report>

    The check value message is used to enable *dry run* functionality on
    :doc:`parameters and commands <../accessibles>`.  It consists of the module and
    accessible name, in addition to the value to be verified.  It allows an ECS
    to verify if a value can be set on a particular parameter without actually
    changing it with a `change` message.  Similarly, it can be used on commands
    to check if a value is a valid argument, without `executing <do>` the
    command.  This check goes beyond a simple validity check based on the
    accessible's datainfo and may depend on the current configuration of the
    entire SEC node.  Upon successful completion of the check, a `checked`
    response is sent, containing a :ref:`data-report` of the verified value.
    The accessible property `checkable` indicates whether an accessible can be
    checked.

    .. admonition:: Remarks

        * The response to a `check` message must not depend on the current
          status of the module.
        * A `check` message must not change anything, neither on the hardware
          nor on any parameter.
        * The `checked` and `error_check` messages are only sent in response to
          the `check` message on the same connection, and not to other clients
          with an activated connection.
        * If the check fails, the error report should indicate whether this is
          due to the current configuration of the SEC node (`Impossible`), or
          because the checked value is outside the range (`RangeError`)
          specified by the `datainfo` property.

    Examples::

        > check mf:target [1.0, 1.0, 2.0]
        < checked mf:target [[1.0, 1.0, 2.0], {}]

        > check mf:target [1.0, 2.0, 2.5]
        < error_check mf:target ["BadValue", "value outside allowed sphere", {"closest_valid": [0.8, 1.6, 2.0]}]

        > check cryo:target 2.7
        < error_check cryo:target ["NotCheckable", "", {}]

    .. dropdown:: Related issues

        | :issue:`075 New messages check and checked`


Logging support
~~~~~~~~~~~~~~~

.. message:: [request] logging <module>[:<parameter>] <level>
             [reply] logging <module>[:<parameter>] <level>
             [reply] error_logging <module> <error-report>

    Enables the SEC node to send log messages generated by the given module.

    The level is a JSON string, either "debug", "info", "error" or "off".  This
    is supposed to set the 'logging level' of the given module (or the whole SEC
    node if the specifier is empty) to the given level:

    This scheme may also be extended to configure logging only for selected
    parameters of selected modules.

    "off"
        Remote logging is completely turned off.
    "error"
        Only errors are logged remotely.
    "info"
        Only 'info' and 'error' messages are logged remotely.
    "debug"
        All log messages are logged remotely.

    A SEC node should reply with an :ref:`error-report` (`ProtocolError`) if
    it doesn't implement this message.  Otherwise it should mirror the request,
    which may be updated with the logging-level actually in use.  I.e. if an SEC
    node does not implement the "debug" level, but "error" and "info" and an ECS
    requests "debug" logging, the reply should contain "info" (as this is
    'closer' to the original request than "error") or "off".  Similarly, if
    logging of a too specific item is requested, the SEC node should activate
    the logging on the least specific item where logging is supported.  E.g. if
    logging for ``<module>:<param>`` is requested, but the SEC node only
    supports logging of the module, this should be reflected in the reply and
    the logging of the module is to be influenced.

    .. note:: It is not foreseen to query the currently active logging level.
              It is supposed to default to ``"off"``.

.. message:: [event] log <modulename>:<loglevel> <message>

    This is an asynchronous event only to be sent by the SEC node to the ECS
    which activated logging.

Logging example::

    # note: empty specifier -> select all modules
    > logging  "debug"
    # SEC node confirms
    < logging  "debug"
    < log mod1:debug "polling value"
    < log mod1:debug "sending request..."
    ...

Another example::

    # enable full logging of mod1
    > logging mod1 "debug"
    # SEC node can only log errors, logging of errors of mod1 is now active
    < logging mod1 "error"
    < log mod1:error "value par1 can not be determined, please refill read-out liquid"
    ...
    > logging mod1 false
    < logging mod1 false