From b1594e6b78b539b5cd65eed1e43584533d92b887 Mon Sep 17 00:00:00 2001 From: Marty Kraimer Date: Wed, 17 Jun 2015 15:28:28 -0400 Subject: [PATCH] changes to README.txt jenkins/cloudbees_build documentation --- README.txt | 6 +- configure/ExampleRELEASE.local | 2 +- .../{easyPVA.html => pvClientCPP.html} | 89 ++++------ .../{overview.html => pvaClientOverview.html} | 166 +++++++++--------- jenkins/cloudbees_build | 6 +- src/pvaClient.h | 2 +- 6 files changed, 122 insertions(+), 149 deletions(-) rename documentation/{easyPVA.html => pvClientCPP.html} (70%) rename documentation/{overview.html => pvaClientOverview.html} (62%) diff --git a/README.txt b/README.txt index b4d961e..123cdc6 100644 --- a/README.txt +++ b/README.txt @@ -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 diff --git a/configure/ExampleRELEASE.local b/configure/ExampleRELEASE.local index 483ab6e..28a63d1 100644 --- a/configure/ExampleRELEASE.local +++ b/configure/ExampleRELEASE.local @@ -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 diff --git a/documentation/easyPVA.html b/documentation/pvClientCPP.html similarity index 70% rename from documentation/easyPVA.html rename to documentation/pvClientCPP.html index dec0657..2050a6e 100644 --- a/documentation/easyPVA.html +++ b/documentation/pvClientCPP.html @@ -4,7 +4,7 @@ - EPICS easyPVA + EPICS pva
-

EPICS easyPVA

+

EPICS pvaClientCPP

EPICS V4 Working Group, Working Draft, -25-Mar-2015

+29-May-2015
This version:
easyPVA.html + href="pvaClientCPP.html">pvaClientCPP.html
Latest version:
+
Still under revision
+
Previous version:
easyPVA_20150609.html
-
Previous version:
-
easyPVA_20150325.html -
Editors:
Marty Kraimer, BNL
-
Matej Sekoranja, Cosylab

Abstract

-

NO LONGER SUPPPORTED: -The functionality has been moved to pvAccessCPP and EasyPva renamed to Pva. -

-

EasyPVA (Easy PVAccess) is a software library that provides to an EPICS client programmer, a friendly +

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.

-

Specifically, easyPVA provides an easy interface for pvAccess, which is the +

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.

-

-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.

-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.

@@ -83,9 +77,9 @@ The data for the channels is presented via normative type NTMultiChannel. -

Status of this Document and of the EasyPVA Software

+

Status of this Document and of the pvaClient Software

-

EasyPVACPP is ready for use.

+

pvaClientCPP is ready for use.

@@ -99,14 +93,14 @@ The data for the channels is presented via normative type NTMultiChannel.

Introduction

-

EasyPVA is a synchronous API for accessing PVData via PVAccess. It provides +

pvaClient is a synchronous API for accessing PVData via PVAccess. It provides an interface to many of the features provided by pvData and pvAccess.

This document describes the layout of the source files in this project.

A user overview is available via overview.html +href="./pvaClientOverview.html">pvaClientOverview.html

@@ -115,27 +109,10 @@ Doxygen documentation is available at href="./html/index.html">doxygenDoc

-

Building

-

After obtaining the source:

-
-cd configure
-cp ExampleRELEASE.local RELEASE.local
-
-

Edit RELEASE.local so that all path names are correct for you environment. -

-

-Then:

-
-cd ..
-make
-
- -

Example and Test Database

+

Example Database

The examples and tests require that an example pvAccess server is runnimg. -This distribution has a file exampleDatabaseEasyPVA.zip. +This distribution has a file exampleDatabasePvaClient.zip. 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.

After unzipping the file: @@ -156,17 +133,17 @@ cd iocBoot/exampleDatabase make runtests

Examples

-

Examples are in directory example/src. +

Examples are in directory pvaExample/src. An example of how to run them is:

 mrk> pwd
-/home/hg/easyPVACPP/example
-mrk> bin/linux-x86_64/exampleEasyGet 
+/home/epicsv4/pvAccessCPP/pvaExample
+mrk> bin/linux-x86_64/examplepvaClientGet

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.

-

exampleEasyGet

+helps to also look at the source for the example.

+

examplePvaClientGet

This has a number of examples:

exampleDouble
@@ -193,7 +170,7 @@ helps to also bee loooking at the source for the example.

have a value field.
-

exampleEasyMonitor

+

examplePvaClientMonitor

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. 

 pvput -r "power.value,voltage.value" examplePowerSupply 6 6
-

exampleEasyPut

+

examplePvaClientPut

This example gets and puts to channel exampleDouble.

-

exampleEasyProcess

+

examplePvaClientProcess

This example makes a process request to channel exampleDouble.

helloWorldPutGet

This is an example of issuing a channelPutGet.

-

exampleEasyMultiDouble

+

examplePvaClientMultiDouble

This is an example of issuing gets and puts to multiple channels where each channel has a numeric scalar value field.

-

exampleEasyNTMultiChannel

+

examplePvaClientNTMultiChannel

This is an example of using NDMultiChannel to obtain data from multiple channels.

helloWorldRPC

This is an example of issuing a channelRPC request. -It does not use easyPVA.

+It does not use pva.

diff --git a/documentation/overview.html b/documentation/pvaClientOverview.html similarity index 62% rename from documentation/overview.html rename to documentation/pvaClientOverview.html index 4e07a0d..cc6e5b7 100644 --- a/documentation/overview.html +++ b/documentation/pvaClientOverview.html @@ -4,7 +4,7 @@ - easyPVA C++ Overview + pva C++ Overview
-

easyPVA C++ Overview

+

PvaClient C++ Overview

@@ -39,135 +39,135 @@

Introduction

-

EasyPVA is a synchronous API for accessing PVData via PVAccess. -It also provides a number of convience methods. +

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.

+but throws an exception if a request fails. +A client can also check for failues and thus prevent exceptions.

-

The EasyPVA API has the following features:

+

The PvaClient API has the following features:

  1. Provides a synchronous API rather than the callback API provided by pvAccess.
    2. -
  2. Makes common requests easy.
    3. +
  3. Makes common requests pva.
  4. Provides full access to the pvAccess API for more demanding applications
  5. Allows efficient client side programs.
  6. Takes care of most object resource management problems.
-

Simple examples of using easyPVA:

+

Simple examples of using pva:

-// easyGet
-EasyPVAPtr easyPVA = EasyPVA::create();
-double value = easyPVA->channel("exampleDouble")->get()->getData()->getDouble();
+// pvaGet
+PvaClientPtr pva = PvaClient::create();
+double value = pva->channel("exampleDouble")->get()->getData()->getDouble();
 
-// easyPut
-EasyChannelPtr channel = easyPVA->channel("exampleDouble");
-EasyPutPtr put = channel->put();
-EasyPutDataPtr putData = put->getData();
+// pvaPut
+PvaClientChannelPtr channel = pva->channel("exampleDouble");
+PvaClientPutPtr put = channel->put();
+PvaClientPutDataPtr putData = put->getData();
 putData->putDouble(3.0); put->put();
 
-// easyMonitor
-EasyMonitorPtr monitor = easyPVA->channel("examplePowerSupply")->monitor("");
-EasyMonitorDataPtr easyData = monitor->getData();
+// pvaMonitor
+PvaClientMonitorPtr monitor = pva->channel("examplePowerSupply")->monitor("");
+PvaClientMonitorDataPtr pvaData = monitor->getData();
 while(true) {
     monitor->waitEvent();
     cout << "changed\n";
-    easyData->showChanged(cout);
+    pvaData->showChanged(cout);
     cout << "overrun\n";
-    easyData->showOverrun(cout);
+    pvaData->showOverrun(cout);
     monitor->releaseEvent();
 }
 
-// easyProcess
-EasyChannelPtr channel = easyPVA->channel("exampleDouble");
-EasyProcessPtr process = channel->createProcess();
+// pvaProcess
+PvaClientChannelPtr channel = pva->channel("exampleDouble");
+PvaClientProcessPtr process = channel->createProcess();
 process->process();
-

easyPVACPP includes a number of examples.

-

easyPVA does not provide support for:

+

pvaExample includes a number of examples.

+

pva does not provide support for:

ChannelArray
TBD
ChannelRPC
-
pvAccess itself already provides an easy to use synchronous interface. +
pvAccess itself already provides a synchronous interface. The examples include helloWorldRPC, which is an example of using channelRP.
-

EasyPVA

-

An instance of EasyPVA is obtained via the call:

+

PvaClient

+

An instance of PvaClient is obtained via the call:

-EasyPVAPtr easyPVA = EasyPVA::create();
+PvaClientPtr pva = PvaClient::create();
-

EasyPVA has methods to create instances of EasyChannel. +

PvaClient has methods to create instances of PvaClientChannel. 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:

-EasyChannelPtr easyChannel = easyPVA->channel("exampleDouble");
+PvaClientChannelPtr pvaChannel = pva->channel("exampleDouble");

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.

An example of using a non cached method is:

-EasyChannelPtr easyChannel = easyPVA->createChannel("exampleDouble");
+PvaClientChannelPtr pvaChannel = pva->createChannel("exampleDouble");
-

This will create an EasyChannel and return it to the client. +

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.

-

EasyChannel - Wrapper For Single Channel

-

EasyChannel

+

PvaClientChannel - Wrapper For Single Channel

+

PvaClientChannel

This provides methods for connecting to a channel and for creating instances of -EasyField, EasyProcess, ..., EasyPutGet.

+PvaClientField, PvaClientProcess, ..., PvaClientPutGet.

Connection must be made before any create method is called or an exception is raised. The following is a synchronous connection request:

-easyChannel->connect(5.0); // BLOCKS AND THROWS IF NO CONNECT
+pvaChannel->connect(5.0); // BLOCKS AND THROWS IF NO CONNECT

This blocks until then connection is made or until timout occurs. An exception is raised if the connection request fails.

The same request can be made without blocking and without exceptions.

-easyChannel->issueConnect(); // DOES NOT BLOCK
+pvaChannel->issueConnect(); // DOES NOT BLOCK
 .....
-Status status =easyChannel->waitConnect(5.0);  // BLOCKS DOES NOT THROW
+Status status =pvaChannel->waitConnect(5.0);  // BLOCKS DOES NOT THROW
 if(!status.isOK()) {
    // failure do something
 }
-

Once the channel is connected other Easy objects can be created. +

Once the channel is connected other PvaClient objects can be created. For example:

-EasyGetPtr easyGet = easyChannel->get(); // DOES BLOCK
+PvaClientGetPtr pvaGet = pvaChannel->get(); // DOES BLOCK

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.

The client can also managed it's own objects:

-EasyGetPtr easyGet = easyChannel->createGet(); // DOES NOT BLOCK
+PvaClientGetPtr pvaGet = pvaChannel->createGet(); // DOES NOT BLOCK
-

The client must connect the easyGet.

+

The client must connect the pvaGet.

-

EasyGetData

-

This provides the data returned by easyGet and easyPutGet. +

PvaClientGetData

+

This provides the data returned by pvaGet and pvaPutGet. It is obtained via:

-EasyGetDataPtr easyData = easyGet->getData();
+PvaClientGetDataPtr pvaData = pvaGet->getData();

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.

An example is:

-double value = easyData->getDouble();
+double value = pvaData->getDouble();

It also keeps a bitSet showing which fields have changed since the last channelGet or channelPutGet.

-

EasyMonitorData

-

To the client this looks identical to EasyGetData except that +

PvaClientMonitorData

+

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.

-

EasyPutData

-

This is used to provided data for easyPut and easyPutGet. -It has many of the same methods as easyGetData. +

PvaClientPutData

+

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:

-void easyData->putDouble(5.0);
+void pvaData->putDouble(5.0);
-

EasyGet

+

PvaClientGet

This provides methods to connect to channelGet and to issue get request. To connect via a single synchronous call:

@@ -201,35 +201,35 @@ eastGet->connect();  // BLOCKS AND CAN THROW

This can also be done in two steps:

-easyGet->issueConnect(); // DOES NOT BLOCK
+pvaGet->issueConnect(); // DOES NOT BLOCK
 ...
-Status status = easyGet->waitConnect(); // BLOCKS AND DOES NOT HROW
+Status status = pvaGet->waitConnect(); // BLOCKS AND DOES NOT HROW

Once connected gets are issued via either:

-void easyGet->get(); // BLOCKS AND CAN THROW
+void pvaGet->get(); // BLOCKS AND CAN THROW
or 
-easyGet->issueGet(); // DOES NOT BLOCK
+pvaGet->issueGet(); // DOES NOT BLOCK
 ...
-Status status = easyGet->waitGet(); // BLOCKS AND DOES NOT THROW
+Status status = pvaGet->waitGet(); // BLOCKS AND DOES NOT THROW
-

EasyPut

-

This is similar to easyGet except that it wraps channelPut instead of channelGet. +

PvaClientPut

+

This is similar to pvaGet except that it wraps channelPut instead of channelGet.

Once connected puts are issued via either:

-void easyPut->put(); // BLOCKS AND CAN THROW
+void pvaPut->put(); // BLOCKS AND CAN THROW
or 
-easyPut->issuePut(); // DOES NOT BLOCK
+pvaPut->issuePut(); // DOES NOT BLOCK
 ...
-Status status = easyPut->waitPut(); // BLOCKS AND DOES NOT THROW
+Status status = pvaPut->waitPut(); // BLOCKS AND DOES NOT THROW
-

EasyMonitor

-

Connecting is similar to easyGet and easyPut. +

PvaClientMonitor

+

Connecting is similar to pvaGet and pvaPut. The other methods are:

start
@@ -238,7 +238,7 @@ The other methods are:

Stops monitoring
poll
polls for a monitorEvent. - The data is avalable via easyMonitorData. + The data is avalable via pvaMonitorData.
releaseEvent
Release the data from the last poll. @@ -251,8 +251,8 @@ The other methods are:

setRequester
A client callback is registered to receive notice of monitorEvents.
-

EasyProcess

-

Connecting is similar to easyGet. +

PvaClientProcess

+

Connecting is similar to pvaGet. It has methods:

process
@@ -263,8 +263,8 @@ It has methods:

waitProcess
Wait for process to complete.
-

EasyPutGet

-

Connecting is similar to easyGet. +

PvaClientPutGet

+

Connecting is similar to pvaGet. It has methods:

putGet
@@ -285,29 +285,29 @@ It has methods:

Gets the data for the put part of channelPutGet.
getPutData
- Returns the EasyData for the put part of channelPutGet. + Returns the PvaClientData for the put part of channelPutGet.
getGetData
- Returns the EasyData for the get part of channelPutGet. + Returns the PvaClientData for the get part of channelPutGet.

Look at javaDoc for details.

-

EasyMultiChannel - Wrapper For Multiple Channels

-

EasyMultiChannel

+

PvaClientMultiChannel - Wrapper For Multiple Channels

+

PvaClientMultiChannel

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.

-

EasyMultiDouble

+

PvaClientMultiDouble

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.

-

EasyNTMultiChannel

+

PvaClientNTMultiChannel

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 diff --git a/jenkins/cloudbees_build b/jenkins/cloudbees_build index 2c602a9..8d72d0e 100644 --- a/jenkins/cloudbees_build +++ b/jenkins/cloudbees_build @@ -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 diff --git a/src/pvaClient.h b/src/pvaClient.h index 558fbab..b79db45 100644 --- a/src/pvaClient.h +++ b/src/pvaClient.h @@ -1656,7 +1656,7 @@ private: /** @page Overview Documentation * - * pvaClientOverview.html + * pvaClientOverview.html * */