NAME

EZCA.pm - Perl extension for EPICS Easy Channel Access library (ezca)

SYNOPSIS

        use EZCA;
        EZCA::AutoErrorMessageOff();
        EZCA::SetTimeout(0.1);
        EZCA::SetRetryCount(10);

        $timeout = EZCA::GetTimeout();
        $retry = EZCA::GetRetryCount();
        print " timeout = $timeout    Retry = $retry \n";

        @data = EZCA::Get("S:SRsecsPastEpochAI","ezcaLong",1);
        print "Status = $data[0]  Value = $data[1]  \n";

        EZCA::GetStatus("ID01:Gap",$tstamp,$tnstamp,$status,$severity);
        print "Time: $tstamp $tnstamp Status = $status Severity= $severity \n";

DESCRIPTION

EZCA.pm is a perl interface to EPICS EZCA library. The routine names are based on EZCA nomenclature. Each routine name in EZCA has an equivalent in perl module. At this time 21 functions have been implemented and tested.

All the commands are similar to what is used in C version of EZCA. The various datatypes as described in EZCA (ezcatype) are used. They are as follows:

ezcaByte
ezcaString
ezcaShort
ezcaLong
ezcaFloat
ezcaDouble

Most fucntion calls return status codes indicating the success/failure of the call. All other values are a indication of a problem. Following are the return codes.

EZCA_OK
EZCA_INVALIDARG
EZCA_FAILEDMALLOC
EZCA_CAFAILURE
EZCA_UDFREG
EZCA_NOTCONNECTED
EZCA_NOTIMELYRESPONSE
EZCA_INGROUP
EZCA_NOTINGROUP

Work in Progress:

Most functions with the exception of the Group function have been implemented and tested.
All functions involving arrays have a limitation of 2000 elements.
In the case of the Put at this time only one element is possible.

Main Functions

@data = EZCA::Get($pvname,"ezcatype", $no_elem): Retrieve values from $pvname and the data type is specified as ezcatype At this time the no of elements $no_elem is limited to 2000. The return status code is stored in $data[0] and the retrieved values are in the rest of the array starting at elements $data[1]
$status = EZCA::GetControlLimits($pvname, $low, $high): Retrive the Control Limits values in $low and $high. $status is the return status.
$status = EZCA::GetGraphicLimits($pvname, $low, $high): Retrive the Graphics Limits values in $low and $high. $status is the return status.
$status = EZCA::GetNelem($pvname,$nelem): The numbe of elements in the C$pvname> is returned in $nelem.
$status = EZCA::GetPrecision($pvname,$prec): The precision for the $pvname is returned in $prec.
EZCA::GetStatus($pvname,$tstamp,$tnstamp,$status,$severity): This call retrieves various information about the said $pvname. The time in seconds is in $tstamp and in nanoseconds is in $tnstamp All times are since EPICS EPOCH. The $status and $severity returns status of the pv and its severity.
$status = EZCA::GetUnits($pvname,$unit): This returns the EGU field of the $pvname in $unit.
$status = EZCA::Put($pvname,"ezcatype",$no_elem,$data): Put values into $pvname. The value is send in $data and the data type is specified as ezcatype. At this time the no of elements $no_elem is limited to 1.

Monitors

$status = EZCA::SetMonitor($pvname,"ezcatype"): Used to set a monitor on the $pvname.
$status = EZCA::ClearMonitor($pvname,"ezcatype"): Used to clear any monitors placed on the $pvname.
$mon = EZCA::NewMonitorValue($pvname,"ezcatype"): Use this function to poll for new values on a previously set monitor. A non zero return value in $mon indicates a new value since the last time the value was read a get call.
$status = EZCA::Delay($seconds): Use to introduce delays between calls. the time $seconds is in seconds. Fractional time is allowed.

Error Handling

EZCA::AutoErrorMessageOn(): Turn ON the EZCA error messages to be printed on the stdout.
EZCA::AutoErrorMessageOff(): Turn OFF the EZCA error messages to be printed on the stdout.
EZCA::Perror($prefix): Use this to optionally add a prefix message to the EZCA error message.
EZCA::GetErrorString(NULL, $stringBuff): Retrieve the EZCA error message in the $stringBuff instead of stdout.
EZCA::Free($stringBuff): Use this to free up the $stringBuff used in the above call.

Tuning EZCA

$seconds = EZCA::GetTimeout(): Retrieve the current CA timeout value in seconds
$number = EZCA::GetRetryCount(): Retrieve the current CA number of retries.
$status = EZCA::SetTimeout($seconds): Set the current CA timeout value in seconds
$status = EZCA::SetRetryCount($number): Set the CA number of retries.

How to get the Software

The software has been built on epics R3.13.9. The software is available as a gzipped tarfile

for solaris http://www.aps.anl.gov/aod/people/mohan/EZCA/solEZCA.tar.gz

for Linux http://www.aps.anl.gov/aod/people/mohan/EZCA/linuxEZCA.tar.gz

For building it standalone, some of the EPICS include files and libraries are included.

AUTHOR

The EZCA perl module was written in 1996 by Mohan Ramanathan. However it was documented only in 2002. During these years the module has been extensively used and tested by the author. This module is used in numerous activities at the Advanced Photon Source.

For latest info contact the author Mohan Ramanathan mohan@aps.anl.gov