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.

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