Difference between revisions of "V4 Standard Properties and Events"

From EPICSWIKI
 
(29 intermediate revisions by 2 users not shown)
Line 5: Line 5:
We start by defining the 'leaf' property names and their meanings.  The hierarchies and their intended usage will be documented below.
We start by defining the 'leaf' property names and their meanings.  The hierarchies and their intended usage will be documented below.


My initial property set doesn't necessarily match what Marty and/or Jeff had in mind, I'm making some changes.
The property identifier used in C/C++ source code to refer to each property should be created from the names given here by prepending 'pid' and capitalizing the first letter of the name, e.g. <tt>pidValue</tt>, <tt>pidTimeStamp</tt> etc.
 
The property identifier used in C/C++ code to refer to each property should be created by (we currently have two methods, both a bit long IMHO):
* Marty appends 'PropId' to the name given, e.g. timeStampPropId, alarmSeverityPropId.
* Jeff and Ralph prepend 'propertyId' to the name, e.g. propertyItTimeStamp, propertyIdAlarmSeverity.
* I'd suggest prepending 'pid' to the name, e.g. pidTimeStamp, pidAlarmSeverity.
 
Which we eventually use doesn't really matter as long as we agree, although IMHO our source code will look slightly more uniform and be easier to read if we prepend rather than append to the name.




Line 31: Line 24:
Alarm severity, an enum {None, Minor, Major, Invalid}.
Alarm severity, an enum {None, Minor, Major, Invalid}.


Q: Did we add Offline to this?  I forget...
'''Q: Did we add Offline to this?  I forget...'''
 


=== alarmStatus ===
=== alarmStatus ===
Line 38: Line 30:
Alarm status, a string.
Alarm status, a string.


It would seem and interesting and logical change for the alarm status to become a subordinate property of the alarm severity (which we could then just call 'alarm'), but this is probably a bad idea for efficiency reasons as it would mean having to create another property catalog just to hold the status string.  Therefor I'm keeping it at the same level unless someone else says something.
It would seem logical for the alarm status to become a subordinate property of the alarm severity (which we could then just call 'alarm'), but this is probably less efficient as it would mean having to create another property catalog just to hold the status string.  Therefor I'm keeping it at the same level unless someone else says something.
 
Q: Do we hide status string compression stuff from the user, or instead make it a special kind of enum that gets longer whenever a new string comes in?
 


=== limits: upper, lower ===
=== limits: upper, lower ===
Line 64: Line 53:
=== alarmLimits ===
=== alarmLimits ===


Marty is using the V3 "limit, severity" pattern repeated four times inside the record, but I would like to simplify this, at least once we get to the property catalogI suggest completely dropping the idea of having an adjustable severity associated with each limit, and instead provide the properties:
Some client programs are interested in finding out the values which will cause a record to go into alarm states, usually to be able to display themThe structure presented here provides that information in a form most useful to this kind of client.
 
* minorAlarmLimits
* majorAlarmLimits
* invalidAlarmLimits


This should reduce the complexity of the code in the clients, since the main reason for providing these limits is to be able to put them up on a meter display or similar, and for that you want to know where the individual limits are.
* upper
** minor
** major
* lower
** minor
** major


=== units ===
=== units ===
Line 77: Line 67:




=== Data Rate-Limiting ===
=== Additional Properties ===
 
 
==== description ====
 
'''Tim Mooney:''' I would like to add a description property, a string containing a field-specific description, entered either by the database designer or by the end user.
 
ANJ: My understanding of Tim's requirement is that he wants a per-record per-field string for displaying on a user interface.
 
TMM: Ideally what I would like is just what V3 provides for engineering units: CA allows a client to ask for the engineering units associated with any particular field of a record, and a record-support routine exists to handle the request.  Thus, the V3 motor record's get_units() routine associates the engineering-unit string "mm" with the VAL field, and the string "mm/s" with the VELO (speed) field.  But V3 does not permit the scaler record to associate, for examples, the description "gamma detector" with scaler channel 1, and the description "upstream ionization chamber" with scaler channel 2.  Typically, these strings would be defined by the user at run time, and written to the data file during a scan.
 
==== Data Rate-Limiting ====


If we're allowing clients to specify the size of their deadbands or to limit data transfer by some other means, we should provide some way for the database designer to give some hint to a CA client that doesn't know anything about a particular record what data rates and/or noise it should expect to see.
If we're allowing clients to specify the size of their deadbands or to limit data transfer by some other means, we should provide some way for the database designer to give some hint to a CA client that doesn't know anything about a particular record what data rates and/or noise it should expect to see.
Line 90: Line 91:


'''Any ideas/comments?'''
'''Any ideas/comments?'''
'''TimMooney:''' If the idea is to throttle, a client would really like to specify the maximum rate at which it wants to receive data.  Deadband and noiseLevel seem like pretty slippery knobs for this purpose.  How about having standard rate classes to which clients could subscribe?
ANJ: This isn't the way in which a client specifies parameters for its subscription, it would be information available to the client to tell it more about the signal before it subscribes.
==== process ====
In the context of doing a PUT we need a way to tell an IOC whether to process the record or not after doing this PUT.  This would be a boolean, write-only property, which seems a little strange so probably needs discussing -- there may be other better ways to pass this information through CA, especially as we need a way of asking CA to process a record before returning a new value in a GET request.


== Views ==
== Views ==


When a client gives a PV name to CA, everything between the first dot and the first colon following that dot is the name of a 'view' associated with that record type, which controls what data will be returned.  The colon may be followed by additional information such as a field name or other data needed to describe the specific view required, but there should be no spaces, since as a whole the PV name should not contain any:
When a client gives a PV name to CA, everything after the first dot is used to request a particular 'view' of that record type, which indicates what data should be returned to the client.


  <recordName>.<viewName>:<viewArgs>,...
If there is no dot in the PV name, the client is asking for the default view of the record, which in V3 meant its VAL field. In V4, the record's DBD file will specify what the default view of the record should be; it will usually return a catalog containing the value field (or some other default field) and some associated metadata.


'''Q: Does anybody want to change that colon into something different?'''
If there is a dot in the PV name, the string following it is parsed looking for one of the following formats:


A record type defines the views it wants to provide in the DBD file - a view consists of a series of (property name, field name) pairs that declare the complete property catalog for this view.
* <tt>recordName.viewName</tt>
* <tt>recordName.viewName(viewParm,...)</tt>


If there is no dot in the PV name, the client is asking for the default view of the record, which in V3 meant its VAL field.  In V4, the record's DBD file will specify what the default view of the record should be; it will usually return a catalog containing the value field (or some other default field) and all of its associated metadata.
The first format without parameters is called a simple view.  A record type can define simple views in the DBD file - these contain a series of (property name, field name/path) pairs that declare the complete property catalog for the view.


A standard view called "field" is created automatically for each record type, which provides access to all of the accessible record fields in the record.
For more information about simple views including how they are defined, see [[V4 DBD Statement Syntax#view|V4 DBD Statement Syntax]].
 
The second format above with parameters is called a parameter view.  These must have code associated with them to specify and interpret the parameters, thus they cannot be declared in the DBD file.  The interface for developing parameter views has not been defined yet.  These views do not have to be created by the record type, they could be registered by some other subsystem that lives in the IOC, such as a replacement for the DESY Archive record.
 
A standard parameter view called "field" will be created automatically for each record type, which provides access to all of the accessible record fields in the record. This is described in more detail below.
 
Examples:
 
These are possible PV names, showing the use of views:
 
; <tt>myMotor</tt>
: Returns the default view of myMotor - a value and several associated metadata properties
; <tt>myMotor.velocity</tt>
: Returns the velocity view of myMotor
; <tt>myMotor.history(position,60)</tt>
: Might return an array containing the history of the last 60 seconds of the position view of myMotor
 
''We should decide whether a PV name may contain spaces - existing tools may not like PV names with spaces in them, but they would be useful in the view parameters, especially if we permit string parameters...''


== Standard Views ==
== Standard Views ==
Line 113: Line 140:
'''Q: What do we do/expect to happen for puts?  Can I change a record's displayLimits by putting a catalog with a displayLimits property to its value view?'''
'''Q: What do we do/expect to happen for puts?  Can I change a record's displayLimits by putting a catalog with a displayLimits property to its value view?'''


=== value ===
=== value view ===
 
Most record types will provide a <tt>value</tt> view, which will usually also be the default view of the record type.
 
For a record that has an inherently analog value, the property hierarchy looks like this:
 
* value
** units
** timeStamp
** alarmSeverity
** alarmStatus
** displayLimits
*** upper
*** lower
** controlLimits
*** upper
*** lower
** alarmLimits
*** upper
**** minor
**** major
*** lower
**** minor
**** major
 
TMM: V3 had "display precision", which was useful even though rather loosely and sometimes arbitrarily defined for floating-point numbers.  But what we've never had is a standard way to convey precision or accuracy -- the resolution of an ADC, the smallest possible step for a motor position, the accuracy of a temperature transducer, etc.  If there is a standard property for this kind of information, it will be practical to propagate it through a measurement or control chain.  Without a standard, you can't really expect to do this unless you write the whole chain yourself.
 
For a record that has an inherently binary or digital value, the property hierarchy looks like this (to be revised/agreed):
 
* value
** stateStrings
** timeStamp
** alarmSeverity
** alarmStatus
** severity
*** change
*** state
 
It's arguable whether it might also want to contain these:
** displayLimits
*** upper
*** lower
** controlLimits
*** upper
*** lower
 
For a record that has an inherently string value, the property hierarchy looks like this (to be revised/agreed):
 
* value
** timeStamp
** alarmSeverity
** alarmStatus
 
 
'''Alternative hierarchy'''


Most record types will provide something like this list of properties from their <tt>value</tt> view, which will usually also be marked as being the default view of the record type.
''This hierarchy is deeper than the one above, but has fewer properties at each level.  Jeff says this is important for performance reasons, although I'm skeptical as there will be many more catalogs involved that each have to be traversed.''


* value
* value
* timeStamp
** units
* alarmSeverity
** timeStamp
* alarmStatus
** alarm (alarmSeverity)
* units
*** reason (status)
* displayLimits
** limits
* majorAlarmLimits
*** display
* minorAlarmLimits
**** upper
* controlLimits
**** lower
*** control
**** upper
**** lower
*** alarm
**** upper
***** minor
***** major
**** lower
***** minor
***** major
 
The intent of the default (value) view is to be the one most commonly used.  An MEDM widget will subscribe for those properties that it wants from the channel, and the record will return those which it has.
 
=== field view ===


The intent here is that an MEDM widget will subscribe for those properties that it wants from the channel, and the record will return those which it has.
A view named <tt>field</tt> is automatically created for each record type to provide direct access to the record's visible fields.  This view optionally accepts a view parameter that specifies a fieldName or even fieldName.structFieldName etc to descend into the field hierarchy.


The property catalog returned will contain a value property, but what this contains depends if there is a view parameter.  If the view parameter is the name of a basic type field, the value returned will be the value of that field; if the field is a structure, the value property will map to a property catalog that contains the complete contents of that structure (the property names used in this catalog will exactly match the field names of the structure).


=== field ===
If no view parameter is provided, the value property will map to a property catalog containing all the readable fields of the record.


There needs to be a view that provides direct access to a record's visible fields, without any of the metadata that the valueView adds to the value field etc.  This view will accept a view argument (after the colon in the channel name) that specifies a field name or even name.name etc to descend into the field hierarchy.
This <tt>field</tt> view may be directly usable for the redundant IOC replication requirement, and will also permit a version of <tt>capr</tt> to be written that just goes to the field view and prints out the complete structure it gets back.


As described above, the property catalog returned will contain a value property, but what this contains depends on the view argument. If the view argument is the name of a basic type field, the value returned will be the value of that field; if the field is a structure, the value property will map to a property catalog that contains the complete contents of that structure (the property names used in this catalog will exactly match the field names of the structure).
Examples of PV names:
;<tt>myRecord.field</tt>
: Returns the values of all readable fields of myRecord.
;<tt>myRecord.field(scan)</tt>
: Returns the value of myRecord's <tt>scan</tt> field.
;<tt>myRecord.field(states[3].name)
: Looks up the third element of myRecord's <tt>states</tt> array field, and returns the <tt>name</tt> field of the structure found there.


If no view argument is provided in the channel name, the value property will map to a property catalog containing all the readable fields of the record.
=== views view ===


:''We could drop the outer catalog and just return every field in the outer catalog, but I think it will be easier for clients to always expect to get a value property and for everything to be found inside that.''
A meta-view named <tt>views</tt> is also provided for each record. It will return an array of strings listing all of the views available for this record.


The <tt>field</tt> view may be directly usable for the redundant IOC replication requirement, and should also permit a version of <tt>capr</tt> to be written that just goes to the field view and prints out the complete structure it gets back.
Example:
; <tt>myRecord.views</tt>
: Returns this list:
:* <tt>value</tt>
:* <tt>field</tt>
:* <tt>field(fieldName)</tt>
:* <tt>views</tt>

Latest revision as of 18:25, 18 October 2005

This page is being used to develop the standard subscription events and related property hierarchies that we expect EPICS V4 servers and clients to use. I'm also introducing the concept of 'views' of a record, which provides ways of looking at different aspects of a record and its fields.

Properties

We start by defining the 'leaf' property names and their meanings. The hierarchies and their intended usage will be documented below.

The property identifier used in C/C++ source code to refer to each property should be created from the names given here by prepending 'pid' and capitalizing the first letter of the name, e.g. pidValue, pidTimeStamp etc.


value

This is the fundamental data value we expect to be returned by all CA data transport operations. It could reference a scalar or array of any of the basic types, or just return the property catalog for a structure, so it isn't necessarily a leaf property.


timeStamp

An epicsTimeStamp.

Note: This may have a subproperty at some sites that further describes the event that caused the value: beam type or destination, etc. I won't discuss this idea any further here, just note the possibility for future reference.


alarmSeverity

Alarm severity, an enum {None, Minor, Major, Invalid}.

Q: Did we add Offline to this? I forget...

alarmStatus

Alarm status, a string.

It would seem logical for the alarm status to become a subordinate property of the alarm severity (which we could then just call 'alarm'), but this is probably less efficient as it would mean having to create another property catalog just to hold the status string. Therefor I'm keeping it at the same level unless someone else says something.

limits: upper, lower

A pair of scalars of the same basic type as the associated value the relate to. Marty is using the names "low" and "high", I prefer "upper" and "lower" which more closely match the old db_access.h structures; we need to pick one.

Limit value pairs are used for various properties:

controlLimits

Range of values over which the user can (easily) change a value, for graphical controls.

convertLimits

Used in the Raw to Engineering units conversion process (this might not really be a standard property).

displayLimits

Expected range the value will lie within, for graphical displays of value.


alarmLimits

Some client programs are interested in finding out the values which will cause a record to go into alarm states, usually to be able to display them. The structure presented here provides that information in a form most useful to this kind of client.

  • upper
    • minor
    • major
  • lower
    • minor
    • major

units

A string containing the units description text of the associated value and limits properties.


Additional Properties

description

Tim Mooney: I would like to add a description property, a string containing a field-specific description, entered either by the database designer or by the end user.

ANJ: My understanding of Tim's requirement is that he wants a per-record per-field string for displaying on a user interface.

TMM: Ideally what I would like is just what V3 provides for engineering units: CA allows a client to ask for the engineering units associated with any particular field of a record, and a record-support routine exists to handle the request. Thus, the V3 motor record's get_units() routine associates the engineering-unit string "mm" with the VAL field, and the string "mm/s" with the VELO (speed) field. But V3 does not permit the scaler record to associate, for examples, the description "gamma detector" with scaler channel 1, and the description "upstream ionization chamber" with scaler channel 2. Typically, these strings would be defined by the user at run time, and written to the data file during a scan.

Data Rate-Limiting

If we're allowing clients to specify the size of their deadbands or to limit data transfer by some other means, we should provide some way for the database designer to give some hint to a CA client that doesn't know anything about a particular record what data rates and/or noise it should expect to see.

The obvious property to support might be

  • deadband

However we could instead use something like

  • noiseLevel

Any ideas/comments?

TimMooney: If the idea is to throttle, a client would really like to specify the maximum rate at which it wants to receive data. Deadband and noiseLevel seem like pretty slippery knobs for this purpose. How about having standard rate classes to which clients could subscribe?

ANJ: This isn't the way in which a client specifies parameters for its subscription, it would be information available to the client to tell it more about the signal before it subscribes.

process

In the context of doing a PUT we need a way to tell an IOC whether to process the record or not after doing this PUT. This would be a boolean, write-only property, which seems a little strange so probably needs discussing -- there may be other better ways to pass this information through CA, especially as we need a way of asking CA to process a record before returning a new value in a GET request.

Views

When a client gives a PV name to CA, everything after the first dot is used to request a particular 'view' of that record type, which indicates what data should be returned to the client.

If there is no dot in the PV name, the client is asking for the default view of the record, which in V3 meant its VAL field. In V4, the record's DBD file will specify what the default view of the record should be; it will usually return a catalog containing the value field (or some other default field) and some associated metadata.

If there is a dot in the PV name, the string following it is parsed looking for one of the following formats:

  • recordName.viewName
  • recordName.viewName(viewParm,...)

The first format without parameters is called a simple view. A record type can define simple views in the DBD file - these contain a series of (property name, field name/path) pairs that declare the complete property catalog for the view.

For more information about simple views including how they are defined, see V4 DBD Statement Syntax.

The second format above with parameters is called a parameter view. These must have code associated with them to specify and interpret the parameters, thus they cannot be declared in the DBD file. The interface for developing parameter views has not been defined yet. These views do not have to be created by the record type, they could be registered by some other subsystem that lives in the IOC, such as a replacement for the DESY Archive record.

A standard parameter view called "field" will be created automatically for each record type, which provides access to all of the accessible record fields in the record. This is described in more detail below.

Examples:

These are possible PV names, showing the use of views:

myMotor
Returns the default view of myMotor - a value and several associated metadata properties
myMotor.velocity
Returns the velocity view of myMotor
myMotor.history(position,60)
Might return an array containing the history of the last 60 seconds of the position view of myMotor

We should decide whether a PV name may contain spaces - existing tools may not like PV names with spaces in them, but they would be useful in the view parameters, especially if we permit string parameters...

Standard Views

These views contain the metadata that we expect most general-purpose CA clients to request when fetching or monitoring a channel.

In all cases the view's property catalog should include a value property, which contains the value of the thing actually being requested. Channel Access will not send any property values that the client doesn't include in its request catalog, so there should be no problem in making the standard views wide, and having the clients limit what gets sent by what they actually request.

Q: What do we do/expect to happen for puts? Can I change a record's displayLimits by putting a catalog with a displayLimits property to its value view?

value view

Most record types will provide a value view, which will usually also be the default view of the record type.

For a record that has an inherently analog value, the property hierarchy looks like this:

  • value
    • units
    • timeStamp
    • alarmSeverity
    • alarmStatus
    • displayLimits
      • upper
      • lower
    • controlLimits
      • upper
      • lower
    • alarmLimits
      • upper
        • minor
        • major
      • lower
        • minor
        • major

TMM: V3 had "display precision", which was useful even though rather loosely and sometimes arbitrarily defined for floating-point numbers. But what we've never had is a standard way to convey precision or accuracy -- the resolution of an ADC, the smallest possible step for a motor position, the accuracy of a temperature transducer, etc. If there is a standard property for this kind of information, it will be practical to propagate it through a measurement or control chain. Without a standard, you can't really expect to do this unless you write the whole chain yourself.

For a record that has an inherently binary or digital value, the property hierarchy looks like this (to be revised/agreed):

  • value
    • stateStrings
    • timeStamp
    • alarmSeverity
    • alarmStatus
    • severity
      • change
      • state

It's arguable whether it might also want to contain these:

    • displayLimits
      • upper
      • lower
    • controlLimits
      • upper
      • lower

For a record that has an inherently string value, the property hierarchy looks like this (to be revised/agreed):

  • value
    • timeStamp
    • alarmSeverity
    • alarmStatus


Alternative hierarchy

This hierarchy is deeper than the one above, but has fewer properties at each level. Jeff says this is important for performance reasons, although I'm skeptical as there will be many more catalogs involved that each have to be traversed.

  • value
    • units
    • timeStamp
    • alarm (alarmSeverity)
      • reason (status)
    • limits
      • display
        • upper
        • lower
      • control
        • upper
        • lower
      • alarm
        • upper
          • minor
          • major
        • lower
          • minor
          • major

The intent of the default (value) view is to be the one most commonly used. An MEDM widget will subscribe for those properties that it wants from the channel, and the record will return those which it has.

field view

A view named field is automatically created for each record type to provide direct access to the record's visible fields. This view optionally accepts a view parameter that specifies a fieldName or even fieldName.structFieldName etc to descend into the field hierarchy.

The property catalog returned will contain a value property, but what this contains depends if there is a view parameter. If the view parameter is the name of a basic type field, the value returned will be the value of that field; if the field is a structure, the value property will map to a property catalog that contains the complete contents of that structure (the property names used in this catalog will exactly match the field names of the structure).

If no view parameter is provided, the value property will map to a property catalog containing all the readable fields of the record.

This field view may be directly usable for the redundant IOC replication requirement, and will also permit a version of capr to be written that just goes to the field view and prints out the complete structure it gets back.

Examples of PV names:

myRecord.field
Returns the values of all readable fields of myRecord.
myRecord.field(scan)
Returns the value of myRecord's scan field.
myRecord.field(states[3].name)
Looks up the third element of myRecord's states array field, and returns the name field of the structure found there.

views view

A meta-view named views is also provided for each record. It will return an array of strings listing all of the views available for this record.

Example:

myRecord.views
Returns this list:
  • value
  • field
  • field(fieldName)
  • views