pvDatabaseCPP

editions

2021.03.01
Original
2021.04.23
Update
Editors:
Marty Kraimer

This product is available via an open source license

Table of Contents

Overview

This document is the guide for pvDatabaseCPP, which is one of the components of EPICS-7

Doxgen for pvDatabase is located at: doxygen .

pvDatabase is a framework for implementing a network accessible database of smart memory resident records.

This document is intended for anyone creating new PVRecords. pvService Describes a good way to create services via PVRecords.

PVDatabase Components

pvDatabase has the following components:

database
The most important components are:
PVRecord
This is a record. It has a PVStructure and a method process, which is what makes it smart.
PVDatabase
The is a database of PVRecords.
pvAccess
This has the following:
ChannelProviderLocal
This a ChannelProvider, defined in pvAccess, that provides access to the PVDatabse records.
ChannelLocal
This provides access to a single PVRecord.
copy
This has the code for pvStructureCopy and all the plugin support.
special
PVRecords that can be created by pvDatabase itself. A record can be created directly by a client or via iocshell commands.
support
deprecated

database

This is the code for creating a PVDatabase, which is a database of PVRecords.

PVRecord

A PVRecord consists of a PVStructure and a set of methods for accessing the record. The PVStructure has the data for the record. There is a base class that implements all the methods associated with accessing the record. But some are virtual and can be implemented by a derived class.

The virtual methods are:

process
This is the method that makes a record smart. Often this is the only method a derived class needs to implement. If it encounters errors it should raise alarms and/or call the message method provided by the base class. If the pvStructure has a top level timeStamp, the base class sets the timeStamp to the current time.
init
A derived class can implement this if finds errors during initilization and does not want the record added to the PVDatabase.
start
This is called before record is added to database.
remove
Remove the PVRecord. Release any resources used and get rid of listeners and requesters. If derived class overrides this then it must call PVRecord::remove() after it has destroyed any resorces it uses.
getService
Return a service corresponding to the specified request PVStructure.

ChannelProviderLocal, described below, allows client to access a record via the network. But another record in the same ioc can access the record via the PVDatabase. For example if the other record wants to put data into the record it must do something like the following:

PVRecordPtr pvr(pvRecord.lock());
if(!pvr) throw std::logic_error("pvRecord is deleted");
try {
    {
        epicsGuard<PVRecord> guard(*pvr);
        pvr->beginGroupPut();
        // put data
        pvr->process();
        pvr->endGroupPut();
    }
} catch(std::exception& ex) {
        // handle error
}

method brief description

The following are virtual methods.
init                 Initialization method.
start                Called before a record is added to database.
process              Process the record.
remove               Remove the PVRecord.
getService           Return a service corresponding to the specified request PVStructure.

The following are implemented by the base class.
create               Create a soft record.
getRecordName        Get the record name.
getPVStructure       Get the PVStructure for the record.
getPVRecordStructure Get the PVRecordStrucure.
findPVRecordField    Find a PVRecordField
lock                 Lock the record. No other code can access the record until unlock
unlock               Unlock the record.
tryLock              Try to lock the record.
lockOtherRecord      Client holding lock can lock one other record.
addPVRecordClient    Every client that accesses the record can call this
                     so that the client can be notified when the record is deleted.
addListener          This must be called before calling pvRecordField.addListener.
nextMasterPVField    PVCopyTraverseMasterCallback method.
removeListener       Remove a listener.
beginGroupPut        Begins a group of puts.
endGroupPut          Ends a group of puts.
getTraceLevel        Get trace level (0,1,2) means (nothing,lifetime,process)
setTraceLevel        Set trace level (0,1,2) means (nothing,lifetime,process)
getAsLevel           Get the AS level.
getAsGroup           Get the AS group name.
setAsLevel           Set access security level.
setAsGroup           Set access security group.

PVRecordStructure

PVRecordStructure has methods:

getPVRecordFields    Get the sub fields.
getPVStructure       Get the PVStructure.

PVRecordField

PVRecordField has methods:

getParent            Get the PVRecordStructure.
getPVField           Get the PVField.
getFullFieldName     Get the full field name.
getFullName          Get the recordName plus the full name of the field.
getPVRecord          Get the PVRecord to which this field belongs.
postPut              This is called by the code that implements the data interface.
                     It is called whenever the put method is called.

PVRecordClient

PVRecordClient has methods:

detach  Detach from the record because it is being removed.

PVListener

PVListener has methods:

dataPut        This is called if the listener has called PVRecordField::addListener for pvRecordField.
beginGroupPut  Begin a set of puts.
endGroupPut    End a set of puts.
unlisten       Connection to record is being terminated.

PVDatabase

PVDatabase has methods:

findRecord       Find a record in the database.
addRecord        Add a record to the database.
removeRecord     Remove a record from the database.
getRecordNames   Get the names of all the records in the database.
getMaster        Get the master database. This is what clients access.

pvAccess

This code provides the ability for a pvAccess client to communicate with PVRecords. qsrv is the server side of pvAccess that provides access to an IOC.

The pvAccess component of pvDatabase implements a provider named local and registers it with qsrv

ChannelProviderLocal

ChannelProviderLocal has methods:

initAs             Initialize access security configuration.
isAsActive         Is access security active.
getProviderName    Returns the channel provider name.
channelFind        Returns either a null channelFind or a channelFind for records in the PVDatabase.
channelList        Provide the caller with a list of the record names on the PVDatabase.
createChannel      Create a channel for a record.
getTraceLevel      Get trace level (0,1,2) means (nothing,lifetime,process)
setTraceLevel      Set trace level (0,1,2) means (nothing,lifetime,process)
getChannelProvider Get the channel provider.

ChannelLocal

ChannelLocal has methods:

detach               This is called when a record is being removed from the database, 
getRequesterName     Get the requester name.
message              Passes the message to the channel requester.
getProvider          Get the channel provider.
getRemoteAddress     Get the remote address.
getConnectionState   Get the connection state.
getChannelName       Get the channel name.
getChannelRequester  Get the channel requester.
isConnected          Is the channel connected?
getField             Get the introspection interface for a subField.
getAccessRights      Get the access rights for the record.
createChannelProcess Create a channelProcess.
createChannelGet     Create a channelGet.
createChannelPut     Create a channelPut.
createChannelPutGet  Create a channelPutGet.
createChannelRPC     Create a channelRPC
                     The PVRecord must implement getService or an empty shared pointer is returned.
createMonitor        Create a Monitor
createChannelArray   Create a channelArray.
printInfo            Displays a message.
canWrite             Can the client write to the record.
canRead              Can the client read from the record.

copy

PVPlugin

PVPlugin has methods:

create               Creates a plugin filter

PVPluginRegistry

PVPluginRegistry has methods:

registerPlugin       Register a plugin.
find                 Find a plugin.

PVFilter

PVFilter has methods:

filter       Update copy or master
getName      Get the filter name.

PVArrayPlugin

PVArrayPlugin has methods:

create       Create a PVArrayFilter

PVArrayFilter

PVArrayFilter has methods:

create      Create an array filter
filter      Perform a filter operation.
getName     Get the filter name.

PVDeadbandPlugin

PVDeadbandPlugin has methods:

create      Create a PVDeadbandFilter

PVDeadbandFilter

PVDeadbandFilter has methods:

create      Create a deadband filter  
filter      Perform a filter operation.
getName     Get the filter name.

PVTimestampPlugin

PVTimestampPlugin has methods:

create    A plugin for a filter that sets a timeStamp to the current time

PVTimestampFilter

PVTimestampFilter has methods:

create      Create a timeStamp filter
filter      Perform a filter operation.
getName     Get the filter name.