pvaClientCPP is ready for use.
-pvaClient is a synchronous API for accessing PVData via PVAccess. It provides -an interface to many of the features provided by pvData and pvAccess.
+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 if a request fails. +A client can also check for failues and thus prevent exceptions.
-This document describes the layout of the source files in this project.
--A user overview is available via -pvaClientOverview.html - -
--Doxygen documentation is available at -doxygenDoc - -
-The examples require that the database provided by project pvaClientTestCPP -is running. -For example:
+Doxygen documentation is available at doxygenDoc
+ +The PvaClient API has the following features:
+Simple examples of using pva:
-mrk> pwd
-/home/epicsv4/pvaClientTestCPP/database/iocBoot/exampleDatabase
-mrk> ../../bin/linux-x86_64/exampleDatabase st.cmd
+// pvaGet
+PvaClientPtr pva = PvaClient::create();
+double value = pva->channel("exampleDouble")->get()->getData()->getDouble();
+
+// pvaPut
+PvaClientChannelPtr channel = pva->channel("exampleDouble");
+PvaClientPutPtr put = channel->put();
+PvaClientPutDataPtr putData = put->getData();
+putData->putDouble(3.0); put->put();
+
+// pvaMonitor
+PvaClientMonitorPtr monitor = pva->channel("examplePowerSupply")->monitor("");
+PvaClientMonitorDataPtr pvaData = monitor->getData();
+while(true) {
+ monitor->waitEvent();
+ cout << "changed\n";
+ pvaData->showChanged(cout);
+ cout << "overrun\n";
+ pvaData->showOverrun(cout);
+ monitor->releaseEvent();
+}
+
+// pvaProcess
+PvaClientChannelPtr channel = pva->channel("exampleDouble");
+PvaClientProcessPtr process = channel->createProcess();
+process->process();
+
-Examples are in directory example/src. -An example of how to run them is:
--mrk> pwd -/home/epicsv4/pvaClientCPP/example -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 look at the source for the example.
-This has a number of examples:
+A separate project exampleCPP has examples for pvDatabaseCPP +and for pvaClientCPP. +See it for pvaClientCPP examples. +
+pvaClient does not provide support for:
This is an example of creating a monitor on a channel. -It monitors a scalar double field. -It also issues puts to the same channel so that it can make the monitors occur. + +
+If a proper RELEASE.local is present one directory level above pvaClientCPP.
-This example gets and puts to channels exampleDouble -and exampleDoubleArray.
-This example makes a process request to channel exampleDouble.
-This is an example of issuing a channelPutGet.
-This is an example of using pvaClientMultiChannel, -pvaClientMultiGetDouble, pvaClientMultiPutDouble, and pvaClientMultiMonitorDouble. +
+Just type:
-This is an example of using pvaClientMultiChannel, -pvaClientNTMultiGet, pvaClientNTMultiPut, pvaClientNTMultiMonitor, and pvaClientNTMultiData. +
+make ++
+An example of a proper RELEASE.local is:
-This is an example of issuing a channelRPC request. -It does not use pva.
+
+EPICS4_DIR=/home/epicsv4/master
+EXAMPLE=${EPICS4_DIR}/exampleCPP
+PVDATABASE=${EPICS4_DIR}/pvDatabaseCPP
+PVACLIENT=${EPICS4_DIR}/pvaClientCPP
+PVASRV=${EPICS4_DIR}/pvaSrv
+PVACCESS=${EPICS4_DIR}/pvAccessCPP
+NORMATIVETYPES=${EPICS4_DIR}/normativeTypesCPP
+PVDATA=${EPICS4_DIR}/pvDataCPP
+PVCOMMON=${EPICS4_DIR}/pvCommonCPP
+
+EPICS_BASE=/home/install/epics/base
+
+
+pvaClientCPP can also be built if a file RELEASE.local exists in directory configure. +To create one do the following:
++mrk> pwd +/home/hg/pvaClientCPP/configure +mrk> cp ExampleRELEASE.local RELEASE.local ++
Then edit RELEASE.local so that it has the correct location of each +product pvaClientCPP requires. +Than at the top level just execute make:
++mrk> cd .. +mrk> pwd +/home/epicsv4/master/pvaClientCPP +mrk> make ++ +
An instance of PvaClient is obtained via the call:
++PvaClientPtr pva = PvaClient::create(); ++ +
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 pvaClient cache channels. +An example of using the cached method is:
+
+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, 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:
+
+PvaClientChannelPtr pvaChannel = pva->createChannel("exampleDouble");
+
+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. +
+ +This provides methods for connecting to a channel and for creating instances of +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:
++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.
+
+pvaChannel->issueConnect(); // DOES NOT BLOCK
+.....
+Status status =pvaChannel->waitConnect(5.0); // BLOCKS DOES NOT THROW
+if(!status.isOK()) {
+ // failure do something
+}
+
+Once the channel is connected other PvaClient objects can be created. +For example:
++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 pvaGet is created than it is connected before it is returned to the client. +
+The client can also managed it's own objects:
++PvaClientGetPtr pvaGet = pvaChannel->createGet(); // DOES NOT BLOCK ++
The client must connect the pvaGet.
+ +This provides the data returned by pvaGet and pvaPutGet. +It is obtained via:
++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 +field that is a scalar or a scalarArray. +Also for a scalar that is a double or a scalarArray with element type double. +
+An example is:
++double value = pvaData->getDouble(); ++
It also keeps a bitSet showing which fields have changed since the last channelGet or channelPutGet.
+ +To the client this looks identical to PvaClientGetData except that +it provides two BitSets: changedBitSet and overrrunBitSet. +It is used by pvaMonitor. +
+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 pvaData->putDouble(5.0); ++
This provides methods to connect to channelGet and to issue get request. +To connect via a single synchronous call:
++easyGet->connect(); // BLOCKS AND CAN THROW ++
This can also be done in two steps:
++pvaGet->issueConnect(); // DOES NOT BLOCK +... +Status status = pvaGet->waitConnect(); // BLOCKS AND DOES NOT THROW ++
Once connected gets are issued via either:
++void pvaGet->get(); // BLOCKS AND CAN THROW ++or +
+pvaGet->issueGet(); // DOES NOT BLOCK +... +Status status = pvaGet->waitGet(); // BLOCKS AND DOES NOT THROW ++
This is similar to pvaGet except that it wraps channelPut instead of channelGet. +
+Once connected puts are issued via either:
++void pvaPut->put(); // BLOCKS AND CAN THROW ++or +
+pvaPut->issuePut(); // DOES NOT BLOCK +... +Status status = pvaPut->waitPut(); // BLOCKS AND DOES NOT THROW ++
Connecting is similar to pvaGet and pvaPut. +The other methods are:
+Connecting is similar to pvaGet. +It has methods:
+Connecting is similar to pvaGet. +It has methods:
+Look at javaDoc for details.
+ +This provides methods for connecting to multiple channels. +
+This provides support for channelGet to multiple channels where each channel has a value field that is a numeric scalar. +
+This provides support for channelPut to multiple channels where each channel has a value field that is a numeric scalar. +
+This provides support for monitoring changes to multiple channels where each channel has a value field that is a numeric scalar. +
+This provides support for channelGet to multiple channels where each channel has a value field that has any valid type. +
+This provides support for channelPut to multiple channels where each channel has a value +field that has any valid type. +
+This provides support for monitoring changes to multiple channels where each channel has a +value field that has any valid type. +
+This provides support for monitoring changes to multiple channels where each channel has a value field that has any valid type. +The client can get the data as normative type NTMultiChannel. +
+