| | |
- caget(pvs, **kargs)
- caget(pvs,
timeout = 5, datatype = None,
format = FORMAT_RAW, count = 0, throw = True)
Retrieves the value from one or more PVs. If a single PV is given then
a single value is returned, otherwise a list of values is returned.
Every value returned has the following fields:
.ok Set to True if the data is good, False if there was an error
(and throw=False has been selected).
.name Name of the pv.
If ok is False then the .errorcode field is set to the appropriate ECA_
error code and str(value) will return an appropriate error message.
The various arguments control the behaviour of caget as follows:
timeout
Timeout for the caget operation. This can be a timeout interval
in seconds, an absolute deadline (in time() format) as a single
element tuple, or None to specify that no timeout will occur. Note
that a timeout of 0 will timeout immediately if any waiting is
required.
datatype
This controls the format of the data that will be requested. This
can be any of the following:
1. None (the default). In this case the "native" datatype provided
by the channel will be returned.
2. A DBR_ value, one of DBR_STRING, DBR_SHORT, DBR_FLOAT, DBR_ENUM,
DBR_CHAR, DBR_LONG or DBR_DOUBLE.
3. A python type compatible with any of the above values, such as
int, float or str.
4. Any numpy dtype compatible with any of the above values.
format
This controls how much auxilliary information will be returned with
the retrieved data, and can be one of the following:
FORMAT_RAW
The data is returned unaugmented except for the .name field.
FORMAT_TIME
The data is augmented by the data timestamp together with
.alarm .status and .severity fields.
FORMAT_CTRL
The data is augmented by channel access "control" fields. This
set of fields depends on the underlying datatype:
DBR_SHORT, DBR_CHAR, DBR_LONG
The alarm .status and .severity fields together with .units
and limit fields:
.upper_disp_limit, .lower_disp_limit,
.upper_alarm_limit, .lower_alarm_limit,
.upper_warning_limit, .lower_warning_limit,
.upper_ctrl_limit, .lower_ctrl_limit.
DBR_FLOAT, DBR_DOUBLE
As above together with a .precision field.
DBR_ENUM
Alarm .status and .severity fields together with .enums, a
list of possible enumeration strings.
DBR_STRING
_CTRL format is not supported for this field type, and
FORMAT_TIME data is returned instead.
count
If specified this can be used to limit the number of waveform values
retrieved from the server.
throw
Normally an exception will be raised if the channel cannot be
connected to or if there is a data error. If this is set to False
then instead for each failing PV an empty value with .ok == False is
returned.
The format of values returned depends on the number of values requested
for each PV. If only one value is requested then the value is returned
as a scalar, otherwise as a numpy array.
- camonitor(pvs, callback, **kargs)
- camonitor(pvs, callback,
events = DBE_VALUE,
datatype = None, format = FORMAT_RAW, count = 0,
all_updates = False, notify_disconnect = False)
Creates a subscription to one or more PVs, returning a subscription
object for each PV. If a single PV is given then a single subscription
object is returned, otherwise a list of subscriptions is returned.
Subscriptions will remain active until the close() method is called on
the returned subscription object.
The precise way in which the callback routine is called on updates
depends on whether pvs is a single name or a list of names. If it is
single name then it is called as
callback(value)
for each update. If pvs is a list of names then each update is
reported as
callback(value, index)
where index is the position in the original array of pvs of the name
generating this update.
Every value has .name and .ok fields: if the channel has disconnected
then .ok will be False, otherwise the value is an augmented
representation of the updated value; for more detail on values see the
documentation for caget.
The parameters modify the behaviour as follows:
events
This identifies the type of update which will be notified. A
bit-wise or of any the following are possible:
DBE_VALUE Notify normal value changes
DBE_LOG Notify archive value changes
DBE_ALARM Notify alarm state changes
datatype
format
count
These all specify the format in which data is returned. See the
documentation for caget for details.
all_updates
If this is True then every update received from channel access will
be delivered to the callback, otherwise multiple updates received
between callback queue dispatches will be merged into the most recent
value.
If updates are being merged then the value returned will be
augmented with a field .update_count recording how many updates
occurred on this value.
notify_disconnect
If this is True then IOC disconnect events will be reported by
calling the callback with a ca_nothing error with .ok False,
otherwise only valid values will be passed to the callback routine.
- caput(pvs, values, **kargs)
- caput(pvs, values,
repeat_value = False, timeout = 5, wait = False, throw = True)
Writes values to one or more PVs. If multiple PVs are given together
with multiple values then both lists or arrays should match in length,
and values[i] is written to pvs[i]. Otherwise, if a single value is
given or if repeat_value=True is specified, the same value is written
to all PVs.
The arguments control the behavour of caput as follows:
repeat_value
When writing an array value to an array of PVs ensures that the
same array of values is written to each PV.
timeout
Timeout for the caput operation. This can be a timeout interval
in seconds, an absolute deadline (in time() format) as a single
element tuple, or None to specify that no timeout will occur. Note
that a timeout of 0 will timeout immediately if any waiting is
required.
wait
If wait=True is specified then channel access put with callback is
invoked, and the caput operation will wait until the server
acknowledges successful completion before returning.
throw
Normally an exception will be raised if the channel cannot be
connected to or if an error is reported. If this is set to False
then instead for each failing PV a sentinel value with .ok == False
is returned.
The return value for each PV is a structure with two fields: .ok and
.name, and possibly a third field .errorcode. If multiple PVs are
specified then a list of values is returned.
If caput completed succesfully then .ok is True and .name is the
corresponding PV name. If throw=False was specified and a put failed
then .errorcode is set to the appropriate ECA_ error code.
- connect(pvs, **kargs)
- connect(pvs, wait = True, timeout = 5, throw = True)
Establishes a connection to one or more PVs. A single PV or a list of PVs
can be given. This does not normally need to be called, as the ca...()
routines will establish their own connections as required, but after a
successful connection we can guarantee that caput(..., wait=False) will
complete immediately without suspension.
The following arguments affect the behaviour of connect as follows:
wait
Normally the connect routine will not return until the requested
connection is established. If wait=False is set then a connection
request will be queued and connect will unconditionally succeed.
timeout
How long to wait for the connection to be established.
throw
Normally an exception will be raised if the channel cannot be
connected to. If this is set to False then instead for each failing
PV a sentinel value with .ok == False is returned.
|