Examples
========

All examples below assume that there is a soft-IOC running with the following
database ("db") file::

  record(calc, "counter")
  # trigger everything
  {
    field(PINI, "YES")
    field(SCAN, "1 second")
    field(CALC, "A+1")
    field(INPA, "counter")
  }

  record(waveform, "waveform")
  {
    field(NELM, "3")
    field(FTVL, "DOUBLE")
  }

  record(compress, "buffer")
  {
      field(ALG, "Circular Buffer")
      field(INP, "counter CPP NMS")
      field(NSAM, "3") # Size of the buffer
  }

  record(ai, "ai_buffer")
  # trigger everything
  {
  }

  record(ao, "ao_buffer")
  {
    field(HOPR, 100)
    field(LOPR, -50)
    field(DRVH, 99)
    field(DRVL, -49)
    field(PREC, 3)
    field(EGU, "VOLT")
  }

  record(mbbo, "mbbo")
  {
    field(ZRST, "VAL0")
    field(ONST, "VAL1")
    field(TWST, "VAL2")
  }

Read a variable synchronously
+++++++++++++++++++++++++++++

This is an example for synchronous read. The program blocks until the value
was read.

Note: This establishes a single new connection to the IOC, fetches the value
and destroys the connection. Do not do this in a loop! ::

  use Pezca;

  $PV="counter";

  my($err, $val)=Pezca::GetDouble($PV);
  print("Err:$err Val:$val\n");

Read a variable asynchronously with a subscription (monitor)
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

This program sets up a monitor on the PV, then tests if there is a new value.
If not, it prints a dot '.'. If there is a new value it fetches the value and
prints it to the console.

By creating a monitor with `SetMonitorDouble`, the script uses an *efficient*
way to communicate with the IOC. Each time the PV has a new value, an
internal callback function stores the value in a buffer. `GetDouble` simply
reads the value from that buffer, so this doesn't create extra network
traffic.

The internal callback function must get time to run, this is in function
`Delay`. You must use this function for delays, do not use `sleep` since this
doesn't process channel access events.

::

  use Pezca;

  $PV="counter";
  Pezca::SetMonitorDouble($PV);
  for(my $i =0; $i<100; $i++)
    {
      if (!Pezca::NewMonitorValueDouble($PV))
        {
          print(".");
          select()->flush();
          Pezca::Delay(0.1);
        }
      else
        {
          my($err, $val)=Pezca::GetDouble($PV);
          print("Err:$err Val:$val\n");
        }
    };

Read a list variable (e.g. Waveform Record)
+++++++++++++++++++++++++++++++++++++++++++

In the following example we read a list with length specification ranging
from 0 to 4::

  use Pezca;

  $PV="buffer";

  for(my $i =0; $i<10; $i++)
    {
      my $no= int($i/2);
      my($err, @val)=Pezca::GetList($PV, "DOUBLE", $no);
      print("No:$no Err:$err Val:@val\n");

      Pezca::Delay(0.5);
    };

Read a list variable with a monitor
+++++++++++++++++++++++++++++++++++

In the following example we read a list variable with a monitor::

  use Pezca;

  $PV="buffer";

  Pezca::SetMonitorDouble($PV);

  for(my $i =0; $i<10; $i++)
    {
      my($err, @val)=Pezca::GetList($PV, "DOUBLE");
      print("No:$no Err:$err Val:@val\n");
      Pezca::Delay(0.5);
    };

Write a variable synchronously
++++++++++++++++++++++++++++++

This is an example for synchronous write. After write, the variable is read to
show that the value was stored in the record::

  use Pezca;

  $PV="ai_buffer";

  my $err=Pezca::PutDouble($PV, $i);
  print("put $i...: Err:$err\n");
  my($err, $val)=Pezca::GetDouble($PV);
  print("get : Err:$err Val:$val\n");

Write a string variable synchronously
+++++++++++++++++++++++++++++++++++++

This is an example for synchronous write of a string variable. After write,
the variable is read to show that the value was stored in the record::

  use Pezca;

  $PV="mbbo";

  my $w_st;
  my $r_st;

  foreach my $w_st (qw(VAL0 VAL1 VAL2))
    {
      my $err=Pezca::PutString($PV,$w_st);
      print("put $w_st...: Err:$err\n");
      my($err, $r_st)=Pezca::GetString($PV);
      print("get : Err:$err Val:$r_st\n");
      Pezca::Delay(2.0);
    }

Write a list variable synchronously
+++++++++++++++++++++++++++++++++++

This is an example for synchronous write of a list variable. After write, the
variable is read to show that the value was stored in the record::

  use Pezca;

  $PV="waveform";

  my $a= $i; my $b= $i+1; my $c= $i+2;
  my $err=Pezca::PutList($PV, "DOUBLE", $a, $b, $c);
  print("put $a $b $c...: Err:$err\n");
  my($err, @val)=Pezca::GetList($PV, "DOUBLE");
  print("get : Err:$err Val:@val\n");

Read some meta information of a record
++++++++++++++++++++++++++++++++++++++

Here we read some extra fields of a record::

  use Pezca;

  $PV1="ao_buffer";
  $PV2="buffer";

  print("Get DRVL and DRVH of $PV1.\n");
  my  ($errcode,$low,$high)= Pezca::GetControlLimits($PV1);
  print("err:$errcode  DRVL:$low  DRVH:$high\n");
  print("\n");
  print("Get LOPR: and HOPR: of $PV1.\n");
  my  ($errcode,$low,$high)= Pezca::GetGraphicLimits($PV1);
  print("err:$errcode  LOPR:$low  HOPR:$high\n");
  print("\n");
  print("Get number of elements from $PV2.\n");
  my ($errcode,$no)= Pezca::GetNelem($PV2);
  print("err:$errcode, elements:$no\n");
  print("\n");
  print("Get precision of $PV1.\n");
  my ($errcode,$prec)= Pezca::GetPrecision($PV1);
  print("err:$errcode, PREC:$prec\n");
  print("\n");
  print("Get units of $PV1.\n");
  my ($errcode,$units)= Pezca::GetUnits($PV1);
  print("err:$errcode, UNITS:$units\n");