Reference
=========

Constants/Data Types
--------------------

For Channel Access data types we use a short string that maps to EPICS Base
datatypes like this:

+----------------+------------------+
| Pezca Datatype |  EPICS Datatype  |
+================+==================+
| BYTE           |                  |
| CHAR           |                  |
| UCHAR          |  DBR_CHAR        |
+----------------+------------------+
| SHORT          |                  |
| USHORT         |  DBR_SHORT       |
+----------------+------------------+
| INT            |                  |
| UINT           |                  |
| LONG           |                  |
| ULONG          |  DBR_LONG        |
+----------------+------------------+
| FLOAT          |  DBR_FLOAT       |
+----------------+------------------+
| DOUBLE         |  DBR_DOUBLE      |
+----------------+------------------+
| STRING         |  DBR_STRING      |
+----------------+------------------+


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.

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.

GetList
+++++++

::

  ($errcode,@values)= Pezca::GetList($channel_name,$type,$no)

Gets a channel name, a type and the number of elements as parameter.
For types see `Constants/Data Types`_.
The type name must not be omitted. If the type is unknown, the function
prints an error message and stops your script.
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. 

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.

PutList
+++++++

::

  $errcode= Pezca::PutList($channel_name,$type,@values)

gets a channel name, a type and the list of elements as parameter.
For types see `Constants/Data Types`_.
The type name must not be omitted. If the type is unknown, the function
prints an error message and stops your script.
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 engineering 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 current timeout. Note that the overall timeout is `GetTimeout() *
GetRetryCount()`. In PezcaCA, the retry counter is used to calculate the
timeout, but it doesn't change anything aside from this, there is no concept of
"retries" here.

GetRetryCount
+++++++++++++

::

  $retry_count= Pezca::GetRetryCount()

Get the current Retry-Count. See GetTimeout() for more details.

SetTimeout
++++++++++

::

  $errcode= Pezca::SetTimeout($timeout)

Set the timeout. Note that the overall timeout is 
`GetTimeout() * GetRetryCount()`. In PezcaCA, the retry counter is used to
calculate the timeout, but it doesn't change anything aside from this,
there is no concept of "retries" here.

Note: The timeout set with `SetTimeout()` is only used to *establish* a
connection. For the timeout while waiting for channel access callbacks, see
below.

Note that the timeout for callbacks is defined by global variable
`$gbl_timeout_short_max`. It should have a value of `2**n/1000`. The
overall timeout for callbacks is then `$gbl_timeout_short_max * 2 -0.001`.

SetRetryCount
+++++++++++++

::

  $errcode= Pezca::SetRetryCount($retry_count)

Set the Retry-Count. See SetTimeout() for more details.

AutoErrorMessageOn
++++++++++++++++++

::

  Pezca::AutoErrorMessageOn()

Print ezca error-messages on stderr, this is the default.

AutoErrorMessageOff
+++++++++++++++++++

::

  Pezca::AutoErrorMessageOff()    

Do not print ezca error-messages on stderr.

Perror
++++++

::

  Pezca::Perror($prefix)    

Print the error message for the last channel access operation.

GetErrorString
++++++++++++++

::

  ($ret,$string)= Pezca::GetErrorString($prefix)    

Get the error message for the last channel access operation.

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()

In PezcaCA, this function does nothing.

EndGroup
++++++++

::

  $errcode= Pezca::EndGroup()

In PezcaCA, this function does nothing.

DebugOn
+++++++

::

  Pezca::DebugOn()

This causes more debug messages to be printed, e.g. with
`SetMonitorDouble`, Pezca prints a message when the callback function is
called. `SetMonitorDouble` is only effected when this function is called
first.

DebugOff
++++++++

::

  Pezca::DebugOff()

This switches off debug messages.

Differences to the original Pezca module
----------------------------------------

It should be possible to use this module as a replacement for the original
Pezca module, some functions are different:

These functions actually do nothing:

- StartGroup
- EndGroup

The timeout setting is compatible with Pezca so the overall timeout is
timeout multiplied by retry count. However, PezcaCA has not concept of
"retries". The synchronous functions do not retry, and the monitored
variables always to reconnect after a disconnect.

The timeout set with `SetTimeout()` is only used to *establish* a
connection. For the timeout while waiting for channel access callbacks, see
below.

The timeout for callbacks is defined by global variable
`$gbl_timeout_short_max`. It should have a value of `2**n/1000`. The
overall timeout for callbacks is then `$gbl_timeout_short_max * 2 -0.001`.