changes to README.txt jenkins/cloudbees_build documentation

This commit is contained in:
Marty Kraimer
2015-06-17 15:28:28 -04:00
parent 0d0b6ebac0
commit b1594e6b78
6 changed files with 122 additions and 149 deletions

View File

@@ -1,7 +1,3 @@
THIS MODULE IS NO LONGER SUPPORTED.
It's functionality has been moved to pvAccessCPP and renamed fro EasyPVA to Pva.
To build do the following:
cd configure
@@ -10,4 +6,4 @@ edit RELEASE.local
cd ..
make
Now read documentation/easyPVA.html
Now read documentation/pvaClientCPP.html

View File

@@ -2,7 +2,7 @@
TEMPLATE_TOP=$(EPICS_BASE)/templates/makeBaseApp/top
EPICS_BASE=/home/install/epics/base
V4BASE=/home/hg
V4BASE=/home/epicsv4
PVCOMMON=${V4BASE}/pvCommonCPP
PVDATA=${V4BASE}/pvDataCPP
NORMATIVETYPES=${V4BASE}/normativeTypesCPP

View File

@@ -4,7 +4,7 @@
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
<title>EPICS easyPVA</title>
<title>EPICS pva</title>
<link rel="stylesheet" type="text/css"
href="http://epics-pvdata.sourceforge.net/base.css" />
<link rel="stylesheet" type="text/css"
@@ -25,54 +25,48 @@
<body>
<div class="head">
<h1>EPICS easyPVA</h1>
<h1>EPICS pvaClientCPP</h1>
<!-- Maturity: Working Draft or Request for Comments, or Recommendation, and date. -->
<h2 class="nocount">EPICS V4 Working Group, Working Draft,
25-Mar-2015</h2>
29-May-2015</h2>
<dl>
<dt>This version:</dt>
<dd><a
href="easyPVA.html">easyPVA.html
href="pvaClientCPP.html">pvaClientCPP.html
</a> </dd>
<dt>Latest version:</dt>
<dd>Still under revision</dd>
<dt>Previous version:</dt>
<dd><a
href="easyPVA_20150609.html">easyPVA_20150609.html</a>
</dd>
<dt>Previous version:</dt>
<dd><a
href="easyPVA_20150325.html">easyPVA_20150325.html</a>
</dd>
<dt>Editors:</dt>
<dd>Marty Kraimer, BNL</dd>
<dd>Matej Sekoranja, Cosylab</dd>
</dl>
<h2 class="nocount">Abstract</h2>
<p><b>NO LONGER SUPPPORTED:</b>
The functionality has been moved to pvAccessCPP and EasyPva renamed to Pva.
</p>
<p>EasyPVA (Easy PVAccess) is a software library that provides to an EPICS client programmer, a friendly
<p>pvaClient is a software library that provides to an EPICS client programmer, a friendly
client side programming interface to the data of an EPICS based control system. It is intended
for such uses as rapid development of ad hoc programs by controls engineers, or to provide
scientists a way to directly develop analytical applications.</p>
<p>Specifically, easyPVA provides an easy interface for pvAccess, which is the
<p>Specifically, pvaClient provides a synchronous interface for pvAccess, which is the
software support for high speed controls network communications used in EPICS version 4.
PvAccess provides a callback based interface, which can be hard to use.
EasyPVA provides an interface that does not require callbacks even for monitors.
pvAccess provides a callback based interface, which can be hard to use.
pvaClient provides an interface that does not require callbacks even for monitors.
</p>
<p>
EasyChannel provides many "convenience" methods to directly get and put
p>
pvaClientChannel provides many "convenience" methods to directly get and put
scalar and scalarArray data types.
Additional methods provide access to the full features of pvAccess.
</p>
<p>
EasyMultiChannel provides access to data from multiple channels.
It can be used directly by a client or via EasyMultiDouble or EasyNTMultiChannel.
EasyMultiDouble allows the client to get and put data to multiple channels.
pvaClientMultiChannel provides access to data from multiple channels.
It can be used directly by a client or via pvaClientMultiDouble or pvaClientNTMultiChannel.
pvaClientMultiDouble allows the client to get and put data to multiple channels.
But each channel must have a value field that is a numeric scalar.
EasyNTMultiChannel allows the client to get and put data to multiple channels.
pvaClientNTMultiChannel allows the client to get and put data to multiple channels.
Each channel must have a value field.
The data for the channels is presented via normative type NTMultiChannel.
</p>
@@ -83,9 +77,9 @@ The data for the channels is presented via normative type NTMultiChannel.
<h2 class="nocount">Status of this Document and of the EasyPVA Software</h2>
<h2 class="nocount">Status of this Document and of the pvaClient Software</h2>
<p>EasyPVACPP is ready for use.</p>
<p>pvaClientCPP is ready for use.</p>
</div> <!-- head -->
@@ -99,14 +93,14 @@ The data for the channels is presented via normative type NTMultiChannel.
<h2>Introduction</h2>
<p>EasyPVA is a synchronous API for accessing PVData via PVAccess. It provides
<p>pvaClient is a synchronous API for accessing PVData via PVAccess. It provides
an interface to many of the features provided by pvData and pvAccess.</p>
<p>This document describes the layout of the source files in this project.</p>
<p>
A user overview is available via
<a
href="./overview.html">overview.html
href="./pvaClientOverview.html">pvaClientOverview.html
</a>
</p>
<p>
@@ -115,27 +109,10 @@ Doxygen documentation is available at
href="./html/index.html">doxygenDoc
</a>
</p>
<h2>Building</h2>
<p>After obtaining the source:</p>
<pre>
cd configure
cp ExampleRELEASE.local RELEASE.local
</pre>
<p>Edit <b>RELEASE.local</b> so that all path names are correct for you environment.
</p>
<p>
Then:</p>
<pre>
cd ..
make
</pre>
<h2>Example and Test Database</h2>
<h2>Example Database</h2>
<p>The examples and tests require that an example pvAccess server is runnimg.
This distribution has a file <b>exampleDatabaseEasyPVA.zip</b>.
This distribution has a file <b>exampleDatabasePvaClient.zip</b>.
When unzipped this is used to create an example IOC database.
The database has the record used by the examples are tests that come with easyPVAJava.
It uses pvDatabaseCPP to build the database.
</p>
<p>
After unzipping the file:
@@ -156,17 +133,17 @@ cd iocBoot/exampleDatabase
make runtests
</pre>
<h2>Examples</h2>
<p>Examples are in directory <b>example/src</b>.
<p>Examples are in directory <b>pvaExample/src</b>.
An example of how to run them is:</p>
<pre>
mrk&gt; pwd
/home/hg/easyPVACPP/example
mrk&gt; bin/linux-x86_64/exampleEasyGet
/home/epicsv4/pvAccessCPP/pvaExample
mrk&gt; bin/linux-x86_64/examplepvaClientGet
</pre>
<p>The following is a brief description of each example.
In order to understand each example it
helps to also bee loooking at the source for the example.</p>
<h2>exampleEasyGet</h2>
helps to also look at the source for the example.</p>
<h2>examplePvaClientGet</h2>
<p>This has a number of examples:</p>
<dl>
<dt>exampleDouble</dt>
@@ -193,7 +170,7 @@ helps to also bee loooking at the source for the example.</p>
have a value field.
</dd>
</dl>
<h2>exampleEasyMonitor</h2>
<h2>examplePvaClientMonitor</h2>
<p>This is an example of creating a monitor on a channel.
It monitors a channel that models a powerSupply, i. e. it is not a "standard" record.
It does not have a value field.
@@ -202,21 +179,21 @@ It does not have a value field.
<pre>
pvput -r "power.value,voltage.value" examplePowerSupply 6 6
</pre>
<h2>exampleEasyPut</h2>
<h2>examplePvaClientPut</h2>
<p>This example gets and puts to channel exampleDouble.</p>
<h2>exampleEasyProcess</h2>
<h2>examplePvaClientProcess</h2>
<p>This example makes a process request to channel exampleDouble.</p>
<h2>helloWorldPutGet</h2>
<p>This is an example of issuing a channelPutGet.</p>
<h2>exampleEasyMultiDouble</h2>
<h2>examplePvaClientMultiDouble</h2>
<p>This is an example of issuing gets and puts to multiple channels where each
channel has a numeric scalar value field.</p>
<h2>exampleEasyNTMultiChannel</h2>
<h2>examplePvaClientNTMultiChannel</h2>
<p>This is an example of using NDMultiChannel to obtain data from multiple channels.
</p>
<h2>helloWorldRPC</h2>
<p>This is an example of issuing a channelRPC request.
It does <b>not</b> use easyPVA.</p>
It does <b>not</b> use pva.</p>
</div> <!-- class="contents" -->
</body>
</html>

View File

@@ -4,7 +4,7 @@
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
<title>easyPVA C++ Overview</title>
<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"
@@ -25,7 +25,7 @@
<body>
<div class="head">
<h1>easyPVA C++ Overview</h1>
<h1>PvaClient C++ Overview</h1>
</div> <!-- head -->
@@ -39,135 +39,135 @@
<h2>Introduction</h2>
<p>EasyPVA is a synchronous API for accessing PVData via PVAccess.
It also provides a number of convience methods.
<p>PvaClient 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 when a reuest fails.
A client can also check for failues and thus prevent failures.</p>
but throws an exception if a request fails.
A client can also check for failues and thus prevent exceptions.</p>
<p>The EasyPVA API has the following features:</p>
<p>The PvaClient 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 easy.</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 easyPVA:</p>
<p>Simple examples of using pva:</p>
<pre>
// easyGet
EasyPVAPtr easyPVA = EasyPVA::create();
double value = easyPVA-&gt;channel("exampleDouble")-&gt;get()-&gt;getData()-&gt;getDouble();
// pvaGet
PvaClientPtr pva = PvaClient::create();
double value = pva-&gt;channel("exampleDouble")-&gt;get()-&gt;getData()-&gt;getDouble();
// easyPut
EasyChannelPtr channel = easyPVA-&gt;channel("exampleDouble");
EasyPutPtr put = channel-&gt;put();
EasyPutDataPtr putData = put-&gt;getData();
// pvaPut
PvaClientChannelPtr channel = pva-&gt;channel("exampleDouble");
PvaClientPutPtr put = channel-&gt;put();
PvaClientPutDataPtr putData = put-&gt;getData();
putData-&gt;putDouble(3.0); put-&gt;put();
// easyMonitor
EasyMonitorPtr monitor = easyPVA-&gt;channel("examplePowerSupply")-&gt;monitor("");
EasyMonitorDataPtr easyData = monitor-&gt;getData();
// pvaMonitor
PvaClientMonitorPtr monitor = pva-&gt;channel("examplePowerSupply")-&gt;monitor("");
PvaClientMonitorDataPtr pvaData = monitor-&gt;getData();
while(true) {
monitor-&gt;waitEvent();
cout &lt;&lt; "changed\n";
easyData-&gt;showChanged(cout);
pvaData-&gt;showChanged(cout);
cout &lt;&lt; "overrun\n";
easyData-&gt;showOverrun(cout);
pvaData-&gt;showOverrun(cout);
monitor-&gt;releaseEvent();
}
// easyProcess
EasyChannelPtr channel = easyPVA-&gt;channel("exampleDouble");
EasyProcessPtr process = channel-&gt;createProcess();
// pvaProcess
PvaClientChannelPtr channel = pva-&gt;channel("exampleDouble");
PvaClientProcessPtr process = channel-&gt;createProcess();
process-&gt;process();
</pre>
<p><b>easyPVACPP</b> includes a number of examples.</p>
<p>easyPVA does <b>not</b> provide support for:</p>
<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 an easy to use synchronous interface.
<dd>pvAccess itself already provides a synchronous interface.
The examples include helloWorldRPC, which is an example of using channelRP.
</dd>
</dl>
<h2>EasyPVA</h2>
<p>An instance of EasyPVA is obtained via the call:</p>
<h2>PvaClient</h2>
<p>An instance of PvaClient is obtained via the call:</p>
<pre>
EasyPVAPtr easyPVA = EasyPVA::create();
PvaClientPtr pva = PvaClient::create();
</pre>
<p>EasyPVA has methods to create instances of <b>EasyChannel</b>.
<p>PvaClient has methods to create instances of <b>PvaClientChannel</b>.
The client can specify the provider name or use the default provider.
The client can manage it's own channels or can let easyPVA cache channels.
The client can manage it's own channels or can let pva cache channels.
An example of using the cached method is:</p>
<pre>
EasyChannelPtr easyChannel = easyPVA-&gt;channel("exampleDouble");
PvaClientChannelPtr pvaChannel = pva-&gt;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, easyPVA caches the easyChannel so that if the
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>
EasyChannelPtr easyChannel = easyPVA-&gt;createChannel("exampleDouble");
PvaClientChannelPtr pvaChannel = pva-&gt;createChannel("exampleDouble");
</pre>
<p>This will create an EasyChannel and return it to the client.
<p>This will create an PvaClientChannel 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>EasyChannel - Wrapper For Single Channel</h2>
<h3>EasyChannel</h3>
<h2>PvaClientChannel - Wrapper For Single Channel</h2>
<h3>PvaClientChannel</h3>
<p>This provides methods for connecting to a channel and for creating instances of
EasyField, EasyProcess, ..., EasyPutGet.</p>
PvaClientField, PvaClientProcess, ..., PvaClientPutGet.</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>
easyChannel-&gt;connect(5.0); // BLOCKS AND THROWS IF NO CONNECT
pvaChannel-&gt;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>
easyChannel-&gt;issueConnect(); // DOES NOT BLOCK
pvaChannel-&gt;issueConnect(); // DOES NOT BLOCK
.....
Status status =easyChannel-&gt;waitConnect(5.0); // BLOCKS DOES NOT THROW
Status status =pvaChannel-&gt;waitConnect(5.0); // BLOCKS DOES NOT THROW
if(!status.isOK()) {
// failure do something
}
</pre>
<p>Once the channel is connected other Easy objects can be created.
<p>Once the channel is connected other PvaClient objects can be created.
For example:</p>
<pre>
EasyGetPtr easyGet = easyChannel-&gt;get(); // DOES BLOCK
PvaClientGetPtr pvaGet = pvaChannel-&gt;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 easyGet is created than it is connected before it is returned to the client.
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>
EasyGetPtr easyGet = easyChannel-&gt;createGet(); // DOES NOT BLOCK
PvaClientGetPtr pvaGet = pvaChannel-&gt;createGet(); // DOES NOT BLOCK
</pre>
<p>The client must connect the easyGet.</p>
<p>The client must connect the pvaGet.</p>
<h3>EasyGetData</h3>
<p>This provides the data returned by easyGet and easyPutGet.
<h3>PvaClientGetData</h3>
<p>This provides the data returned by pvaGet and pvaPutGet.
It is obtained via:</p>
<pre>
EasyGetDataPtr easyData = easyGet-&gt;getData();
PvaClientGetDataPtr pvaData = pvaGet-&gt;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
@@ -176,24 +176,24 @@ Also for a scalar that is a double or a scalarArray with element type double.
</p>
<p>An example is:</p>
<pre>
double value = easyData-&gt;getDouble();
double value = pvaData-&gt;getDouble();
</pre>
<p>It also keeps a bitSet showing which fields have changed since the last channelGet or channelPutGet.</p>
<h3>EasyMonitorData</h3>
<p>To the client this looks identical to EasyGetData except that
<h3>PvaClientMonitorData</h3>
<p>To the client this looks identical to PvaClientGetData except that
it provides two BitSets: changedBitSet and overrrunBitSet.
It is used by easyMonitor.
It is used by pvaMonitor.
</p>
<h3>EasyPutData</h3>
<p>This is used to provided data for easyPut and easyPutGet.
It has many of the same methods as easyGetData.
<h3>PvaClientPutData</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 easyData-&gt;putDouble(5.0);
void pvaData-&gt;putDouble(5.0);
</pre>
<h3>EasyGet</h3>
<h3>PvaClientGet</h3>
<p>This provides methods to connect to channelGet and to issue get request.
To connect via a single synchronous call:</p>
<pre>
@@ -201,35 +201,35 @@ eastGet-&gt;connect(); // BLOCKS AND CAN THROW
</pre>
<p>This can also be done in two steps:</p>
<pre>
easyGet-&gt;issueConnect(); // DOES NOT BLOCK
pvaGet-&gt;issueConnect(); // DOES NOT BLOCK
...
Status status = easyGet-&gt;waitConnect(); // BLOCKS AND DOES NOT HROW
Status status = pvaGet-&gt;waitConnect(); // BLOCKS AND DOES NOT HROW
</pre>
<p>Once connected gets are issued via either:</p>
<pre>
void easyGet-&gt;get(); // BLOCKS AND CAN THROW
void pvaGet-&gt;get(); // BLOCKS AND CAN THROW
</pre>
or
<pre>
easyGet-&gt;issueGet(); // DOES NOT BLOCK
pvaGet-&gt;issueGet(); // DOES NOT BLOCK
...
Status status = easyGet-&gt;waitGet(); // BLOCKS AND DOES NOT THROW
Status status = pvaGet-&gt;waitGet(); // BLOCKS AND DOES NOT THROW
</pre>
<h3>EasyPut</h3>
<p>This is similar to easyGet except that it wraps channelPut instead of channelGet.
<h3>PvaClientPut</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 easyPut-&gt;put(); // BLOCKS AND CAN THROW
void pvaPut-&gt;put(); // BLOCKS AND CAN THROW
</pre>
or
<pre>
easyPut-&gt;issuePut(); // DOES NOT BLOCK
pvaPut-&gt;issuePut(); // DOES NOT BLOCK
...
Status status = easyPut-&gt;waitPut(); // BLOCKS AND DOES NOT THROW
Status status = pvaPut-&gt;waitPut(); // BLOCKS AND DOES NOT THROW
</pre>
<h3>EasyMonitor</h3>
<p>Connecting is similar to easyGet and easyPut.
<h3>PvaClientMonitor</h3>
<p>Connecting is similar to pvaGet and pvaPut.
The other methods are:</p>
<dl>
<dt>start</dt>
@@ -238,7 +238,7 @@ The other methods are:</p>
<dd>Stops monitoring</dd>
<dt>poll</dt>
<dd>polls for a monitorEvent.
The data is avalable via easyMonitorData.
The data is avalable via pvaMonitorData.
</dd>
<dt>releaseEvent</dt>
<dd>Release the data from the last poll.
@@ -251,8 +251,8 @@ The other methods are:</p>
<dt>setRequester</dt>
<dd>A client callback is registered to receive notice of monitorEvents.</dd>
</dl>
<h3>EasyProcess</h3>
<p>Connecting is similar to easyGet.
<h3>PvaClientProcess</h3>
<p>Connecting is similar to pvaGet.
It has methods:</p>
<dl>
<dt>process</dt>
@@ -263,8 +263,8 @@ It has methods:</p>
<dt>waitProcess</dt>
<dd>Wait for process to complete.</dd>
</dl>
<h3>EasyPutGet</h3>
<p>Connecting is similar to easyGet.
<h3>PvaClientPutGet</h3>
<p>Connecting is similar to pvaGet.
It has methods:</p>
<dl>
<dt>putGet</dt>
@@ -285,29 +285,29 @@ It has methods:</p>
<dd>Gets the data for the put part of channelPutGet.</dd>
<dt>getPutData</dt>
<dd>
Returns the EasyData for the put part of channelPutGet.
Returns the PvaClientData for the put part of channelPutGet.
</dd>
<dt>getGetData</dt>
<dd>
Returns the EasyData for the get part of channelPutGet.
Returns the PvaClientData for the get part of channelPutGet.
</dd>
</dl>
<p>Look at javaDoc for details.</p>
<h2>EasyMultiChannel - Wrapper For Multiple Channels</h2>
<h3>EasyMultiChannel</h3>
<h2>PvaClientMultiChannel - Wrapper For Multiple Channels</h2>
<h3>PvaClientMultiChannel</h3>
<p>This provides methods for connecting to multiple channels.
A client can either use EasyMultiChannel directly or use EasyMultiDouble or EasyNTMultiChannel.
A client can either use PvaClientMultiChannel directly or use PvaClientMultiDouble or PvaClientNTMultiChannel.
But both impose restrictions on what can be accessed.
</p>
<h3>EasyMultiDouble</h3>
<h3>PvaClientMultiDouble</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>EasyNTMultiChannel</h3>
<h3>PvaClientNTMultiChannel</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

View File

@@ -1,4 +1,4 @@
# easyPVA C++ implementation
# pvaClient C++ implementation
# Jenkins @ Cloudbees build script
#
# Jenkins invokes scripts with the "-ex" option. So the build is considered a failure
@@ -68,11 +68,11 @@ make runtests
###########################################
# Create distribution
tar --exclude=test* -czf easyPVA.CB-dist.tar.gz lib include
tar --exclude=test* -czf pvaClient.CB-dist.tar.gz lib include
###########################################
# Publish documentation
if [ "${BUILD_DOCS}" ]; then
rsync -aqP --delete -e ssh documentation epics-jenkins@web.sourceforge.net:/home/project-web/epics-pvdata/htdocs/docbuild/easyPVACPP/tip
rsync -aqP --delete -e ssh documentation epics-jenkins@web.sourceforge.net:/home/project-web/epics-pvdata/htdocs/docbuild/pvaClientCPP/tip
fi

View File

@@ -1656,7 +1656,7 @@ private:
/** @page Overview Documentation
*
* <a href = "pvaClientOverview.html">pvaClientOverview.html</a>
* <a href = "../pvaClientOverview.html">pvaClientOverview.html</a>
*
*/