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 whole area into minorAlarmLimits and majorAlarmLimits when we get to properties, completely dropping the idea of having an adjustable severity associated with each limit. 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 only want to know where the minor and major limits are.

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 properties to support would be

• monitorDeadband
• archiveDeadband

However we could change these to something like

• noiseLevel
• dataRate

Any ideas/comments?

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:

<recordName>.<viewName>:<viewArgs>,...

Does anybody want to change that colon into something different?

A record type names the views it directly supports in the DBD file - a view of this type will consist of a field (which may itself be a structure) and its associated metadata. The field itself will be passed as the valuePropId for this view, and the metadata specifies the other property IDs to be included.

We could change this to an even more flexible way of specifying all the properties making up the view including the value, in which case we'd move the metadata out of the field specifications into the view specification.

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.

There will be other views created automatically which provide access to the individual fields in the record (without metadata), and also to provide introspection of the record field types, structures, sizes etc. These are a bit more open-ended, so I may not define them here.

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 where we're getting value data (as against introspection information, see later), the server'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 for puts? Can I change a record's displayLimits by putting a displayLimits property to its value view? I don't like that myself

valueView

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

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

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.

Q: Should this view support any viewArgs, to allow descending into a value field that happens to be a structure, or for direct access to sub-properties? Would be able to do both - what about name clashes?

fieldView

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.

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

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

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. However I might be persuaded otherwise!

The 'all fields' catalog may be directly usable for the redundant IOC replication requirement, and should 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.