Re: C++ APIs

[Marty Kraimer <mrkraimer@comcast.net>]

On 07/22/2018 07:53 PM, Hartman, Steven M. wrote:

Let’s have a teleconference meeting this week: Tuesday July 24 at the usual time (14:00 UTC).

I assume that our  teleconference meeting next Tuesday July 31 will discuss this issue.
The following is in preparation for the discussion.

The primary conflict relates to the pvRequest structure that is an argument of the Channel create methods, i.e createChannelGet, createChannelPut, etc.

The pvRequest structure is described in

http://epics-pvdata.sourceforge.net/informative/developerGuide/developerGuide.html

In particular the sections
9. pvRequest and pvCopy
10. pvRequest Option

For this discussion you can ignore the discussion of pvCopy.

9.2 describes CreateRequest which the client can use to create a pvRequest structure.

The main features are:

Purpose

CreateRequest allows a client to select an arbitrary subset of the fields in the top level structure associated with a channel. It also allows the client to specify options. Thus the client can specify:

Global Options

Global options are options that apply to the record itself.

Desired Fields

An arbitrary set of fields can be selected from the top level structure that holds the data in the record.

Field Options

These are options that apply to a selected field.

NOTE: The term record is adapted from pvDatabase. A pvDatabase has a memory resident database of smart records. A pvAcccess channel is a connection to a record. A record has a top level PVStructure that holds the data for the record. A pvAcccess server can be implemented that does not use the pvDatabase model but it must provide top level PVStructures to which a pvAcccess Channel can be attached. qsrv, which provides access to iocCore V3 records, is an example that also accepts a pvRequest created by a call to createRequest.

One other important point.
The client  asks for the set of fields of interest to the client, e. g. "value,alarm,timeStamp".
The server provides to the client only fields the client requests AND that the server supports.
Also the server determines the type for each field it supports.

Now for a little history.

The Channel API was originally created as part of the JavaIOC project that started in 2006.
For the first few years the only developers were Matej Sekoranja and me.

I remember that we had discussion about how a client could pass options to the server.
We went through a couple of iterations but each was not generic enough and would require changes to the network protocol.

Then we realized that since we already had the ability to create complex data structures just have a argument that is a PVStructure.
Thus the client can pass anything it wants to the server without changing the network protocol.

But how do client and server agree of what is a valid request?

The solution was CreateRequest and the PVStructure it creates.

This was all in the JavaIOC by about 2008.

In about 2010 BobDalesio said:

This javaIOC is nice but what is required is a C++ implementation.
 It can  used by  clients and even more important can be used in an IOC.

Matej and I started on the C++ implementation with help mainly from Michael Davidsaver and David Hicken.

So now we have both Java and C++ implementations of pvData, pvAccess, normativeTypes, pvaCliient, and pvDatabase.

In addition a pvAccess server for accessing DBRecords was created.
This was called pvaSrv.
This became the responsibility of Ralph Lange.
It used pvRequest as expected.

A couple of years ago Matej no longer had time to work on pvData/pvAccess.
Ownership  of pvDataCPP and pvAccessCPP was assigned to Michael Davidsaver.
In addition he was developing pva2pva, which was a combination of a gateway and a successor to pvaSrv.

Michael decided, without any serious discussion with others that he did not like the pvRequest mechanism that was in place.
So he often ignored it.

qsrv is a particular problem.

For example:

mrk> pvget -p pva -r "value" DBRdouble
DBRdouble
epics:nt/NTScalar:1.0
    double value 0
    alarm_t alarm NO_ALARM NO_STATUS NO_ALARM
    time_t timeStamp 2018-07-26T10:13:45.754 0
    display_t display
        double limitLow -10
        double limitHigh 10
        string description
        string format
        string units volts
    control_t control
        double limitLow -9
        double limitHigh 9
        double minStep 0
    valueAlarm_t valueAlarm
        boolean active false
        double lowAlarmLimit -8
        double lowWarningLimit -6
        double highWarningLimit 6
        double highAlarmLimit 8
        int lowAlarmSeverity 0
        int lowWarningSeverity 0
        int highWarningSeverity 0
        int highAlarmSeverity 0
        double hysteresis 0


mrk> pvget -p ca -r "value" DBRdouble
DBRdouble
structure
    double value 0


mrk>

There are other problems but qsrv is the really big one.