170 lines
5.8 KiB
ReStructuredText
170 lines
5.8 KiB
ReStructuredText
.. _pvalink:
|
|
|
|
PVA Links
|
|
#########
|
|
|
|
Since 1.3.0
|
|
|
|
JSON Reference
|
|
==============
|
|
|
|
A PVA link `JSON schema <pvalink-schema-0.json>`_ definition file is available.
|
|
|
|
Default values for all keys. ::
|
|
|
|
record(longin, "tgt") {}
|
|
record(longin, "src") {
|
|
field(INP, {pva:{
|
|
pv:"tgt",
|
|
field:"",
|
|
local:false,
|
|
Q:4,
|
|
pipeline:false,
|
|
proc:none,
|
|
sevr:false,
|
|
time:false,
|
|
monorder:0,
|
|
retry:false,
|
|
always:false,
|
|
defer:false
|
|
}})
|
|
}
|
|
|
|
Certain keys are only relevant with certain link types.
|
|
|
|
+----------+-------+--------+---------+
|
|
| Key | Input | Output | Forward |
|
|
+==========+=======+========+=========+
|
|
| pv | X | X | X |
|
|
+----------+-------+--------+---------+
|
|
| field | X | X | X |
|
|
+----------+-------+--------+---------+
|
|
| local | X | X | X |
|
|
+----------+-------+--------+---------+
|
|
| proc | | X | X |
|
|
+----------+-------+--------+---------+
|
|
| retry | | X | X |
|
|
+----------+-------+--------+---------+
|
|
| atomic | X | | |
|
|
+----------+-------+--------+---------+
|
|
| defer | X | | |
|
|
+----------+-------+--------+---------+
|
|
| monorder | X | | |
|
|
+----------+-------+--------+---------+
|
|
| pipeline | X | | |
|
|
+----------+-------+--------+---------+
|
|
| Q | X | | |
|
|
+----------+-------+--------+---------+
|
|
| sevr | X | | |
|
|
+----------+-------+--------+---------+
|
|
| time | X | | |
|
|
+----------+-------+--------+---------+
|
|
| always | | | |
|
|
+----------+-------+--------+---------+
|
|
|
|
``pv`` names the target PV in full.
|
|
|
|
``field`` selects a sub-structure of the target PV.
|
|
By default ``""`` the top level structure is used.
|
|
If the target field is a Structure, then ``.value``
|
|
and various NTScalar meta-data fields are used.
|
|
Otherwise, the the targeted field is used as the value
|
|
without any meta-data.
|
|
|
|
``local`` set to require that ``pv`` reference a record in the local database.
|
|
|
|
``Q`` requests a certain subscription queue depth.
|
|
|
|
``pipeline`` selects per-subscription flow control.
|
|
|
|
``proc`` may be set to:
|
|
|
|
- ``null`` (default). Server selects ``"NPP"`` or ``"PP"`` behavior.
|
|
- ``true`` / ``"PP""``. Requests target recorded be "processed" after value update.
|
|
- ``false`` / ``"NPP"``. Requests only value update.
|
|
- ``"CP"`` Subscribes to target PV. Process this record on each update as well as (dis)connect event.
|
|
- ``"CPP"``. Equivalent to ``"CP"`` if ``SCAN=Passive``. Otherwise behaves like ``"NPP"``.
|
|
|
|
``sevr`` controls if and how alarm state of target PV is applied to Maximize Severity.
|
|
|
|
- ``"NMS"`` (default) Target PV severity is not considered.
|
|
- ``"MS"`` All target PV severities are considered.
|
|
- ``"MSI"`` Only ``INVALID`` severity is considered.
|
|
- ``"MSS"`` Currently equivalent to ``"MSI"``.
|
|
|
|
``time`` If ``true`` (not default) and the selected field of the target PV has a ``timeStamp`` sub-structure,
|
|
then this time will be written to the record ``TIME`` field.
|
|
In almost all cases if will also be necessary to set ``field(TSE, "-2")``.
|
|
|
|
``retry``. For an output link, and ``true`` (not default), then the most recent incomplete PUT
|
|
will be re-tried when the target PV (re)connects.
|
|
|
|
``always``. Ignored. ``false`` (default).
|
|
|
|
``atomic``. When ``true`` (not default) then ``"CP"`` and ``"CPP"`` link processing will
|
|
be done all related records locked (cf. ``dbLockMany()``).
|
|
If several records with ``atomic:true`` are linked to different structure fields of the same target this PV,
|
|
then all records will be locked together and all resulting processing will be atomic.
|
|
|
|
``monorder`` the relative ordering (increasing) of processing of ``"CP"`` and ``"CPP"`` records linked to the same target PV.
|
|
|
|
``defer``. If ``true`` (not default) this output link will only cache the value to be PUT,
|
|
but will not issue a network operation.
|
|
Can be used to update several structure fields in a single network PUT.
|
|
|
|
Input Links
|
|
===========
|
|
|
|
Creating a ``pva`` link will result in a subscription being made to the target PV.
|
|
Updates will be accumulated in a local cache.
|
|
Link processing reads the most recent value/alarm/time from this cache.
|
|
While disconnected, a link will read the most recent value/time, with an ``INVALID`` alarm severity. ::
|
|
|
|
record(longout, "src") {
|
|
field(INP, {pva:{pv:"target:pv"}})
|
|
}
|
|
|
|
To trigger record processing when a monitor update arrives,
|
|
add the ``proc:"CP"`` modifier. ::
|
|
|
|
record(longout, "src") {
|
|
field(INP, {pva:{
|
|
pv:"target:pv",
|
|
proc:"CP"
|
|
}})
|
|
}
|
|
|
|
Output Links
|
|
============
|
|
|
|
The default behavior of a ``pva`` output link is to write the link value into a local cache,
|
|
and then immediately flush that cache and into a network PUT operation.
|
|
``defer:true`` allows prevents a link from immediately flushing,
|
|
which allows changes to multiple fields to be combined into a single PUT (eg. writing to :ref:`grouppv`).
|
|
|
|
By default, an output link will write the ``.value`` structure field of the target PV.
|
|
Any processing is at the discretion of the server.
|
|
(hint, look for ``pp(TRUE)`` or ``pp(FALSE)`` in ``*Record.dbd``) ::
|
|
|
|
record(longout, "src") {
|
|
field(OUT, {pva:"target:pv"})
|
|
}
|
|
|
|
or equivalently: ::
|
|
|
|
record(longout, "src") {
|
|
field(OUT, {pva:{
|
|
"pv":"target:pv"
|
|
}})
|
|
}
|
|
|
|
Additionally, as with DB links, a link may request control of target processing
|
|
by setting the ``proc:`` key with ``true`` / ``"PP""``, or the opposite with
|
|
``false`` / ``"NPP"``.
|
|
|
|
Forward Links
|
|
=============
|
|
|
|
A ``pva`` forward link will send an empty PUT request (no field changes) to the target PV with ``proc:true``.
|
|
If the target PV is a record, then this is equivalent to a PUT of ``.PROC``.
|