This Perl module is included in EPICS Base from release 3.14.10 on. The separately downloadable cap5 module is no longer being maintained.
CA - Perl 5 interface to EPICS Channel Access
use lib '/path/to/cap5/lib/perl'; use CA;
my $chan = CA->new('pvname'); CA->pend_io(1);
my @access = ('no ', ''); printf " PV name: %s\n", $chan->name; printf " Data type: %s\n", $chan->field_type; printf " Element count: %d\n", $chan->element_count; printf " Host: %s\n", $chan->host_name; printf " State: %s\n", $chan->state; printf " Access: %sread, %swrite\n", $access[$chan->read_access], $access[$chan->write_access];
die "PV not found!" unless $chan->is_connected;
$chan->get; CA->pend_io(1); printf " Value: %s\n", $chan->value;
$chan->create_subscription('v', \&callback, 'DBR_TIME_DOUBLE'); CA->pend_event(10);
sub callback { my ($chan, $status, $data) = @_; if ($status) { printf "%-30s %s\n", $chan->name, $status; } else { printf " Value: %g\n", $data->{value}; printf " Severity: %s\n", $data->{severity}; printf " Timestamp: %d.%09d\n", $data->{stamp}, $data->{stamp_fraction}; } }
CA
is an efficient interface to the EPICS Channel Access client library for
use by Perl 5 programs. It provides most of the functionality of the C library
(omitting Synchronous Groups) but only handles the three standard Perl data
types integer (long), floating point (double) and string. Programmers who
understand the C API will very quickly pick up how to use this library since the
calls and concepts are virtually identical.
Create a channel for the named PV. If given, SUB will be called whenever the connection state of the channel changes. The arguments passed to SUB are the channel object and a scalar value that is true if the channel is now up.
The underlying CA channel will be cleaned up properly when the channel object is garbage-collected by Perl.
The following methods are provided for channel objects returned by
CA->new()
.
The PV name provided when this channel was created.
Returns the native DBF type of the process variable as a string, or the string
TYPENOTCONN
if unconnected.
The maximum array element count from the server. Zero if the channel is not connected.
A string containing the server's hostname and port number. If the channel is
disconnected it will report <disconnected>
.
A true/false value that indicates whether the client has read or write access to the specified channel.
A string giving the current connection state of the channel, one of never
connected
, previously connected
, connected
or closed
.
Returns true
if the channel is currently connected, else false
. Use this
in preference to the equivalent code $chan->state eq 'connected'
.
The get
method makes a ca_get()
request for a single element of the Perl
type closest to the channel's native data type (DBF_ENUM
fields will be
fetched as strings). Once the server has returned the value (for which see the
pend_io
function below) it can be retrieved using the channel's value
method. Note that this method deliberately has only very limited capabilities;
the get_callback
method must be used for more complex requirements.
The get_callback
method takes a subroutine reference or name and calls that
routine when the server returns the data requested. With no other arguments the
request will be for native data type of the channel, and if the channel is an
array it will request all possible array elements. The subroutine will be
called with three arguments: the channel object, a status value from the server,
and the returned data. If there was no error the status value will be undef
and the data will be valid; if there was an error the data will be undef
and
the status is a printable string giving more information. The format of the
data is described under Channel Data below.
The element count can be overridden by providing an integer argument in the
range 1 .. element_count
. The data type can also be given as a string naming
the desired DBR_xxx_yyy
type; the actual type used will have the yyy
part
widened to one of STRING
, LONG
or DOUBLE
. The valid type names are
listed in the Channel Access Reference Manual under the section
titled Channel Access Data Types; look in the CA Type Code column of the two
tables
Register a state change subscription and specify a subroutine to be called
whenever the process variable undergoes a significant state change. MASK
must be a string containing one or more of the letters v
, l
and a
which
indicate that this subscription is for Value, Log or Alarm changes. The
subroutine SUB is called as described in the get_callback
method, and the
same optional TYPE and COUNT arguments may be supplied to modify the data
type and element count requested from the server.
The create_subscription
method returns a ca::subscription
object which is
required to cancel that particular subscription. Either call the clear
method on that object directly, or pass it to the CA->clear_subscription
class method.
The put
method makes a ca_put()
or ca_array_put()
call depending on the
number of elements given in its argument list. The data type used will be the
native type of the channel, widened to one of STRING
, LONG
or DOUBLE
.
put_callback
is similar to the put
method with the addition of the
subroutine reference or name SUB which is called when the server reports that
all actions resulting from the put have completed. For some applications this
callback can be delayed by minutes, hours or possibly even longer. The data
type is chosen the same way as for put
. The arguments to the subroutine will
be the channel object and the status value from the server which is undef
or
a printable string if an error occurred.
Applications that need to ackowledge alarms by doing a ca_put()
with type
DBR_PUT_ACKS
can do so using the put_acks
method. The severity argument
can be an integer from zero through three or a string containing one of the
corresponding EPICS severity names NO_ALARM
, MINOR
, MAJOR
or
INVALID
. If a subroutine reference is provided it will be called as describe
in put_callback
above.
This method is for applications that need to enable/disable transient alarms by
doing a ca_put()
with type DBR_PUT_ACKT
. The TRANS
argument is a
true/false value, and an optional subroutine reference can be provided as
above.
This method replaces, adds or cancels the connection handler subroutine for the
channel; see the new
constructor for details. If SUB is undef
any
existing handler is removed, otherwise the new subroutine will be used for all
future connection events on this channel.
The data provided to a callback function registered with either get_callback
or create_subscription
can be a scalar value or a reference to an array or a
hash, depending on the data type that was used for the data transfer. If the
request was for a single item of one of the basic data types, the data argument
will be a perl scalar that holds the value directly. If the request was for
multiple items of one of the basic types, the data argument will be a reference
to an array holding the data.
If the request was for one of the compound data types, the data argument will be
a reference to a hash with keys as described below. Keys that are not classed
as metadata are named directly after the fields in the C struct dbr_xxx_yyy
,
and are only included when the C structure contains that particular field.
These metadata will always be present in the hash:
The DBR_xxx_yyy
name of the data type from the server.
The number of elements in the data returned by the server.
These fields are always present in the hash:
The actual process variable data. If COUNT is 1 value
will be the data as
a scalar; if the channel returned multiple elements, value
will be a
reference to an array of scalars.
If TYPE is DBR_GR_ENUM
or DBR_CTRL_ENUM
, value
can be accessed both
as the integer choice value and (if within range) as the string associated with
that particular choice.
The alarm status of the PV as a printable string, or undef
if not in alarm.
The alarm severity of the PV, or undef
if not in alarm. A defined severity
can be used as a human readable string or as a number giving the numeric value
of the alarm severity (1 = MINOR, 2 = MAJOR, 3 = INVALID).
These fields are only present for some values of TYPE:
A reference to an array containing all the possible choice strings for an ENUM.
Present only when TYPE is DBR_GR_ENUM
or DBR_CTRL_ENUM
.
The number of choices defined for an ENUM.
Present only when TYPE is DBR_GR_ENUM
or DBR_CTRL_ENUM
.
The process variable timestamp, converted to a local time_t
. This value is
suitable for passing to the perl localtime
or gmtime
functions.
Present only when TYPE is DBR_TIME_yyy
.
The fractional part of the process variable timestamp as a positive floating point number less than 1.0.
Present only when TYPE is DBR_TIME_yyy
.
The value of the process variable's transient acknowledgment flag, an integer.
Present only when TYPE is DBR_STSACK_STRING
.
The alarm severity of the highest unacknowledged alarm for this process
variable. As with the severity
value, this scalar is both a string and
numeric severity.
Present only when TYPE is DBR_STSACK_STRING
.
The process variable's display precision, an integer giving the number of decimal places to display.
Present only when TYPE is DBR_GR_DOUBLE
or DBR_CTRL_DOUBLE
.
The engineering units string for the process variable.
Present only when TYPE is DBR_GR_yyy
or DBR_CTRL_yyy
where yyy
is
not STRING
.
The display range for the process variable; graphical tools often provide a way to override these limits.
Present only when TYPE is DBR_GR_yyy
or DBR_CTRL_yyy
where yyy
is
not STRING
.
These items give the values at which the process variable should go into an alarm state, although in practice the alarm severity associated with each level is not provided.
Present only when TYPE is DBR_GR_yyy
or DBR_CTRL_yyy
where yyy
is
not STRING
.
The range over which a client can control the value of the process variable.
Present only when TYPE is DBR_CTRL_yyy
where yyy
is not STRING
.
The following functions are not channel methods, and should be called using the
class method syntax, e.g. CA->pend_io(10)
.
Flush outstanding IO requests to the server. This routine is useful for users who need to flush requests prior to performing client side labor in parallel with labor performed in the server. Outstanding requests are also sent whenever the buffer which holds them becomes full.
This function tests to see if all get
requests are complete and channels
created without a connection callback subroutine are connected. It will return
a true value if all such operations are complete, otherwise false.
This function flushes the send buffer and then blocks until all outstanding
get
requests complete and all channels created without a connection callback
subroutine have connected for the first time. Unlike pend_event
, this
routine does not process CA's background activities if no IO requests are
pending.
If any I/O or connection operations remain incomplete after TIMEOUT seconds,
the function will die with the error ECA_TIMEOUT
; see ERROR HANDLING
below. A TIMEOUT interval of zero is taken to mean wait forever if
necessary. The TIMEOUT value should take into account worst case network
delays such as Ethernet collision exponential back off until retransmission
delays which can be quite long on overloaded networks.
Flush the send buffer and process CA's background activities for TIMEOUT seconds. This function always blocks for the full TIMEOUT period, and if a value of zero is used it will never return.
Flush the send buffer and process any outstanding CA background activity.
Cancel a subscription. Note that for this to take effect immediately it is
necessary to call CA->flush_io
or one of the other class methods that
flushes the send buffer.
Trap exception events and execute SUB whenever they occur. The subroutine is
provided with four arguments: The channel object (if applicable), the status
value from the server, a printable context string giving more information about
the error, and a hash reference containing some additional data. If the
exception is not specific to a particular channel the channel object will be
undef
. The status value is a printable string. The hash may contain any of
the following members:
The operation in progress when the exception occurred. This scalar when used as
a string is one of GET
, PUT
, CREATE_CHANNEL
, ADD_EVENT
,
CLEAR_EVENT
or OTHER
but can also be accessed as an integer (0-5).
The DBR_xxx_yyy
name of the data type involved.
The number of elements in the request.
These refer to the source file and line number inside the CA client library where the exception was noticed.
This function provides a method to trap error messages from the CA client
library and redirect them to some other place than the STDERR
stream. The
subroutine provided will be called with a single string argument every time the
client library wishes to output an error or warning message. Note that a single
message may result in several calls to this subroutine.
To revert back to the original handler, call CA->replace_printf_handler()
passing undef
as the subroutine reference.
Errors in using the library will be indicated by the module throwing an
exception, i.e. calling croak()
with an appropriate error message. These
exceptions can be caught using the standard Parl eval {}
statement and
testing the $@
variable afterwards; if not caught, they will cause the
running program to die
with an appropriate error message pointing to the
program line that called the CA
library.
Errors messages reported by the underlying CA client library all start with the
string ECA_
and the remainder of the symbol for the associated CA error
number, and are followed after a space-hyphen-space by a human-readable message
describing the error. Errors that are detected by the perl interface layer do
not follow this pattern, but are still printable strings.
Andrew Johnson, <[email protected]>
Copyright (C) 2008 UChicago Argonne LLC, as Operator of Argonne National Laboratory.
This software is distributed under the terms of the EPICS Open License.