V4 Standard Properties and Events

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.

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

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

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 catalog. I suggest completely dropping the idea of having an adjustable severity associated with each limit, and instead provide the properties:

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

Idea: How about providing a string field associated with each limit that would be the alarmStatus value when the limit is breached?

units

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

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?

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 something like this property hierarchy from their value view, which will usually also be the default view of the record type.

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

Alternative hierarchy

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

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

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:

myRecord.field(scan)

Returns the value of myRecord's scan field.

myRecord.field

Returns the values of all readable fields of myRecord.

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

Return this list:

• value
• field
• field(fieldName)
• views

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

Return this list:

• value
• field
• field(fieldName)
• views