Difference between revisions of "V4 Standard Properties and Events"

From EPICSWIKI
Line 1: Line 1:
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.
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 ==
== Properties ==
Line 5: Line 5:
I'll start by going through the 'leaf' property names and their meanings.  The hierarchies will be documented below under Catalogs, and their usage under Events.
I'll start by going through the 'leaf' property names and their meanings.  The hierarchies will be documented below under Catalogs, and their usage under Events.


My initial property set doesn't necessarily match what Marty and/or Jeff have in mind...
My initial property set doesn't necessarily match what Marty and/or Jeff had in mind. The property Id used in C/C++ code is found by appending 'PropId' to the name given below, e.g. timeStampPropId, alarmSeverityPropId.
 


=== value ===
=== value ===


This is a scalar or n-dimensional array of any of the basic types.
This is the basic value returned by all CA operations. It could be a basic type, an array, or a property catalog for a structure, so it isn't necessarily a leaf property.
 
Q: Should array values use a different property name?  If implicit conversion from an array type to a scalar type is supported then the answer can be no, but without such implicit conversion then we might want to make these different.




Line 18: Line 17:
An epicsTimeStamp.
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 any further.
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 any further yet.




Line 34: Line 33:
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 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.


Q: Do we hide status string compression stuff from the user, or instead make it a special kind of enum that keeps getting longer?
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 67: Line 67:
=== choices ===
=== choices ===


An array of strings containing the choice text for each of the enumerated choices of the associated value.  I'm assuming we need this, although I may be misunderstanding how Data Access handles enumerated types.
'''This property may be completely wrong'''


An array of strings containing the choice text for each of the enumerated choices of the associated value - this is presumably always be a subordinate property of the value itself.  I'm assuming we need this, although I may be misunderstanding how Data Access handles enumerated types (if it does yet).


== Catalogs ==


This section documents the standard property hierarchies, giving each one a property catalog name.  It seems that we should only need to define the catalogs and the hierarchy that will get posted as a result of an event subscription.
== 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 similar data needed to construct the view.


=== valueTimeAlarmCatalog ===
''recordName''.''view'':''viewArgs'',...
 
 
A record type names (some of) the views supported by its records in the DBD file - a view in this case consists of a field (which may itself be a structure) and all of its associated metadata.  The field itself will be passed as the valuePropId for this view, and the metadata specifies the other property IDs; or maybe we have some even more flexible way of specifying all the properties in the view including the value.
 
If there is no dot in the PV name, the client is asking for the default view of the record, which in V3 meant the VAL field.  In V4, the record's DBD file will have specified 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.
 
There will be other views created by the database access layer which provide access to the individual fields in the record (without metadata), and also to provide introspection of the record field structure.


* value
* timeStamp
* alarmSeverity
* alarmStatus


This is the basic value monitor event catalog.
== Standard Views ==




=== guiCatalog ===
=== value ===


This deliberately does not contain the value. It does seem a bit big though, can/should we split it up a bit?
Most record types will provide something like this list of properties from their value view, which will usually be marked as being the default view of the record type.


* choices
* value
* timeStamp
* alarmSeverity
* alarmStatus
* units
* units
* displayLimits
* displayLimits
Line 97: Line 104:




=== valueCatalog ===
=== rawValue ===


* value
* value
 
* timeStamp
This is used for modifying fields, or if you really only want to get a record's value field with no associated metadata.
 
 
=== alarmCatalog ===
 
* alarmSeverity
* alarmSeverity
* alarmStatus
* alarmStatus
This is intended for alarm handlers, that really only want the alarm severity and status without the value.  Is there a need for the timeStamp too?
== Events ==
=== value ===
Posts a valueTimeAlarmCatalog
=== archive ===
Assuming we still want this, it posts a valueTimeAlarmCatalog
=== alarm ===
alarmCatalog
=== gui change ===

Revision as of 20:51, 10 May 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

I'll start by going through the 'leaf' property names and their meanings. The hierarchies will be documented below under Catalogs, and their usage under Events.

My initial property set doesn't necessarily match what Marty and/or Jeff had in mind. The property Id used in C/C++ code is found by appending 'PropId' to the name given below, e.g. timeStampPropId, alarmSeverityPropId.


value

This is the basic value returned by all CA operations. It could be a basic type, an array, or a 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 any further yet.


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 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.

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

A pair of scalars of the same basic type as the associated value they are subordinate properties of. Marty likes to use the names "low" and "high", but I think I prefer "upper" and "lower", which is what I'm proposing here.

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

Marty has these replicating the current "high, low, severity" pattern repeated for an inner and outer range, but I would like to simplify this whole area into just minorAlarmLimits and majorAlarmLimits and drop the adjustable severity thing completely. This could reduce the complexity of the code in lots of places.


units

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


choices

This property may be completely wrong

An array of strings containing the choice text for each of the enumerated choices of the associated value - this is presumably always be a subordinate property of the value itself. I'm assuming we need this, although I may be misunderstanding how Data Access handles enumerated types (if it does yet).


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 similar data needed to construct the view. 

recordName.view:viewArgs,...


A record type names (some of) the views supported by its records in the DBD file - a view in this case consists of a field (which may itself be a structure) and all of its associated metadata. The field itself will be passed as the valuePropId for this view, and the metadata specifies the other property IDs; or maybe we have some even more flexible way of specifying all the properties in the view including the value.

If there is no dot in the PV name, the client is asking for the default view of the record, which in V3 meant the VAL field. In V4, the record's DBD file will have specified 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.

There will be other views created by the database access layer which provide access to the individual fields in the record (without metadata), and also to provide introspection of the record field structure.


Standard Views

value

Most record types will provide something like this list of properties from their value view, which will usually be marked as being the default view of the record type.

  • value
  • timeStamp
  • alarmSeverity
  • alarmStatus
  • units
  • displayLimits
  • majorAlarmLimits
  • minorAlarmLimits
  • controlLimits


rawValue

  • value
  • timeStamp
  • alarmSeverity
  • alarmStatus
Retrieved from "https://wiki-ext.aps.anl.gov/epics/index.php?title=V4_Standard_Properties_and_Events&oldid=74"