322 lines
10 KiB
HTML
322 lines
10 KiB
HTML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
|
|
<title>pva C++ Overview</title>
|
|
<link rel="stylesheet" type="text/css"
|
|
href="http://epics-pvdata.sourceforge.net/base.css" />
|
|
<link rel="stylesheet" type="text/css"
|
|
href="http://epics-pvdata.sourceforge.net/epicsv4.css" />
|
|
<style type="text/css">
|
|
/*<![CDATA[*/
|
|
.about { margin-left: 3em; margin-right: 3em; font-size: .83em}
|
|
table { margin-left: auto; margin-right: auto }
|
|
.diagram { text-align: center; margin: 2.5em 0 }
|
|
body { margin-right: 10% }
|
|
/*]]>*/</style>
|
|
|
|
<!-- Script that generates the Table of Contents -->
|
|
<script type="text/javascript" src="http://epics-pvdata.sourceforge.net/script/tocgen.js"></script>
|
|
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<div class="head">
|
|
<h1>Pva C++ Overview</h1>
|
|
|
|
</div> <!-- head -->
|
|
|
|
<div id="toc">
|
|
<h2 class="nocount">Table of Contents</h2>
|
|
</div>
|
|
|
|
<!-- Place what you would like in the Table of Contents, inside the contents div -->
|
|
<div id="contents" class="contents">
|
|
<hr />
|
|
|
|
<h2>Introduction</h2>
|
|
|
|
<p>Pva is a synchronous API for accessing PVData via PVAccess.
|
|
It also provides a number of convenience methods.
|
|
It allows the client to request access without checking for failure,
|
|
but throws an exception if a request fails.
|
|
A client can also check for failues and thus prevent exceptions.</p>
|
|
|
|
<p>The Pva API has the following features:</p>
|
|
<ol>
|
|
<li>Provides a synchronous API rather than the callback API provided by pvAccess.</li>
|
|
<li>Makes common requests pva.</li>
|
|
<li>Provides full access to the pvAccess API for more demanding
|
|
applications</li>
|
|
<li>Allows efficient client side programs.</li>
|
|
<li>Takes care of most object resource management problems.</li>
|
|
</ol>
|
|
<p>Simple examples of using pva:</p>
|
|
<pre>
|
|
// pvaGet
|
|
PvaPtr pva = Pva::create();
|
|
double value = pva->channel("exampleDouble")->get()->getData()->getDouble();
|
|
|
|
// pvaPut
|
|
PvaChannelPtr channel = pva->channel("exampleDouble");
|
|
PvaPutPtr put = channel->put();
|
|
PvaPutDataPtr putData = put->getData();
|
|
putData->putDouble(3.0); put->put();
|
|
|
|
// pvaMonitor
|
|
PvaMonitorPtr monitor = pva->channel("examplePowerSupply")->monitor("");
|
|
PvaMonitorDataPtr pvaData = monitor->getData();
|
|
while(true) {
|
|
monitor->waitEvent();
|
|
cout << "changed\n";
|
|
pvaData->showChanged(cout);
|
|
cout << "overrun\n";
|
|
pvaData->showOverrun(cout);
|
|
monitor->releaseEvent();
|
|
}
|
|
|
|
// pvaProcess
|
|
PvaChannelPtr channel = pva->channel("exampleDouble");
|
|
PvaProcessPtr process = channel->createProcess();
|
|
process->process();
|
|
|
|
</pre>
|
|
<p><b>pvaExample</b> includes a number of examples.</p>
|
|
<p>pva does <b>not</b> provide support for:</p>
|
|
<dl>
|
|
<dt>ChannelArray</dt>
|
|
<dd>TBD</dd>
|
|
<dt>ChannelRPC</dt>
|
|
<dd>pvAccess itself already provides a synchronous interface.
|
|
The examples include helloWorldRPC, which is an example of using channelRP.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h2>Pva</h2>
|
|
<p>An instance of Pva is obtained via the call:</p>
|
|
<pre>
|
|
PvaPtr pva = Pva::create();
|
|
</pre>
|
|
|
|
<p>Pva has methods to create instances of <b>PvaChannel</b>.
|
|
The client can specify the provider name or use the default provider.
|
|
The client can manage it's own channels or can let pva cache channels.
|
|
An example of using the cached method is:</p>
|
|
<pre>
|
|
PvaChannelPtr pvaChannel = pva->channel("exampleDouble");
|
|
</pre>
|
|
<p>This will attempt to connect to channel exampleDouble.
|
|
Since the client did not specify a timeout an exception wll be thrown if
|
|
the connection request fails.
|
|
The client will block until the connection is made or an exception is thrown.
|
|
If the request succeeds, pva caches the pvaChannel so that if the
|
|
client makes another request for the same channel the cached object is
|
|
returned to the client.
|
|
</p>
|
|
<p>An example of using a non cached method is:</p>
|
|
<pre>
|
|
PvaChannelPtr pvaChannel = pva->createChannel("exampleDouble");
|
|
</pre>
|
|
<p>This will create an PvaChannel and return it to the client.
|
|
The client must itself connect.
|
|
This is useful if the client wants to connect to multiple channels in parallel.
|
|
</p>
|
|
|
|
<h2>PvaChannel - Wrapper For Single Channel</h2>
|
|
<h3>PvaChannel</h3>
|
|
<p>This provides methods for connecting to a channel and for creating instances of
|
|
PvaField, PvaProcess, ..., PvaPutGet.</p>
|
|
<p>Connection must be made before any create method is called or
|
|
an exception is raised.
|
|
The following is a synchronous connection request:</p>
|
|
<pre>
|
|
pvaChannel->connect(5.0); // BLOCKS AND THROWS IF NO CONNECT
|
|
</pre>
|
|
<p>This blocks until then connection is made or until timout occurs.
|
|
An exception is raised if the connection request fails.
|
|
</p>
|
|
<p>The same request can be made without blocking and without exceptions.</p>
|
|
<pre>
|
|
pvaChannel->issueConnect(); // DOES NOT BLOCK
|
|
.....
|
|
Status status =pvaChannel->waitConnect(5.0); // BLOCKS DOES NOT THROW
|
|
if(!status.isOK()) {
|
|
// failure do something
|
|
}
|
|
</pre>
|
|
<p>Once the channel is connected other Pva objects can be created.
|
|
For example:</p>
|
|
<pre>
|
|
PvaGetPtr pvaGet = pvaChannel->get(); // DOES BLOCK
|
|
</pre>
|
|
<p>This is a caching request.
|
|
If the client already has made an identical request the client will receive the
|
|
cached object.
|
|
If a new pvaGet is created than it is connected before it is returned to the client.
|
|
</p>
|
|
<p>The client can also managed it's own objects:</p>
|
|
<pre>
|
|
PvaGetPtr pvaGet = pvaChannel->createGet(); // DOES NOT BLOCK
|
|
</pre>
|
|
<p>The client must connect the pvaGet.</p>
|
|
|
|
<h3>PvaGetData</h3>
|
|
<p>This provides the data returned by pvaGet and pvaPutGet.
|
|
It is obtained via:</p>
|
|
<pre>
|
|
PvaGetDataPtr pvaData = pvaGet->getData();
|
|
</pre>
|
|
<p>It provides methods to get everything returned by channelGet.
|
|
In addition there are methods that make it easier to handle a value
|
|
field that is a scalar or a scalarArray.
|
|
Also for a scalar that is a double or a scalarArray with element type double.
|
|
</p>
|
|
<p>An example is:</p>
|
|
<pre>
|
|
double value = pvaData->getDouble();
|
|
</pre>
|
|
<p>It also keeps a bitSet showing which fields have changed since the last channelGet or channelPutGet.</p>
|
|
|
|
<h3>PvaMonitorData</h3>
|
|
<p>To the client this looks identical to PvaGetData except that
|
|
it provides two BitSets: changedBitSet and overrrunBitSet.
|
|
It is used by pvaMonitor.
|
|
</p>
|
|
<h3>PvaPutData</h3>
|
|
<p>This is used to provided data for pvaPut and pvaPutGet.
|
|
It has many of the same methods as pvaGetData.
|
|
It does not have a bitSet.
|
|
It also has put methods like:</p>
|
|
<pre>
|
|
void pvaData->putDouble(5.0);
|
|
</pre>
|
|
<h3>PvaGet</h3>
|
|
<p>This provides methods to connect to channelGet and to issue get request.
|
|
To connect via a single synchronous call:</p>
|
|
<pre>
|
|
eastGet->connect(); // BLOCKS AND CAN THROW
|
|
</pre>
|
|
<p>This can also be done in two steps:</p>
|
|
<pre>
|
|
pvaGet->issueConnect(); // DOES NOT BLOCK
|
|
...
|
|
Status status = pvaGet->waitConnect(); // BLOCKS AND DOES NOT HROW
|
|
</pre>
|
|
<p>Once connected gets are issued via either:</p>
|
|
<pre>
|
|
void pvaGet->get(); // BLOCKS AND CAN THROW
|
|
</pre>
|
|
or
|
|
<pre>
|
|
pvaGet->issueGet(); // DOES NOT BLOCK
|
|
...
|
|
Status status = pvaGet->waitGet(); // BLOCKS AND DOES NOT THROW
|
|
</pre>
|
|
<h3>PvaPut</h3>
|
|
<p>This is similar to pvaGet except that it wraps channelPut instead of channelGet.
|
|
</p>
|
|
<p>Once connected puts are issued via either:</p>
|
|
<pre>
|
|
void pvaPut->put(); // BLOCKS AND CAN THROW
|
|
</pre>
|
|
or
|
|
<pre>
|
|
pvaPut->issuePut(); // DOES NOT BLOCK
|
|
...
|
|
Status status = pvaPut->waitPut(); // BLOCKS AND DOES NOT THROW
|
|
</pre>
|
|
<h3>PvaMonitor</h3>
|
|
<p>Connecting is similar to pvaGet and pvaPut.
|
|
The other methods are:</p>
|
|
<dl>
|
|
<dt>start</dt>
|
|
<dd>Starts monitoring</dd>
|
|
<dt>stop</dt>
|
|
<dd>Stops monitoring</dd>
|
|
<dt>poll</dt>
|
|
<dd>polls for a monitorEvent.
|
|
The data is avalable via pvaMonitorData.
|
|
</dd>
|
|
<dt>releaseEvent</dt>
|
|
<dd>Release the data from the last poll.
|
|
Note that this must be called before another poll is requested.
|
|
</dd>
|
|
<dt>waitEvent</dt>
|
|
<dd>Block until a monitorEvent is available.
|
|
If true is returned a poll has already been issued.
|
|
</dd>
|
|
<dt>setRequester</dt>
|
|
<dd>A client callback is registered to receive notice of monitorEvents.</dd>
|
|
</dl>
|
|
<h3>PvaProcess</h3>
|
|
<p>Connecting is similar to pvaGet.
|
|
It has methods:</p>
|
|
<dl>
|
|
<dt>process</dt>
|
|
<dd>call issueProcess and waitProcess.</dd>
|
|
<dt>issueProcess</dt>
|
|
<dd>call channelProcess->process() and return immediately.
|
|
</dd>
|
|
<dt>waitProcess</dt>
|
|
<dd>Wait for process to complete.</dd>
|
|
</dl>
|
|
<h3>PvaPutGet</h3>
|
|
<p>Connecting is similar to pvaGet.
|
|
It has methods:</p>
|
|
<dl>
|
|
<dt>putGet</dt>
|
|
<dd>calls issuePutGet and waitPutGet.
|
|
throws an exception if not successfull.
|
|
</dd>
|
|
<dt>issuePutGet</dt>
|
|
<dd>
|
|
Calls channel->putGet() and returns.
|
|
</dd>
|
|
<dt>waitPutGet</dt>
|
|
<dd>
|
|
Waits until putGet completes and returns status.
|
|
</dd>
|
|
<dt>getGet,issueGetGet, and waitGetGet</dt>
|
|
<dd>Gets the data for the get part of channelPutGet.</dd>
|
|
<dt>getPut,issueGetPut,and waitGetPut</dt>
|
|
<dd>Gets the data for the put part of channelPutGet.</dd>
|
|
<dt>getPutData</dt>
|
|
<dd>
|
|
Returns the PvaData for the put part of channelPutGet.
|
|
</dd>
|
|
<dt>getGetData</dt>
|
|
<dd>
|
|
Returns the PvaData for the get part of channelPutGet.
|
|
</dd>
|
|
</dl>
|
|
<p>Look at javaDoc for details.</p>
|
|
|
|
<h2>PvaMultiChannel - Wrapper For Multiple Channels</h2>
|
|
<h3>PvaMultiChannel</h3>
|
|
<p>This provides methods for connecting to multiple channels.
|
|
A client can either use PvaMultiChannel directly or use PvaMultiDouble or PvaNTMultiChannel.
|
|
But both impose restrictions on what can be accessed.
|
|
</p>
|
|
<h3>PvaMultiDouble</h3>
|
|
<p>This provides support for gets and puts to the value field of multiple channels.
|
|
Each channel must have a value field that is a numeric scalar.
|
|
The client always sees the data as a PVDoubleArray.
|
|
All channels must connect.
|
|
If any problems occur an exception is thrown.
|
|
</p>
|
|
<h3>PvaNTMultiChannel</h3>
|
|
<p>This provides support for gets and puts to the value field of multiple channels.
|
|
Each channel must have a value field.
|
|
The client always sees the data as a NTMultiChannel, which is one
|
|
of the types provided by normativeTypesCPP.
|
|
All channels must connect.
|
|
If any problems occur an exception is thrown.
|
|
</p>
|
|
|
|
</div> <!-- class="contents" -->
|
|
</body>
|
|
</html>
|