EPICSWIKI - User contributions [en]

How to Configure Channel Access

2013-10-16T21:52:31Z

KayKasemir: Initial attempt

= How to Configure Channel Access =

= Basic Operation, One IOC on same subnet =
Assume an IOC has a record "fred", and you want to use "caget fred" or a similar CA client to read it.

When starting out with one IOC on the network, things are simple:

CA clients will by default broadcast name search requests to UDP port 5064 on the subnet.
As long as the IOC is on any computer on the subnet, it should eventually receive those search requests. Server and client then establish a TCP connection, and data is exchanged.

= Multiple IOCs on different computers, but same subnet =
If running multiple IOCs, each on their own computer, on the same subnet, the basic broadcast name search will still succeed, no change necessary.

= IOCs on different subnets =
The default broadcast name search is limited to the subnet of the computer running the CA client.
To reach IOCs on one or more additional subnets, the environment variable EPICS_CA_ADDR_LIST needs to be configured.
It can list either the specific IP addresses of each IOC, or the broadcast address of their subnet.
Note, however, that routers will often not forward broadcast requests, which suggests using specific IP addresses.

= Multiple IOCs on the same computer =
When starting the first IOC on a computer, it will listen to name searches on UDP port 5064.
When starting a second IOC on the same computer, it will also listen to name searches on UDP port 5064.
Due to limitations in most network kernels, however, only the IOC started ''last'' will actually receive UDP search requests that are sent to that computer, port 5064. As a workaround, you need to configure the EPICS_CA_ADDR_LIST to use the broadcast address of the respective subnet.

= Multiple IOCs on the same computer but on a different subnet =
Combining the last two points results in a problem:
To reach multiple IOCs on the same computer, EPICS_CA_ADDR_LIST must be set to the broadcast address of that computer's subnet.
If that subnet, however, is different from the CA client's subnet, routers tend to not allow such broadcast traffic.

There are several options to solve this:

== Channel Access Gateway ==
The gateway, running on the subnet that has the desired IOCs, will use the broadcast address of that subnet in its EPICS_CA_ADDR_LIST, so it can reach all IOCs, including multiple IOCs running on the same computer, throughout that subnet.
The CA client on a different subnet uses only EPICS_CA_ADDR_LIST=ip-of-the-gateway to directly reach the gateway, which is possible via routers.

In addition to establishing the basic connectivity, the gateway also offers IOC load reduction and it can add access security, for example limit write access.

== CA Nameserver ==
You can run a CA Name Server in the GUI subnet which knows about the IOCs and responds to search requests; in this case you would *not* set the EPICS_CA_ADDR_LIST variables. This is almost equivalent to running a CA Gateway, but is slightly more robust in that if the Nameserver process dies it wouldn't kill any existing connections.

== UDP Broadcast Packet Relay ==
If you have access to a machine with a network interface on both subnets you could also try running a program on it called UDP Broadcast Packet Relay https://www.joachim-breitner.de/udp-broadcast-relay/ which forwards broadcast packets between subnets. You would probably have to run it twice, once on port 5064 and once on 5065; the first one will forward CA search requests between the subnets, and the second sends the CA beacons. If you do have success with this please let us know, we use it here at the APS for forwarding timing UDP packets but not for CA.

= Firewalls =
Firewalls may need to be configured to pass the UDP and TCP 5064 traffic.

The channel access reference manual,
http://www.aps.anl.gov/epics/base/R3-14/8-docs/CAref.html
provides a lot more detail.

HowTo Documents

2013-10-16T21:29:17Z

KayKasemir: How to Configure Channel Access...

This is a directory of various How-To documents written by members of the EPICS collaboration. Contributions to this page are most welcome!

=== EPICS Base on Different Architectures and Operating Systems ===

* [http://www.aps.anl.gov/epics/base/RTEMS/tutorial/ Getting Started with EPICS on RTEMS]
* [[HowToPC104|Getting Started with R3.14.7 on a PC104 running Linux]]
* [[How To Port EPICS to a new OS/Architecture]]
* [[How To Use Posix Thread Priority Scheduling under Linux]]
* [[How To cross compile EPICS and a IOC to an old x86 Linux system]]

=== Drivers and Device Support ===

* [http://www.aps.anl.gov/epics/modules/soft/asyn/HowToDoSerial_StreamDevice.html How To Do Serial (using Asyn Driver and StreamDevice)] (also covers VXI-11)
* [http://www.aps.anl.gov/epics/modules/soft/asyn/R4-15/HowToDoSerial/tutorial.pdf How To Do Serial (using Asyn Driver and devGPIB)]
* [[How to make your EPICS driver operating system independent]]
* [[How To Write Device Support that uses Asyn Driver]] ''(Incomplete!)''
* [[How to use GPIB ports with linux-gpib and StreamDevice]]
* [[How to avoid copying arrays with waveformRecord]]

=== Applications ===

* [[Common Database patterns]]
* [[How To Install Channel Archiver On Scientific Linux]]
* [[What PV Save and Restore Tools are available]]
* [[How to Add a New Breakpoint Table]]
* [["Best Practice" Guidelines]]
* [[How do I get EPICS applications to work with a Mac OS X firewall?]]

=== Infrastructure and Other Stuff ===

* [[How To Set Up a Linux Box as an IOC Boot Server]]
* [[How To Set Up a Mirror of the EPICS Web Site]]
* [[How to Set Up a Soft IOC Framework on Linux]]
* [[How to Configure Channel Access]]
* [[How to Set Up Console Access and Logging for VME and Soft IOCs]]
* [[How to Set Up NAL (Nagios Alarm Handler) to monitor an EPICS network]]

=== Collaboration Stuff ===

* [[How to run an EPICS Collaboration Meeting]]

What PV Save and Restore Tools are available

2007-06-28T15:36:40Z

KayKasemir:

There are a number of different tools available within the EPICS community for saving and restoring values of PVs. This page gives somewhere for them to be briefly described, since they all have somewhat different characteristics. This page may be incomplete; if you know of a published tool that is not described here, please consider adding it, or email <volunteer anyone?> about it.

__TOC__

== IOC-based Tools ==

=== [http://www.aps.anl.gov/aod/bcda/synApps/autosave/autosave.html SynApps Autosave] ===

Autosave automatically saves the values of EPICS process variables (PVs) to files on a server, and restores those values when the IOC is rebooted.

=== ... ===

...

== Host-based Tools ==

=== XAL 'score' ===
The XAL collection of high-level applications includes 'score':
A Table of PV names, each with a current value and a saved value.
One can see which PVs differ from their saved state,
restore them etc.

Don't know a good web page, but try
[http://neutrons.ornl.gov/APGroup/appProg/xal/xal.htm this one ].

=== CSS 'PV Table' ===
Similar to 'score', but simpler and still unter development.
Saves values to XML files, no connection to RDB.

For more on CSS (Control System Studio),
see the [http://css.desy.de main page at DESY].

=== ... ===

...

What PV Save and Restore Tools are available

2007-06-28T15:33:56Z

KayKasemir:

There are a number of different tools available within the EPICS community for saving and restoring values of PVs. This page gives somewhere for them to be briefly described, since they all have somewhat different characteristics. This page may be incomplete; if you know of a published tool that is not described here, please consider adding it, or email <volunteer anyone?> about it.

__TOC__

== IOC-based Tools ==

=== [http://www.aps.anl.gov/aod/bcda/synApps/autosave/autosave.html SynApps Autosave] ===

Autosave automatically saves the values of EPICS process variables (PVs) to files on a server, and restores those values when the IOC is rebooted.

=== ... ===

...

== Host-based Tools ==

=== XAL 'score' ===
The XAL collection of high-level applications includes 'score':
A Table of PV names, each with a current value and a saved value.
One can see which PVs differ from their saved state,
restore them etc.

=== CSS 'PV Table' ===
Similar to 'score', but simpler and still unter development.
Saves values to XML files, no connection to RDB.

=== ... ===

...

V4 Use Cases

2005-10-11T15:05:51Z

KayKasemir: Added thoughts from EPICS meeting

== Overview ==

These are example use cases where we need to assert that each layer of EPICS V4 handles them:

1. Can the CA client user API articulate the request?

2. Can the network protocol transfer the request?

3. Do the database & drivers understand the request and provide the necessary data?

4. Does the data get back up to the client in the appropriate form and at the requested time?

== Use Cases ==

=== Command-line tools for debugging and scripting ===
1. List all channels that match a given name pattern.

2. Dump the current "value" property of the channel "fred".

3. Dump all properties, their type, and current value for a given channel.

4. Dump the timestamp, value, units, status, severity of "fred" once a second.

5. ... whenever any of the timestamp, ... severity change.

6. List all events that a PV supports: On change, 1Hz, RF Pulse, Beam Pulse, ...

7. Dump the value of the cavity waveform for every beam pulse.

=== Display Manager ===
1. Display an analog input value on a bar: 
Get limits, subscribe to values, receive value & display it, receive change-of-display-range notification,...

2. Display a menu output for a 2 state valve on a text update: 
Get state strings, subscribe to (numeric?) value, display incoming data, receive state string updates, ...

3. Give a controller for a 2 state valve controller on a radio button. Handle same as 2?

4. Display a waveform on an xy plot. 
Similar to 1, but array data?

5. Attempt to display a string on a bar

6. Universal PV Inspector: 
Get properties, allow user to select properties. 
If writeable string -> display text entry field. 
If read-only string -> display text update field. 
If writeable numeric with limits -> display slider with range of number. 
....

7. Display as bars, a list of BPMs where I can set the offset in time to fetch (assuming that these BPMs are read as arrays that are all triggered at one time – but I want to see them at different points in time as it goes down the beamline).

=== Physics Application ===

BPM-related ideas

1. List all channels available that are BPMs.

2. Select all of them in sector 6

3. Get the values of all BPMs in a sector, once, as a snapshot. This means all the BPMs must be read at the same time, for the same beam pulse, or whatever a specific site considers "at once".
A variant would be: Display them when the beam is going to the end station A (one of 8 destinations possible)

4. Same, but display them periodically, for example on the .1 Hz event

5. Find the corrector magnet PVs that belong to a list of BPMs. Read the BPMs and current maget settings "at once", compute new settings, write the new settings "at once".

Scan a probe in the beam line

1. Find PVs for some beam line device: 
Stepper motors for probe's X & Y position, intensity of beam transmitted by probe,
beam shutter open/close, beam available

2. Scan sequence: 
Assert shutter is closed;
move X/Y to 0/0, wait for completion
until done:
open shutter, wait until open
measure intensity for 1 second while beam_available
close shutter
move to next position, wait until you get there

=== Archiver ===
1. Get value, timestamp, status/severity of a channel once per second

2. Archive default properties of a channel using the default deadband. 
How are they defined? How does the archiver learn about them?

3. Given that there is a new view defined in the stepper motor that includes all motor readback data:Subscribe to counterClockWiseLimit, clockWiseLimit, moving, doneRetries, homeLimit at 10 Hz.

=== Infrastructure for various applications ===
1. Serialize and de-serialize the data type description in human-readable form. 

1.1 Used to get common syntax for user-input to command line tools or for the archiver config file, where users need to describe what to get/put/archive and how: 
'value' as double, 'units' as string, ...

1.2 Used to get common output from tools that 'dump' the data type for info or debug purposes.

2. Serialize and de-... in rather compact form

2.1 Used by data storage tools to store the type information in the header of data blocks.

2.2 Maybe also used by the network layer to initially xfer the data types.

Could those formats be the same, i.e. a short yet human readable format?

"{d:value,s:units,{d:low,d:high}limits}"

could describe this structure:
{
double value;
string units;
struct
{
double low;
double high;
} limits;
}

3. Need to provide standard serialization of the data type description _and_ the data? Or should the developers of the network layer and archiver each invent their own?

V4 Data Interface

2005-09-02T20:21:08Z

KayKasemir: DA code example

== Issue ==
I think the following data interface is easier to understand
than the data access approach.

Am I wrong, because Data Access is really much easier?

Am I right, but the approach shown here will never work?

Would it work, but performance would be unacceptable?

[[Image:V4DataInter.jpg]]

=== Data Interface Classes ===

// Description of basic data character
enum EpicsDataCharacter
{
Octet, // Raw bits,known to a server/client pair, but no one else
Bool,
Integer, // Discrete, available with 16, 32, 64 bits
Real, // Floating-point, available with 32 and 64 bits
String, // UTF-8
Enum, // >=0 Integer with state names
Structure,
TimeStamp // For efficiency?
};

// Full description of the data
// This could be a pure interface,
// while Ben suggests to use a struct/class
// so that the user can easier get it as a whole.
// Ben also suggests that getNumDims throws an
// exception for scalars.
// I think a scalar has dimension 1, size 1,
// no exception.
class EpicsDataDescriptor
{
public:
virtual EpicsDataCharacter getType() = 0;
virtual int getNumDims() = 0; // Scalar, vector: 1, matrix: >1
virtual int getSize(int dim) = 0; // Scalar: 1
virtual int getBitsize() = 0; // bits of integer or real. 0 for rest?
virtual bool isSigned() = 0; // Integer might be unsigned?
};

// When the exact size-locked types are needed,
// use these integer types from stdint.h:
// int8_t, int16_t, int32_t, int64_t
// and the following:
typedef bool bool_t;
typedef float real32_t;
typedef double real64_t;

// Read-Access to the data.
// This one tries to allow as many conversions as possible.
// Given for example an underlying Real, 64bit, scalar,
// one can ask for a real64 but also int, string, ...
// You can also ask for the 5th element of a double array
// or try to access the structure detail,
// but then you have to expect a failed response.
// So a simple client uses
// if (! getDouble()) { .. error .. }
// and a more sopisticated one uses
// getType() == Real or Integer --> getDouble()
//
// The alternative would be individual reader interfaces
// for numerics, strings, structures, numeric arrays, string arrays, ...
// or even separate ones for int8, int16, ...
// Marty's "network accessable data" email to core talk did the latter.
// JCA also currently goes that way:
// getDBR() == DOUBLE ? --> ( (DBR_Double)getValue() ).getDoubleValue()
// getDBR() == INT ? --> ( (DBR_Int)getValue() ).getIntValue()
class EpicsDataReader : public EpicsDataDescriptor
{
public:
// Get data as type XX as best as possible.
// Example: getDouble returns true for
// Bool (d=0.0, 1.0), Integer, Real, Enum.
virtual bool getReal64(real64_t &r) = 0;
virtual bool getDouble(double &d) = 0;
virtual bool getInt(int &d) = 0;
// String
virtual bool getString(char *buf, int buf_len) = 0;
virtual int getStringLength() = 0;
virtual bool getCstring(const char *&c_ptr) = 0;
/// many more, at least one for each supported type.

// A structure is accessed via a (sub-)catalog.
// See below for PropertyCatalog.
virtual class EpicsPropertyCatalog *getStructure() = 0;

// Get array element. getDouble(x) == getArrayDouble(0, x)
virtual bool getArrayDouble(int element, double &d) = 0;
virtual bool getMatrixDouble(int dim, int element, double &d) = 0;
virtual class EpicsPropertyCatalog *getArrayStructure(int element) = 0;
/// For arrays, it could include per-element access
/// as well as accessors that copy sub-arrays into client buffers.
};

// "Property" has a name and data reader interface
class EpicsProperty : public EpicsDataReader
{
public:
virtual const char *getName() = 0;
};

// A catalog of properties
class EpicsPropertyCatalog
{
public:
virtual int getNumProperties() = 0;
virtual EpicsProperty *findProperty(const char *name) = 0;
virtual EpicsProperty *getProperty(int index) = 0;
/// Could also support name <-> ID conversions and
/// access via numeric ID.
};

=== C++ Implementation ===
// On the first read, skip to the 'Usage Example' below.
// This code isn't the greatest, but simply here to get
// example code that actually compiles & runs.
#include <string>
using std::string;
#include <string.h>

// Base class for the following EpicsProperty implementations.
// Provides default handlers for everything.
class EpicsPropertyBase : public EpicsProperty
{
public:
EpicsPropertyBase(const char *name)
{ this->name = name; }

// EpicsDataDescriptor
// defaults for scalar
int getNumDims()
{ return 1; }
int getSize(int dim)
{ return dim==0 ? 1 : 0; }
int getBitsize()
{ return 0; }
bool isSigned()
{ return true; }

// DataReader
bool getReal64(real64_t &r)
{ return getDouble(r); }
bool getDouble(double &d)
{
int i;
if (!getInt(i))
return false;
d = i;
return true;
}
bool getInt(int &i)
{
double d;
if (!getDouble(d))
return false;
i = (int)d;
return true;
}
bool getString(char *buf, int buf_len)
{
const char *ptr;
if (!getCstring(ptr))
return false;
strncpy(buf, ptr, buf_len-1);
return true;
}
int getStringLength()
{ return 0; }
bool getCstring(const char *&c_ptr)
{ return false; }
EpicsPropertyCatalog *getStructure()
{ return 0; }
bool getArrayDouble(int element, double &d)
{ return (element == 0) ? getDouble(d) : false; }
bool getMatrixDouble(int dim, int element, double &d)
{ return (dim == 0) ? getArrayDouble(element, d) : false; }
EpicsPropertyCatalog *getArrayStructure(int element)
{ return element==0 ? getStructure() : 0; }

// EpicsProperty
const char *getName()
{ return name.c_str(); }
private:
string name;
};

// EpicsProperty for 'double'. Actual data is outside,
// the EpicsDoubleProperty keeps a pointer to it.
class EpicsDoubleProperty : public EpicsPropertyBase
{
public:
EpicsDoubleProperty(const char *name, const double *p)
: EpicsPropertyBase(name)
{ this->p = p; }
// EpicsDataDescriptor
EpicsDataCharacter getType()
{ return Real; }
int getBitsize()
{ return sizeof(double)*8; }
// EpicsDataReader
bool getDouble(double &d)
{ d = *p;
return true;
}
private:
const double *p;
};

// Handler for string. Data is not owned by this class.
class EpicsStringProperty : public EpicsPropertyBase
{
public:
EpicsStringProperty(const char *name, const string *p)
: EpicsPropertyBase(name)
{ this->p = p; }
// EpicsDataDescriptor
EpicsDataCharacter getType()
{ return String; }
// EpicsDataReader
int getStringLength()
{ return p->length(); }
virtual bool getCstring(const char *&c_ptr)
{
c_ptr = p->c_str();
return true;
}
private:
const string *p;
};

class EpicsPropertyCatalogBase : public EpicsPropertyCatalog
{
public:
EpicsPropertyCatalogBase(int num_properties, EpicsProperty **properties)
: num_properties(num_properties), properties(properties)
{}
// EpicsPropertyCatalog
int getNumProperties()
{ return num_properties; }
EpicsProperty *findProperty(const char *name)
{
int i;
for (i=0; i<num_properties; ++i)
if (!strcmp(properties[i]->getName(), name))
return properties[i];
return 0;
}
EpicsProperty *getProperty(int index)
{
return (index >=0 && index < num_properties) ? properties[index] : 0;
}
private:
int num_properties;
EpicsProperty **properties;
};

// Handler for struct. Keeps pointers to EpicsProperty
// interfaces for the struct's fields.
class EpicsStructureProperty : public EpicsPropertyBase
{
public:
EpicsStructureProperty(const char *name, int num_properties, EpicsProperty **properties)
: EpicsPropertyBase(name), pc(num_properties, properties)
{}
// EpicsDataDescriptor
EpicsDataCharacter getType()
{ return Structure; }
// EpicsDataReader
EpicsPropertyCatalog *getStructure()
{ return &pc; }
private:
EpicsPropertyCatalogBase pc;
};

=== Example for data known at compile-time ===
// This is the code that provides a property catalog.
// Again skip on the first read.
//
// All of this could be generated from DBD information.
class TestRecord : public EpicsPropertyCatalogBase
{
public:
TestRecord();
// Unsure if database code with pointer to the record
// should still directly access the data,
// or if the data should be protected/private.
double value;
string units;
struct
{
double x, y;
} point;
private:
EpicsProperty *properties[3];
EpicsProperty *point_properties[2];
};

TestRecord::TestRecord()
: EpicsPropertyCatalogBase(3, properties)
{
point_properties[0] = new EpicsDoubleProperty("x", &point.x);
point_properties[1] = new EpicsDoubleProperty("y", &point.y);
properties[0] = new EpicsDoubleProperty("value", &value);
properties[1] = new EpicsStringProperty("units", &units);
properties[2] = new EpicsStructureProperty("point", 2, point_properties);
}

=== Example Generic 'Dumper' ===

class EpicsPropertyDumper
{
public:
static const char *type2string(EpicsDataCharacter c)
{
const char *strings[] =
{
"Octet",
"Bool",
"Integer",
"Real",
"String",
"Enum",
"Structure",
"TimeStamp"
};

if (c < 0 || c >= sizeof(strings)/sizeof(const char *))
return "<unknown>";
return strings[c];
}

static void dump(EpicsPropertyCatalog *pc)
{ dump(0, pc); }
private:
static void indent(int level)
{ for (int i=0; i<level; ++i) printf(" "); }
static void dump(int level, EpicsPropertyCatalog *pc)
{
double d;
int i;
for (i=0; i<pc->getNumProperties(); ++i)
{
indent(level);
EpicsProperty *p = pc->getProperty(i);
EpicsDataCharacter type = p->getType();
printf("%s (%s, %d %s, %d bits) = ",
p->getName(), type2string(type),
p->getSize(0),
(p->getSize(0) == 1 ? "element" : "elements"),
p->getBitsize());
switch (type)
{
case String:
const char *s;
if (p->getCstring(s))
printf("'%s' (%d chars)\n", s, p->getStringLength());
else
printf("<cannot get string>\n");
break;
case Bool:
case Integer:
case Real:
double d;
if (p->getDouble(d))
printf("%.2f\n", d);
else
printf("<cannot get double>\n");
break;
case Structure:
indent(level);
printf("\n{\n");
dump(level+1, p->getStructure());
indent(level);
printf("}\n");
break;
default:
printf("<unhandled type %d>\n", p->getType());
}
}
}
};

=== Usage Example ===
#include <stdio.h>

int main()
{
TestRecord fred;
// Record/device support might have direct access to the fields:
fred.value = 42.3;
fred.units = "a.u.";
fred.point.x = 10;
fred.point.y = 15;

// Other code uses PropertyCatalog
EpicsPropertyCatalog *pc = &fred;

// It can access known properties in chosen order
EpicsProperty *p = pc->findProperty("value");
double d;
if (p && p->getDouble(d))
printf("Value = %.2f\n", d);
else
printf("Cannot get value as double\n");

// Or inspect unknown property catalogs
EpicsPropertyDumper::dump(pc);

return 0;
}

== Comparable DataAccess Example? ==
This is the result of my attempt to implement the TestRecord
and main() code based on the August 23 snapshot of DataAccess.

#include <iostream>
#include <string>
#include "dataAccess.h"
#include "daPropertyId.h"

using namespace da;

static const propertyId pi_value("value");
static const propertyId pi_units("units");
static const propertyId pi_point("point");
static const propertyId pi_x("x");
static const propertyId pi_y("y");

class TestRecord : public propertyCatalog
{
public:
virtual ~TestRecord() {};
// Unsure if database code with pointer to the record
// should still directly access the data,
// or if the data should be protected/private.
double value;
string units;
struct
{
double x, y;
} point;

// propertyCatalog
void traverse ( propertyViewer &v) const
{
v.reveal(pi_value, this->value);
// Don't know how to turn a std::string into a stringSegment
// v.reveal(pi_units, this->units); ??
// Don't know how to reveal the 'point'
// without changing the struct point itself
// into a class derived from propertyCatalog
v.reveal(pi_x, this->point.x);
v.reveal(pi_y, this->point.y);
}
// Basically the same, supposedly no longer necessary with latest DA
traverseModifyStatus traverse ( propertyManipulator & m)
{
m.reveal(pi_value, this->value);
// m.reveal(pi_units, this->units); ??
m.reveal(pi_x, this->point.x);
m.reveal(pi_y, this->point.y);
return tmsSuccess;
}
bool find ( const propertyId & id, propertyViewer & v) const
{ // Naive, not using the 'locator' helper, but less code
if (id == pi_value)
{
v.reveal(pi_value, this->value);
return true;
}
if (id == pi_x)
{
v.reveal(pi_value, this->point.x);
return true;
}
if (id == pi_y)
{
v.reveal(pi_value, this->point.y);
return true;
}
return false;
}
};

class Viewer : public propertyViewer
{
public:
void reveal ( const propertyId &id, const double &d, const propertyCatalog &x)
{ // Don't know how to print the id.getName() stringSegment.
cout << "?? = " << d << "\n";
}
void reveal ( const propertyId &, const int &, const propertyCatalog &x)
{
}
void reveal ( const propertyId &, const unsigned int &, const propertyCatalog &x)
{
}
void reveal ( const propertyId &, const long &, const propertyCatalog &x)
{
}
void reveal ( const propertyId &, const unsigned long &, const propertyCatalog &x)
{
}
void reveal ( const propertyId &, const epicsTime &, const propertyCatalog &x)
{
}
void reveal ( const propertyId &, const stringSegment &, const propertyCatalog &x)
{
}
void reveal ( const propertyId &, const enumStateSet & )
{
}
void reveal ( const propertyId &, const arraySegment &, const propertyCatalog &x)
{
}
void reveal ( const propertyId &, const propertyCatalog &x)
{
}
};

int main ()
{
TestRecord fred;
// Record/device support might have direct access to the fields:
fred.value = 42.3;
fred.units = "a.u.";
fred.point.x = 10;
fred.point.y = 15;

// Assume other code that uses PropertyCatalog
// without knowing about TestRecord
propertyCatalog *pc = &fred;
// It can access known properties in chosen order
// Unclear how to get the 'value' as a 'double'.
// This will 'reveal' whatever's there.
// I assume one would have to implement a propertyCatalog
// for target = 'double value' and then assign the given pc
// to that target.
Viewer dumper;
pc->find(pi_value, dumper);
// Or inspect unknown property catalogs
pc->traverse(dumper);

return 0;
}

== Thoughts ==
DataAccess
- does not provide type information
+ property ID handling already optimized
+ allows segmented strings and arrays
- unclear how to interface a std::string or char [] string
- cannot interface the example record without turning 'struct point' into its own class, derived from propertyCatalog?
* might be more complete but doesn't all compile

This Interface
+ does provide type information
- property IDs only strings
- requires contiguous C-String
+ supports C-string
+ can interface the struct point as is
* is incomplete but compiles

V4 Data Interface

2005-08-09T13:05:08Z

KayKasemir: Class Layout Image

File:V4DataInter.jpg

2005-08-09T13:03:58Z

KayKasemir: Data Interface Layout

Data Interface Layout

V4 Data Interface

2005-08-04T20:21:13Z

KayKasemir: added structure handling to example

V4 Data Interface

2005-07-27T22:23:56Z

KayKasemir:

Ancient V4 Design

2005-07-27T22:16:17Z

KayKasemir: data interface

V4 Use Cases

2005-07-18T19:30:30Z

KayKasemir: Tried to format it better. Still ugly.

V4 Use Cases

2005-07-18T19:15:20Z

KayKasemir:

== Use Cases ==

These are examples that need to get handled
by the CA client user API, the network protocol,
the database, down to drivers and back up to
the client.

=== Command-line tools for debugging and scripting ===
1. Dump the current "value" of the channel "fred".
2. Dump all properties, their type, current value for a given channel.
3. Dump the timestamp, value, units, status, severity of "fred" once a second.
4. ... whenever any of the timestamp, ... severity change.
5. List all events that a PV supports: On change, 1Hz, RF Pulse, Beam Pulse, ...
6. Dump the value of the cavity waveform for every beam pulse.

=== Display Manager ===
1. Display an analog input value on a bar
Get limits, subscribe to values, receive value & display it, receive change-of-display-range notification,...
2. Display a menu output for a 2 state valve on a text update
Get state strings, subscribe to (numeric?) value, display incoming data, receive state string updates, ...
3. Give a controller for a 2 state valve controller on a radio button
Handle same as 2?
4. Display a waveform on an xy plot
Similar to 1, but array data?
5. Attempt to display a string on a bar
6. Universal PV Inspector:
Get properties, allow user to select properties.
If writeable string -> display text entry field
If read-only string -> display text update field
If writeable numeric with limits -> display slider with range of number
....
7. Display as bars, a list of BPMs where I can set the offset in time to fetch (assuming that these BPMs are read as arrays that are all triggered at one time – but I want to see them at different points in time as it goes down the beamline).

=== Physics Application ===
1. BPM-related ideas
1.1. List all channels available that are BPMs
1.2. Select all of them in sector 6
1.3 Display them when the beam is going to the end station A (one of 8 destinations possible)
1.4 Same, but display all BPMs on the .1 Hz event

2. Scan a probe in the beam line
2.1 Find PVs for some beam line device:
Stepper motors for probe's X & Y position, intensity of beam transmitted by probe,
beam shutter open/close, beam available
2.2 Scan sequence:
Assert shutter is closed;
move X/Y to 0/0, wait for completion
until done:
open shutter, wait until open
measure intensity for 1 second while beam_available
close shutter
move to next position, wait until you get there

=== Archiver ===
1. Get value, timestamp, status/severity of a channel once per second
2. Archive default properties of a channel using the default deadband
How are they defined? How does the archiver learn about them?
3. Given that there is a new view defined in the stepper motor that includes all motor readback data:
Subscribe to counterClockWiseLimit, clockWiseLimit, moving, doneRetries, homeLimit
at 10 Hz.

Ancient V4 Design

2005-07-18T19:11:56Z

KayKasemir:

Ancient V4 Design

2005-07-18T19:11:32Z

KayKasemir: use cases

This page links to various documents for discussion by the EPICS core developers.

'''Code to implement this stuff doesn't exist yet, and the designs may change!'''

''Note to authors: please use 'V4' at the start of page names for Version 4 documentation, as this makes it clear which wiki pages refer to the new designs just from the page name.''

I've started listing some discussion topics for a [[V4 July Meeting Agenda]], feel free to add to these - Andrew Johnson

== Overall Design ==
* [[V4 Use Cases]] - Bob Dalesio, Kay Kasemir

== Core and Database ==

* [[V4 Modules and Interfaces]] - Andrew Johnson

* [[V4 Requirements for Standard Types]] - Andrew Johnson
* [[V4 Standard Properties and Events]] - Andrew Johnson

* V4 Database Definition: [[V4 Database Definition|(old version)]] - Marty Kraimer, Andrew Johnson
** [[V4 DBD Statement Syntax]] - Marty Kraimer, Andrew Johnson
** [[V4 DBD dbCommon and iocRecord]] - Marty Kraimer
** [[V4 DBD Examples]] - Marty Kraimer, Andrew Johnson
** [[V4 DB Record Instance Syntax]] - Andrew Johnson
** [[V4 DBD Generated Code]] - Marty Kraimer
** [[V4 View Generated Code]] - Andrew Johnson

* V4 Database Access:
** [[V4 Design: epicsTypes]] - Marty Kraimer, Andrew Johnson
** [[V4 Design: dbdClass]] - Marty Kraimer
** [[V4 Design: dbdClass Examples]] - Marty Kraimer
** [[V4 Design: Database Initialization]] - Marty Kraimer
** [[V4 Design: Database Access Semantics]] - Marty Kraimer
** [[V4 Design: Record Processing]] - Marty Kraimer
** [[V4 Design: Assembling Record Support]] - Ben Franksen
** [[V4 Design: driverInterfaces]] - Marty Kraimer

* [[V4 User-defined fields]] - Kay Kasemir

* [[V4 Server Side Plugins]] - Ralph Lange, Benjamin Franksen

== Core and Database ==

* [[V4 Modules and Interfaces]] - Andrew Johnson

* [[V4 Requirements for Standard Types]] - Andrew Johnson
* [[V4 Standard Properties and Events]] - Andrew Johnson

* V4 Database Definition: [[V4 Database Definition|(old version)]] - Marty Kraimer, Andrew Johnson
** [[V4 DBD Statement Syntax]] - Marty Kraimer, Andrew Johnson
** [[V4 DBD dbCommon and iocRecord]] - Marty Kraimer
** [[V4 DBD Examples]] - Marty Kraimer, Andrew Johnson
** [[V4 DB Record Instance Syntax]] - Andrew Johnson
** [[V4 DBD Generated Code]] - Marty Kraimer
** [[V4 View Generated Code]] - Andrew Johnson

* V4 Database Access:
** [[V4 Design: epicsTypes]] - Marty Kraimer, Andrew Johnson
** [[V4 Design: dbdClass]] - Marty Kraimer
** [[V4 Design: dbdClass Examples]] - Marty Kraimer
** [[V4 Design: Database Initialization]] - Marty Kraimer
** [[V4 Design: Database Access Semantics]] - Marty Kraimer
** [[V4 Design: Record Processing]] - Marty Kraimer
** [[V4 Design: Assembling Record Support]] - Ben Franksen
** [[V4 Design: driverInterfaces]] - Marty Kraimer

* [[V4 User-defined fields]] - Kay Kasemir

* [[V4 Server Side Plugins]] - Ralph Lange, Benjamin Franksen

== Network Communications ==

* [[V4 Name Server]] - Doug Murray, Kay Kasemir
* [[V4 CA Interfaces]] - Jeff Hill
* [[V4 CA Client User Interface]] - Doug Murray, Kay Kasemir

== Other Services ==

* [[V4 Replacement for drvTS]] - Timo Korhonen
* [[V4 Replacement for SNL]] - Ben Franksen, Götz Pfeiffer
* [[V4 Data Store]] - Ralph Lange

Ancient V4 Design

2005-07-18T19:11:28Z

KayKasemir: use cases

V4 CA Client User Interface

2005-07-16T19:13:44Z

KayKasemir: TIPC

== Channel Access Client User Interface ==
Under V4, a ProcessVariable would no longer be limited
to the current properties 'value', 'units', ... but allow the users to create
CA servers and clients that understand new properties.

The low-level V4 CA client API is likely to be rather complex because it
now needs to handle arbitrary property catalogs.
* There still needs to be an easy to use high-level API, not much more complex than the existing one.
* There needs to be access to CA from languages like Matlab in a way that's as easy as
pv = caopen('fred');
value = caget(pv);

== Food for thought ==
Is there anything we can learn from other communication libraries?
* A brief look at [[ZeroC ICE]]
* TIPC, the Transparent Inter Process Communication protocol (TIPC) started out as a communications layer for building clusters, I think by Ericson, and is now becoming more open and also supported by the latest WindRiver vxWorks releases. The Buzz:
** allows socket-based applications to communicate easily and efficient
** based on publicly available source code
** A location-transparent addressing scheme
** Efficient, rapid, and reliable interprocess communication within a node and between nodes, using either connection-oriented or connectionless modes of operation
** Rapid notification of changes in topology and the ability to adjust quickly to these changes

== Constraints ==
* Initial implementation will be in C++
* Should very easily translate into Java, just like e.g. some XML APIs use the exact same classes and methods in C++ and Java. Ideally, Java and C++ version will be available from the start.
* Ideally, the C++ headers would be simple enough to be parsed by SWIG and hence perl/tcl/python/... glue code could be auto-generated via SWIG
* API is of course specific to EPICS CA, but ideally it'll also be usable as an interface to other protocols, so that EPICS Office can use an API that is only a slight extension of the CA client user API.

== Skeleton API ==
What follows is in the form of pseudo classes and associated methods
that a CA client API should provide.

=== Directory ===
The directory is used to discover available channels and map them to the CA Server address and port.
* Directory(string URL-type-server-address = "") Constructor; uses site-specific default server or specific one. The 'URL' might contain a user & password, which decides if this name server connection is read-only (for OPI clients) or if writes are allowed (for IOCs that add PVs to the name server).
* getChannelInfo(string PV_or_pattern) Returns list of
** CA server - IP & port of server that has the PV
** quality - is this the IOC, a gateway, backup/primary
* addChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to register their PV in directory
* deleteChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to remove their PV from directory

There is a default directory, available via something like "EPICSDefaults::getDirectory()" and "...setDirectory()".
The implementation could use
* LDAP
* Broadcast (as before)
* your custom implementation as long as it uses the above interface and registers itself as the default.

Note that Ben argues to hide the directory lookup from the CA client us
er.
See separate [[V4 Name Server]] wiki for the issue of "record" and "PV" information.

=== Data ===
The available ''data'' constists of property names, types and values, for example:
double value; // The "value" property of our data
string units; // The "units" property....
time_stamp time;

The data might contain arrays and structures.
The user might not want all the properties, and the user might also want to get properties in non-native types (strings for convenience, float instead of double to preserve space, ...).
The client has to provide storage, and might allocate this:
float value;
string units;

The user interface must provide the following:
* getAllProperties() Get a list of all the property names and their data type so that the client can make an informed decision for allocating its storage of the data. There might be helper routines to convert between human-usable strings and more efficient numeric identifiers.
* bool hasWriteAccess(string property) Could also be part of the info return by previous method.

This functionality is available without getting any actual data.
To retrieve values, the user asks the client library to place the data into
the client-provided storage.
The ''traverse'' of the "dataAccess" proposal handles this by asking
the user to implement a property catalog that ''reveals'' each storage element.
The end effect is not too different from having the user invoke methods
like these:
* getAsString(string property, string *my_storage)
* getAsDouble(string property, double *my_storage)
* ...many more, one for each available data type.

=== Channel ===
* Channel(string name, Directory dir = default) Constructor. Channel has to have a name. Uses the 'best' channel from the default directory or from a given directory.
* Channel(string name, CASInfo) ... in case you want a specific server after querying the directory yourself or not using a directory at all.
* getName() Returns the name of the channel.
* addListener(Listener l), removeListener(Listener l) Register for notifications, see below.
* getProperties() A read or subscription will return a dataAccess interface to the retrieved data. That might exclude properties that this client cannot access. It will include the data, which might be huge. This separate call will only get property information, no data, for all properties, including read/write access information. The result could be in the form of dataAccess, except all access to actual data yields empty results, only the property-info related part of dataAccess is functional.

Note that Ben suggests that the CA client library should select the CA server automatically by querying a server or via broadcasts; it should also pick amongst competing PVs of the same name without user interaction.

Note also that in order to read or write, one needs to know what properties to access.
Does the channel magically provide a list of all properties?
Is there a "get all properties" request that reads them on-demand
from the CA server?
Or does the directory hold the list of available properties and their types?

=== Channel: Listener ===
The Channel::Listener interface is invoked in response to the many asynchronous methods of the Channel.
* writeComplete(Channel ch)
** Channel that send this notification
* newData(Channel ch, DataAccess data, Event why)
** DataAccess interface to the data
** Reason for the update: Value deadband exceeded, minimum period expired, event 'blue beam', ...
* accessRightChange(Channel ch)

Alternatively, these could be separate interfaces for a writeListener, dataListener, stateListener.

=== Channel: State ===
In contrast to the V3 API, the user doesn't 'connect'.
The first data notification implies that we're connected.

* bool isConnected() .. for those who want to poll
* xxx getServerInfo(), xxx getType() .. only valid when isConnected().
* setUser(), ... Sets/changes the 'user' that determines the access rights, allowing OPI tools to adjust this per-channel at runtime. To avoid security issues, setUser will probably send a public key and not a user name and password.

=== Channel: Writing ===
* write(new value) Sends the value to the server.
* createWriteRequest(new value, receipt {delivery, completion, response}) Sends the value to the server, invokes Listener when CA server has received the value (delivery) or all the processing triggered by the new value has completed (completion). In addition, some records might support command/response, in which case one can write a command and wait for a response callback which looks just like the result of a read request.
* scheduleWriteRequest(new value, event) Sends the value to the server, which will perform the write when the given event fires. Invokes Listener when CA server has performed the write.

=== Channel: Reading ===
* createSubscription(list<string> properties, Event e) Will invoke Listener once data arrives.
* cancelSubscription(....) Use properties & event or an ID returned from createSubscription?

Event is a class that allows the user to select what triggers an update:
* useDefaultValueDeadband() Default if nothing else is called.
* setValueDeadband(double change)
* setPercentageDeadband(double percent)
* setLogarithmicDeadband(double exponent_of_ten)
* setMinimumRate(double seconds) There will be notifications at at least this rate, even if value didn't change.
* setMaximumRate(double vals_per_second)
* useAlarmConditionChange()
* useHardwareEvent(int event_id) Somehow, event_id might be linked to 'Blue Beam'
* setMaxValueCount Setting this to '1' turns the subscription into a single-value 'get'.

Unclear how to present the Event to a user. For example, how would a 'camonitor' tool allow the user to select the events? Via 20 command-line switches, or should there be a syntax ala
"valueDeadband=1.0, maximumRate=20" which is supported by methods
* string toString()
* bood fromString(string event_specification)

=== ChannelGroup ===
A channel group synchronizes access to multiple channels.
It listens to all members of the channel group and for example
allows waiting for ''all'' outstanding read or write requests
to return.

* add/remove channels By name? Already existing Channel? Add channels that match a pattern, or go via the directory?
* read/write Has to handle reading/writing the same properties from all channels in group. Also channel-specific list of properties?

=== SyncChannel ===
A wrapper class around the async. Channel.
Uses a configurable timeout and provides synchronous 'read'.

* Inherits from Channel.
* double getTimeout(), void setTimeout(double seconds)
* DataAccess read(list<string> properties) Synchronous read of current values of properties.
* DataAccess read(string property) Synchronous read of current value of one property.

=== Container ===
The Channel does not store any data.
When attaching a container to a channel, the container will subscribe
to the channel and keep a copy of all data, so one can always ask
the container for the current values.
* attach(channel)
* detach()
* implements the DataAccess interface to allow access to the data.

Also see [[V4 Data Store]]

== caget 101 ==
This is how a simple 'caget' could be written:

SyncChannel channel("fred");
DataAccess da = channel.read("value");
cout << "Value of " << channel.getName() << " : " << da.getAsString("value") << "\n";

We can imagine an even simpler example:

cout << "Value of fred:" << Epics::get("fred") << "\n";

This implies lots of work under the hood, with reasonable defaults.

== camonitor 101 ==
This is the goal for a 'camonitor':

class MyMonitor : public Channel::Listener
{
public:
newData(Channel ch, DataAccess data, Event why)
{
cout << channel.getName() << " = " << da.getAsString("value") << "\n";
}
};
...
Channel channel("fred");
list<string> properties;
properties.push_back("value");
Event e;
e. setMaximumRate(10.0);
channel.createSubscription(properties, e);

V4 CA Client User Interface

2005-07-16T05:10:53Z

KayKasemir: start over with requirements, dropping details that are controversial

== Channel Access Client User Interface ==
Under V4, a ProcessVariable would no longer be limited
to the current properties 'value', 'units', ... but allow the users to create
CA servers and clients that understand new properties.

The low-level V4 CA client API is likely to be rather complex because it
now needs to handle arbitrary property catalogs.
* There still needs to be an easy to use high-level API, not much more complex than the existing one.
* There needs to be access to CA from languages like Matlab in a way that's as easy as
pv = caopen('fred');
value = caget(pv);

== Food for thought ==
Is there anything we can learn from other communication libraries?
* A brief look at [[ZeroC ICE]]

== Constraints ==
* Initial implementation will be in C++
* Should very easily translate into Java, just like e.g. some XML APIs use the exact same classes and methods in C++ and Java. Ideally, Java and C++ version will be available from the start.
* Ideally, the C++ headers would be simple enough to be parsed by SWIG and hence perl/tcl/python/... glue code could be auto-generated via SWIG
* API is of course specific to EPICS CA, but ideally it'll also be usable as an interface to other protocols, so that EPICS Office can use an API that is only a slight extension of the CA client user API.

== Skeleton API ==
What follows is in the form of pseudo classes and associated methods
that a CA client API should provide.

=== Directory ===
The directory is used to discover available channels and map them to the CA Server address and port.
* Directory(string URL-type-server-address = "") Constructor; uses site-specific default server or specific one. The 'URL' might contain a user & password, which decides if this name server connection is read-only (for OPI clients) or if writes are allowed (for IOCs that add PVs to the name server).
* getChannelInfo(string PV_or_pattern) Returns list of
** CA server - IP & port of server that has the PV
** quality - is this the IOC, a gateway, backup/primary
* addChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to register their PV in directory
* deleteChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to remove their PV from directory

There is a default directory, available via something like "EPICSDefaults::getDirectory()" and "...setDirectory()".
The implementation could use
* LDAP
* Broadcast (as before)
* your custom implementation as long as it uses the above interface and registers itself as the default.

Note that Ben argues to hide the directory lookup from the CA client us
er.
See separate [[V4 Name Server]] wiki for the issue of "record" and "PV" information.

=== Data ===
The available ''data'' constists of property names, types and values, for example:
double value; // The "value" property of our data
string units; // The "units" property....
time_stamp time;

The data might contain arrays and structures.
The user might not want all the properties, and the user might also want to get properties in non-native types (strings for convenience, float instead of double to preserve space, ...).
The client has to provide storage, and might allocate this:
float value;
string units;

The user interface must provide the following:
* getAllProperties() Get a list of all the property names and their data type so that the client can make an informed decision for allocating its storage of the data. There might be helper routines to convert between human-usable strings and more efficient numeric identifiers.
* bool hasWriteAccess(string property) Could also be part of the info return by previous method.

This functionality is available without getting any actual data.
To retrieve values, the user asks the client library to place the data into
the client-provided storage.
The ''traverse'' of the "dataAccess" proposal handles this by asking
the user to implement a property catalog that ''reveals'' each storage element.
The end effect is not too different from having the user invoke methods
like these:
* getAsString(string property, string *my_storage)
* getAsDouble(string property, double *my_storage)
* ...many more, one for each available data type.

=== Channel ===
* Channel(string name, Directory dir = default) Constructor. Channel has to have a name. Uses the 'best' channel from the default directory or from a given directory.
* Channel(string name, CASInfo) ... in case you want a specific server after querying the directory yourself or not using a directory at all.
* getName() Returns the name of the channel.
* addListener(Listener l), removeListener(Listener l) Register for notifications, see below.
* getProperties() A read or subscription will return a dataAccess interface to the retrieved data. That might exclude properties that this client cannot access. It will include the data, which might be huge. This separate call will only get property information, no data, for all properties, including read/write access information. The result could be in the form of dataAccess, except all access to actual data yields empty results, only the property-info related part of dataAccess is functional.

Note that Ben suggests that the CA client library should select the CA server automatically by querying a server or via broadcasts; it should also pick amongst competing PVs of the same name without user interaction.

Note also that in order to read or write, one needs to know what properties to access.
Does the channel magically provide a list of all properties?
Is there a "get all properties" request that reads them on-demand
from the CA server?
Or does the directory hold the list of available properties and their types?

=== Channel: Listener ===
The Channel::Listener interface is invoked in response to the many asynchronous methods of the Channel.
* writeComplete(Channel ch)
** Channel that send this notification
* newData(Channel ch, DataAccess data, Event why)
** DataAccess interface to the data
** Reason for the update: Value deadband exceeded, minimum period expired, event 'blue beam', ...
* accessRightChange(Channel ch)

Alternatively, these could be separate interfaces for a writeListener, dataListener, stateListener.

=== Channel: State ===
In contrast to the V3 API, the user doesn't 'connect'.
The first data notification implies that we're connected.

* bool isConnected() .. for those who want to poll
* xxx getServerInfo(), xxx getType() .. only valid when isConnected().
* setUser(), ... Sets/changes the 'user' that determines the access rights, allowing OPI tools to adjust this per-channel at runtime. To avoid security issues, setUser will probably send a public key and not a user name and password.

=== Channel: Writing ===
* write(new value) Sends the value to the server.
* createWriteRequest(new value, receipt {delivery, completion, response}) Sends the value to the server, invokes Listener when CA server has received the value (delivery) or all the processing triggered by the new value has completed (completion). In addition, some records might support command/response, in which case one can write a command and wait for a response callback which looks just like the result of a read request.
* scheduleWriteRequest(new value, event) Sends the value to the server, which will perform the write when the given event fires. Invokes Listener when CA server has performed the write.

=== Channel: Reading ===
* createSubscription(list<string> properties, Event e) Will invoke Listener once data arrives.
* cancelSubscription(....) Use properties & event or an ID returned from createSubscription?

Event is a class that allows the user to select what triggers an update:
* useDefaultValueDeadband() Default if nothing else is called.
* setValueDeadband(double change)
* setPercentageDeadband(double percent)
* setLogarithmicDeadband(double exponent_of_ten)
* setMinimumRate(double seconds) There will be notifications at at least this rate, even if value didn't change.
* setMaximumRate(double vals_per_second)
* useAlarmConditionChange()
* useHardwareEvent(int event_id) Somehow, event_id might be linked to 'Blue Beam'
* setMaxValueCount Setting this to '1' turns the subscription into a single-value 'get'.

Unclear how to present the Event to a user. For example, how would a 'camonitor' tool allow the user to select the events? Via 20 command-line switches, or should there be a syntax ala
"valueDeadband=1.0, maximumRate=20" which is supported by methods
* string toString()
* bood fromString(string event_specification)

=== ChannelGroup ===
A channel group synchronizes access to multiple channels.
It listens to all members of the channel group and for example
allows waiting for ''all'' outstanding read or write requests
to return.

* add/remove channels By name? Already existing Channel? Add channels that match a pattern, or go via the directory?
* read/write Has to handle reading/writing the same properties from all channels in group. Also channel-specific list of properties?

=== SyncChannel ===
A wrapper class around the async. Channel.
Uses a configurable timeout and provides synchronous 'read'.

* Inherits from Channel.
* double getTimeout(), void setTimeout(double seconds)
* DataAccess read(list<string> properties) Synchronous read of current values of properties.
* DataAccess read(string property) Synchronous read of current value of one property.

=== Container ===
The Channel does not store any data.
When attaching a container to a channel, the container will subscribe
to the channel and keep a copy of all data, so one can always ask
the container for the current values.
* attach(channel)
* detach()
* implements the DataAccess interface to allow access to the data.

Also see [[V4 Data Store]]

== caget 101 ==
This is how a simple 'caget' could be written:

SyncChannel channel("fred");
DataAccess da = channel.read("value");
cout << "Value of " << channel.getName() << " : " << da.getAsString("value") << "\n";

We can imagine an even simpler example:

cout << "Value of fred:" << Epics::get("fred") << "\n";

This implies lots of work under the hood, with reasonable defaults.

== camonitor 101 ==
This is the goal for a 'camonitor':

class MyMonitor : public Channel::Listener
{
public:
newData(Channel ch, DataAccess data, Event why)
{
cout << channel.getName() << " = " << da.getAsString("value") << "\n";
}
};
...
Channel channel("fred");
list<string> properties;
properties.push_back("value");
Event e;
e. setMaximumRate(10.0);
channel.createSubscription(properties, e);

V4 User-defined fields

2005-07-14T22:28:25Z

KayKasemir: /* Overview */

== Overview ==
Records, the building blocks of an EPICS run-time database,
are much more powerful than the fundamental commands
of programming languages like C, C++, LabVIEW or PLC
ladder logic: A record like the AI record provides scanning,
various conversions, alarms, smoothing and more.

On the downside, very few record instances use the full functionality
of the record type. Extending their functionality is rather involved,
and very few custom record types get shared in the community.

If it was easier to create, modify and extend records,
we could start with simpler record types and extend them
as needed.

This is a suggestion for supporting user-defined fields in V4,
allowing the user to add fields to a record instance without
first having to create a new record type.

By now, the 'Vampire' (see [[V4_Server_Side_Plugins]]) seems to handle all but the forward link,
and seems an overall better idea.

== User-defined fields ==

For example, I'd like to allow users to define "analog input" records
with the usual fields '''and''' allow them to add new fields to some
instance without having to create a new record type:

calc("fred")
{
field(SCAN, "1 second")
user_field(SMOO, iocFloat64T, "0.5", smoo_handler)
}

This record will have a 'SMOO' field of type double (float 64) that presumably implements
smoothing in the user-supplied smoo_handler.

The idea is that one can add these user-defined fields on a per-instance basis
to pretty much any record type simply by editing the DB file and loading the
handler code, without having to recompile the rest of EPICS base.

Example code for a ''handler'' and what the ''database'' code would have to do
follows.

=== database.h ===

#include <iostream>
#include <string>
#include <list>

using namespace std;

enum iocType
{
iocUnknownT,iocBooleanT,iocOctetT,
iocInt16T,iocUInt16T,iocInt32T,iocUInt32T,iocInt64T,iocUInt64T,
iocFloat32T,iocFloat64T,
iocStringT,iocMenuT,iocEnumT,iocLinkT,iocDeviceT,iocArrayT
};
// ------------------------------------------------------------------
// Support for user-defined fields in base
// ------------------------------------------------------------------
// forwards
class record;
class user_field_handler;

// Information for one user-defined field
class user_field_data
{
public:
string name;
iocType type;
void *data;
string parm;
user_field_handler *handler;
};

// The 'handler' specified for a user field needs to implement
// this interface:
class user_field_handler
{
public:
virtual void init(user_field_data *field, record *rec) {}
virtual void update(user_field_data *field, record *rec) {}
virtual void destroy(user_field_data *field, record *rec) {}
};

// Records need to support hooks similar to Java 'listeners'
// so that user fields can hook into record processing.
// Unclear at what levels hooks are needed.
class got_data_hook
{
public: virtual void run_got_data_hook()=0;
};
class post_monitor_hook
{
public: virtual void run_post_monitor_hook()=0;
};

// Pieces of record code in order to show where the hooks
// are handled inside of 'process()'
class record
{
public:
record(string name) : name(name) {}

void add_user_field(string name, iocType type, string parm,
user_field_handler *handler)
{
user_field_data ufd;
ufd.name = name;
ufd.type = type;
ufd.parm = parm;
ufd.handler = handler;
user_fields.push_back(ufd);
}
void add_got_data_hook(got_data_hook *hook)
{
got_data_hooks.push_back(hook);
}
// TODO: remove_got_data_hook();
void add_post_monitor_hook(post_monitor_hook *hook)
{
post_monitor_hooks.push_back(hook);
}
// TODO: remove_post_monitor_hook();

void iocInit();

void process();
private:
string name;
list<user_field_data> user_fields;
list<got_data_hook *> got_data_hooks;
list<post_monitor_hook *> post_monitor_hooks;
};

=== database.cpp ===

#include "database.h"

void *get_iocType_mem(iocType type)
{
switch (type)
{
case iocFloat32T: return new float;
case iocFloat64T: return new double;
case iocStringT: return new string;
}
return 0;
}

void record::iocInit()
{
cout << "record::iocInit(" << name << ")\n";
list<user_field_data>::iterator ufi;
for (ufi = user_fields.begin(); ufi != user_fields.end(); ++ufi)
{
if ((ufi->data = get_iocType_mem(ufi->type)) != 0)
ufi->handler->init(&(*ufi), this);
else
ufi->type = iocUnknownT;
}
}

void record::process()
{
cout << "record::process(" << name << ")\n";
#ifdef TODO
status=readValue(pai); /* read the new value */
if ( !pact && pai->pact ) return(0);
pai->pact = TRUE;

recGblGetTimeStamp(pai);
if (status==0) convert(pai);
else if (status==2) status=0;
#endif
list<got_data_hook *>::iterator gdhi;
for (gdhi = got_data_hooks.begin(); gdhi != got_data_hooks.end(); ++gdhi)
(*gdhi)->run_got_data_hook();
#ifdef TODO
checkAlarms(pai);
monitor(pai);
#endif
list<post_monitor_hook *>::iterator pmhi;
for (pmhi=post_monitor_hooks.begin(); pmhi!=post_monitor_hooks.end(); ++pmhi)
(*pmhi)->run_post_monitor_hook();
#ifdef TODO
pai->pact=FALSE;
#endif
}

// TODO:
// Record will need to check all it's user_fields[].name
// in case CA tries to get/put.

=== example.cpp ===

/* Goals:
- Avg or other statistical calc:
deposits calculated data into new fields,
doesn't affect the rest of the record.
- Circ Buffer (archive record):
Similar, does something with the current VAL
outside of the record.
- Put Logging: Simlar.
- SMOO: Can it modify the VAL field?
- BPM combiner of 4 AIs: Unclear.
- conversions (new breakpt. table): unclear.
- FLNK (w/ delays?): Should happen _after_ all else is done.

The following implements handlers for some of the above.

*/
#include "database.h"
// ------------------------------------------------------------------
// MAX (easier to calc. then e.g. running average
// ------------------------------------------------------------------
class max_handler : public user_field_handler, got_data_hook
{
void init(user_field_data *field, record *rec)
{
max = (double *)field->data;
// TODO: val = record->get_field_addr("VAL")
rec->add_got_data_hook(this);
}
void run_got_data_hook()
{
// if (*val > *max) *max = *val;
cout << "Max is " << *max << "\n";
}
private:
double *max;
};

// ------------------------------------------------------------------
// SMOO
// ------------------------------------------------------------------
class smoo_handler : public user_field_handler, got_data_hook
{
void init(user_field_data *field, record *rec)
{
smoo = (double *)field->data;
*smoo = atof(field->parm.c_str());
// TODO: val = record->get_field_addr("VAL")
rec->add_got_data_hook(this);
}
void run_got_data_hook()
{
// *val = smoo*(*val) + (1-smoo)*prev_value;
// prev_value = *val;
cout << "Smoothing by " << *smoo << "\n";
}
private:
double *smoo;
double prev_value;
};

// ------------------------------------------------------------------
// FLNK
// ------------------------------------------------------------------
class flnk_handler : public user_field_handler, post_monitor_hook
{
void init(user_field_data *field, record *rec)
{
link_text = (string *)field->data;
*link_text = field->parm;
update(field, rec);
rec->add_post_monitor_hook(this);
}
void update(user_field_data *field, record *rec)
{
// TODO: ink_info = parse_link_info_from_string(*link_text);
link_info = *link_text;
}
void run_post_monitor_hook()
{
cout << "FLNKing to " << link_info << "\n";
// TODO: dbProcessLink(this->link_info);
// Or with additional delay parm:
// wdStart(delay, dbProcessLink, this->link_info); ?
}
private:
string *link_text;
string link_info;
};

// ------------------------------------------------------------------
// Example database snippet and how it's used
// ------------------------------------------------------------------
/*
ai("fred")
{
# NAME, TYPE, PARM, HANDLER
user_field(smoo, iocFloat64T, "0.5", smoo_handler)
user_field(max, iocFloat64T, "", max_handler)
user_field(flnk1, iocStringT, "recordA", flnk_handler)
user_field(flnk2, iocStringT, "recordB", flnk_handler)
user_field(flnk3, iocStringT, "recordC", flnk_handler)
# In these examples, the PARM is the initial value of the field.
# But it could be any string that's used to configure the handler:
# user_field(syslog, iocStringT, "server=124.0.0.5:9876,interval=1", syslog_handler)
}
*/
int main()
{
// This is sort of what would need to happen inside dbLoadDatabase().
// The tricky part is the "new xxx_handler":
// Each handler will have to use the registry to register a factory
// method so that dbLoadDatabase can invoke "new xxx_handler" without
// recompilation.
record fred("fred");
fred.add_user_field("smoo", iocFloat64T, "0.5", new smoo_handler());
fred.add_user_field("max", iocFloat64T, "", new max_handler());
fred.add_user_field("flnk1", iocStringT, "recordA", new flnk_handler());
fred.add_user_field("flnk2", iocStringT, "recordB", new flnk_handler());
fred.add_user_field("flnk3", iocStringT, "recordC", new flnk_handler());
//
fred.iocInit();
//
fred.process();
cout << "\n";
fred.process();

return 0;
}

/*
When run, this basically processes the record and the
code for the user-defined fields is invoked as intended:

record::iocInit(fred)
record::process(fred)
Smoothing by 0.5
Max is 0
FLNKing to recordA
FLNKing to recordB
FLNKing to recordC

record::process(fred)
Smoothing by 0.5
Max is 0
FLNKing to recordA
FLNKing to recordB
FLNKing to recordC

UNCLEAR:
Is string parm enough, or are structs requires?

I believe that all the goals 1-7 can be handled
by providing the appropriate hooks.
Question: How many hooks will that be?

*/

== Comments ==
The example code for user_field_handler::init()
assumes that the record has
a routine get_field_addr(string name) that provides a raw pointer
to each field of a record. Would have to use dataAccess or whatever the
runtime database will ultimately provide.

Some pro and cons when comparing this type of user-defined field to writing a custom record:

=== Pro ===
* One can add fields per record instance as needed. No need to create a possibly confusing plethora of specialized record types: BasicAI, MaxAI, AverageAI, AverageAndMaxAI, BasicAO, MaxAO, ...
* Under vxWorks, one can do so without recompilation:
ld <smoo_handlerLib.o
dbLoadDataBase("..../records_that_use_smoo_handler")

=== Contra ===
* The actions inside a user-field handler are limited to quick, synchronous actions.
* In order to handle the goals mentioned in example.cpp, only two hooks into the record's process() routine are needed. Unclear if this is sufficient in the long run.
* While easy to use, the code requires more runtime checks, more type casts, more boilerplate code. For example, the smoo_handler should react accordingly if the record does not have a numeric value field. In a custom record type, compile-time checks would reduce the code size and increase maintainabililty.

V4 User-defined fields

2005-07-14T22:27:08Z

KayKasemir: /* Overview */

== Overview ==
The 'Vampire' (see [[V4_Server_Side_Plugins]]) seems to handle all but the forward link,
and seems an overall better idea.

Records, the building blocks of an EPICS run-time database,
are much more powerful than the fundamental commands
of programming languages like C, C++, LabVIEW or PLC
ladder logic: A record like the AI record provides scanning,
various conversions, alarms, smoothing and more.

On the downside, very few record instances use the full functionality
of the record type. Extending their functionality is rather involved,
and very few custom record types get shared in the community.

If it was easier to create, modify and extend records,
we could start with simpler record types and extend them
as needed.

This is a suggestion for supporting user-defined fields in V4,
allowing the user to add fields to a record instance without
first having to create a new record type.
There is an alternate proposal,
[[V4 Design: Assembling Record Support]],
that would simplify the creation of new record types.

== User-defined fields ==

For example, I'd like to allow users to define "analog input" records
with the usual fields '''and''' allow them to add new fields to some
instance without having to create a new record type:

calc("fred")
{
field(SCAN, "1 second")
user_field(SMOO, iocFloat64T, "0.5", smoo_handler)
}

This record will have a 'SMOO' field of type double (float 64) that presumably implements
smoothing in the user-supplied smoo_handler.

The idea is that one can add these user-defined fields on a per-instance basis
to pretty much any record type simply by editing the DB file and loading the
handler code, without having to recompile the rest of EPICS base.

Example code for a ''handler'' and what the ''database'' code would have to do
follows.

=== database.h ===

#include <iostream>
#include <string>
#include <list>

using namespace std;

enum iocType
{
iocUnknownT,iocBooleanT,iocOctetT,
iocInt16T,iocUInt16T,iocInt32T,iocUInt32T,iocInt64T,iocUInt64T,
iocFloat32T,iocFloat64T,
iocStringT,iocMenuT,iocEnumT,iocLinkT,iocDeviceT,iocArrayT
};
// ------------------------------------------------------------------
// Support for user-defined fields in base
// ------------------------------------------------------------------
// forwards
class record;
class user_field_handler;

// Information for one user-defined field
class user_field_data
{
public:
string name;
iocType type;
void *data;
string parm;
user_field_handler *handler;
};

// The 'handler' specified for a user field needs to implement
// this interface:
class user_field_handler
{
public:
virtual void init(user_field_data *field, record *rec) {}
virtual void update(user_field_data *field, record *rec) {}
virtual void destroy(user_field_data *field, record *rec) {}
};

// Records need to support hooks similar to Java 'listeners'
// so that user fields can hook into record processing.
// Unclear at what levels hooks are needed.
class got_data_hook
{
public: virtual void run_got_data_hook()=0;
};
class post_monitor_hook
{
public: virtual void run_post_monitor_hook()=0;
};

// Pieces of record code in order to show where the hooks
// are handled inside of 'process()'
class record
{
public:
record(string name) : name(name) {}

void add_user_field(string name, iocType type, string parm,
user_field_handler *handler)
{
user_field_data ufd;
ufd.name = name;
ufd.type = type;
ufd.parm = parm;
ufd.handler = handler;
user_fields.push_back(ufd);
}
void add_got_data_hook(got_data_hook *hook)
{
got_data_hooks.push_back(hook);
}
// TODO: remove_got_data_hook();
void add_post_monitor_hook(post_monitor_hook *hook)
{
post_monitor_hooks.push_back(hook);
}
// TODO: remove_post_monitor_hook();

void iocInit();

void process();
private:
string name;
list<user_field_data> user_fields;
list<got_data_hook *> got_data_hooks;
list<post_monitor_hook *> post_monitor_hooks;
};

=== database.cpp ===

#include "database.h"

void *get_iocType_mem(iocType type)
{
switch (type)
{
case iocFloat32T: return new float;
case iocFloat64T: return new double;
case iocStringT: return new string;
}
return 0;
}

void record::iocInit()
{
cout << "record::iocInit(" << name << ")\n";
list<user_field_data>::iterator ufi;
for (ufi = user_fields.begin(); ufi != user_fields.end(); ++ufi)
{
if ((ufi->data = get_iocType_mem(ufi->type)) != 0)
ufi->handler->init(&(*ufi), this);
else
ufi->type = iocUnknownT;
}
}

void record::process()
{
cout << "record::process(" << name << ")\n";
#ifdef TODO
status=readValue(pai); /* read the new value */
if ( !pact && pai->pact ) return(0);
pai->pact = TRUE;

recGblGetTimeStamp(pai);
if (status==0) convert(pai);
else if (status==2) status=0;
#endif
list<got_data_hook *>::iterator gdhi;
for (gdhi = got_data_hooks.begin(); gdhi != got_data_hooks.end(); ++gdhi)
(*gdhi)->run_got_data_hook();
#ifdef TODO
checkAlarms(pai);
monitor(pai);
#endif
list<post_monitor_hook *>::iterator pmhi;
for (pmhi=post_monitor_hooks.begin(); pmhi!=post_monitor_hooks.end(); ++pmhi)
(*pmhi)->run_post_monitor_hook();
#ifdef TODO
pai->pact=FALSE;
#endif
}

// TODO:
// Record will need to check all it's user_fields[].name
// in case CA tries to get/put.

=== example.cpp ===

/* Goals:
- Avg or other statistical calc:
deposits calculated data into new fields,
doesn't affect the rest of the record.
- Circ Buffer (archive record):
Similar, does something with the current VAL
outside of the record.
- Put Logging: Simlar.
- SMOO: Can it modify the VAL field?
- BPM combiner of 4 AIs: Unclear.
- conversions (new breakpt. table): unclear.
- FLNK (w/ delays?): Should happen _after_ all else is done.

The following implements handlers for some of the above.

*/
#include "database.h"
// ------------------------------------------------------------------
// MAX (easier to calc. then e.g. running average
// ------------------------------------------------------------------
class max_handler : public user_field_handler, got_data_hook
{
void init(user_field_data *field, record *rec)
{
max = (double *)field->data;
// TODO: val = record->get_field_addr("VAL")
rec->add_got_data_hook(this);
}
void run_got_data_hook()
{
// if (*val > *max) *max = *val;
cout << "Max is " << *max << "\n";
}
private:
double *max;
};

// ------------------------------------------------------------------
// SMOO
// ------------------------------------------------------------------
class smoo_handler : public user_field_handler, got_data_hook
{
void init(user_field_data *field, record *rec)
{
smoo = (double *)field->data;
*smoo = atof(field->parm.c_str());
// TODO: val = record->get_field_addr("VAL")
rec->add_got_data_hook(this);
}
void run_got_data_hook()
{
// *val = smoo*(*val) + (1-smoo)*prev_value;
// prev_value = *val;
cout << "Smoothing by " << *smoo << "\n";
}
private:
double *smoo;
double prev_value;
};

// ------------------------------------------------------------------
// FLNK
// ------------------------------------------------------------------
class flnk_handler : public user_field_handler, post_monitor_hook
{
void init(user_field_data *field, record *rec)
{
link_text = (string *)field->data;
*link_text = field->parm;
update(field, rec);
rec->add_post_monitor_hook(this);
}
void update(user_field_data *field, record *rec)
{
// TODO: ink_info = parse_link_info_from_string(*link_text);
link_info = *link_text;
}
void run_post_monitor_hook()
{
cout << "FLNKing to " << link_info << "\n";
// TODO: dbProcessLink(this->link_info);
// Or with additional delay parm:
// wdStart(delay, dbProcessLink, this->link_info); ?
}
private:
string *link_text;
string link_info;
};

// ------------------------------------------------------------------
// Example database snippet and how it's used
// ------------------------------------------------------------------
/*
ai("fred")
{
# NAME, TYPE, PARM, HANDLER
user_field(smoo, iocFloat64T, "0.5", smoo_handler)
user_field(max, iocFloat64T, "", max_handler)
user_field(flnk1, iocStringT, "recordA", flnk_handler)
user_field(flnk2, iocStringT, "recordB", flnk_handler)
user_field(flnk3, iocStringT, "recordC", flnk_handler)
# In these examples, the PARM is the initial value of the field.
# But it could be any string that's used to configure the handler:
# user_field(syslog, iocStringT, "server=124.0.0.5:9876,interval=1", syslog_handler)
}
*/
int main()
{
// This is sort of what would need to happen inside dbLoadDatabase().
// The tricky part is the "new xxx_handler":
// Each handler will have to use the registry to register a factory
// method so that dbLoadDatabase can invoke "new xxx_handler" without
// recompilation.
record fred("fred");
fred.add_user_field("smoo", iocFloat64T, "0.5", new smoo_handler());
fred.add_user_field("max", iocFloat64T, "", new max_handler());
fred.add_user_field("flnk1", iocStringT, "recordA", new flnk_handler());
fred.add_user_field("flnk2", iocStringT, "recordB", new flnk_handler());
fred.add_user_field("flnk3", iocStringT, "recordC", new flnk_handler());
//
fred.iocInit();
//
fred.process();
cout << "\n";
fred.process();

return 0;
}

/*
When run, this basically processes the record and the
code for the user-defined fields is invoked as intended:

record::iocInit(fred)
record::process(fred)
Smoothing by 0.5
Max is 0
FLNKing to recordA
FLNKing to recordB
FLNKing to recordC

record::process(fred)
Smoothing by 0.5
Max is 0
FLNKing to recordA
FLNKing to recordB
FLNKing to recordC

UNCLEAR:
Is string parm enough, or are structs requires?

I believe that all the goals 1-7 can be handled
by providing the appropriate hooks.
Question: How many hooks will that be?

*/

== Comments ==
The example code for user_field_handler::init()
assumes that the record has
a routine get_field_addr(string name) that provides a raw pointer
to each field of a record. Would have to use dataAccess or whatever the
runtime database will ultimately provide.

Some pro and cons when comparing this type of user-defined field to writing a custom record:

=== Pro ===
* One can add fields per record instance as needed. No need to create a possibly confusing plethora of specialized record types: BasicAI, MaxAI, AverageAI, AverageAndMaxAI, BasicAO, MaxAO, ...
* Under vxWorks, one can do so without recompilation:
ld <smoo_handlerLib.o
dbLoadDataBase("..../records_that_use_smoo_handler")

=== Contra ===
* The actions inside a user-field handler are limited to quick, synchronous actions.
* In order to handle the goals mentioned in example.cpp, only two hooks into the record's process() routine are needed. Unclear if this is sufficient in the long run.
* While easy to use, the code requires more runtime checks, more type casts, more boilerplate code. For example, the smoo_handler should react accordingly if the record does not have a numeric value field. In a custom record type, compile-time checks would reduce the code size and increase maintainabililty.

V4 CA Client User Interface

2005-07-14T20:36:39Z

KayKasemir: /* Data Access */

== Channel Access Client User Interface ==
Under V4, a ProcessVariable would no longer be limited
to the current properties 'value', 'units', ... but allow the users to create
CA servers and clients that understand new properties.

The low-level V4 CA client API is likely to be rather complex because it
now needs to handle arbitrary property catalogs.
* There still needs to be an easy to use high-level API, not much more complex than the existing one.
* There needs to be access to CA from languages like Matlab in a way that's as easy as
pv = caopen('fred');
value = caget(pv);

== Food for thought ==
Is there anything we can learn from other communication libraries?
* A brief look at [[ZeroC ICE]]

== Constraints ==
* Initial implementation will be in C++
* Should very easily translate into Java, just like e.g. some XML APIs use the exact same classes and methods in C++ and Java. Ideally, Java and C++ version will be available from the start.
* Ideally, the C++ headers would be simple enough to be parsed by SWIG and hence perl/tcl/python/... glue code could be auto-generated via SWIG
* API is of course specific to EPICS CA, but ideally it'll also be usable as an interface to other protocols, so that EPICS Office can use an API that is only a slight extension of the CA client user API.

== Skeleton API ==
What follows is in the form of pseudo classes and associated methods
that a CA client API should provide.

=== Directory ===
The directory is used to discover available channels and map them to the CA Server address and port.
* Directory(string URL-type-server-address = "") Constructor; uses site-specific default server or specific one. The 'URL' might contain a user & password, which decides if this name server connection is read-only (for OPI clients) or if writes are allowed (for IOCs that add PVs to the name server).
* getChannelInfo(string PV_or_pattern) Returns list of
** CA server - IP & port of server that has the PV
** quality - is this the IOC, a gateway, backup/primary
* addChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to register their PV in directory
* deleteChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to remove their PV from directory

There is a default directory, available via something like "EPICSDefaults::getDirectory()" and "...setDirectory()".
The implementation could use
* LDAP
* Broadcast (as before)
* your custom implementation as long as it uses the above interface and registers itself as the default.

Note that Ben argues to hide the directory lookup from the CA client us
er.
See separate [[V4 Name Server]] wiki for the issue of "record" and "PV" information.

=== Data ===
All the data is accessed via DataAccess, which handles the introspection
of arbitrary data types. The existing dataAccess interface is based on
a visitor pattern. The user cannot list the available properties nor pick
a selected property. Instead, the user can request complete traversal
or a callback for a specific property.

This might be the most efficient implementation, but not necessarily
the one that's easiest to understand. The user interface to dataAccess
should thus also provide the following convenience routines:
* list<string> getProperties() Get a list of all the properties
* type_info getType(string property)
* bool hasWriteAccess(string property)
* string getAsString(string property)

Marty has a more complete idea, where a proterty catalog converts strings to IDs
and then those are actually used to access the data:

struct Property {
epicsInt32 id;
dbfType type;
void *pdbf;
};
interface PropertyViewer {
Property *getFirst();
Property *getNext(Property &);
Property *get(epicsInt32 id);
}
interface PropertyCatalogManager {
epicsInt32 getId(EpicsString &);
EpicsString *getName(epicsInt32 id);
epicsInt32 createId(EpicsString &);
};

In the following, each method that uses the property name
will need a twin that uses the ID or Property *.

=== Channel ===
* Channel(string name, Directory dir = default) Constructor. Channel has to have a name. Uses the 'best' channel from the default directory or from a given directory.
* Channel(string name, CASInfo) ... in case you want a specific server after querying the directory yourself or not using a directory at all.
* getName() Returns the name of the channel.
* addListener(Listener l), removeListener(Listener l) Register for notifications, see below.
* getProperties() A read or subscription will return a dataAccess interface to the retrieved data. That might exclude properties that this client cannot access. It will include the data, which might be huge. This separate call will only get property information, no data, for all properties, including read/write access information. The result could be in the form of dataAccess, except all access to actual data yields empty results, only the property-info related part of dataAccess is functional.

Note that Ben suggests that the CA client library should select the CA server automatically by querying a server or via broadcasts; it should also pick amongst competing PVs of the same name without user interaction.

Note also that in order to read or write, one needs to know what properties to access.
Does the channel magically provide a list of all properties?
Is there a "get all properties" request that reads them on-demand
from the CA server?
Or does the directory hold the list of available properties and their types?

=== Channel: Listener ===
The Channel::Listener interface is invoked in response to the many asynchronous methods of the Channel.
* writeComplete(Channel ch)
** Channel that send this notification
* newData(Channel ch, DataAccess data, Event why)
** DataAccess interface to the data
** Reason for the update: Value deadband exceeded, minimum period expired, event 'blue beam', ...
* accessRightChange(Channel ch)

Alternatively, these could be separate interfaces for a writeListener, dataListener, stateListener.

=== Channel: State ===
In contrast to the V3 API, the user doesn't 'connect'.
The first data notification implies that we're connected.

* bool isConnected() .. for those who want to poll
* xxx getServerInfo(), xxx getType() .. only valid when isConnected().
* setUser(), ... Sets/changes the 'user' that determines the access rights, allowing OPI tools to adjust this per-channel at runtime. To avoid security issues, setUser will probably send a public key and not a user name and password.

=== Channel: Writing ===
* write(new value) Sends the value to the server.
* createWriteRequest(new value, receipt {delivery, completion, response}) Sends the value to the server, invokes Listener when CA server has received the value (delivery) or all the processing triggered by the new value has completed (completion). In addition, some records might support command/response, in which case one can write a command and wait for a response callback which looks just like the result of a read request.
* scheduleWriteRequest(new value, event) Sends the value to the server, which will perform the write when the given event fires. Invokes Listener when CA server has performed the write.

=== Channel: Reading ===
* createSubscription(list<string> properties, Event e) Will invoke Listener once data arrives.
* cancelSubscription(....) Use properties & event or an ID returned from createSubscription?

Event is a class that allows the user to select what triggers an update:
* useDefaultValueDeadband() Default if nothing else is called.
* setValueDeadband(double change)
* setPercentageDeadband(double percent)
* setLogarithmicDeadband(double exponent_of_ten)
* setMinimumRate(double seconds) There will be notifications at at least this rate, even if value didn't change.
* setMaximumRate(double vals_per_second)
* useAlarmConditionChange()
* useHardwareEvent(int event_id) Somehow, event_id might be linked to 'Blue Beam'
* setMaxValueCount Setting this to '1' turns the subscription into a single-value 'get'.

Unclear how to present the Event to a user. For example, how would a 'camonitor' tool allow the user to select the events? Via 20 command-line switches, or should there be a syntax ala
"valueDeadband=1.0, maximumRate=20" which is supported by methods
* string toString()
* bood fromString(string event_specification)

=== ChannelGroup ===
A channel group synchronizes access to multiple channels.
It listens to all members of the channel group and for example
allows waiting for ''all'' outstanding read or write requests
to return.

* add/remove channels By name? Already existing Channel? Add channels that match a pattern, or go via the directory?
* read/write Has to handle reading/writing the same properties from all channels in group. Also channel-specific list of properties?

=== SyncChannel ===
A wrapper class around the async. Channel.
Uses a configurable timeout and provides synchronous 'read'.

* Inherits from Channel.
* double getTimeout(), void setTimeout(double seconds)
* DataAccess read(list<string> properties) Synchronous read of current values of properties.
* DataAccess read(string property) Synchronous read of current value of one property.

=== Container ===
The Channel does not store any data.
When attaching a container to a channel, the container will subscribe
to the channel and keep a copy of all data, so one can always ask
the container for the current values.
* attach(channel)
* detach()
* implements the DataAccess interface to allow access to the data.

Also see [[V4 Data Store]]

== caget 101 ==
This is how a simple 'caget' could be written:

SyncChannel channel("fred");
DataAccess da = channel.read("value");
cout << "Value of " << channel.getName() << " : " << da.getAsString("value") << "\n";

We can imagine an even simpler example:

cout << "Value of fred:" << Epics::get("fred") << "\n";

This implies lots of work under the hood, with reasonable defaults.

== camonitor 101 ==
This is the goal for a 'camonitor':

class MyMonitor : public Channel::Listener
{
public:
newData(Channel ch, DataAccess data, Event why)
{
cout << channel.getName() << " = " << da.getAsString("value") << "\n";
}
};
...
Channel channel("fred");
list<string> properties;
properties.push_back("value");
Event e;
e. setMaximumRate(10.0);
channel.createSubscription(properties, e);

V4 CA Client User Interface

2005-07-14T20:19:17Z

KayKasemir: /* Channel: Writing */

== Channel Access Client User Interface ==
Under V4, a ProcessVariable would no longer be limited
to the current properties 'value', 'units', ... but allow the users to create
CA servers and clients that understand new properties.

The low-level V4 CA client API is likely to be rather complex because it
now needs to handle arbitrary property catalogs.
* There still needs to be an easy to use high-level API, not much more complex than the existing one.
* There needs to be access to CA from languages like Matlab in a way that's as easy as
pv = caopen('fred');
value = caget(pv);

== Food for thought ==
Is there anything we can learn from other communication libraries?
* A brief look at [[ZeroC ICE]]

== Constraints ==
* Initial implementation will be in C++
* Should very easily translate into Java, just like e.g. some XML APIs use the exact same classes and methods in C++ and Java. Ideally, Java and C++ version will be available from the start.
* Ideally, the C++ headers would be simple enough to be parsed by SWIG and hence perl/tcl/python/... glue code could be auto-generated via SWIG
* API is of course specific to EPICS CA, but ideally it'll also be usable as an interface to other protocols, so that EPICS Office can use an API that is only a slight extension of the CA client user API.

== Skeleton API ==
What follows is in the form of pseudo classes and associated methods
that a CA client API should provide.

=== Directory ===
The directory is used to discover available channels and map them to the CA Server address and port.
* Directory(string URL-type-server-address = "") Constructor; uses site-specific default server or specific one. The 'URL' might contain a user & password, which decides if this name server connection is read-only (for OPI clients) or if writes are allowed (for IOCs that add PVs to the name server).
* getChannelInfo(string PV_or_pattern) Returns list of
** CA server - IP & port of server that has the PV
** quality - is this the IOC, a gateway, backup/primary
* addChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to register their PV in directory
* deleteChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to remove their PV from directory

There is a default directory, available via something like "EPICSDefaults::getDirectory()" and "...setDirectory()".
The implementation could use
* LDAP
* Broadcast (as before)
* your custom implementation as long as it uses the above interface and registers itself as the default.

Note that Ben argues to hide the directory lookup from the CA client us
er.
See separate [[V4 Name Server]] wiki for the issue of "record" and "PV" information.

=== Data Access ===
All the data is accessed via DataAccess, which handles the introspection
of arbitrary data types. It should provide the following convenience
routines in addition to whatever more efficient methods it might have
(using hash IDs instead property name string etc.):
* list<string> getProperties() Get a list of all the properties
* type_info getType(string property)
* bool hasWriteAccess(string property)
* string getAsString(string property)

Marty has a more complete idea, where a proterty catalog converts strings to IDs
and then those are actually used to access the data:

struct Property {
epicsInt32 id;
dbfType type;
void *pdbf;
};
interface PropertyViewer {
Property *getFirst();
Property *getNext(Property &);
Property *get(epicsInt32 id);
}
interface PropertyCatalogManager {
epicsInt32 getId(EpicsString &);
EpicsString *getName(epicsInt32 id);
epicsInt32 createId(EpicsString &);
};

In the following, each method that uses the property name
will need a twin that uses the ID or Property *.

=== Channel ===
* Channel(string name, Directory dir = default) Constructor. Channel has to have a name. Uses the 'best' channel from the default directory or from a given directory.
* Channel(string name, CASInfo) ... in case you want a specific server after querying the directory yourself or not using a directory at all.
* getName() Returns the name of the channel.
* addListener(Listener l), removeListener(Listener l) Register for notifications, see below.
* getProperties() A read or subscription will return a dataAccess interface to the retrieved data. That might exclude properties that this client cannot access. It will include the data, which might be huge. This separate call will only get property information, no data, for all properties, including read/write access information. The result could be in the form of dataAccess, except all access to actual data yields empty results, only the property-info related part of dataAccess is functional.

Note that Ben suggests that the CA client library should select the CA server automatically by querying a server or via broadcasts; it should also pick amongst competing PVs of the same name without user interaction.

Note also that in order to read or write, one needs to know what properties to access.
Does the channel magically provide a list of all properties?
Is there a "get all properties" request that reads them on-demand
from the CA server?
Or does the directory hold the list of available properties and their types?

=== Channel: Listener ===
The Channel::Listener interface is invoked in response to the many asynchronous methods of the Channel.
* writeComplete(Channel ch)
** Channel that send this notification
* newData(Channel ch, DataAccess data, Event why)
** DataAccess interface to the data
** Reason for the update: Value deadband exceeded, minimum period expired, event 'blue beam', ...
* accessRightChange(Channel ch)

Alternatively, these could be separate interfaces for a writeListener, dataListener, stateListener.

=== Channel: State ===
In contrast to the V3 API, the user doesn't 'connect'.
The first data notification implies that we're connected.

* bool isConnected() .. for those who want to poll
* xxx getServerInfo(), xxx getType() .. only valid when isConnected().
* setUser(), ... Sets/changes the 'user' that determines the access rights, allowing OPI tools to adjust this per-channel at runtime. To avoid security issues, setUser will probably send a public key and not a user name and password.

=== Channel: Writing ===
* write(new value) Sends the value to the server.
* createWriteRequest(new value, receipt {delivery, completion, response}) Sends the value to the server, invokes Listener when CA server has received the value (delivery) or all the processing triggered by the new value has completed (completion). In addition, some records might support command/response, in which case one can write a command and wait for a response callback which looks just like the result of a read request.
* scheduleWriteRequest(new value, event) Sends the value to the server, which will perform the write when the given event fires. Invokes Listener when CA server has performed the write.

=== Channel: Reading ===
* createSubscription(list<string> properties, Event e) Will invoke Listener once data arrives.
* cancelSubscription(....) Use properties & event or an ID returned from createSubscription?

Event is a class that allows the user to select what triggers an update:
* useDefaultValueDeadband() Default if nothing else is called.
* setValueDeadband(double change)
* setPercentageDeadband(double percent)
* setLogarithmicDeadband(double exponent_of_ten)
* setMinimumRate(double seconds) There will be notifications at at least this rate, even if value didn't change.
* setMaximumRate(double vals_per_second)
* useAlarmConditionChange()
* useHardwareEvent(int event_id) Somehow, event_id might be linked to 'Blue Beam'
* setMaxValueCount Setting this to '1' turns the subscription into a single-value 'get'.

Unclear how to present the Event to a user. For example, how would a 'camonitor' tool allow the user to select the events? Via 20 command-line switches, or should there be a syntax ala
"valueDeadband=1.0, maximumRate=20" which is supported by methods
* string toString()
* bood fromString(string event_specification)

=== ChannelGroup ===
A channel group synchronizes access to multiple channels.
It listens to all members of the channel group and for example
allows waiting for ''all'' outstanding read or write requests
to return.

* add/remove channels By name? Already existing Channel? Add channels that match a pattern, or go via the directory?
* read/write Has to handle reading/writing the same properties from all channels in group. Also channel-specific list of properties?

=== SyncChannel ===
A wrapper class around the async. Channel.
Uses a configurable timeout and provides synchronous 'read'.

* Inherits from Channel.
* double getTimeout(), void setTimeout(double seconds)
* DataAccess read(list<string> properties) Synchronous read of current values of properties.
* DataAccess read(string property) Synchronous read of current value of one property.

=== Container ===
The Channel does not store any data.
When attaching a container to a channel, the container will subscribe
to the channel and keep a copy of all data, so one can always ask
the container for the current values.
* attach(channel)
* detach()
* implements the DataAccess interface to allow access to the data.

Also see [[V4 Data Store]]

== caget 101 ==
This is how a simple 'caget' could be written:

SyncChannel channel("fred");
DataAccess da = channel.read("value");
cout << "Value of " << channel.getName() << " : " << da.getAsString("value") << "\n";

We can imagine an even simpler example:

cout << "Value of fred:" << Epics::get("fred") << "\n";

This implies lots of work under the hood, with reasonable defaults.

== camonitor 101 ==
This is the goal for a 'camonitor':

class MyMonitor : public Channel::Listener
{
public:
newData(Channel ch, DataAccess data, Event why)
{
cout << channel.getName() << " = " << da.getAsString("value") << "\n";
}
};
...
Channel channel("fred");
list<string> properties;
properties.push_back("value");
Event e;
e. setMaximumRate(10.0);
channel.createSubscription(properties, e);

V4 CA Client User Interface

2005-07-14T17:52:24Z

KayKasemir:

== Channel Access Client User Interface ==
Under V4, a ProcessVariable would no longer be limited
to the current properties 'value', 'units', ... but allow the users to create
CA servers and clients that understand new properties.

The low-level V4 CA client API is likely to be rather complex because it
now needs to handle arbitrary property catalogs.
* There still needs to be an easy to use high-level API, not much more complex than the existing one.
* There needs to be access to CA from languages like Matlab in a way that's as easy as
pv = caopen('fred');
value = caget(pv);

== Food for thought ==
Is there anything we can learn from other communication libraries?
* A brief look at [[ZeroC ICE]]

== Constraints ==
* Initial implementation will be in C++
* Should very easily translate into Java, just like e.g. some XML APIs use the exact same classes and methods in C++ and Java. Ideally, Java and C++ version will be available from the start.
* Ideally, the C++ headers would be simple enough to be parsed by SWIG and hence perl/tcl/python/... glue code could be auto-generated via SWIG
* API is of course specific to EPICS CA, but ideally it'll also be usable as an interface to other protocols, so that EPICS Office can use an API that is only a slight extension of the CA client user API.

== Skeleton API ==
What follows is in the form of pseudo classes and associated methods
that a CA client API should provide.

=== Directory ===
The directory is used to discover available channels and map them to the CA Server address and port.
* Directory(string URL-type-server-address = "") Constructor; uses site-specific default server or specific one. The 'URL' might contain a user & password, which decides if this name server connection is read-only (for OPI clients) or if writes are allowed (for IOCs that add PVs to the name server).
* getChannelInfo(string PV_or_pattern) Returns list of
** CA server - IP & port of server that has the PV
** quality - is this the IOC, a gateway, backup/primary
* addChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to register their PV in directory
* deleteChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to remove their PV from directory

There is a default directory, available via something like "EPICSDefaults::getDirectory()" and "...setDirectory()".
The implementation could use
* LDAP
* Broadcast (as before)
* your custom implementation as long as it uses the above interface and registers itself as the default.

Note that Ben argues to hide the directory lookup from the CA client us
er.
See separate [[V4 Name Server]] wiki for the issue of "record" and "PV" information.

=== Data Access ===
All the data is accessed via DataAccess, which handles the introspection
of arbitrary data types. It should provide the following convenience
routines in addition to whatever more efficient methods it might have
(using hash IDs instead property name string etc.):
* list<string> getProperties() Get a list of all the properties
* type_info getType(string property)
* bool hasWriteAccess(string property)
* string getAsString(string property)

Marty has a more complete idea, where a proterty catalog converts strings to IDs
and then those are actually used to access the data:

struct Property {
epicsInt32 id;
dbfType type;
void *pdbf;
};
interface PropertyViewer {
Property *getFirst();
Property *getNext(Property &);
Property *get(epicsInt32 id);
}
interface PropertyCatalogManager {
epicsInt32 getId(EpicsString &);
EpicsString *getName(epicsInt32 id);
epicsInt32 createId(EpicsString &);
};

In the following, each method that uses the property name
will need a twin that uses the ID or Property *.

=== Channel ===
* Channel(string name, Directory dir = default) Constructor. Channel has to have a name. Uses the 'best' channel from the default directory or from a given directory.
* Channel(string name, CASInfo) ... in case you want a specific server after querying the directory yourself or not using a directory at all.
* getName() Returns the name of the channel.
* addListener(Listener l), removeListener(Listener l) Register for notifications, see below.
* getProperties() A read or subscription will return a dataAccess interface to the retrieved data. That might exclude properties that this client cannot access. It will include the data, which might be huge. This separate call will only get property information, no data, for all properties, including read/write access information. The result could be in the form of dataAccess, except all access to actual data yields empty results, only the property-info related part of dataAccess is functional.

Note that Ben suggests that the CA client library should select the CA server automatically by querying a server or via broadcasts; it should also pick amongst competing PVs of the same name without user interaction.

Note also that in order to read or write, one needs to know what properties to access.
Does the channel magically provide a list of all properties?
Is there a "get all properties" request that reads them on-demand
from the CA server?
Or does the directory hold the list of available properties and their types?

=== Channel: Listener ===
The Channel::Listener interface is invoked in response to the many asynchronous methods of the Channel.
* writeComplete(Channel ch)
** Channel that send this notification
* newData(Channel ch, DataAccess data, Event why)
** DataAccess interface to the data
** Reason for the update: Value deadband exceeded, minimum period expired, event 'blue beam', ...
* accessRightChange(Channel ch)

Alternatively, these could be separate interfaces for a writeListener, dataListener, stateListener.

=== Channel: State ===
In contrast to the V3 API, the user doesn't 'connect'.
The first data notification implies that we're connected.

* bool isConnected() .. for those who want to poll
* xxx getServerInfo(), xxx getType() .. only valid when isConnected().
* setUser(), ... Sets/changes the 'user' that determines the access rights, allowing OPI tools to adjust this per-channel at runtime. To avoid security issues, setUser will probably send a public key and not a user name and password.

=== Channel: Writing ===
* write(new value) Sends the value to the server.
* createWriteRequest(new value, receipt {delivery, completion}) Sends the value to the server, invokes Listener when CA server has received the value respectively all the processing triggered by the new value has completed.
* scheduleWriteRequest(new value, event) Sends the value to the server, which will perform the write when the given event fires. Invokes Listener when CA server has performed the write.

=== Channel: Reading ===
* createSubscription(list<string> properties, Event e) Will invoke Listener once data arrives.
* cancelSubscription(....) Use properties & event or an ID returned from createSubscription?

Event is a class that allows the user to select what triggers an update:
* useDefaultValueDeadband() Default if nothing else is called.
* setValueDeadband(double change)
* setPercentageDeadband(double percent)
* setLogarithmicDeadband(double exponent_of_ten)
* setMinimumRate(double seconds) There will be notifications at at least this rate, even if value didn't change.
* setMaximumRate(double vals_per_second)
* useAlarmConditionChange()
* useHardwareEvent(int event_id) Somehow, event_id might be linked to 'Blue Beam'
* setMaxValueCount Setting this to '1' turns the subscription into a single-value 'get'.

Unclear how to present the Event to a user. For example, how would a 'camonitor' tool allow the user to select the events? Via 20 command-line switches, or should there be a syntax ala
"valueDeadband=1.0, maximumRate=20" which is supported by methods
* string toString()
* bood fromString(string event_specification)

=== ChannelGroup ===
A channel group synchronizes access to multiple channels.
It listens to all members of the channel group and for example
allows waiting for ''all'' outstanding read or write requests
to return.

* add/remove channels By name? Already existing Channel? Add channels that match a pattern, or go via the directory?
* read/write Has to handle reading/writing the same properties from all channels in group. Also channel-specific list of properties?

=== SyncChannel ===
A wrapper class around the async. Channel.
Uses a configurable timeout and provides synchronous 'read'.

* Inherits from Channel.
* double getTimeout(), void setTimeout(double seconds)
* DataAccess read(list<string> properties) Synchronous read of current values of properties.
* DataAccess read(string property) Synchronous read of current value of one property.

=== Container ===
The Channel does not store any data.
When attaching a container to a channel, the container will subscribe
to the channel and keep a copy of all data, so one can always ask
the container for the current values.
* attach(channel)
* detach()
* implements the DataAccess interface to allow access to the data.

Also see [[V4 Data Store]]

== caget 101 ==
This is how a simple 'caget' could be written:

SyncChannel channel("fred");
DataAccess da = channel.read("value");
cout << "Value of " << channel.getName() << " : " << da.getAsString("value") << "\n";

We can imagine an even simpler example:

cout << "Value of fred:" << Epics::get("fred") << "\n";

This implies lots of work under the hood, with reasonable defaults.

== camonitor 101 ==
This is the goal for a 'camonitor':

class MyMonitor : public Channel::Listener
{
public:
newData(Channel ch, DataAccess data, Event why)
{
cout << channel.getName() << " = " << da.getAsString("value") << "\n";
}
};
...
Channel channel("fred");
list<string> properties;
properties.push_back("value");
Event e;
e. setMaximumRate(10.0);
channel.createSubscription(properties, e);

V4 CA Client User Interface

2005-07-14T17:50:35Z

KayKasemir: Constraints

== Channel Access Client User Interface ==
Under V4, a ProcessVariable would no longer be limited
to the current properties 'value', 'units', ... but allow the users to create
CA servers and clients that understand new properties.

The low-level V4 CA client API is likely to be rather complex because it
now needs to handle arbitrary property catalogs.
* There still needs to be an easy to use high-level API, not much more complex than the existing one.
* There needs to be access to CA from languages like Matlab in a way that's as easy as
pv = caopen('fred');
value = caget(pv);

== Food for thought ==
Is there anything we can learn from other communication libraries?
* A brief look at [[ZeroC ICE]]

== Constraints ==
* Initial implementation will be in C++
* Should very easily translate into Java, just like e.g. some XML APIs use the exact same classes and methods in C++ and Java. Ideally, Java and C++ version will be available from the start.
* Ideally, the C++ headers would be simple enough to be parsed by SWIG and hence perl/tcl/python/... glue code could be auto-generated via SWIG

== Constraints ==
* Initial implementation will be in C++
* Should very easily translate into Java, just like e.g. some XML APIs use the exact same classes and methods in C++ and Java. Ideally, Java and C++ version will be available from the start.
* Ideally, the C++ headers would be simple enough to be parsed by SWIG and hence perl/tcl/python/... glue code could be auto-generated via SWIG

== Skeleton API ==
What follows is in the form of pseudo classes and associated methods
that a CA client API should provide.

=== Directory ===
The directory is used to discover available channels and map them to the CA Server address and port.
* Directory(string URL-type-server-address = "") Constructor; uses site-specific default server or specific one. The 'URL' might contain a user & password, which decides if this name server connection is read-only (for OPI clients) or if writes are allowed (for IOCs that add PVs to the name server).
* getChannelInfo(string PV_or_pattern) Returns list of
** CA server - IP & port of server that has the PV
** quality - is this the IOC, a gateway, backup/primary
* addChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to register their PV in directory
* deleteChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to remove their PV from directory

There is a default directory, available via something like "EPICSDefaults::getDirectory()" and "...setDirectory()".
The implementation could use
* LDAP
* Broadcast (as before)
* your custom implementation as long as it uses the above interface and registers itself as the default.

Note that Ben argues to hide the directory lookup from the CA client us
er.
See separate [[V4 Name Server]] wiki for the issue of "record" and "PV" information.

=== Data Access ===
All the data is accessed via DataAccess, which handles the introspection
of arbitrary data types. It should provide the following convenience
routines in addition to whatever more efficient methods it might have
(using hash IDs instead property name string etc.):
* list<string> getProperties() Get a list of all the properties
* type_info getType(string property)
* bool hasWriteAccess(string property)
* string getAsString(string property)

Marty has a more complete idea, where a proterty catalog converts strings to IDs
and then those are actually used to access the data:

struct Property {
epicsInt32 id;
dbfType type;
void *pdbf;
};
interface PropertyViewer {
Property *getFirst();
Property *getNext(Property &);
Property *get(epicsInt32 id);
}
interface PropertyCatalogManager {
epicsInt32 getId(EpicsString &);
EpicsString *getName(epicsInt32 id);
epicsInt32 createId(EpicsString &);
};

In the following, each method that uses the property name
will need a twin that uses the ID or Property *.

=== Channel ===
* Channel(string name, Directory dir = default) Constructor. Channel has to have a name. Uses the 'best' channel from the default directory or from a given directory.
* Channel(string name, CASInfo) ... in case you want a specific server after querying the directory yourself or not using a directory at all.
* getName() Returns the name of the channel.
* addListener(Listener l), removeListener(Listener l) Register for notifications, see below.
* getProperties() A read or subscription will return a dataAccess interface to the retrieved data. That might exclude properties that this client cannot access. It will include the data, which might be huge. This separate call will only get property information, no data, for all properties, including read/write access information. The result could be in the form of dataAccess, except all access to actual data yields empty results, only the property-info related part of dataAccess is functional.

Note that Ben suggests that the CA client library should select the CA server automatically by querying a server or via broadcasts; it should also pick amongst competing PVs of the same name without user interaction.

Note also that in order to read or write, one needs to know what properties to access.
Does the channel magically provide a list of all properties?
Is there a "get all properties" request that reads them on-demand
from the CA server?
Or does the directory hold the list of available properties and their types?

=== Channel: Listener ===
The Channel::Listener interface is invoked in response to the many asynchronous methods of the Channel.
* writeComplete(Channel ch)
** Channel that send this notification
* newData(Channel ch, DataAccess data, Event why)
** DataAccess interface to the data
** Reason for the update: Value deadband exceeded, minimum period expired, event 'blue beam', ...
* accessRightChange(Channel ch)

Alternatively, these could be separate interfaces for a writeListener, dataListener, stateListener.

=== Channel: State ===
In contrast to the V3 API, the user doesn't 'connect'.
The first data notification implies that we're connected.

* bool isConnected() .. for those who want to poll
* xxx getServerInfo(), xxx getType() .. only valid when isConnected().
* setUser(), ... Sets/changes the 'user' that determines the access rights, allowing OPI tools to adjust this per-channel at runtime. To avoid security issues, setUser will probably send a public key and not a user name and password.

=== Channel: Writing ===
* write(new value) Sends the value to the server.
* createWriteRequest(new value, receipt {delivery, completion}) Sends the value to the server, invokes Listener when CA server has received the value respectively all the processing triggered by the new value has completed.
* scheduleWriteRequest(new value, event) Sends the value to the server, which will perform the write when the given event fires. Invokes Listener when CA server has performed the write.

=== Channel: Reading ===
* createSubscription(list<string> properties, Event e) Will invoke Listener once data arrives.
* cancelSubscription(....) Use properties & event or an ID returned from createSubscription?

Event is a class that allows the user to select what triggers an update:
* useDefaultValueDeadband() Default if nothing else is called.
* setValueDeadband(double change)
* setPercentageDeadband(double percent)
* setLogarithmicDeadband(double exponent_of_ten)
* setMinimumRate(double seconds) There will be notifications at at least this rate, even if value didn't change.
* setMaximumRate(double vals_per_second)
* useAlarmConditionChange()
* useHardwareEvent(int event_id) Somehow, event_id might be linked to 'Blue Beam'
* setMaxValueCount Setting this to '1' turns the subscription into a single-value 'get'.

Unclear how to present the Event to a user. For example, how would a 'camonitor' tool allow the user to select the events? Via 20 command-line switches, or should there be a syntax ala
"valueDeadband=1.0, maximumRate=20" which is supported by methods
* string toString()
* bood fromString(string event_specification)

=== ChannelGroup ===
A channel group synchronizes access to multiple channels.
It listens to all members of the channel group and for example
allows waiting for ''all'' outstanding read or write requests
to return.

* add/remove channels By name? Already existing Channel? Add channels that match a pattern, or go via the directory?
* read/write Has to handle reading/writing the same properties from all channels in group. Also channel-specific list of properties?

=== SyncChannel ===
A wrapper class around the async. Channel.
Uses a configurable timeout and provides synchronous 'read'.

* Inherits from Channel.
* double getTimeout(), void setTimeout(double seconds)
* DataAccess read(list<string> properties) Synchronous read of current values of properties.
* DataAccess read(string property) Synchronous read of current value of one property.

=== Container ===
The Channel does not store any data.
When attaching a container to a channel, the container will subscribe
to the channel and keep a copy of all data, so one can always ask
the container for the current values.
* attach(channel)
* detach()
* implements the DataAccess interface to allow access to the data.

Also see [[V4 Data Store]]

== caget 101 ==
This is how a simple 'caget' could be written:

SyncChannel channel("fred");
DataAccess da = channel.read("value");
cout << "Value of " << channel.getName() << " : " << da.getAsString("value") << "\n";

We can imagine an even simpler example:

cout << "Value of fred:" << Epics::get("fred") << "\n";

This implies lots of work under the hood, with reasonable defaults.

== camonitor 101 ==
This is the goal for a 'camonitor':

class MyMonitor : public Channel::Listener
{
public:
newData(Channel ch, DataAccess data, Event why)
{
cout << channel.getName() << " = " << da.getAsString("value") << "\n";
}
};
...
Channel channel("fred");
list<string> properties;
properties.push_back("value");
Event e;
e. setMaximumRate(10.0);
channel.createSubscription(properties, e);

V4 CA Client User Interface

2005-07-14T17:50:30Z

KayKasemir: Constraints

== Channel Access Client User Interface ==
Under V4, a ProcessVariable would no longer be limited
to the current properties 'value', 'units', ... but allow the users to create
CA servers and clients that understand new properties.

The low-level V4 CA client API is likely to be rather complex because it
now needs to handle arbitrary property catalogs.
* There still needs to be an easy to use high-level API, not much more complex than the existing one.
* There needs to be access to CA from languages like Matlab in a way that's as easy as
pv = caopen('fred');
value = caget(pv);

== Food for thought ==
Is there anything we can learn from other communication libraries?
* A brief look at [[ZeroC ICE]]

== Constraints ==
* Initial implementation will be in C++
* Should very easily translate into Java, just like e.g. some XML APIs use the exact same classes and methods in C++ and Java. Ideally, Java and C++ version will be available from the start.
* Ideally, the C++ headers would be simple enough to be parsed by SWIG and hence perl/tcl/python/... glue code could be auto-generated via SWIG

== Skeleton API ==
What follows is in the form of pseudo classes and associated methods
that a CA client API should provide.

=== Directory ===
The directory is used to discover available channels and map them to the CA Server address and port.
* Directory(string URL-type-server-address = "") Constructor; uses site-specific default server or specific one. The 'URL' might contain a user & password, which decides if this name server connection is read-only (for OPI clients) or if writes are allowed (for IOCs that add PVs to the name server).
* getChannelInfo(string PV_or_pattern) Returns list of
** CA server - IP & port of server that has the PV
** quality - is this the IOC, a gateway, backup/primary
* addChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to register their PV in directory
* deleteChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to remove their PV from directory

There is a default directory, available via something like "EPICSDefaults::getDirectory()" and "...setDirectory()".
The implementation could use
* LDAP
* Broadcast (as before)
* your custom implementation as long as it uses the above interface and registers itself as the default.

Note that Ben argues to hide the directory lookup from the CA client us
er.
See separate [[V4 Name Server]] wiki for the issue of "record" and "PV" information.

=== Data Access ===
All the data is accessed via DataAccess, which handles the introspection
of arbitrary data types. It should provide the following convenience
routines in addition to whatever more efficient methods it might have
(using hash IDs instead property name string etc.):
* list<string> getProperties() Get a list of all the properties
* type_info getType(string property)
* bool hasWriteAccess(string property)
* string getAsString(string property)

Marty has a more complete idea, where a proterty catalog converts strings to IDs
and then those are actually used to access the data:

struct Property {
epicsInt32 id;
dbfType type;
void *pdbf;
};
interface PropertyViewer {
Property *getFirst();
Property *getNext(Property &);
Property *get(epicsInt32 id);
}
interface PropertyCatalogManager {
epicsInt32 getId(EpicsString &);
EpicsString *getName(epicsInt32 id);
epicsInt32 createId(EpicsString &);
};

In the following, each method that uses the property name
will need a twin that uses the ID or Property *.

=== Channel ===
* Channel(string name, Directory dir = default) Constructor. Channel has to have a name. Uses the 'best' channel from the default directory or from a given directory.
* Channel(string name, CASInfo) ... in case you want a specific server after querying the directory yourself or not using a directory at all.
* getName() Returns the name of the channel.
* addListener(Listener l), removeListener(Listener l) Register for notifications, see below.
* getProperties() A read or subscription will return a dataAccess interface to the retrieved data. That might exclude properties that this client cannot access. It will include the data, which might be huge. This separate call will only get property information, no data, for all properties, including read/write access information. The result could be in the form of dataAccess, except all access to actual data yields empty results, only the property-info related part of dataAccess is functional.

Note that Ben suggests that the CA client library should select the CA server automatically by querying a server or via broadcasts; it should also pick amongst competing PVs of the same name without user interaction.

Note also that in order to read or write, one needs to know what properties to access.
Does the channel magically provide a list of all properties?
Is there a "get all properties" request that reads them on-demand
from the CA server?
Or does the directory hold the list of available properties and their types?

=== Channel: Listener ===
The Channel::Listener interface is invoked in response to the many asynchronous methods of the Channel.
* writeComplete(Channel ch)
** Channel that send this notification
* newData(Channel ch, DataAccess data, Event why)
** DataAccess interface to the data
** Reason for the update: Value deadband exceeded, minimum period expired, event 'blue beam', ...
* accessRightChange(Channel ch)

Alternatively, these could be separate interfaces for a writeListener, dataListener, stateListener.

=== Channel: State ===
In contrast to the V3 API, the user doesn't 'connect'.
The first data notification implies that we're connected.

* bool isConnected() .. for those who want to poll
* xxx getServerInfo(), xxx getType() .. only valid when isConnected().
* setUser(), ... Sets/changes the 'user' that determines the access rights, allowing OPI tools to adjust this per-channel at runtime. To avoid security issues, setUser will probably send a public key and not a user name and password.

=== Channel: Writing ===
* write(new value) Sends the value to the server.
* createWriteRequest(new value, receipt {delivery, completion}) Sends the value to the server, invokes Listener when CA server has received the value respectively all the processing triggered by the new value has completed.
* scheduleWriteRequest(new value, event) Sends the value to the server, which will perform the write when the given event fires. Invokes Listener when CA server has performed the write.

=== Channel: Reading ===
* createSubscription(list<string> properties, Event e) Will invoke Listener once data arrives.
* cancelSubscription(....) Use properties & event or an ID returned from createSubscription?

Event is a class that allows the user to select what triggers an update:
* useDefaultValueDeadband() Default if nothing else is called.
* setValueDeadband(double change)
* setPercentageDeadband(double percent)
* setLogarithmicDeadband(double exponent_of_ten)
* setMinimumRate(double seconds) There will be notifications at at least this rate, even if value didn't change.
* setMaximumRate(double vals_per_second)
* useAlarmConditionChange()
* useHardwareEvent(int event_id) Somehow, event_id might be linked to 'Blue Beam'
* setMaxValueCount Setting this to '1' turns the subscription into a single-value 'get'.

Unclear how to present the Event to a user. For example, how would a 'camonitor' tool allow the user to select the events? Via 20 command-line switches, or should there be a syntax ala
"valueDeadband=1.0, maximumRate=20" which is supported by methods
* string toString()
* bood fromString(string event_specification)

=== ChannelGroup ===
A channel group synchronizes access to multiple channels.
It listens to all members of the channel group and for example
allows waiting for ''all'' outstanding read or write requests
to return.

* add/remove channels By name? Already existing Channel? Add channels that match a pattern, or go via the directory?
* read/write Has to handle reading/writing the same properties from all channels in group. Also channel-specific list of properties?

=== SyncChannel ===
A wrapper class around the async. Channel.
Uses a configurable timeout and provides synchronous 'read'.

* Inherits from Channel.
* double getTimeout(), void setTimeout(double seconds)
* DataAccess read(list<string> properties) Synchronous read of current values of properties.
* DataAccess read(string property) Synchronous read of current value of one property.

=== Container ===
The Channel does not store any data.
When attaching a container to a channel, the container will subscribe
to the channel and keep a copy of all data, so one can always ask
the container for the current values.
* attach(channel)
* detach()
* implements the DataAccess interface to allow access to the data.

Also see [[V4 Data Store]]

== caget 101 ==
This is how a simple 'caget' could be written:

SyncChannel channel("fred");
DataAccess da = channel.read("value");
cout << "Value of " << channel.getName() << " : " << da.getAsString("value") << "\n";

We can imagine an even simpler example:

cout << "Value of fred:" << Epics::get("fred") << "\n";

This implies lots of work under the hood, with reasonable defaults.

== camonitor 101 ==
This is the goal for a 'camonitor':

class MyMonitor : public Channel::Listener
{
public:
newData(Channel ch, DataAccess data, Event why)
{
cout << channel.getName() << " = " << da.getAsString("value") << "\n";
}
};
...
Channel channel("fred");
list<string> properties;
properties.push_back("value");
Event e;
e. setMaximumRate(10.0);
channel.createSubscription(properties, e);

V4 CA Client User Interface

2005-07-13T20:38:58Z

KayKasemir: /* ChannelGroup */

== Channel Access Client User Interface ==
Under V4, a ProcessVariable would no longer be limited
to the current properties 'value', 'units', ... but allow the users to create
CA servers and clients that understand new properties.

The low-level V4 CA client API is likely to be rather complex because it
now needs to handle arbitrary property catalogs.
* There still needs to be an easy to use high-level API, not much more complex than the existing one.
* There needs to be access to CA from languages like Matlab in a way that's as easy as
pv = caopen('fred');
value = caget(pv);

== Food for thought ==
Is there anything we can learn from other communication libraries?
* A brief look at [[ZeroC ICE]]

== Skeleton API ==
What follows is in the form of pseudo classes and associated methods
that a CA client API should provide.

=== Directory ===
The directory is used to discover available channels and map them to the CA Server address and port.
* Directory(string URL-type-server-address = "") Constructor; uses site-specific default server or specific one. The 'URL' might contain a user & password, which decides if this name server connection is read-only (for OPI clients) or if writes are allowed (for IOCs that add PVs to the name server).
* getChannelInfo(string PV_or_pattern) Returns list of
** CA server - IP & port of server that has the PV
** quality - is this the IOC, a gateway, backup/primary
* addChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to register their PV in directory
* deleteChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to remove their PV from directory

There is a default directory, available via something like "EPICSDefaults::getDirectory()" and "...setDirectory()".
The implementation could use
* LDAP
* Broadcast (as before)
* your custom implementation as long as it uses the above interface and registers itself as the default.

Note that Ben argues to hide the directory lookup from the CA client us
er.
See separate [[V4 Name Server]] wiki for the issue of "record" and "PV" information.

=== Data Access ===
All the data is accessed via DataAccess, which handles the introspection
of arbitrary data types. It should provide the following convenience
routines in addition to whatever more efficient methods it might have
(using hash IDs instead property name string etc.):
* list<string> getProperties() Get a list of all the properties
* type_info getType(string property)
* bool hasWriteAccess(string property)
* string getAsString(string property)

Marty has a more complete idea, where a proterty catalog converts strings to IDs
and then those are actually used to access the data:

struct Property {
epicsInt32 id;
dbfType type;
void *pdbf;
};
interface PropertyViewer {
Property *getFirst();
Property *getNext(Property &);
Property *get(epicsInt32 id);
}
interface PropertyCatalogManager {
epicsInt32 getId(EpicsString &);
EpicsString *getName(epicsInt32 id);
epicsInt32 createId(EpicsString &);
};

In the following, each method that uses the property name
will need a twin that uses the ID or Property *.

=== Channel ===
* Channel(string name, Directory dir = default) Constructor. Channel has to have a name. Uses the 'best' channel from the default directory or from a given directory.
* Channel(string name, CASInfo) ... in case you want a specific server after querying the directory yourself or not using a directory at all.
* getName() Returns the name of the channel.
* addListener(Listener l), removeListener(Listener l) Register for notifications, see below.
* getProperties() A read or subscription will return a dataAccess interface to the retrieved data. That might exclude properties that this client cannot access. It will include the data, which might be huge. This separate call will only get property information, no data, for all properties, including read/write access information. The result could be in the form of dataAccess, except all access to actual data yields empty results, only the property-info related part of dataAccess is functional.

Note that Ben suggests that the CA client library should select the CA server automatically by querying a server or via broadcasts; it should also pick amongst competing PVs of the same name without user interaction.

Note also that in order to read or write, one needs to know what properties to access.
Does the channel magically provide a list of all properties?
Is there a "get all properties" request that reads them on-demand
from the CA server?
Or does the directory hold the list of available properties and their types?

=== Channel: Listener ===
The Channel::Listener interface is invoked in response to the many asynchronous methods of the Channel.
* writeComplete(Channel ch)
** Channel that send this notification
* newData(Channel ch, DataAccess data, Event why)
** DataAccess interface to the data
** Reason for the update: Value deadband exceeded, minimum period expired, event 'blue beam', ...
* accessRightChange(Channel ch)

Alternatively, these could be separate interfaces for a writeListener, dataListener, stateListener.

=== Channel: State ===
In contrast to the V3 API, the user doesn't 'connect'.
The first data notification implies that we're connected.

* bool isConnected() .. for those who want to poll
* xxx getServerInfo(), xxx getType() .. only valid when isConnected().
* setUser(), ... Sets/changes the 'user' that determines the access rights, allowing OPI tools to adjust this per-channel at runtime. To avoid security issues, setUser will probably send a public key and not a user name and password.

=== Channel: Writing ===
* write(new value) Sends the value to the server.
* createWriteRequest(new value, receipt {delivery, completion}) Sends the value to the server, invokes Listener when CA server has received the value respectively all the processing triggered by the new value has completed.
* scheduleWriteRequest(new value, event) Sends the value to the server, which will perform the write when the given event fires. Invokes Listener when CA server has performed the write.

=== Channel: Reading ===
* createSubscription(list<string> properties, Event e) Will invoke Listener once data arrives.
* cancelSubscription(....) Use properties & event or an ID returned from createSubscription?

Event is a class that allows the user to select what triggers an update:
* useDefaultValueDeadband() Default if nothing else is called.
* setValueDeadband(double change)
* setPercentageDeadband(double percent)
* setLogarithmicDeadband(double exponent_of_ten)
* setMinimumRate(double seconds) There will be notifications at at least this rate, even if value didn't change.
* setMaximumRate(double vals_per_second)
* useAlarmConditionChange()
* useHardwareEvent(int event_id) Somehow, event_id might be linked to 'Blue Beam'
* setMaxValueCount Setting this to '1' turns the subscription into a single-value 'get'.

Unclear how to present the Event to a user. For example, how would a 'camonitor' tool allow the user to select the events? Via 20 command-line switches, or should there be a syntax ala
"valueDeadband=1.0, maximumRate=20" which is supported by methods
* string toString()
* bood fromString(string event_specification)

=== ChannelGroup ===
A channel group synchronizes access to multiple channels.
It listens to all members of the channel group and for example
allows waiting for ''all'' outstanding read or write requests
to return.

* add/remove channels By name? Already existing Channel? Add channels that match a pattern, or go via the directory?
* read/write Has to handle reading/writing the same properties from all channels in group. Also channel-specific list of properties?

=== SyncChannel ===
A wrapper class around the async. Channel.
Uses a configurable timeout and provides synchronous 'read'.

* Inherits from Channel.
* double getTimeout(), void setTimeout(double seconds)
* DataAccess read(list<string> properties) Synchronous read of current values of properties.
* DataAccess read(string property) Synchronous read of current value of one property.

=== Container ===
The Channel does not store any data.
When attaching a container to a channel, the container will subscribe
to the channel and keep a copy of all data, so one can always ask
the container for the current values.
* attach(channel)
* detach()
* implements the DataAccess interface to allow access to the data.

Also see [[V4 Data Store]]

== caget 101 ==
This is how a simple 'caget' could be written:

SyncChannel channel("fred");
DataAccess da = channel.read("value");
cout << "Value of " << channel.getName() << " : " << da.getAsString("value") << "\n";

We can imagine an even simpler example:

cout << "Value of fred:" << Epics::get("fred") << "\n";

This implies lots of work under the hood, with reasonable defaults.

== camonitor 101 ==
This is the goal for a 'camonitor':

class MyMonitor : public Channel::Listener
{
public:
newData(Channel ch, DataAccess data, Event why)
{
cout << channel.getName() << " = " << da.getAsString("value") << "\n";
}
};
...
Channel channel("fred");
list<string> properties;
properties.push_back("value");
Event e;
e. setMaximumRate(10.0);
channel.createSubscription(properties, e);

V4 CA Client User Interface

2005-07-13T20:23:35Z

KayKasemir: /* Channel: State */

== Channel Access Client User Interface ==
Under V4, a ProcessVariable would no longer be limited
to the current properties 'value', 'units', ... but allow the users to create
CA servers and clients that understand new properties.

The low-level V4 CA client API is likely to be rather complex because it
now needs to handle arbitrary property catalogs.
* There still needs to be an easy to use high-level API, not much more complex than the existing one.
* There needs to be access to CA from languages like Matlab in a way that's as easy as
pv = caopen('fred');
value = caget(pv);

== Food for thought ==
Is there anything we can learn from other communication libraries?
* A brief look at [[ZeroC ICE]]

== Skeleton API ==
What follows is in the form of pseudo classes and associated methods
that a CA client API should provide.

=== Directory ===
The directory is used to discover available channels and map them to the CA Server address and port.
* Directory(string URL-type-server-address = "") Constructor; uses site-specific default server or specific one. The 'URL' might contain a user & password, which decides if this name server connection is read-only (for OPI clients) or if writes are allowed (for IOCs that add PVs to the name server).
* getChannelInfo(string PV_or_pattern) Returns list of
** CA server - IP & port of server that has the PV
** quality - is this the IOC, a gateway, backup/primary
* addChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to register their PV in directory
* deleteChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to remove their PV from directory

There is a default directory, available via something like "EPICSDefaults::getDirectory()" and "...setDirectory()".
The implementation could use
* LDAP
* Broadcast (as before)
* your custom implementation as long as it uses the above interface and registers itself as the default.

Note that Ben argues to hide the directory lookup from the CA client us
er.
See separate [[V4 Name Server]] wiki for the issue of "record" and "PV" information.

=== Data Access ===
All the data is accessed via DataAccess, which handles the introspection
of arbitrary data types. It should provide the following convenience
routines in addition to whatever more efficient methods it might have
(using hash IDs instead property name string etc.):
* list<string> getProperties() Get a list of all the properties
* type_info getType(string property)
* bool hasWriteAccess(string property)
* string getAsString(string property)

Marty has a more complete idea, where a proterty catalog converts strings to IDs
and then those are actually used to access the data:

struct Property {
epicsInt32 id;
dbfType type;
void *pdbf;
};
interface PropertyViewer {
Property *getFirst();
Property *getNext(Property &);
Property *get(epicsInt32 id);
}
interface PropertyCatalogManager {
epicsInt32 getId(EpicsString &);
EpicsString *getName(epicsInt32 id);
epicsInt32 createId(EpicsString &);
};

In the following, each method that uses the property name
will need a twin that uses the ID or Property *.

=== Channel ===
* Channel(string name, Directory dir = default) Constructor. Channel has to have a name. Uses the 'best' channel from the default directory or from a given directory.
* Channel(string name, CASInfo) ... in case you want a specific server after querying the directory yourself or not using a directory at all.
* getName() Returns the name of the channel.
* addListener(Listener l), removeListener(Listener l) Register for notifications, see below.
* getProperties() A read or subscription will return a dataAccess interface to the retrieved data. That might exclude properties that this client cannot access. It will include the data, which might be huge. This separate call will only get property information, no data, for all properties, including read/write access information. The result could be in the form of dataAccess, except all access to actual data yields empty results, only the property-info related part of dataAccess is functional.

Note that Ben suggests that the CA client library should select the CA server automatically by querying a server or via broadcasts; it should also pick amongst competing PVs of the same name without user interaction.

Note also that in order to read or write, one needs to know what properties to access.
Does the channel magically provide a list of all properties?
Is there a "get all properties" request that reads them on-demand
from the CA server?
Or does the directory hold the list of available properties and their types?

=== Channel: Listener ===
The Channel::Listener interface is invoked in response to the many asynchronous methods of the Channel.
* writeComplete(Channel ch)
** Channel that send this notification
* newData(Channel ch, DataAccess data, Event why)
** DataAccess interface to the data
** Reason for the update: Value deadband exceeded, minimum period expired, event 'blue beam', ...
* accessRightChange(Channel ch)

Alternatively, these could be separate interfaces for a writeListener, dataListener, stateListener.

=== Channel: State ===
In contrast to the V3 API, the user doesn't 'connect'.
The first data notification implies that we're connected.

* bool isConnected() .. for those who want to poll
* xxx getServerInfo(), xxx getType() .. only valid when isConnected().
* setUser(), ... Sets/changes the 'user' that determines the access rights, allowing OPI tools to adjust this per-channel at runtime. To avoid security issues, setUser will probably send a public key and not a user name and password.

=== Channel: Writing ===
* write(new value) Sends the value to the server.
* createWriteRequest(new value, receipt {delivery, completion}) Sends the value to the server, invokes Listener when CA server has received the value respectively all the processing triggered by the new value has completed.
* scheduleWriteRequest(new value, event) Sends the value to the server, which will perform the write when the given event fires. Invokes Listener when CA server has performed the write.

=== Channel: Reading ===
* createSubscription(list<string> properties, Event e) Will invoke Listener once data arrives.
* cancelSubscription(....) Use properties & event or an ID returned from createSubscription?

Event is a class that allows the user to select what triggers an update:
* useDefaultValueDeadband() Default if nothing else is called.
* setValueDeadband(double change)
* setPercentageDeadband(double percent)
* setLogarithmicDeadband(double exponent_of_ten)
* setMinimumRate(double seconds) There will be notifications at at least this rate, even if value didn't change.
* setMaximumRate(double vals_per_second)
* useAlarmConditionChange()
* useHardwareEvent(int event_id) Somehow, event_id might be linked to 'Blue Beam'
* setMaxValueCount Setting this to '1' turns the subscription into a single-value 'get'.

Unclear how to present the Event to a user. For example, how would a 'camonitor' tool allow the user to select the events? Via 20 command-line switches, or should there be a syntax ala
"valueDeadband=1.0, maximumRate=20" which is supported by methods
* string toString()
* bood fromString(string event_specification)

=== ChannelGroup ===

A channel group synchronizes access to multiple channels.
It listens to all members of the channel group and for example
allows waiting for ''all'' outstanding read or write requests
to return.

=== SyncChannel ===
A wrapper class around the async. Channel.
Uses a configurable timeout and provides synchronous 'read'.

* Inherits from Channel.
* double getTimeout(), void setTimeout(double seconds)
* DataAccess read(list<string> properties) Synchronous read of current values of properties.
* DataAccess read(string property) Synchronous read of current value of one property.

=== Container ===
The Channel does not store any data.
When attaching a container to a channel, the container will subscribe
to the channel and keep a copy of all data, so one can always ask
the container for the current values.
* attach(channel)
* detach()
* implements the DataAccess interface to allow access to the data.

Also see [[V4 Data Store]]

== caget 101 ==
This is how a simple 'caget' could be written:

SyncChannel channel("fred");
DataAccess da = channel.read("value");
cout << "Value of " << channel.getName() << " : " << da.getAsString("value") << "\n";

We can imagine an even simpler example:

cout << "Value of fred:" << Epics::get("fred") << "\n";

This implies lots of work under the hood, with reasonable defaults.

== camonitor 101 ==
This is the goal for a 'camonitor':

class MyMonitor : public Channel::Listener
{
public:
newData(Channel ch, DataAccess data, Event why)
{
cout << channel.getName() << " = " << da.getAsString("value") << "\n";
}
};
...
Channel channel("fred");
list<string> properties;
properties.push_back("value");
Event e;
e. setMaximumRate(10.0);
channel.createSubscription(properties, e);

V4 CA Client User Interface

2005-07-13T20:22:30Z

KayKasemir: /* SyncChannel */ , ChannelGroup

== Channel Access Client User Interface ==
Under V4, a ProcessVariable would no longer be limited
to the current properties 'value', 'units', ... but allow the users to create
CA servers and clients that understand new properties.

The low-level V4 CA client API is likely to be rather complex because it
now needs to handle arbitrary property catalogs.
* There still needs to be an easy to use high-level API, not much more complex than the existing one.
* There needs to be access to CA from languages like Matlab in a way that's as easy as
pv = caopen('fred');
value = caget(pv);

== Food for thought ==
Is there anything we can learn from other communication libraries?
* A brief look at [[ZeroC ICE]]

== Skeleton API ==
What follows is in the form of pseudo classes and associated methods
that a CA client API should provide.

=== Directory ===
The directory is used to discover available channels and map them to the CA Server address and port.
* Directory(string URL-type-server-address = "") Constructor; uses site-specific default server or specific one. The 'URL' might contain a user & password, which decides if this name server connection is read-only (for OPI clients) or if writes are allowed (for IOCs that add PVs to the name server).
* getChannelInfo(string PV_or_pattern) Returns list of
** CA server - IP & port of server that has the PV
** quality - is this the IOC, a gateway, backup/primary
* addChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to register their PV in directory
* deleteChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to remove their PV from directory

There is a default directory, available via something like "EPICSDefaults::getDirectory()" and "...setDirectory()".
The implementation could use
* LDAP
* Broadcast (as before)
* your custom implementation as long as it uses the above interface and registers itself as the default.

Note that Ben argues to hide the directory lookup from the CA client us
er.
See separate [[V4 Name Server]] wiki for the issue of "record" and "PV" information.

=== Data Access ===
All the data is accessed via DataAccess, which handles the introspection
of arbitrary data types. It should provide the following convenience
routines in addition to whatever more efficient methods it might have
(using hash IDs instead property name string etc.):
* list<string> getProperties() Get a list of all the properties
* type_info getType(string property)
* bool hasWriteAccess(string property)
* string getAsString(string property)

Marty has a more complete idea, where a proterty catalog converts strings to IDs
and then those are actually used to access the data:

struct Property {
epicsInt32 id;
dbfType type;
void *pdbf;
};
interface PropertyViewer {
Property *getFirst();
Property *getNext(Property &);
Property *get(epicsInt32 id);
}
interface PropertyCatalogManager {
epicsInt32 getId(EpicsString &);
EpicsString *getName(epicsInt32 id);
epicsInt32 createId(EpicsString &);
};

In the following, each method that uses the property name
will need a twin that uses the ID or Property *.

=== Channel ===
* Channel(string name, Directory dir = default) Constructor. Channel has to have a name. Uses the 'best' channel from the default directory or from a given directory.
* Channel(string name, CASInfo) ... in case you want a specific server after querying the directory yourself or not using a directory at all.
* getName() Returns the name of the channel.
* addListener(Listener l), removeListener(Listener l) Register for notifications, see below.
* getProperties() A read or subscription will return a dataAccess interface to the retrieved data. That might exclude properties that this client cannot access. It will include the data, which might be huge. This separate call will only get property information, no data, for all properties, including read/write access information. The result could be in the form of dataAccess, except all access to actual data yields empty results, only the property-info related part of dataAccess is functional.

Note that Ben suggests that the CA client library should select the CA server automatically by querying a server or via broadcasts; it should also pick amongst competing PVs of the same name without user interaction.

Note also that in order to read or write, one needs to know what properties to access.
Does the channel magically provide a list of all properties?
Is there a "get all properties" request that reads them on-demand
from the CA server?
Or does the directory hold the list of available properties and their types?

=== Channel: Listener ===
The Channel::Listener interface is invoked in response to the many asynchronous methods of the Channel.
* writeComplete(Channel ch)
** Channel that send this notification
* newData(Channel ch, DataAccess data, Event why)
** DataAccess interface to the data
** Reason for the update: Value deadband exceeded, minimum period expired, event 'blue beam', ...
* accessRightChange(Channel ch)

Alternatively, these could be separate interfaces for a writeListener, dataListener, stateListener.

=== Channel: State ===
In contrast to the V3 API, the user doesn't 'connect'.
The first data notification implies that we're connected.

* bool isConnected() .. for those who want to poll
* xxx getServerInfo(), xxx getType() .. only valid when isConnected().
* setUser(), ... Sets/changes the 'user' that determines the access rights, allowing OPI tools to adjust this per-channel at runtime.

=== Channel: Writing ===
* write(new value) Sends the value to the server.
* createWriteRequest(new value, receipt {delivery, completion}) Sends the value to the server, invokes Listener when CA server has received the value respectively all the processing triggered by the new value has completed.
* scheduleWriteRequest(new value, event) Sends the value to the server, which will perform the write when the given event fires. Invokes Listener when CA server has performed the write.

=== Channel: Reading ===
* createSubscription(list<string> properties, Event e) Will invoke Listener once data arrives.
* cancelSubscription(....) Use properties & event or an ID returned from createSubscription?

Event is a class that allows the user to select what triggers an update:
* useDefaultValueDeadband() Default if nothing else is called.
* setValueDeadband(double change)
* setPercentageDeadband(double percent)
* setLogarithmicDeadband(double exponent_of_ten)
* setMinimumRate(double seconds) There will be notifications at at least this rate, even if value didn't change.
* setMaximumRate(double vals_per_second)
* useAlarmConditionChange()
* useHardwareEvent(int event_id) Somehow, event_id might be linked to 'Blue Beam'
* setMaxValueCount Setting this to '1' turns the subscription into a single-value 'get'.

Unclear how to present the Event to a user. For example, how would a 'camonitor' tool allow the user to select the events? Via 20 command-line switches, or should there be a syntax ala
"valueDeadband=1.0, maximumRate=20" which is supported by methods
* string toString()
* bood fromString(string event_specification)

=== ChannelGroup ===

A channel group synchronizes access to multiple channels.
It listens to all members of the channel group and for example
allows waiting for ''all'' outstanding read or write requests
to return.

=== SyncChannel ===
A wrapper class around the async. Channel.
Uses a configurable timeout and provides synchronous 'read'.

* Inherits from Channel.
* double getTimeout(), void setTimeout(double seconds)
* DataAccess read(list<string> properties) Synchronous read of current values of properties.
* DataAccess read(string property) Synchronous read of current value of one property.

=== Container ===
The Channel does not store any data.
When attaching a container to a channel, the container will subscribe
to the channel and keep a copy of all data, so one can always ask
the container for the current values.
* attach(channel)
* detach()
* implements the DataAccess interface to allow access to the data.

Also see [[V4 Data Store]]

== caget 101 ==
This is how a simple 'caget' could be written:

SyncChannel channel("fred");
DataAccess da = channel.read("value");
cout << "Value of " << channel.getName() << " : " << da.getAsString("value") << "\n";

We can imagine an even simpler example:

cout << "Value of fred:" << Epics::get("fred") << "\n";

This implies lots of work under the hood, with reasonable defaults.

== camonitor 101 ==
This is the goal for a 'camonitor':

class MyMonitor : public Channel::Listener
{
public:
newData(Channel ch, DataAccess data, Event why)
{
cout << channel.getName() << " = " << da.getAsString("value") << "\n";
}
};
...
Channel channel("fred");
list<string> properties;
properties.push_back("value");
Event e;
e. setMaximumRate(10.0);
channel.createSubscription(properties, e);

V4 CA Client User Interface

2005-07-13T20:20:33Z

KayKasemir: /* Channel: Reading */

== Channel Access Client User Interface ==
Under V4, a ProcessVariable would no longer be limited
to the current properties 'value', 'units', ... but allow the users to create
CA servers and clients that understand new properties.

The low-level V4 CA client API is likely to be rather complex because it
now needs to handle arbitrary property catalogs.
* There still needs to be an easy to use high-level API, not much more complex than the existing one.
* There needs to be access to CA from languages like Matlab in a way that's as easy as
pv = caopen('fred');
value = caget(pv);

== Food for thought ==
Is there anything we can learn from other communication libraries?
* A brief look at [[ZeroC ICE]]

== Skeleton API ==
What follows is in the form of pseudo classes and associated methods
that a CA client API should provide.

=== Directory ===
The directory is used to discover available channels and map them to the CA Server address and port.
* Directory(string URL-type-server-address = "") Constructor; uses site-specific default server or specific one. The 'URL' might contain a user & password, which decides if this name server connection is read-only (for OPI clients) or if writes are allowed (for IOCs that add PVs to the name server).
* getChannelInfo(string PV_or_pattern) Returns list of
** CA server - IP & port of server that has the PV
** quality - is this the IOC, a gateway, backup/primary
* addChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to register their PV in directory
* deleteChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to remove their PV from directory

There is a default directory, available via something like "EPICSDefaults::getDirectory()" and "...setDirectory()".
The implementation could use
* LDAP
* Broadcast (as before)
* your custom implementation as long as it uses the above interface and registers itself as the default.

Note that Ben argues to hide the directory lookup from the CA client us
er.
See separate [[V4 Name Server]] wiki for the issue of "record" and "PV" information.

=== Data Access ===
All the data is accessed via DataAccess, which handles the introspection
of arbitrary data types. It should provide the following convenience
routines in addition to whatever more efficient methods it might have
(using hash IDs instead property name string etc.):
* list<string> getProperties() Get a list of all the properties
* type_info getType(string property)
* bool hasWriteAccess(string property)
* string getAsString(string property)

Marty has a more complete idea, where a proterty catalog converts strings to IDs
and then those are actually used to access the data:

struct Property {
epicsInt32 id;
dbfType type;
void *pdbf;
};
interface PropertyViewer {
Property *getFirst();
Property *getNext(Property &);
Property *get(epicsInt32 id);
}
interface PropertyCatalogManager {
epicsInt32 getId(EpicsString &);
EpicsString *getName(epicsInt32 id);
epicsInt32 createId(EpicsString &);
};

In the following, each method that uses the property name
will need a twin that uses the ID or Property *.

=== Channel ===
* Channel(string name, Directory dir = default) Constructor. Channel has to have a name. Uses the 'best' channel from the default directory or from a given directory.
* Channel(string name, CASInfo) ... in case you want a specific server after querying the directory yourself or not using a directory at all.
* getName() Returns the name of the channel.
* addListener(Listener l), removeListener(Listener l) Register for notifications, see below.
* getProperties() A read or subscription will return a dataAccess interface to the retrieved data. That might exclude properties that this client cannot access. It will include the data, which might be huge. This separate call will only get property information, no data, for all properties, including read/write access information. The result could be in the form of dataAccess, except all access to actual data yields empty results, only the property-info related part of dataAccess is functional.

Note that Ben suggests that the CA client library should select the CA server automatically by querying a server or via broadcasts; it should also pick amongst competing PVs of the same name without user interaction.

Note also that in order to read or write, one needs to know what properties to access.
Does the channel magically provide a list of all properties?
Is there a "get all properties" request that reads them on-demand
from the CA server?
Or does the directory hold the list of available properties and their types?

=== Channel: Listener ===
The Channel::Listener interface is invoked in response to the many asynchronous methods of the Channel.
* writeComplete(Channel ch)
** Channel that send this notification
* newData(Channel ch, DataAccess data, Event why)
** DataAccess interface to the data
** Reason for the update: Value deadband exceeded, minimum period expired, event 'blue beam', ...
* accessRightChange(Channel ch)

Alternatively, these could be separate interfaces for a writeListener, dataListener, stateListener.

=== Channel: State ===
In contrast to the V3 API, the user doesn't 'connect'.
The first data notification implies that we're connected.

* bool isConnected() .. for those who want to poll
* xxx getServerInfo(), xxx getType() .. only valid when isConnected().
* setUser(), ... Sets/changes the 'user' that determines the access rights, allowing OPI tools to adjust this per-channel at runtime.

=== Channel: Writing ===
* write(new value) Sends the value to the server.
* createWriteRequest(new value, receipt {delivery, completion}) Sends the value to the server, invokes Listener when CA server has received the value respectively all the processing triggered by the new value has completed.
* scheduleWriteRequest(new value, event) Sends the value to the server, which will perform the write when the given event fires. Invokes Listener when CA server has performed the write.

=== Channel: Reading ===
* createSubscription(list<string> properties, Event e) Will invoke Listener once data arrives.
* cancelSubscription(....) Use properties & event or an ID returned from createSubscription?

Event is a class that allows the user to select what triggers an update:
* useDefaultValueDeadband() Default if nothing else is called.
* setValueDeadband(double change)
* setPercentageDeadband(double percent)
* setLogarithmicDeadband(double exponent_of_ten)
* setMinimumRate(double seconds) There will be notifications at at least this rate, even if value didn't change.
* setMaximumRate(double vals_per_second)
* useAlarmConditionChange()
* useHardwareEvent(int event_id) Somehow, event_id might be linked to 'Blue Beam'
* setMaxValueCount Setting this to '1' turns the subscription into a single-value 'get'.

Unclear how to present the Event to a user. For example, how would a 'camonitor' tool allow the user to select the events? Via 20 command-line switches, or should there be a syntax ala
"valueDeadband=1.0, maximumRate=20" which is supported by methods
* string toString()
* bood fromString(string event_specification)

=== SyncChannel ===
A wrapper class around the async. Channel.
Uses a configurable timeout and provides synchronous 'read'.

* Inherits from Channel.
* double getTimeout(), void setTimeout(double seconds)
* DataAccess read(list<string> properties) Synchronous read of current values of properties.
* DataAccess read(string property) Synchronous read of current value of one property.

=== Container ===
The Channel does not store any data.
When attaching a container to a channel, the container will subscribe
to the channel and keep a copy of all data, so one can always ask
the container for the current values.
* attach(channel)
* detach()
* implements the DataAccess interface to allow access to the data.

Also see [[V4 Data Store]]

== caget 101 ==
This is how a simple 'caget' could be written:

SyncChannel channel("fred");
DataAccess da = channel.read("value");
cout << "Value of " << channel.getName() << " : " << da.getAsString("value") << "\n";

We can imagine an even simpler example:

cout << "Value of fred:" << Epics::get("fred") << "\n";

This implies lots of work under the hood, with reasonable defaults.

== camonitor 101 ==
This is the goal for a 'camonitor':

class MyMonitor : public Channel::Listener
{
public:
newData(Channel ch, DataAccess data, Event why)
{
cout << channel.getName() << " = " << da.getAsString("value") << "\n";
}
};
...
Channel channel("fred");
list<string> properties;
properties.push_back("value");
Event e;
e. setMaximumRate(10.0);
channel.createSubscription(properties, e);

V4 CA Client User Interface

2005-07-07T17:06:23Z

KayKasemir: no connect, thus no disconnect; Event from info to interface; camonitor

== Channel Access Client User Interface ==
Under V4, a ProcessVariable would no longer be limited
to the current properties 'value', 'units', ... but allow the users to create
CA servers and clients that understand new properties.

The low-level V4 CA client API is likely to be rather complex because it
now needs to handle arbitrary property catalogs.
* There still needs to be an easy to use high-level API, not much more complex than the existing one.
* There needs to be access to CA from languages like Matlab in a way that's as easy as
pv = caopen('fred');
value = caget(pv);

== Food for thought ==
Is there anything we can learn from other communication libraries?
* A brief look at [[ZeroC ICE]]

== Skeleton API ==
What follows is in the form of pseudo classes and associated methods
that a CA client API should provide.

=== Directory ===
The directory is used to discover available channels and map them to the CA Server address and port.
* Directory(string URL-type-server-address = "") Constructor; uses site-specific default server or specific one. The 'URL' might contain a user & password, which decides if this name server connection is read-only (for OPI clients) or if writes are allowed (for IOCs that add PVs to the name server).
* getChannelInfo(string PV_or_pattern) Returns list of
** CA server - IP & port of server that has the PV
** quality - is this the IOC, a gateway, backup/primary
* addChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to register their PV in directory
* deleteChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...) Used by CA servers to remove their PV from directory

There is a default directory, available via something like "EPICSDefaults::getDirectory()" and "...setDirectory()".
The implementation could use
* LDAP
* Broadcast (as before)
* your custom implementation as long as it uses the above interface and registers itself as the default.

Note that Ben argues to hide the directory lookup from the CA client us
er.
See separate [[V4 Name Server]] wiki for the issue of "record" and "PV" information.

=== Data Access ===
All the data is accessed via DataAccess, which handles the introspection
of arbitrary data types. It should provide the following convenience
routines in addition to whatever more efficient methods it might have
(using hash IDs instead property name string etc.):
* list<string> getProperties() Get a list of all the properties
* type_info getType(string property)
* bool hasWriteAccess(string property)
* string getAsString(string property)

Marty has a more complete idea, where a proterty catalog converts strings to IDs
and then those are actually used to access the data:

struct Property {
epicsInt32 id;
dbfType type;
void *pdbf;
};
interface PropertyViewer {
Property *getFirst();
Property *getNext(Property &);
Property *get(epicsInt32 id);
}
interface PropertyCatalogManager {
epicsInt32 getId(EpicsString &);
EpicsString *getName(epicsInt32 id);
epicsInt32 createId(EpicsString &);
};

In the following, each method that uses the property name
will need a twin that uses the ID or Property *.

=== Channel ===
* Channel(string name, Directory dir = default) Constructor. Channel has to have a name. Uses the 'best' channel from the default directory or from a given directory.
* Channel(string name, CASInfo) ... in case you want a specific server after querying the directory yourself or not using a directory at all.
* getName() Returns the name of the channel.
* addListener(Listener l), removeListener(Listener l) Register for notifications, see below.
* getProperties() A read or subscription will return a dataAccess interface to the retrieved data. That might exclude properties that this client cannot access. It will include the data, which might be huge. This separate call will only get property information, no data, for all properties, including read/write access information. The result could be in the form of dataAccess, except all access to actual data yields empty results, only the property-info related part of dataAccess is functional.

Note that Ben suggests that the CA client library should select the CA server automatically by querying a server or via broadcasts; it should also pick amongst competing PVs of the same name without user interaction.

Note also that in order to read or write, one needs to know what properties to access.
Does the channel magically provide a list of all properties?
Is there a "get all properties" request that reads them on-demand
from the CA server?
Or does the directory hold the list of available properties and their types?

=== Channel: Listener ===
The Channel::Listener interface is invoked in response to the many asynchronous methods of the Channel.
* writeComplete(Channel ch)
** Channel that send this notification
* newData(Channel ch, DataAccess data, Event why)
** DataAccess interface to the data
** Reason for the update: Value deadband exceeded, minimum period expired, event 'blue beam', ...
* accessRightChange(Channel ch)

Alternatively, these could be separate interfaces for a writeListener, dataListener, stateListener.

=== Channel: State ===
In contrast to the V3 API, the user doesn't 'connect'.
The first data notification implies that we're connected.

* bool isConnected() .. for those who want to poll
* xxx getServerInfo(), xxx getType() .. only valid when isConnected().
* setUser(), ... Sets/changes the 'user' that determines the access rights, allowing OPI tools to adjust this per-channel at runtime.

=== Channel: Writing ===
* write(new value) Sends the value to the server.
* createWriteRequest(new value, receipt {delivery, completion}) Sends the value to the server, invokes Listener when CA server has received the value respectively all the processing triggered by the new value has completed.
* scheduleWriteRequest(new value, event) Sends the value to the server, which will perform the write when the given event fires. Invokes Listener when CA server has performed the write.

=== Channel: Reading ===
* createSubscription(list<string> properties, Event e) Will invoke Listener once data arrives.
* cancelSubscription(....) Use properties & event or an ID returned from createSubscription?

Event is a class that allows the user to select what triggers an update:
* useDefaultValueDeadband() Default if nothing else is called.
* setValueDeadband(double change)
* setPercantageDeadband(double percent)
* setLogarithmicDeadband(double exponent_of_ten)
* setMinimumRate(double seconds) There will be notifications at at least this rate, even if value didn't change.
* setMaximumRate(double vals_per_second)
* useAlarmConditionChange()
* useHardwareEvent(int event_id) Somehow, event_id might be linked to 'Blue Beam'
* setMaxValueCount Setting this to '1' turns the subscription into a single-value 'get'.

Unclear how to present the Event to a user. For example, how would a 'camonitor' tool allow the user to select the events? Via 20 command-line switches, or should there be a syntax ala
"valueDeadband=1.0, maximumRate=20" which is supported by methods
* string toString()
* bood fromString(string event_specification)

=== SyncChannel ===
A wrapper class around the async. Channel.
Uses a configurable timeout and provides synchronous 'read'.

* Inherits from Channel.
* double getTimeout(), void setTimeout(double seconds)
* DataAccess read(list<string> properties) Synchronous read of current values of properties.
* DataAccess read(string property) Synchronous read of current value of one property.

=== Container ===
The Channel does not store any data.
When attaching a container to a channel, the container will subscribe
to the channel and keep a copy of all data, so one can always ask
the container for the current values.
* attach(channel)
* detach()
* implements the DataAccess interface to allow access to the data.

== caget 101 ==
This is how a simple 'caget' could be written:

SyncChannel channel("fred");
DataAccess da = channel.read("value");
cout << "Value of " << channel.getName() << " : " << da.getAsString("value") << "\n";

== camonitor 101 ==
This is the goal for a 'camonitor':

class MyMonitor : public Channel::Listener
{
public:
newData(Channel ch, DataAccess data, Event why)
{
cout << channel.getName() << " = " << da.getAsString("value") << "\n";
}
};
...
Channel channel("fred");
list<string> properties;
properties.push_back("value");
Event e;
e. setMaximumRate(10.0);
channel.createSubscription(properties, e);

V4 CA Client User Interface

2005-07-07T16:47:40Z

KayKasemir: Had the 'read' misplaced

V4 CA Client User Interface

2005-07-07T16:42:57Z

KayKasemir: Hint to Marty's prop. handling idea. Had dropped the basic 'read'.

V4 Name Server

2005-07-07T16:05:15Z

KayKasemir: Reduced to essentials

== Directory Server ==

EPICS ChannelAccess currently uses a broadcast mechanism for resolving
channel names.
Advantages:
* Minimal if not zero initial setup.
* At least initially very fast, because a client can send multiple name requests in one network packet, all servers receive it simultaneously and can answer to known names.

Disadvantages:
* Unclear how to extend this service to redundant servers, archived data, ...
* Currently, no wildcard searches.
* Currently, no statistics on available number of channels, types of records, ...
* Bigger installations run into problems with broadcast traffic:
** All devices see the requests, even though only one server has a given channel name.
** Continued searches for unresolved names to overcome UDP limitations.

As Larry Hoff pointed out, we really want a ''Directory'' server for
EPICS, something beyond a name server. A directory will not only map PV
names to IP addresses of ChannelAccess servers, but also support
* wildcard searches, reports on number of channels per IOC etc.
* redundant servers
* info about reduntant IOCs with the same PV, archived data for a PV
* backup/restore locations for a PV
* PV meta information like engineer-in-charge, CA security rules, ...

== Channels, Records, PVs, Properties ==
We currently have records with fields and channels with properties.
Each field of a record can become a channel name,
the field itself ends up in the 'value' property of the channel,
and the record decides how to fill the remaining properties.

Will the directory list all record names or all possible channels?
I think only record names.

Will it include the record type? Not enough information if we add user-defined fields.
Will it lists all fields of a record?

I think for now that only listing record names is enough in order to allow
connections.

The CA client would then have to query the CA server for all the available properties
of a PV, and note that properties might even change at runtime when we allow
online add & delete.

Whenever a tool like a command-line 'caget' or the 'probe' GUI requires a PV name,
it needs to be decided what properties "fred" would access. In the past, it was equal
to "fred.VAL". There is much more detail in the 'view' section of the
[[V4 DBD Statement Syntax]].

== LDAP, Directory, RDB, Schema, Entries, dn, cn, dc, ... ==

The ''Lightweight Directory Access Protocol'' (LDAP) is a network protocol.
It defines how to access data over the network, regardless of language
or underlying data storage. In contrast, RDBs like Oracle or MySQL define the
data storage and SQL dialect, while the network access to the data is then
added almost as an afterthought.

LDAP is meant as a Directory for simple attribute-based information
for fast, high volume lookup. Simple search filters are supported:
Patterns, "and", "or". In contrast to RDBs, there is no support for
arbitrary relations between entries, there are no transactions nor rollback.

There are open-source servers for LDAP, and client libraries for
C, Perl, Java and other languages. MacOSX, Linux, Windows 2000
already include LDAP clients. MS ActiveDirectory uses LDAP.

LDAP requires the data to be organized into hierarchical ''Entries''.
Each Entry has a globally unique ''Distinguished Name'' (dn),
and various ''Attributes'', that is Type/Value pairs.
The ''Schema'' defines which attributes an entry must have and which ones
it might have. There are existing schemas for DNS-type data or personell
information, including types like ''Common Name'' (cn) or ''Domain Component'' (dc),
but one can add custom schemata. Values might include binary data, e.g. images.

=== Mapping EPICS PV Information to LDAP ===

Each LDAP entry must have a unique name (dn). EPICS PVs must be unique as well,
but only within the search domain currently defined by the EPICS_CA_ADDR_LIST.
It might make sense to synchronize LDAP servers across these boundaries,
in which case the LDAP dn will have to include more than just the PV name.
For example, one could have a PV "fred" in both the accelerator and office network
of the SNS, and enter them into an SNS-wide LDAP directory like this:

fred.linac.sns.epics: cas="linacioc1:5065"
fred.office.sns.epics: cas="testioc47.sns.ornl.gov:7987", description="Fred's test PV"

In this example, the directory includes the ChannelAccess server for both PVs,
and in one case also a description.

While an EPICS-specific tool might present the data as shown above,
most generic LDAP tools and APIs use the ''LDAP Data Interchange Format'' (LDIF).
In LDIF, part of the above data could look like this:

dn: dc=epics
objectclass: dcObject
objectclass: organization
o: Root of all EPICS PVs
dc: epics

dn: dc=sns,dc=epics
# Details omitted; similar to previous entry

dn: dc=linac,dc=sns,dc=epics
objectclass: dcObject
objectclass: organization
o: Root of all EPICS PVs in the SNS Linac
dc: linac

dn: cn=fred,dc=linac,dc=sns,dc=epics
objectclass: ProcessVariable
cn: fred
cas: linacioc1:5065

Some points I had to learn:
* Each entry has an objectclass. The schema for "ProcessVariable" would for example require a "cn" attribute, with optional "cas", "description" and maybe other attributes. The schema would also determine if searches for PV names are case-sensitive or not.
* The hierarchical path "fred.linac.sns.epics" translates into a dn "cn=fred,dc=linac,dc=sns,dc=epics" which lists the relative dn of the entry itself and all path elements.
* Each path element must exists, so to bootstrap one has to create entries "dc=epics" and "dc=sns,dc=epics" etc., for which I used the pre-defined "organization" schema.
* To locate the PV 'fred', any of the following LDAP searches would work:
** Scope "base" with base "cn=fred,dc=linac,dc=sns,dc=epics".
** Scope "one" with base "dc=linac,dc=sns,dc=epics" and filter "(cn=fred)".
** Scope "one" with base "dc=linac,dc=sns,dc=epics" and filter "(cn=f*d)", though this might return more records which happen to match the pattern.
** Scope "sub" with base "dc=sns,dc=epics" and filter "(cn=fred)", which would also return an entry with dn "cn=fred,dc=office,dc=sns,dc=epics".
** There is a filter option "~=" for 'approximately equal'. Unclear what exactly defines approximate, but this might be very handy for detecing typos.

=== OpenLDAP ===

OpenLDAP [http://www.openldap.org] is an open-source LDAP
client library for C and an LDAP server which can store the
actual data in /dev/null, a BerkeleyDB, SQL, Perl, a remote LDAP server.

OpenLDAP includes authentication and encrypted (SSL) transport,
replication (single master -> multiple slaves),
and referrals from one server to another one which has more details.

=== EPICS PV Tests ===

Using OpenLDAP-stable-20050429 and perl-ldap-0.3202 on a 1.3 GHz PowerBook G4
with 780 MB RAM under MacOS X 10.3.8, I used a perl script to create
PV entries, search them, and remove them.
In addition, the 'ldapsearch' that comes with RedHat Enterprise AS 3 was
used to check remote accessibillity.

When trying to list all PVs with an appropriate search pattern,
the default server configuration limits the response to 500 answers.
This was changed such that 'paged' searches which keep requesting data
in increments of e.g. 500 entries are allowed to continue until all data is retrieved.
From the command-line tool, that's done like this:
ldapsearch -x -LLL -E pr=10/noprompt -b 'dc=epics' '(cn=testpv*)' cas

== Performance ==

Based on the default OpenLDAP server config with an additional
index "cn pres,eq" on the common name of the PVs,
PVs with names 'testrec0000000001', 'testrec0000000002' etc.
were added, then looked up one-by-one via their exact name,
and finially deleted one by one.

When using a C++ test client based on the OpenLDAP library,
the results for smaller numbers are:
Add 10000 records : 22.76 secs
Locate 10000 records : 6.49 secs
Delete 10000 records : 22.20 secs

In another test, a very rough estimated PV count of the SNS linac
was used:
Add 200000 records : 675.89 secs (38.74 CPU)
Locate 200000 records : 142.85 secs (27.91 CPU)
Delete 200000 records : 807.28 secs (37.28 CPU)

Those 200000 records use about 900MB of file space.
The results indicate that one can add 300 .. 440 records/sec,
locate 1400.. 1540 records/sec and delete 250..450 records/sec.
Without an index, the addition and deletion will be faster
at the expense of lookup times.

A typical SNS LLRF IOCs has 2300 records.
On startup, sending those to the directory server would take around 7 seconds.
A typical SNS LLRF overview screen has about 400 PVs,
and current connection times vary from less than a second to
several tens of seconds, depending on how well the search requests
reach the IOCs.
Resolving their CA servers would take about 0.3 seconds with LDAP,
which would then be followed by the time required to actually connect
to those servers.

In previous test using perl, the individual PV search actually used an LDIF
filter with exact match like 'testrec0000000001'. In addition, all PVs matching
a filter 'testrec*' were retrieved, and no index was used:
Adding 1000 records: 4 wallclock secs ( 2.29 usr + 0.14 sys = 2.43 CPU)
Locating 1000 records: 49 wallclock secs ( 4.10 usr + 0.21 sys = 4.31 CPU)
Match all 1000: 1 wallclock secs ( 1.18 usr + 0.02 sys = 1.20 CPU)
Delete 1000 records: 4 wallclock secs ( 1.35 usr + 0.14 sys = 1.49 CPU)

When locating individual records via the complete LDIF base without a filter,
the search is much faster:
Locating 1000 records: 5 wallclock secs ( 3.20 usr + 0.18 sys = 3.38 CPU)

When adding an "index cn pres,eq" to the server config, the results are the
same for both the filter and the base search case.
No difference observed when tripling the cachesize from the default of 1000.
The behavior scales linearly with the number of channels,
always a little over 200 additions or lookups per second:
Adding 10000 records: 47 wallclock secs (21.72 usr + 1.28 sys = 23.00 CPU)
Locating 10000 records: 44 wallclock secs (32.20 usr + 1.55 sys = 33.75 CPU)
Match all 10000: 15 wallclock secs (12.15 usr + 0.64 sys = 12.79 CPU)
Delete 10000 records: 38 wallclock secs (15.41 usr + 1.16 sys = 16.57 CPU)

Adding 50000 records: 243 wallclock secs (110.36 usr + 7.18 sys = 117.54 CPU)
Locating 50000 records: 226 wallclock secs (164.97 usr + 7.67 sys = 172.64 CPU)
Match all 50000: 80 wallclock secs (63.09 usr + 3.42 sys = 66.51 CPU)
Delete 50000 records: 219 wallclock secs (82.11 usr + 6.61 sys = 88.72 CPU)

Adding 200000 records: 1293 wallclock secs (483.65 usr + 33.20 sys = 516.85 CPU)

"index cn,dc pres,eq,approx,sub" takes longer to insert/delete
without improved search performance:
Adding 10000 records: 104 wallclock secs (26.25 usr + 1.67 sys = 27.92 CPU)
Locating 10000 records: 45 wallclock secs (32.86 usr + 1.55 sys = 34.41 CPU)
Match all 10000: 15 wallclock secs (12.31 usr + 0.47 sys = 12.78 CPU)
Delete 10000 records: 97 wallclock secs (17.89 usr + 1.34 sys = 19.23 CPU)

The CPU load is a rough 50/50 split between the perl and slapd processes.
The perl ldap library is 100% perl, including the network handling and
quite some data conversions from arrays into hashes and back,
so a pure C client might be a little faster.

Though an index slows down the insertion of PVs, it speeds up certain
retrieval methods, as probably desired for an EPICS directory server.
The search mechanism is based on round-trip requests.
Searching PVs one PV name at a time is slower than requesting all
PVs that match a pattern. Unfortunately, typical CA clients will
have to request data for specific PV names, not by pattern.

==== JOH: For comparison purposes, here is the performance of CA's built-in name resolution. ====

Testing with 100000 channels named joh:bill
channel connect test
Elapsed Per Item = 0.00001683 sec, 59427.3 Items per sec, 31.4 Mbps
Search tries per chan - mean=1.000930 std dev=0.030482 min=1.000000 max=2.000000

== API ==
[[V4 CA Interfaces]] already has a lookup interface for a name service
that uses asynchronous callbacks and a property catalog to return the results.

This is the interface I used for the test code. It is synchronous without configurable timeout (bad), but includes addition and removal of names (good), and the PVEntry lists the actual properties of an entry.

/// Client-Interface to the EPICS directory
class Directory
{
public:
/// Constuctor
Directory();

/// Destructor (will disconnect)
~Directory();

/// Connect to directory server
/// Better: URL ala "LDAP://cn=Manager,dc=epics:secret@localhost:389"
/// which would allow other services without changing the API?
bool connect(const char *host = "localhost:389",
const char *user = "cn=Manager,dc=epics",
const char *password = "secret");

/// Disconnect from directory server
void disconnect();

/// Directory entry for one PV

/// Unclear how to best deal with this with regard to real-time OS
/// where we don't want to allocate too much mem at runtime.
/// This API allows caller to reuse the same 'PVEntry' over and over.
static const size_t SLEN = 100;
static const size_t MAXCAS = 3;
static const char PATH_SEP = '/';
class PVEntry
{
public:
char pv[SLEN];
char path[SLEN];
char description[SLEN];
char cas[MAXCAS][SLEN];
};

bool Directory::add_pventry(const PVEntry *pv);

/// Given pv->pv, fills remaining PVEntry information from directory
bool get_pventry(PVEntry *pv);

bool delete_pventry(const char *pv, const char *path);
};

=== To be investigated ===

* How to access it from vxWorks
* How does an LDAP server used for EPICS cooperate with existing LDAP servers for DNS, email etc. Should it be one and the same? Use special port numbers for 'EPICS' LDAP?
* API: What type of API would EPICS tools use? Whatever LDAP library they use? An 'EPICS wrapper' around LDAP? Gasper suggested to look at the Java JNDI API for inspiration.
* Common Database headaches:
** To simply get a PV into LDAP, one has to check if this PV already exists and then either 'add' or 'modify'.
** What if a channel is no longer available? An IOC shutting down could remove PVs from the LDAP server, but an IOC that crashes won't.
* Replication: How to use it, how fast is it etc.
* Authentication and encryption: How hard is it to configure?

V4 Name Server

2005-07-07T16:02:23Z

KayKasemir: Added test API

== Directory Server ==

EPICS ChannelAccess currently uses a broadcast mechanism for resolving
channel names.
Advantages:
* Minimal if not zero initial setup.
* At least initially very fast, because a client can send multiple name requests in one network packet, all servers receive it simultaneously and can answer to known names.

Disadvantages:
* Unclear how to extend this service to redundant servers, archived data, ...
* Currently, no wildcard searches.
* Currently, no statistics on available number of channels, types of records, ...
* Bigger installations run into problems with broadcast traffic:
** All devices see the requests, even though only one server has a given channel name.
** Continued searches for unresolved names to overcome UDP limitations.

As Larry Hoff pointed out, we really want a ''Directory'' server for
EPICS, something beyond a name server. A directory will not only map PV
names to IP addresses of ChannelAccess servers, but also support
* wildcard searches, reports on number of channels per IOC etc.
* redundant servers
* info about reduntant IOCs with the same PV, archived data for a PV
* backup/restore locations for a PV
* PV meta information like engineer-in-charge, CA security rules, ...

== Channels, Records, PVs, Properties ==
We currently have records with fields and channels with properties.
Each field of a record can become a channel name,
the field itself ends up in the 'value' property of the channel,
and the record decides how to fill the remaining properties.

Will the directory list all record names or all possible channels?
I think only record names.

Will it include the record type? Not enough information if we add user-defined fields.
Will it lists all fields of a record?

I think for now that only listing record names is enough in order to allow
connections.

The CA client would then have to query the CA server for all the available properties
of a PV, and note that properties might even change at runtime when we allow
online add & delete.

Whenever a tool like a command-line 'caget' or the 'probe' GUI requires a PV name,
it needs to be decided what properties "fred" would access. In the past, it was equal
to "fred.VAL". There is much more detail in the 'view' section of the
[[V4 DBD Statement Syntax]].

== LDAP, Directory, RDB, Schema, Entries, dn, cn, dc, ... ==

The ''Lightweight Directory Access Protocol'' (LDAP) is a network protocol.
It defines how to access data over the network, regardless of language
or underlying data storage. In contrast, RDBs like Oracle or MySQL define the
data storage and SQL dialect, while the network access to the data is then
added almost as an afterthought.

LDAP is meant as a Directory for simple attribute-based information
for fast, high volume lookup. Simple search filters are supported:
Patterns, "and", "or". In contrast to RDBs, there is no support for
arbitrary relations between entries, there are no transactions nor rollback.

There are open-source servers for LDAP, and client libraries for
C, Perl, Java and other languages. MacOSX, Linux, Windows 2000
already include LDAP clients. MS ActiveDirectory uses LDAP.

LDAP requires the data to be organized into hierarchical ''Entries''.
Each Entry has a globally unique ''Distinguished Name'' (dn),
and various ''Attributes'', that is Type/Value pairs.
The ''Schema'' defines which attributes an entry must have and which ones
it might have. There are existing schemas for DNS-type data or personell
information, including types like ''Common Name'' (cn) or ''Domain Component'' (dc),
but one can add custom schemata. Values might include binary data, e.g. images.

=== Mapping EPICS PV Information to LDAP ===

Each LDAP entry must have a unique name (dn). EPICS PVs must be unique as well,
but only within the search domain currently defined by the EPICS_CA_ADDR_LIST.
It might make sense to synchronize LDAP servers across these boundaries,
in which case the LDAP dn will have to include more than just the PV name.
For example, one could have a PV "fred" in both the accelerator and office network
of the SNS, and enter them into an SNS-wide LDAP directory like this:

fred.linac.sns.epics: cas="linacioc1:5065"
fred.office.sns.epics: cas="testioc47.sns.ornl.gov:7987", description="Fred's test PV"

In this example, the directory includes the ChannelAccess server for both PVs,
and in one case also a description.

While an EPICS-specific tool might present the data as shown above,
most generic LDAP tools and APIs use the ''LDAP Data Interchange Format'' (LDIF).
In LDIF, part of the above data could look like this:

dn: dc=epics
objectclass: dcObject
objectclass: organization
o: Root of all EPICS PVs
dc: epics

dn: dc=sns,dc=epics
# Details omitted; similar to previous entry

dn: dc=linac,dc=sns,dc=epics
objectclass: dcObject
objectclass: organization
o: Root of all EPICS PVs in the SNS Linac
dc: linac

dn: cn=fred,dc=linac,dc=sns,dc=epics
objectclass: ProcessVariable
cn: fred
cas: linacioc1:5065

Some points I had to learn:
* Each entry has an objectclass. The schema for "ProcessVariable" would for example require a "cn" attribute, with optional "cas", "description" and maybe other attributes. The schema would also determine if searches for PV names are case-sensitive or not.
* The hierarchical path "fred.linac.sns.epics" translates into a dn "cn=fred,dc=linac,dc=sns,dc=epics" which lists the relative dn of the entry itself and all path elements.
* Each path element must exists, so to bootstrap one has to create entries "dc=epics" and "dc=sns,dc=epics" etc., for which I used the pre-defined "organization" schema.
* To locate the PV 'fred', any of the following LDAP searches would work:
** Scope "base" with base "cn=fred,dc=linac,dc=sns,dc=epics".
** Scope "one" with base "dc=linac,dc=sns,dc=epics" and filter "(cn=fred)".
** Scope "one" with base "dc=linac,dc=sns,dc=epics" and filter "(cn=f*d)", though this might return more records which happen to match the pattern.
** Scope "sub" with base "dc=sns,dc=epics" and filter "(cn=fred)", which would also return an entry with dn "cn=fred,dc=office,dc=sns,dc=epics".
** There is a filter option "~=" for 'approximately equal'. Unclear what exactly defines approximate, but this might be very handy for detecing typos.

=== OpenLDAP ===

OpenLDAP [http://www.openldap.org] is an open-source LDAP
client library for C and an LDAP server which can store the
actual data in /dev/null, a BerkeleyDB, SQL, Perl, a remote LDAP server.

OpenLDAP includes authentication and encrypted (SSL) transport,
replication (single master -> multiple slaves),
and referrals from one server to another one which has more details.

=== EPICS PV Tests ===

Using OpenLDAP-stable-20050429 and perl-ldap-0.3202 on a 1.3 GHz PowerBook G4
with 780 MB RAM under MacOS X 10.3.8, I used a perl script to create
PV entries, search them, and remove them.
In addition, the 'ldapsearch' that comes with RedHat Enterprise AS 3 was
used to check remote accessibillity.

When trying to list all PVs with an appropriate search pattern,
the default server configuration limits the response to 500 answers.
This was changed such that 'paged' searches which keep requesting data
in increments of e.g. 500 entries are allowed to continue until all data is retrieved.
From the command-line tool, that's done like this:
ldapsearch -x -LLL -E pr=10/noprompt -b 'dc=epics' '(cn=testpv*)' cas

== Performance ==

Based on the default OpenLDAP server config with an additional
index "cn pres,eq" on the common name of the PVs,
PVs with names 'testrec0000000001', 'testrec0000000002' etc.
were added, then looked up one-by-one via their exact name,
and finially deleted one by one.

When using a C++ test client based on the OpenLDAP library,
the results for smaller numbers are:
Add 10000 records : 22.76 secs
Locate 10000 records : 6.49 secs
Delete 10000 records : 22.20 secs

In another test, a very rough estimated PV count of the SNS linac
was used:
Add 200000 records : 675.89 secs (38.74 CPU)
Locate 200000 records : 142.85 secs (27.91 CPU)
Delete 200000 records : 807.28 secs (37.28 CPU)

Those 200000 records use about 900MB of file space.
The results indicate that one can add 300 .. 440 records/sec,
locate 1400.. 1540 records/sec and delete 250..450 records/sec.
Without an index, the addition and deletion will be faster
at the expense of lookup times.

A typical SNS LLRF IOCs has 2300 records.
On startup, sending those to the directory server would take around 7 seconds.
A typical SNS LLRF overview screen has about 400 PVs,
and current connection times vary from less than a second to
several tens of seconds, depending on how well the search requests
reach the IOCs.
Resolving their CA servers would take about 0.3 seconds with LDAP,
which would then be followed by the time required to actually connect
to those servers.

In previous test using perl, the individual PV search actually used an LDIF
filter with exact match like 'testrec0000000001'. In addition, all PVs matching
a filter 'testrec*' were retrieved, and no index was used:
Adding 1000 records: 4 wallclock secs ( 2.29 usr + 0.14 sys = 2.43 CPU)
Locating 1000 records: 49 wallclock secs ( 4.10 usr + 0.21 sys = 4.31 CPU)
Match all 1000: 1 wallclock secs ( 1.18 usr + 0.02 sys = 1.20 CPU)
Delete 1000 records: 4 wallclock secs ( 1.35 usr + 0.14 sys = 1.49 CPU)

When locating individual records via the complete LDIF base without a filter,
the search is much faster:
Locating 1000 records: 5 wallclock secs ( 3.20 usr + 0.18 sys = 3.38 CPU)

When adding an "index cn pres,eq" to the server config, the results are the
same for both the filter and the base search case.
No difference observed when tripling the cachesize from the default of 1000.
The behavior scales linearly with the number of channels,
always a little over 200 additions or lookups per second:
Adding 10000 records: 47 wallclock secs (21.72 usr + 1.28 sys = 23.00 CPU)
Locating 10000 records: 44 wallclock secs (32.20 usr + 1.55 sys = 33.75 CPU)
Match all 10000: 15 wallclock secs (12.15 usr + 0.64 sys = 12.79 CPU)
Delete 10000 records: 38 wallclock secs (15.41 usr + 1.16 sys = 16.57 CPU)

Adding 50000 records: 243 wallclock secs (110.36 usr + 7.18 sys = 117.54 CPU)
Locating 50000 records: 226 wallclock secs (164.97 usr + 7.67 sys = 172.64 CPU)
Match all 50000: 80 wallclock secs (63.09 usr + 3.42 sys = 66.51 CPU)
Delete 50000 records: 219 wallclock secs (82.11 usr + 6.61 sys = 88.72 CPU)

Adding 200000 records: 1293 wallclock secs (483.65 usr + 33.20 sys = 516.85 CPU)

"index cn,dc pres,eq,approx,sub" takes longer to insert/delete
without improved search performance:
Adding 10000 records: 104 wallclock secs (26.25 usr + 1.67 sys = 27.92 CPU)
Locating 10000 records: 45 wallclock secs (32.86 usr + 1.55 sys = 34.41 CPU)
Match all 10000: 15 wallclock secs (12.31 usr + 0.47 sys = 12.78 CPU)
Delete 10000 records: 97 wallclock secs (17.89 usr + 1.34 sys = 19.23 CPU)

The CPU load is a rough 50/50 split between the perl and slapd processes.
The perl ldap library is 100% perl, including the network handling and
quite some data conversions from arrays into hashes and back,
so a pure C client might be a little faster.

Though an index slows down the insertion of PVs, it speeds up certain
retrieval methods, as probably desired for an EPICS directory server.
The search mechanism is based on round-trip requests.
Searching PVs one PV name at a time is slower than requesting all
PVs that match a pattern. Unfortunately, typical CA clients will
have to request data for specific PV names, not by pattern.

==== JOH: For comparison purposes, here is the performance of CA's built-in name resolution. ====

Testing with 100000 channels named joh:bill
channel connect test
Elapsed Per Item = 0.00001683 sec, 59427.3 Items per sec, 31.4 Mbps
Search tries per chan - mean=1.000930 std dev=0.030482 min=1.000000 max=2.000000

== API ==
[[V4 CA Interfaces]] already has a lookup interface for a name service
that uses asynchronous callbacks and a property catalog to return the results.

This is the interface I used for the test code. It is synchronous without configurable timeout (bad), but includes addition and removal of names (good), and the PVEntry lists the actual properties of an entry.

/// Client-Interface to the EPICS directory
class Directory
{
public:
/// Constuctor
Directory();

/// Destructor (will disconnect)
~Directory();

/// Connect to directory server
bool connect(const char *host = "localhost:389",
const char *user = "cn=Manager,dc=epics",
const char *password = "secret");

/// Disconnect from directory server
void disconnect();

/// Get some info string
void api_info(char *buf, size_t len);

/// Useless API
void dump_PVs();

/// Directory entry for one PV

/// Unclear how to best deal with this with regard to real-time OS
/// where we don't want to allocate too much mem at runtime.
/// This API allows caller to reuse the same 'PVEntry' over and over.
static const size_t SLEN = 100;
static const size_t MAXCAS = 3;
static const char PATH_SEP = '/';
class PVEntry
{
public:
char pv[SLEN];
char path[SLEN];
char description[SLEN];
char cas[MAXCAS][SLEN];
};

bool Directory::add_pventry(const PVEntry *pv);

/// Given pv->pv, fills remaining PVEntry information from directory
bool get_pventry(PVEntry *pv);

bool delete_pventry(const char *pv, const char *path);
};

=== To be investigated ===

* How to access it from vxWorks
* How does an LDAP server used for EPICS cooperate with existing LDAP servers for DNS, email etc. Should it be one and the same? Use special port numbers for 'EPICS' LDAP?
* API: What type of API would EPICS tools use? Whatever LDAP library they use? An 'EPICS wrapper' around LDAP? Gasper suggested to look at the Java JNDI API for inspiration.
* Common Database headaches:
** To simply get a PV into LDAP, one has to check if this PV already exists and then either 'add' or 'modify'.
** What if a channel is no longer available? An IOC shutting down could remove PVs from the LDAP server, but an IOC that crashes won't.
* Replication: How to use it, how fast is it etc.
* Authentication and encryption: How hard is it to configure?

V4 User-defined fields

2005-07-06T13:52:28Z

KayKasemir: Link to record building blocks, Ben's comments

== Overview ==
Records, the building blocks of an EPICS run-time database,
are much more powerful than the fundamental commands
of programming languages like C, C++, LabVIEW or PLC
ladder logic: A record like the AI record provides scanning,
various conversions, alarms, smoothing and more.

On the downside, very few record instances use the full functionality
of the record type. Extending their functionality is rather involved,
and very few custom record types get shared in the community.

If it was easier to create, modify and extend records,
we could start with simpler record types and extend them
as needed.

This is a suggestion for supporting user-defined fields in V4,
allowing the user to add fields to a record instance without
first having to create a new record type.
There is an alternate proposal,
[[V4 Design: Assembling Record Support]],
that would simplify the creation of new record types.

== User-defined fields ==

For example, I'd like to allow users to define "analog input" records
with the usual fields '''and''' allow them to add new fields to some
instance without having to create a new record type:

calc("fred")
{
field(SCAN, "1 second")
user_field(SMOO, iocFloat64T, "0.5", smoo_handler)
}

This record will have a 'SMOO' field of type double (float 64) that presumably implements
smoothing in the user-supplied smoo_handler.

The idea is that one can add these user-defined fields on a per-instance basis
to pretty much any record type simply by editing the DB file and loading the
handler code, without having to recompile the rest of EPICS base.

Example code for a ''handler'' and what the ''database'' code would have to do
follows.

=== database.h ===

#include <iostream>
#include <string>
#include <list>

using namespace std;

enum iocType
{
iocUnknownT,iocBooleanT,iocOctetT,
iocInt16T,iocUInt16T,iocInt32T,iocUInt32T,iocInt64T,iocUInt64T,
iocFloat32T,iocFloat64T,
iocStringT,iocMenuT,iocEnumT,iocLinkT,iocDeviceT,iocArrayT
};
// ------------------------------------------------------------------
// Support for user-defined fields in base
// ------------------------------------------------------------------
// forwards
class record;
class user_field_handler;

// Information for one user-defined field
class user_field_data
{
public:
string name;
iocType type;
void *data;
string parm;
user_field_handler *handler;
};

// The 'handler' specified for a user field needs to implement
// this interface:
class user_field_handler
{
public:
virtual void init(user_field_data *field, record *rec) {}
virtual void update(user_field_data *field, record *rec) {}
virtual void destroy(user_field_data *field, record *rec) {}
};

// Records need to support hooks similar to Java 'listeners'
// so that user fields can hook into record processing.
// Unclear at what levels hooks are needed.
class got_data_hook
{
public: virtual void run_got_data_hook()=0;
};
class post_monitor_hook
{
public: virtual void run_post_monitor_hook()=0;
};

// Pieces of record code in order to show where the hooks
// are handled inside of 'process()'
class record
{
public:
record(string name) : name(name) {}

void add_user_field(string name, iocType type, string parm,
user_field_handler *handler)
{
user_field_data ufd;
ufd.name = name;
ufd.type = type;
ufd.parm = parm;
ufd.handler = handler;
user_fields.push_back(ufd);
}
void add_got_data_hook(got_data_hook *hook)
{
got_data_hooks.push_back(hook);
}
// TODO: remove_got_data_hook();
void add_post_monitor_hook(post_monitor_hook *hook)
{
post_monitor_hooks.push_back(hook);
}
// TODO: remove_post_monitor_hook();

void iocInit();

void process();
private:
string name;
list<user_field_data> user_fields;
list<got_data_hook *> got_data_hooks;
list<post_monitor_hook *> post_monitor_hooks;
};

=== database.cpp ===

#include "database.h"

void *get_iocType_mem(iocType type)
{
switch (type)
{
case iocFloat32T: return new float;
case iocFloat64T: return new double;
case iocStringT: return new string;
}
return 0;
}

void record::iocInit()
{
cout << "record::iocInit(" << name << ")\n";
list<user_field_data>::iterator ufi;
for (ufi = user_fields.begin(); ufi != user_fields.end(); ++ufi)
{
if ((ufi->data = get_iocType_mem(ufi->type)) != 0)
ufi->handler->init(&(*ufi), this);
else
ufi->type = iocUnknownT;
}
}

void record::process()
{
cout << "record::process(" << name << ")\n";
#ifdef TODO
status=readValue(pai); /* read the new value */
if ( !pact && pai->pact ) return(0);
pai->pact = TRUE;

recGblGetTimeStamp(pai);
if (status==0) convert(pai);
else if (status==2) status=0;
#endif
list<got_data_hook *>::iterator gdhi;
for (gdhi = got_data_hooks.begin(); gdhi != got_data_hooks.end(); ++gdhi)
(*gdhi)->run_got_data_hook();
#ifdef TODO
checkAlarms(pai);
monitor(pai);
#endif
list<post_monitor_hook *>::iterator pmhi;
for (pmhi=post_monitor_hooks.begin(); pmhi!=post_monitor_hooks.end(); ++pmhi)
(*pmhi)->run_post_monitor_hook();
#ifdef TODO
pai->pact=FALSE;
#endif
}

// TODO:
// Record will need to check all it's user_fields[].name
// in case CA tries to get/put.

=== example.cpp ===

/* Goals:
- Avg or other statistical calc:
deposits calculated data into new fields,
doesn't affect the rest of the record.
- Circ Buffer (archive record):
Similar, does something with the current VAL
outside of the record.
- Put Logging: Simlar.
- SMOO: Can it modify the VAL field?
- BPM combiner of 4 AIs: Unclear.
- conversions (new breakpt. table): unclear.
- FLNK (w/ delays?): Should happen _after_ all else is done.

The following implements handlers for some of the above.

*/
#include "database.h"
// ------------------------------------------------------------------
// MAX (easier to calc. then e.g. running average
// ------------------------------------------------------------------
class max_handler : public user_field_handler, got_data_hook
{
void init(user_field_data *field, record *rec)
{
max = (double *)field->data;
// TODO: val = record->get_field_addr("VAL")
rec->add_got_data_hook(this);
}
void run_got_data_hook()
{
// if (*val > *max) *max = *val;
cout << "Max is " << *max << "\n";
}
private:
double *max;
};

// ------------------------------------------------------------------
// SMOO
// ------------------------------------------------------------------
class smoo_handler : public user_field_handler, got_data_hook
{
void init(user_field_data *field, record *rec)
{
smoo = (double *)field->data;
*smoo = atof(field->parm.c_str());
// TODO: val = record->get_field_addr("VAL")
rec->add_got_data_hook(this);
}
void run_got_data_hook()
{
// *val = smoo*(*val) + (1-smoo)*prev_value;
// prev_value = *val;
cout << "Smoothing by " << *smoo << "\n";
}
private:
double *smoo;
double prev_value;
};

// ------------------------------------------------------------------
// FLNK
// ------------------------------------------------------------------
class flnk_handler : public user_field_handler, post_monitor_hook
{
void init(user_field_data *field, record *rec)
{
link_text = (string *)field->data;
*link_text = field->parm;
update(field, rec);
rec->add_post_monitor_hook(this);
}
void update(user_field_data *field, record *rec)
{
// TODO: ink_info = parse_link_info_from_string(*link_text);
link_info = *link_text;
}
void run_post_monitor_hook()
{
cout << "FLNKing to " << link_info << "\n";
// TODO: dbProcessLink(this->link_info);
// Or with additional delay parm:
// wdStart(delay, dbProcessLink, this->link_info); ?
}
private:
string *link_text;
string link_info;
};

// ------------------------------------------------------------------
// Example database snippet and how it's used
// ------------------------------------------------------------------
/*
ai("fred")
{
# NAME, TYPE, PARM, HANDLER
user_field(smoo, iocFloat64T, "0.5", smoo_handler)
user_field(max, iocFloat64T, "", max_handler)
user_field(flnk1, iocStringT, "recordA", flnk_handler)
user_field(flnk2, iocStringT, "recordB", flnk_handler)
user_field(flnk3, iocStringT, "recordC", flnk_handler)
# In these examples, the PARM is the initial value of the field.
# But it could be any string that's used to configure the handler:
# user_field(syslog, iocStringT, "server=124.0.0.5:9876,interval=1", syslog_handler)
}
*/
int main()
{
// This is sort of what would need to happen inside dbLoadDatabase().
// The tricky part is the "new xxx_handler":
// Each handler will have to use the registry to register a factory
// method so that dbLoadDatabase can invoke "new xxx_handler" without
// recompilation.
record fred("fred");
fred.add_user_field("smoo", iocFloat64T, "0.5", new smoo_handler());
fred.add_user_field("max", iocFloat64T, "", new max_handler());
fred.add_user_field("flnk1", iocStringT, "recordA", new flnk_handler());
fred.add_user_field("flnk2", iocStringT, "recordB", new flnk_handler());
fred.add_user_field("flnk3", iocStringT, "recordC", new flnk_handler());
//
fred.iocInit();
//
fred.process();
cout << "\n";
fred.process();

return 0;
}

/*
When run, this basically processes the record and the
code for the user-defined fields is invoked as intended:

record::iocInit(fred)
record::process(fred)
Smoothing by 0.5
Max is 0
FLNKing to recordA
FLNKing to recordB
FLNKing to recordC

record::process(fred)
Smoothing by 0.5
Max is 0
FLNKing to recordA
FLNKing to recordB
FLNKing to recordC

UNCLEAR:
Is string parm enough, or are structs requires?

I believe that all the goals 1-7 can be handled
by providing the appropriate hooks.
Question: How many hooks will that be?

*/

== Comments ==
The example code for user_field_handler::init()
assumes that the record has
a routine get_field_addr(string name) that provides a raw pointer
to each field of a record. Would have to use dataAccess or whatever the
runtime database will ultimately provide.

Some pro and cons when comparing this type of user-defined field to writing a custom record:

=== Pro ===
* One can add fields per record instance as needed. No need to create a possibly confusing plethora of specialized record types: BasicAI, MaxAI, AverageAI, AverageAndMaxAI, BasicAO, MaxAO, ...
* Under vxWorks, one can do so without recompilation:
ld <smoo_handlerLib.o
dbLoadDataBase("..../records_that_use_smoo_handler")

=== Contra ===
* The actions inside a user-field handler are limited to quick, synchronous actions.
* In order to handle the goals mentioned in example.cpp, only two hooks into the record's process() routine are needed. Unclear if this is sufficient in the long run.
* While easy to use, the code requires more runtime checks, more type casts, more boilerplate code. For example, the smoo_handler should react accordingly if the record does not have a numeric value field. In a custom record type, compile-time checks would reduce the code size and increase maintainabililty.

V4 Name Server

2005-06-29T16:17:48Z

KayKasemir: views

== Directory Server ==

EPICS ChannelAccess currently uses a broadcast mechanism for resolving
channel names.
Advantages:
* Minimal if not zero initial setup.
* At least initially very fast, because a client can send multiple name requests in one network packet, all servers receive it simultaneously and can answer to known names.

Disadvantages:
* Unclear how to extend this service to redundant servers, archived data, ...
* Currently, no wildcard searches.
* Currently, no statistics on available number of channels, types of records, ...
* Bigger installations run into problems with broadcast traffic:
** All devices see the requests, even though only one server has a given channel name.
** Continued searches for unresolved names to overcome UDP limitations.

As Larry Hoff pointed out, we really want a ''Directory'' server for
EPICS, something beyond a name server. A directory will not only map PV
names to IP addresses of ChannelAccess servers, but also support
* wildcard searches, reports on number of channels per IOC etc.
* redundant servers
* info about reduntant IOCs with the same PV, archived data for a PV
* backup/restore locations for a PV
* PV meta information like engineer-in-charge, CA security rules, ...

== Channels, Records, PVs, Properties ==
We currently have records with fields and channels with properties.
Each field of a record can become a channel name,
the field itself ends up in the 'value' property of the channel,
and the record decides how to fill the remaining properties.

Will the directory list all record names or all possible channels?
I think only record names.

Will it include the record type? Not enough information if we add user-defined fields.
Will it lists all fields of a record?

I think for now that only listing record names is enough in order to allow
connections.

The CA client would then have to query the CA server for all the available properties
of a PV, and note that properties might even change at runtime when we allow
online add & delete.

Whenever a tool like a command-line 'caget' or the 'probe' GUI requires a PV name,
it needs to be decided what properties "fred" would access. In the past, it was equal
to "fred.VAL". There is much more detail in the 'view' section of the
[[V4 DBD Statement Syntax]].

== LDAP, Directory, RDB, Schema, Entries, dn, cn, dc, ... ==

The ''Lightweight Directory Access Protocol'' (LDAP) is a network protocol.
It defines how to access data over the network, regardless of language
or underlying data storage. In contrast, RDBs like Oracle or MySQL define the
data storage and SQL dialect, while the network access to the data is then
added almost as an afterthought.

LDAP is meant as a Directory for simple attribute-based information
for fast, high volume lookup. Simple search filters are supported:
Patterns, "and", "or". In contrast to RDBs, there is no support for
arbitrary relations between entries, there are no transactions nor rollback.

There are open-source servers for LDAP, and client libraries for
C, Perl, Java and other languages. MacOSX, Linux, Windows 2000
already include LDAP clients. MS ActiveDirectory uses LDAP.

LDAP requires the data to be organized into hierarchical ''Entries''.
Each Entry has a globally unique ''Distinguished Name'' (dn),
and various ''Attributes'', that is Type/Value pairs.
The ''Schema'' defines which attributes an entry must have and which ones
it might have. There are existing schemas for DNS-type data or personell
information, including types like ''Common Name'' (cn) or ''Domain Component'' (dc),
but one can add custom schemata. Values might include binary data, e.g. images.

=== Mapping EPICS PV Information to LDAP ===

Each LDAP entry must have a unique name (dn). EPICS PVs must be unique as well,
but only within the search domain currently defined by the EPICS_CA_ADDR_LIST.
It might make sense to synchronize LDAP servers across these boundaries,
in which case the LDAP dn will have to include more than just the PV name.
For example, one could have a PV "fred" in both the accelerator and office network
of the SNS, and enter them into an SNS-wide LDAP directory like this:

fred.linac.sns.epics: cas="linacioc1:5065"
fred.office.sns.epics: cas="testioc47.sns.ornl.gov:7987", description="Fred's test PV"

In this example, the directory includes the ChannelAccess server for both PVs,
and in one case also a description.

While an EPICS-specific tool might present the data as shown above,
most generic LDAP tools and APIs use the ''LDAP Data Interchange Format'' (LDIF).
In LDIF, part of the above data could look like this:

dn: dc=epics
objectclass: dcObject
objectclass: organization
o: Root of all EPICS PVs
dc: epics

dn: dc=sns,dc=epics
# Details omitted; similar to previous entry

dn: dc=linac,dc=sns,dc=epics
objectclass: dcObject
objectclass: organization
o: Root of all EPICS PVs in the SNS Linac
dc: linac

dn: cn=fred,dc=linac,dc=sns,dc=epics
objectclass: ProcessVariable
cn: fred
cas: linacioc1:5065

Some points I had to learn:
* Each entry has an objectclass. The schema for "ProcessVariable" would for example require a "cn" attribute, with optional "cas", "description" and maybe other attributes. The schema would also determine if searches for PV names are case-sensitive or not.
* The hierarchical path "fred.linac.sns.epics" translates into a dn "cn=fred,dc=linac,dc=sns,dc=epics" which lists the relative dn of the entry itself and all path elements.
* Each path element must exists, so to bootstrap one has to create entries "dc=epics" and "dc=sns,dc=epics" etc., for which I used the pre-defined "organization" schema.
* To locate the PV 'fred', any of the following LDAP searches would work:
** Scope "base" with base "cn=fred,dc=linac,dc=sns,dc=epics".
** Scope "one" with base "dc=linac,dc=sns,dc=epics" and filter "(cn=fred)".
** Scope "one" with base "dc=linac,dc=sns,dc=epics" and filter "(cn=f*d)", though this might return more records which happen to match the pattern.
** Scope "sub" with base "dc=sns,dc=epics" and filter "(cn=fred)", which would also return an entry with dn "cn=fred,dc=office,dc=sns,dc=epics".
** There is a filter option "~=" for 'approximately equal'. Unclear what exactly defines approximate, but this might be very handy for detecing typos.

=== OpenLDAP ===

OpenLDAP [http://www.openldap.org] is an open-source LDAP
client library for C and an LDAP server which can store the
actual data in /dev/null, a BerkeleyDB, SQL, Perl, a remote LDAP server.

OpenLDAP includes authentication and encrypted (SSL) transport,
replication (single master -> multiple slaves),
and referrals from one server to another one which has more details.

=== EPICS PV Tests ===

Using OpenLDAP-stable-20050429 and perl-ldap-0.3202 on a 1.3 GHz PowerBook G4
with 780 MB RAM under MacOS X 10.3.8, I used a perl script to create
PV entries, search them, and remove them.
In addition, the 'ldapsearch' that comes with RedHat Enterprise AS 3 was
used to check remote accessibillity.

When trying to list all PVs with an appropriate search pattern,
the default server configuration limits the response to 500 answers.
This was changed such that 'paged' searches which keep requesting data
in increments of e.g. 500 entries are allowed to continue until all data is retrieved.
From the command-line tool, that's done like this:
ldapsearch -x -LLL -E pr=10/noprompt -b 'dc=epics' '(cn=testpv*)' cas

== Performance ==

Based on the default OpenLDAP server config with an additional
index "cn pres,eq" on the common name of the PVs,
PVs with names 'testrec0000000001', 'testrec0000000002' etc.
were added, then looked up one-by-one via their exact name,
and finially deleted one by one.

When using a C++ test client based on the OpenLDAP library,
the results for smaller numbers are:
Add 10000 records : 22.76 secs
Locate 10000 records : 6.49 secs
Delete 10000 records : 22.20 secs

In another test, a very rough estimated PV count of the SNS linac
was used:
Add 200000 records : 675.89 secs (38.74 CPU)
Locate 200000 records : 142.85 secs (27.91 CPU)
Delete 200000 records : 807.28 secs (37.28 CPU)

Those 200000 records use about 900MB of file space.
The results indicate that one can add 300 .. 440 records/sec,
locate 1400.. 1540 records/sec and delete 250..450 records/sec.
Without an index, the addition and deletion will be faster
at the expense of lookup times.

A typical SNS LLRF IOCs has 2300 records.
On startup, sending those to the directory server would take around 7 seconds.
A typical SNS LLRF overview screen has about 400 PVs,
and current connection times vary from less than a second to
several tens of seconds, depending on how well the search requests
reach the IOCs.
Resolving their CA servers would take about 0.3 seconds with LDAP,
which would then be followed by the time required to actually connect
to those servers.

In previous test using perl, the individual PV search actually used an LDIF
filter with exact match like 'testrec0000000001'. In addition, all PVs matching
a filter 'testrec*' were retrieved, and no index was used:
Adding 1000 records: 4 wallclock secs ( 2.29 usr + 0.14 sys = 2.43 CPU)
Locating 1000 records: 49 wallclock secs ( 4.10 usr + 0.21 sys = 4.31 CPU)
Match all 1000: 1 wallclock secs ( 1.18 usr + 0.02 sys = 1.20 CPU)
Delete 1000 records: 4 wallclock secs ( 1.35 usr + 0.14 sys = 1.49 CPU)

When locating individual records via the complete LDIF base without a filter,
the search is much faster:
Locating 1000 records: 5 wallclock secs ( 3.20 usr + 0.18 sys = 3.38 CPU)

When adding an "index cn pres,eq" to the server config, the results are the
same for both the filter and the base search case.
No difference observed when tripling the cachesize from the default of 1000.
The behavior scales linearly with the number of channels,
always a little over 200 additions or lookups per second:
Adding 10000 records: 47 wallclock secs (21.72 usr + 1.28 sys = 23.00 CPU)
Locating 10000 records: 44 wallclock secs (32.20 usr + 1.55 sys = 33.75 CPU)
Match all 10000: 15 wallclock secs (12.15 usr + 0.64 sys = 12.79 CPU)
Delete 10000 records: 38 wallclock secs (15.41 usr + 1.16 sys = 16.57 CPU)

Adding 50000 records: 243 wallclock secs (110.36 usr + 7.18 sys = 117.54 CPU)
Locating 50000 records: 226 wallclock secs (164.97 usr + 7.67 sys = 172.64 CPU)
Match all 50000: 80 wallclock secs (63.09 usr + 3.42 sys = 66.51 CPU)
Delete 50000 records: 219 wallclock secs (82.11 usr + 6.61 sys = 88.72 CPU)

Adding 200000 records: 1293 wallclock secs (483.65 usr + 33.20 sys = 516.85 CPU)

"index cn,dc pres,eq,approx,sub" takes longer to insert/delete
without improved search performance:
Adding 10000 records: 104 wallclock secs (26.25 usr + 1.67 sys = 27.92 CPU)
Locating 10000 records: 45 wallclock secs (32.86 usr + 1.55 sys = 34.41 CPU)
Match all 10000: 15 wallclock secs (12.31 usr + 0.47 sys = 12.78 CPU)
Delete 10000 records: 97 wallclock secs (17.89 usr + 1.34 sys = 19.23 CPU)

The CPU load is a rough 50/50 split between the perl and slapd processes.
The perl ldap library is 100% perl, including the network handling and
quite some data conversions from arrays into hashes and back,
so a pure C client might be a little faster.

Though an index slows down the insertion of PVs, it speeds up certain
retrieval methods, as probably desired for an EPICS directory server.
The search mechanism is based on round-trip requests.
Searching PVs one PV name at a time is slower than requesting all
PVs that match a pattern. Unfortunately, typical CA clients will
have to request data for specific PV names, not by pattern.

=== To be investigated ===

* How to access it from vxWorks
* How does an LDAP server used for EPICS cooperate with existing LDAP servers for DNS, email etc. Should it be one and the same? Use special port numbers for 'EPICS' LDAP?
* API: What type of API would EPICS tools use? Whatever LDAP library they use? An 'EPICS wrapper' around LDAP? Gasper suggested to look at the Java JNDI API for inspiration.
* Common Database headaches:
** To simply get a PV into LDAP, one has to check if this PV already exists and then either 'add' or 'modify'.
** What if a channel is no longer available? An IOC shutting down could remove PVs from the LDAP server, but an IOC that crashes won't.
* Replication: How to use it, how fast is it etc.
* Authentication and encryption: How hard is it to configure?

V4 CA Client User Interface

2005-06-29T15:42:43Z

KayKasemir: channel::getProperties?

V4 CA Client User Interface

2005-06-27T19:44:33Z

KayKasemir: /* Directory */

V4 Name Server

2005-06-27T19:33:32Z

KayKasemir: defaults, properties

== Directory Server ==

EPICS ChannelAccess currently uses a broadcast mechanism for resolving
channel names.
Advantages:
* Minimal if not zero initial setup.
* At least initially very fast, because a client can send multiple name requests in one network packet, all servers receive it simultaneously and can answer to known names.

Disadvantages:
* Unclear how to extend this service to redundant servers, archived data, ...
* Currently, no wildcard searches.
* Currently, no statistics on available number of channels, types of records, ...
* Bigger installations run into problems with broadcast traffic:
** All devices see the requests, even though only one server has a given channel name.
** Continued searches for unresolved names to overcome UDP limitations.

As Larry Hoff pointed out, we really want a ''Directory'' server for
EPICS, something beyond a name server. A directory will not only map PV
names to IP addresses of ChannelAccess servers, but also support
* wildcard searches, reports on number of channels per IOC etc.
* redundant servers
* info about reduntant IOCs with the same PV, archived data for a PV
* backup/restore locations for a PV
* PV meta information like engineer-in-charge, CA security rules, ...

== Channels, Records, PVs, Properties ==
We currently have records with fields and channels with properties.
Each field of a record can become a channel name,
the field itself ends up in the 'value' property of the channel,
and the record decides how to fill the remaining properties.

Will the directory list all record names or all possible channels?
I think only record names.

Will it include the record type? Not enough information if we add user-defined fields.
Will it lists all fields of a record?

I think for now that only listing record names is enough in order to allow
connections.

The CA client would then have to query the CA server for all the available properties
of a PV, and note that properties might even change at runtime when we allow
online add & delete.

Whenever a tool like a command-line 'caget' or the 'probe' GUI requires a PV name,
the convention might be that "fred" will address all properties of the channel "fred".
In order to get the value, one would have to use "fred.value".
Note that the "fred" == "fred.VAL" default would no longer apply.
This change would scale better when accessing hierarchical properties:
"fred.limits" would get all limits, while "fred.limits.display.high" would only get
the requested element.

== LDAP, Directory, RDB, Schema, Entries, dn, cn, dc, ... ==

The ''Lightweight Directory Access Protocol'' (LDAP) is a network protocol.
It defines how to access data over the network, regardless of language
or underlying data storage. In contrast, RDBs like Oracle or MySQL define the
data storage and SQL dialect, while the network access to the data is then
added almost as an afterthought.

LDAP is meant as a Directory for simple attribute-based information
for fast, high volume lookup. Simple search filters are supported:
Patterns, "and", "or". In contrast to RDBs, there is no support for
arbitrary relations between entries, there are no transactions nor rollback.

There are open-source servers for LDAP, and client libraries for
C, Perl, Java and other languages. MacOSX, Linux, Windows 2000
already include LDAP clients. MS ActiveDirectory uses LDAP.

LDAP requires the data to be organized into hierarchical ''Entries''.
Each Entry has a globally unique ''Distinguished Name'' (dn),
and various ''Attributes'', that is Type/Value pairs.
The ''Schema'' defines which attributes an entry must have and which ones
it might have. There are existing schemas for DNS-type data or personell
information, including types like ''Common Name'' (cn) or ''Domain Component'' (dc),
but one can add custom schemata. Values might include binary data, e.g. images.

=== Mapping EPICS PV Information to LDAP ===

Each LDAP entry must have a unique name (dn). EPICS PVs must be unique as well,
but only within the search domain currently defined by the EPICS_CA_ADDR_LIST.
It might make sense to synchronize LDAP servers across these boundaries,
in which case the LDAP dn will have to include more than just the PV name.
For example, one could have a PV "fred" in both the accelerator and office network
of the SNS, and enter them into an SNS-wide LDAP directory like this:

fred.linac.sns.epics: cas="linacioc1:5065"
fred.office.sns.epics: cas="testioc47.sns.ornl.gov:7987", description="Fred's test PV"

In this example, the directory includes the ChannelAccess server for both PVs,
and in one case also a description.

While an EPICS-specific tool might present the data as shown above,
most generic LDAP tools and APIs use the ''LDAP Data Interchange Format'' (LDIF).
In LDIF, part of the above data could look like this:

dn: dc=epics
objectclass: dcObject
objectclass: organization
o: Root of all EPICS PVs
dc: epics

dn: dc=sns,dc=epics
# Details omitted; similar to previous entry

dn: dc=linac,dc=sns,dc=epics
objectclass: dcObject
objectclass: organization
o: Root of all EPICS PVs in the SNS Linac
dc: linac

dn: cn=fred,dc=linac,dc=sns,dc=epics
objectclass: ProcessVariable
cn: fred
cas: linacioc1:5065

Some points I had to learn:
* Each entry has an objectclass. The schema for "ProcessVariable" would for example require a "cn" attribute, with optional "cas", "description" and maybe other attributes. The schema would also determine if searches for PV names are case-sensitive or not.
* The hierarchical path "fred.linac.sns.epics" translates into a dn "cn=fred,dc=linac,dc=sns,dc=epics" which lists the relative dn of the entry itself and all path elements.
* Each path element must exists, so to bootstrap one has to create entries "dc=epics" and "dc=sns,dc=epics" etc., for which I used the pre-defined "organization" schema.
* To locate the PV 'fred', any of the following LDAP searches would work:
** Scope "base" with base "cn=fred,dc=linac,dc=sns,dc=epics".
** Scope "one" with base "dc=linac,dc=sns,dc=epics" and filter "(cn=fred)".
** Scope "one" with base "dc=linac,dc=sns,dc=epics" and filter "(cn=f*d)", though this might return more records which happen to match the pattern.
** Scope "sub" with base "dc=sns,dc=epics" and filter "(cn=fred)", which would also return an entry with dn "cn=fred,dc=office,dc=sns,dc=epics".
** There is a filter option "~=" for 'approximately equal'. Unclear what exactly defines approximate, but this might be very handy for detecing typos.

=== OpenLDAP ===

OpenLDAP [http://www.openldap.org] is an open-source LDAP
client library for C and an LDAP server which can store the
actual data in /dev/null, a BerkeleyDB, SQL, Perl, a remote LDAP server.

OpenLDAP includes authentication and encrypted (SSL) transport,
replication (single master -> multiple slaves),
and referrals from one server to another one which has more details.

=== EPICS PV Tests ===

Using OpenLDAP-stable-20050429 and perl-ldap-0.3202 on a 1.3 GHz PowerBook G4
with 780 MB RAM under MacOS X 10.3.8, I used a perl script to create
PV entries, search them, and remove them.
In addition, the 'ldapsearch' that comes with RedHat Enterprise AS 3 was
used to check remote accessibillity.

When trying to list all PVs with an appropriate search pattern,
the default server configuration limits the response to 500 answers.
This was changed such that 'paged' searches which keep requesting data
in increments of e.g. 500 entries are allowed to continue until all data is retrieved.
From the command-line tool, that's done like this:
ldapsearch -x -LLL -E pr=10/noprompt -b 'dc=epics' '(cn=testpv*)' cas

== Performance ==

Based on the default OpenLDAP server config with an additional
index "cn pres,eq" on the common name of the PVs,
PVs with names 'testrec0000000001', 'testrec0000000002' etc.
were added, then looked up one-by-one via their exact name,
and finially deleted one by one.

When using a C++ test client based on the OpenLDAP library,
the results for smaller numbers are:
Add 10000 records : 22.76 secs
Locate 10000 records : 6.49 secs
Delete 10000 records : 22.20 secs

In another test, a very rough estimated PV count of the SNS linac
was used:
Add 200000 records : 675.89 secs (38.74 CPU)
Locate 200000 records : 142.85 secs (27.91 CPU)
Delete 200000 records : 807.28 secs (37.28 CPU)

Those 200000 records use about 900MB of file space.
The results indicate that one can add 300 .. 440 records/sec,
locate 1400.. 1540 records/sec and delete 250..450 records/sec.
Without an index, the addition and deletion will be faster
at the expense of lookup times.

A typical SNS LLRF IOCs has 2300 records.
On startup, sending those to the directory server would take around 7 seconds.
A typical SNS LLRF overview screen has about 400 PVs,
and current connection times vary from less than a second to
several tens of seconds, depending on how well the search requests
reach the IOCs.
Resolving their CA servers would take about 0.3 seconds with LDAP,
which would then be followed by the time required to actually connect
to those servers.

In previous test using perl, the individual PV search actually used an LDIF
filter with exact match like 'testrec0000000001'. In addition, all PVs matching
a filter 'testrec*' were retrieved, and no index was used:
Adding 1000 records: 4 wallclock secs ( 2.29 usr + 0.14 sys = 2.43 CPU)
Locating 1000 records: 49 wallclock secs ( 4.10 usr + 0.21 sys = 4.31 CPU)
Match all 1000: 1 wallclock secs ( 1.18 usr + 0.02 sys = 1.20 CPU)
Delete 1000 records: 4 wallclock secs ( 1.35 usr + 0.14 sys = 1.49 CPU)

When locating individual records via the complete LDIF base without a filter,
the search is much faster:
Locating 1000 records: 5 wallclock secs ( 3.20 usr + 0.18 sys = 3.38 CPU)

When adding an "index cn pres,eq" to the server config, the results are the
same for both the filter and the base search case.
No difference observed when tripling the cachesize from the default of 1000.
The behavior scales linearly with the number of channels,
always a little over 200 additions or lookups per second:
Adding 10000 records: 47 wallclock secs (21.72 usr + 1.28 sys = 23.00 CPU)
Locating 10000 records: 44 wallclock secs (32.20 usr + 1.55 sys = 33.75 CPU)
Match all 10000: 15 wallclock secs (12.15 usr + 0.64 sys = 12.79 CPU)
Delete 10000 records: 38 wallclock secs (15.41 usr + 1.16 sys = 16.57 CPU)

Adding 50000 records: 243 wallclock secs (110.36 usr + 7.18 sys = 117.54 CPU)
Locating 50000 records: 226 wallclock secs (164.97 usr + 7.67 sys = 172.64 CPU)
Match all 50000: 80 wallclock secs (63.09 usr + 3.42 sys = 66.51 CPU)
Delete 50000 records: 219 wallclock secs (82.11 usr + 6.61 sys = 88.72 CPU)

Adding 200000 records: 1293 wallclock secs (483.65 usr + 33.20 sys = 516.85 CPU)

"index cn,dc pres,eq,approx,sub" takes longer to insert/delete
without improved search performance:
Adding 10000 records: 104 wallclock secs (26.25 usr + 1.67 sys = 27.92 CPU)
Locating 10000 records: 45 wallclock secs (32.86 usr + 1.55 sys = 34.41 CPU)
Match all 10000: 15 wallclock secs (12.31 usr + 0.47 sys = 12.78 CPU)
Delete 10000 records: 97 wallclock secs (17.89 usr + 1.34 sys = 19.23 CPU)

The CPU load is a rough 50/50 split between the perl and slapd processes.
The perl ldap library is 100% perl, including the network handling and
quite some data conversions from arrays into hashes and back,
so a pure C client might be a little faster.

Though an index slows down the insertion of PVs, it speeds up certain
retrieval methods, as probably desired for an EPICS directory server.
The search mechanism is based on round-trip requests.
Searching PVs one PV name at a time is slower than requesting all
PVs that match a pattern. Unfortunately, typical CA clients will
have to request data for specific PV names, not by pattern.

=== To be investigated ===

* How to access it from vxWorks
* How does an LDAP server used for EPICS cooperate with existing LDAP servers for DNS, email etc. Should it be one and the same? Use special port numbers for 'EPICS' LDAP?
* API: What type of API would EPICS tools use? Whatever LDAP library they use? An 'EPICS wrapper' around LDAP? Gasper suggested to look at the Java JNDI API for inspiration.
* Common Database headaches:
** To simply get a PV into LDAP, one has to check if this PV already exists and then either 'add' or 'modify'.
** What if a channel is no longer available? An IOC shutting down could remove PVs from the LDAP server, but an IOC that crashes won't.
* Replication: How to use it, how fast is it etc.
* Authentication and encryption: How hard is it to configure?

V4 CA Client User Interface

2005-06-27T19:14:28Z

KayKasemir: how to get property info?

V4 CA Client User Interface

2005-06-27T15:48:54Z

KayKasemir: scheduled write

V4 CA Client User Interface

2005-06-27T15:23:35Z

KayKasemir: Ben: hide

V4 CA Client User Interface

2005-06-27T15:21:30Z

KayKasemir: Ben: hide

V4 CA Client User Interface

2005-06-24T16:07:22Z

KayKasemir: Ideas for the event & Filter. Separate "SyncChannel"

V4 CA Client User Interface

2005-06-24T14:45:14Z

KayKasemir: /* Data Access */

V4 Name Server

2005-06-23T23:08:05Z

KayKasemir: channels or records?

== Directory Server ==

EPICS ChannelAccess currently uses a broadcast mechanism for resolving
channel names.
Advantages:
* Minimal if not zero initial setup.
* At least initially very fast, because a client can send multiple name requests in one network packet, all servers receive it simultaneously and can answer to known names.

Disadvantages:
* Unclear how to extend this service to redundant servers, archived data, ...
* Currently, no wildcard searches.
* Currently, no statistics on available number of channels, types of records, ...
* Bigger installations run into problems with broadcast traffic:
** All devices see the requests, even though only one server has a given channel name.
** Continued searches for unresolved names to overcome UDP limitations.

As Larry Hoff pointed out, we really want a ''Directory'' server for
EPICS, something beyond a name server. A directory will not only map PV
names to IP addresses of ChannelAccess servers, but also support
* wildcard searches, reports on number of channels per IOC etc.
* redundant servers
* info about reduntant IOCs with the same PV, archived data for a PV
* backup/restore locations for a PV
* PV meta information like engineer-in-charge, CA security rules, ...

== Channels, Records, PVs ==
We currently have records with fields and channels with properties.
Each field of a record can become a channel name,
the field itself ends up in the 'value' property of the channel,
and the record decides how fill the remaining properties.

Will the directory list all record names or all possible channels?
I think only record names.

Will it include the record type? Not enough information if we add user-defined fields.
Will it lists all fields of a record?

I think for now that only listing record names is enough in order to allow
connections.

== LDAP, Directory, RDB, Schema, Entries, dn, cn, dc, ... ==

The ''Lightweight Directory Access Protocol'' (LDAP) is a network protocol.
It defines how to access data over the network, regardless of language
or underlying data storage. In contrast, RDBs like Oracle or MySQL define the
data storage and SQL dialect, while the network access to the data is then
added almost as an afterthought.

LDAP is meant as a Directory for simple attribute-based information
for fast, high volume lookup. Simple search filters are supported:
Patterns, "and", "or". In contrast to RDBs, there is no support for
arbitrary relations between entries, there are no transactions nor rollback.

There are open-source servers for LDAP, and client libraries for
C, Perl, Java and other languages. MacOSX, Linux, Windows 2000
already include LDAP clients. MS ActiveDirectory uses LDAP.

LDAP requires the data to be organized into hierarchical ''Entries''.
Each Entry has a globally unique ''Distinguished Name'' (dn),
and various ''Attributes'', that is Type/Value pairs.
The ''Schema'' defines which attributes an entry must have and which ones
it might have. There are existing schemas for DNS-type data or personell
information, including types like ''Common Name'' (cn) or ''Domain Component'' (dc),
but one can add custom schemata. Values might include binary data, e.g. images.

=== Mapping EPICS PV Information to LDAP ===

Each LDAP entry must have a unique name (dn). EPICS PVs must be unique as well,
but only within the search domain currently defined by the EPICS_CA_ADDR_LIST.
It might make sense to synchronize LDAP servers across these boundaries,
in which case the LDAP dn will have to include more than just the PV name.
For example, one could have a PV "fred" in both the accelerator and office network
of the SNS, and enter them into an SNS-wide LDAP directory like this:

fred.linac.sns.epics: cas="linacioc1:5065"
fred.office.sns.epics: cas="testioc47.sns.ornl.gov:7987", description="Fred's test PV"

In this example, the directory includes the ChannelAccess server for both PVs,
and in one case also a description.

While an EPICS-specific tool might present the data as shown above,
most generic LDAP tools and APIs use the ''LDAP Data Interchange Format'' (LDIF).
In LDIF, part of the above data could look like this:

dn: dc=epics
objectclass: dcObject
objectclass: organization
o: Root of all EPICS PVs
dc: epics

dn: dc=sns,dc=epics
# Details omitted; similar to previous entry

dn: dc=linac,dc=sns,dc=epics
objectclass: dcObject
objectclass: organization
o: Root of all EPICS PVs in the SNS Linac
dc: linac

dn: cn=fred,dc=linac,dc=sns,dc=epics
objectclass: ProcessVariable
cn: fred
cas: linacioc1:5065

Some points I had to learn:
* Each entry has an objectclass. The schema for "ProcessVariable" would for example require a "cn" attribute, with optional "cas", "description" and maybe other attributes. The schema would also determine if searches for PV names are case-sensitive or not.
* The hierarchical path "fred.linac.sns.epics" translates into a dn "cn=fred,dc=linac,dc=sns,dc=epics" which lists the relative dn of the entry itself and all path elements.
* Each path element must exists, so to bootstrap one has to create entries "dc=epics" and "dc=sns,dc=epics" etc., for which I used the pre-defined "organization" schema.
* To locate the PV 'fred', any of the following LDAP searches would work:
** Scope "base" with base "cn=fred,dc=linac,dc=sns,dc=epics".
** Scope "one" with base "dc=linac,dc=sns,dc=epics" and filter "(cn=fred)".
** Scope "one" with base "dc=linac,dc=sns,dc=epics" and filter "(cn=f*d)", though this might return more records which happen to match the pattern.
** Scope "sub" with base "dc=sns,dc=epics" and filter "(cn=fred)", which would also return an entry with dn "cn=fred,dc=office,dc=sns,dc=epics".
** There is a filter option "~=" for 'approximately equal'. Unclear what exactly defines approximate, but this might be very handy for detecing typos.

=== OpenLDAP ===

OpenLDAP [http://www.openldap.org] is an open-source LDAP
client library for C and an LDAP server which can store the
actual data in /dev/null, a BerkeleyDB, SQL, Perl, a remote LDAP server.

OpenLDAP includes authentication and encrypted (SSL) transport,
replication (single master -> multiple slaves),
and referrals from one server to another one which has more details.

=== EPICS PV Tests ===

Using OpenLDAP-stable-20050429 and perl-ldap-0.3202 on a 1.3 GHz PowerBook G4
with 780 MB RAM under MacOS X 10.3.8, I used a perl script to create
PV entries, search them, and remove them.
In addition, the 'ldapsearch' that comes with RedHat Enterprise AS 3 was
used to check remote accessibillity.

When trying to list all PVs with an appropriate search pattern,
the default server configuration limits the response to 500 answers.
This was changed such that 'paged' searches which keep requesting data
in increments of e.g. 500 entries are allowed to continue until all data is retrieved.
From the command-line tool, that's done like this:
ldapsearch -x -LLL -E pr=10/noprompt -b 'dc=epics' '(cn=testpv*)' cas

== Performance ==

Based on the default OpenLDAP server config with an additional
index "cn pres,eq" on the common name of the PVs,
PVs with names 'testrec0000000001', 'testrec0000000002' etc.
were added, then looked up one-by-one via their exact name,
and finially deleted one by one.

When using a C++ test client based on the OpenLDAP library,
the results for smaller numbers are:
Add 10000 records : 22.76 secs
Locate 10000 records : 6.49 secs
Delete 10000 records : 22.20 secs

In another test, a very rough estimated PV count of the SNS linac
was used:
Add 200000 records : 675.89 secs (38.74 CPU)
Locate 200000 records : 142.85 secs (27.91 CPU)
Delete 200000 records : 807.28 secs (37.28 CPU)

Those 200000 records use about 900MB of file space.
The results indicate that one can add 300 .. 440 records/sec,
locate 1400.. 1540 records/sec and delete 250..450 records/sec.
Without an index, the addition and deletion will be faster
at the expense of lookup times.

A typical SNS LLRF IOCs has 2300 records.
On startup, sending those to the directory server would take around 7 seconds.
A typical SNS LLRF overview screen has about 400 PVs,
and current connection times vary from less than a second to
several tens of seconds, depending on how well the search requests
reach the IOCs.
Resolving their CA servers would take about 0.3 seconds with LDAP,
which would then be followed by the time required to actually connect
to those servers.

In previous test using perl, the individual PV search actually used an LDIF
filter with exact match like 'testrec0000000001'. In addition, all PVs matching
a filter 'testrec*' were retrieved, and no index was used:
Adding 1000 records: 4 wallclock secs ( 2.29 usr + 0.14 sys = 2.43 CPU)
Locating 1000 records: 49 wallclock secs ( 4.10 usr + 0.21 sys = 4.31 CPU)
Match all 1000: 1 wallclock secs ( 1.18 usr + 0.02 sys = 1.20 CPU)
Delete 1000 records: 4 wallclock secs ( 1.35 usr + 0.14 sys = 1.49 CPU)

When locating individual records via the complete LDIF base without a filter,
the search is much faster:
Locating 1000 records: 5 wallclock secs ( 3.20 usr + 0.18 sys = 3.38 CPU)

When adding an "index cn pres,eq" to the server config, the results are the
same for both the filter and the base search case.
No difference observed when tripling the cachesize from the default of 1000.
The behavior scales linearly with the number of channels,
always a little over 200 additions or lookups per second:
Adding 10000 records: 47 wallclock secs (21.72 usr + 1.28 sys = 23.00 CPU)
Locating 10000 records: 44 wallclock secs (32.20 usr + 1.55 sys = 33.75 CPU)
Match all 10000: 15 wallclock secs (12.15 usr + 0.64 sys = 12.79 CPU)
Delete 10000 records: 38 wallclock secs (15.41 usr + 1.16 sys = 16.57 CPU)

Adding 50000 records: 243 wallclock secs (110.36 usr + 7.18 sys = 117.54 CPU)
Locating 50000 records: 226 wallclock secs (164.97 usr + 7.67 sys = 172.64 CPU)
Match all 50000: 80 wallclock secs (63.09 usr + 3.42 sys = 66.51 CPU)
Delete 50000 records: 219 wallclock secs (82.11 usr + 6.61 sys = 88.72 CPU)

Adding 200000 records: 1293 wallclock secs (483.65 usr + 33.20 sys = 516.85 CPU)

"index cn,dc pres,eq,approx,sub" takes longer to insert/delete
without improved search performance:
Adding 10000 records: 104 wallclock secs (26.25 usr + 1.67 sys = 27.92 CPU)
Locating 10000 records: 45 wallclock secs (32.86 usr + 1.55 sys = 34.41 CPU)
Match all 10000: 15 wallclock secs (12.31 usr + 0.47 sys = 12.78 CPU)
Delete 10000 records: 97 wallclock secs (17.89 usr + 1.34 sys = 19.23 CPU)

The CPU load is a rough 50/50 split between the perl and slapd processes.
The perl ldap library is 100% perl, including the network handling and
quite some data conversions from arrays into hashes and back,
so a pure C client might be a little faster.

Though an index slows down the insertion of PVs, it speeds up certain
retrieval methods, as probably desired for an EPICS directory server.
The search mechanism is based on round-trip requests.
Searching PVs one PV name at a time is slower than requesting all
PVs that match a pattern. Unfortunately, typical CA clients will
have to request data for specific PV names, not by pattern.

=== To be investigated ===

* How to access it from vxWorks
* How does an LDAP server used for EPICS cooperate with existing LDAP servers for DNS, email etc. Should it be one and the same? Use special port numbers for 'EPICS' LDAP?
* API: What type of API would EPICS tools use? Whatever LDAP library they use? An 'EPICS wrapper' around LDAP? Gasper suggested to look at the Java JNDI API for inspiration.
* Common Database headaches:
** To simply get a PV into LDAP, one has to check if this PV already exists and then either 'add' or 'modify'.
** What if a channel is no longer available? An IOC shutting down could remove PVs from the LDAP server, but an IOC that crashes won't.
* Replication: How to use it, how fast is it etc.
* Authentication and encryption: How hard is it to configure?

V4 CA Client User Interface

2005-06-23T22:55:23Z

KayKasemir: Split DataListener off

V4 CA Client User Interface

2005-06-23T22:29:28Z

KayKasemir:

V4 CA Client User Interface

2005-06-23T22:27:48Z

KayKasemir: /* Channel, Connection Related Methods */

V4 CA Client User Interface

2005-06-23T21:46:41Z

KayKasemir: access is per connected channel and property, doesn't belong into directory