NAME

Pezca - a Perl extension for the easy channel access library (part of EPICS)

SYNOPSIS

use Pezca;

DESCRIPTION

Preface

This module gives access to some functions of the ezca library. ezca is a library that simplifies the usage of channel-access, the tcp/ip-based protocol that is used in the Experimental Physics Industrial Control System (EPICS). This software is copyrighted by the terms described in the file LICENSE which is part of the software distribution.

Implemented Functions:

GetDouble
```
($errcode,$val)= Pezca::GetDouble($channel_name)
```
Gets a channel name as parameter (a string) and returns a list containing of the error-code and the value of the operation. This function can block when the channel is not immediately available. This function replaces Pezca::Get().
GetString
```
($errcode,$val)= Pezca::GetString($channel_name)
```
gets a channel name as parameter (a string) and returns a list containing of the value and the error-code of the operation. The value is read as a string. This function can block when the channel is not immediately available. This function replaces Pezca::GetS().
GetList
```
($errcode,@values)= Pezca::GetList($channel_name,$type,$no)
```
gets a channel name, a type and the number of elements as parameter. Known types (upper or lower case strings allowed) are byte, char, uchar, short, ushort, long, ulong, int, uint, float, double and string. The type name must not be omitted. If the type is unknown, the function prints an error message and returns errcode -1. If the number of elements is omitted, all elements of the channel are fetched. The function returns the error-code and a list of elements. This function can block when the channel is not immediately available.
PutDouble
```
$errcode= Pezca::PutDouble($channel_name,$value)
```
get a channel name (string) and a value (floating point) as parameter. The functions return the error-code of the put-operation. They can block when the channel is not immediately available. Both functions are identical, the Pezca::Put() shouldn't be used in future applications since it is not complient with the new naming convention of this module.
PutDoubleOldCa
```
$errcode= Pezca::PutDoubleOldCa($channel_name,$value)
```
get a channel name (string) and a value (floating point) as parameter. The functions return the error-code of the put-operation. They can block when the channel is not immediately available. Both functions are identical, the Pezca::Put() shouldn't be used in future applications since it is not complient with the new naming convention of this module.
PutString
```
$errcode= Pezca::PutString($channel_name,$value)
```
get a channel name (string) and a value (string) as parameter. The functions return the error-code of the opreration. They can block when the channel is not immediately available. Pezca::PutS() shouldn't be used in future applications since it is not complient with the new naming convention of this module.
PutStringOldCa
```
$errcode= Pezca::PutStringOldCa($channel_name,$value)
```
get a channel name (string) and a value (string) as parameter. The functions return the error-code of the opreration. They can block when the channel is not immediately available. Pezca::PutS() shouldn't be used in future applications since it is not complient with the new naming convention of this module.
PutList
```
$errcode= Pezca::PutList($channel_name,$type,@values)
```
gets a channel name, a type and the list of elements as parameter. Known types (upper or lower case strings allowed) are byte, char, uchar, short, ushort, long, ulong, int, uint, float, double and string. The type name must not be omitted. If the type is unknown, the function prints an error message and returns errcode -1. The function returns the error-code of the operation. This function can block when the channel is not immediately available.
PutListOldCa
```
$errcode= Pezca::PutListOldCa($channel_name,$type,@values)
```
gets a channel name, a type and the list of elements as parameter. Known types (upper or lower case strings allowed) are byte, char, uchar, short, ushort, long, ulong, int, uint, float, double and string. The type name must not be omitted. If the type is unknown, the function prints an error message and returns errcode -1. The function returns the error-code of the operation. This function can block when the channel is not immediately available.
GetControlLimits
```
($errcode,$low,$high)= Pezca::GetControlLimits($channel)
```
Get the control limits of the given channel.
GetGraphicLimits
```
($errcode,$low,$high)= Pezca::GetGraphicLimits($channel)
```
Get the graphic limits of the given channel.
GetNelem
```
($errcode,$no)= Pezca::GetNelem($channel)
```
Get the number of elements of the given channel. See also Pezca::GetList() and Pezca::PutList().
GetPrecision
```
($errcode,$prec)= Pezca::GetPrecision($channel)
```
Get the precision of the given channel.
GetUnits
```
($errcode,$units)= Pezca::GetUnits($channel)
```
Get the engeneering units (a string) of the given channel.
SetMonitorDouble
```
$errcode= Pezca::SetMonitorDouble($channel_name)
```
This function sets a channel-access monitor on the given channel. A buffer is set up that is notified each time the value of the given channel changes. All following calls of Pezca::GetDouble() access that local buffer. This is a way to reduce network traffic, when Pesca::GetDouble() is called more frequently than the underlying value actually changes. Note that the data-types of the monitors and the get functions must match, so Pezca::SetMonitorDouble() should only be used with Pezca:GetDouble().
SetMonitorString
```
$errcode= Pezca::SetMonitorString($channel_name)
```
This function sets a channel-access monitor on the given channel. A buffer is set up that is notified each time the value of the given channel changes. All following calls of Pezca::GetString() access that local buffer. This is a way to reduce network traffic, when Pesca::GetString() is called more frequently than the underlying value actually changes. Note that the data-types of the monitors and the get functions must match, so Pezca::SetMonitorString() should only be used with Pezca:GetString().
ClearMonitorDouble
```
$errcode= Pezca::ClearMonitorDouble($channel_name)
```
These functions remove the monitor that was set up with Pezca::SetMonitorDouble().
ClearMonitorString
```
$errcode= Pezca::ClearMonitorString($channel_name)
```
This function removes the monitor that was set up with Pezca::SetMonitorString().
NewMonitorValueDouble
```
$errcode= Pezca::NewMonitorValueDouble($channel_name)
```
This function returns 1 if there is a new value in the monitor that was set up with Pezca::SetMonitorDouble().
NewMonitorValueString
```
$errcode= Pezca::NewMonitorValueString($channel_name)
```
This function returns 1 if there is a new value in the monitor that was set up with Pezca::SetMonitorString().
GetTimeout
```
$tmout= Pezca::GetTimeout()
```
Get the actual timeout of the ezca library (see ezca documentation)
GetRetryCount
```
$retry_count= Pezca::GetRetryCount()
```
Get the actual Retry-Count of the ezca library (see ezca documentation)
SetTimeout
```
$errcode= Pezca::SetTimeout($timeout)
```
Set the timeout of the ezca-library (see ezca documentation)
SetTimeout
```
$errcode= Pezca::SetRetryCount($retry_count)
```
Set the retry-counter of the ezca-library (see ezca documentation)
AutoErrorMessageOn
```
Pezca::AutoErrorMessageOn()
```
Switch ezca error-messages to stdout on (default)
AutoErrorMessageOff
```
Pezca::AutoErrorMessageOff()    
```
Switch ezca error-messages to stdout off
Perror
```
Pezca::Perror($prefix)    
```
Print the status and possible error string of the last Channel Access call. The prefix string is prepended to the string.
GetErrorString
```
($ret,$string)= Pezca::GetErrorString($prefix)    
```
Return the status and possible error string of the last Channel Access call. The prefix string is prepended to the string that is returned. The return value "$ret" is the return code of ezcaGetErrorString().
Delay
```
$errcode= Pezca::Delay($time)
```
This function has to be called when a monitor is set up and there is a rather long time between two consecutive calls of Pesca::Get(). The given parameter should be 0.01 (see also ezca documentation).
Pend_Event
```
$errcode= Pezca::Pend_Event($time)
```
This function calls ca_pend_event() which gives channel access the chance to process incoming data. The parameter is a timeout-time (in seconds), after which Pend_Event returns.
StartGroup
```
Pezca::StartGroup()
```
When doing a large block of unconditional reads and/or writes, it is more efficient to do them in a group rather than individually. The call of this function starts group. The actual work is postponed until the end of the group is encountered.
EndGroup
```
$errcode= Pezca::EndGroup()
```
When doing a large block of unconditional reads and/or writes, it is more efficient to do them in a group rather than individually. The call of this function ends group. The actual work is postponed until the end of the group is encountered.
DebugOn
```
Pezca::DebugOn()
```
Turn ON EZCA debug messages
DebugOff
```
Pezca::DebugOff()
```
Turn OFF EZCA debug messages

functions for backwards-compability:

These functions are here for backwards compability only. Do not use them in future applications.

Get

($val,$errcode)= Pezca::Get($channel_name)

Similar to Pezca::GetDouble()

GetS

($val,$errcode)= Pezca::GetS($channel_name)

Similar to Pezca::GetString()

Put

$errcode= Pezca::Put($channel_name,$value)

Similar to Pezca::PutDouble()

PutS

$errcode= Pezca::PutS($channel_name,$value)

Similar to Pezca::PutString()

SetMonitor
```
$errcode= Pezca::SetMonitor($channel_name)
```
Similar to Pezca::SetMonitorDouble()
SetMonitorS
```
$errcode= Pezca::SetMonitorS($channel_name)
```
Similar to Pezca::SetMonitorString()
ClearMonitor
```
$errcode= Pezca::ClearMonitor($channel_name)
```
Similar to Pezca::ClearMonitorDouble()
ClearMonitorS
```
$errcode= Pezca::ClearMonitorS($channel_name)
```
Similar to Pezca::ClearMonitorString()
NewMonitorValue
```
$errcode= Pezca::NewMonitorValue($channel_name)
```
Similar to Pezca::NewMonitorValueDouble()
NewMonitorValueS
```
$errcode= Pezca::NewMonitorValueS($channel_name)
```
Similar to Pezca::NewMonitorValueString()

AUTHOR

Goetz Pfeiffer, Goetz.Pfeiffer@helmholtz-berlin.de