EPICS normativeTypesCPP

Release 5.1-DEV - 2016.03.18

Editors:
Marty Kraimer, BNL
Matej Sekoranja, CosyLab
David Hickin, Diamond Light Source

Abstract

EPICS Version 4 provides efficient storage, access, and communication, of memory resident structured data. The EPICS V4 Normative Types are a collection of structured data types that can be used by the application level of EPICS V4 network endpoints, to interoperably exchange scientific data. normativeTypesCPP is the C++ implementation. It is one part of the set of related products in the EPICS V4 control system programming environment:
relatedDocumentsV4.html

Status of this Document

This is the 18-March-2016 version for the 5.1-development release of the C++ implementation of normativeTypes.

RELEASE_NOTES.md provides changes since the last release. TODO.md describes things to do before the next release.

Table of Contents

Introduction

This manual assumes that the reader is familiar with the material in pvDataCPP.html

At present the following normative types are implemented:

There is also additional support for NTAttributes which are extended as required by NTNDArray.

Thus normativeTypesCPP implements fully the March 16 2015 version the Normative Types Specification.

This version of the document only covers the types originally implemented:

NTScalar
This has a value field that has type scalar.
NTScalarArray
This has a value field that has type scalarArray.
NTNameValue
This has a field name that is a string array and a field value that has type scalarArray. Each name[i] is associated with value[i].
NTTable
This has a number of scalar array fields representing the columns of a table as well as a string array called containing representing column headers.
NTMultiChannel
This has a value field that is a union array. A primary use of this type is to access data from a set of pvAccess channels. Each element of value holds data from a channel.
NTNDArray
This type holds NDArray data as defined by the areaDetector facility.

Documentation for the remaining types will addressed in the next version of this document.

Each normative type consists of a set of mandatory fields, a set of optional fields, and any arbitrary number of extra fields. The mandatory and optional fields are meant for use by standard tools such as Display Managers and Alarm Handlers. The extra fields are for specialized tools.

A helper class NTField is provided to enforce the proper implementation of property fields as defined by pvData. A property field is normally associated with a field that has the name "value". The property fields currently used are alarm, timeStamp, display, control, and alarmLimit. In addition pvData defines a standard structure for a value field that represents enumerated values. NTField has methods associated with each of these.

An include file "nt.h" includes all the other header files that are provided by ntCPP.

The next section describes NTField. Next a set of standard optional fields used by many normative types is described. Then each normative type is described.

NTField

These are helper classes for creating standard fields for normative types. There is a single instance of this class, which is obtained via NTField::get().

class NTField{
public:
    static NTFieldPtr get();
    ~NTField() {}

    bool isEnumerated(FieldConstPtr const & field);
    bool isTimeStamp(FieldConstPtr const & field);
    bool isAlarm(FieldConstPtr const & field);
    bool isDisplay(FieldConstPtr const & field);
    bool isAlarmLimit(FieldConstPtr const & field);
    bool isControl(FieldConstPtr const & field);

    StructureConstPtr createEnumerated();
    StructureConstPtr createTimeStamp();
    StructureConstPtr createAlarm();
    StructureConstPtr createDisplay();
    StructureConstPtr createControl();

    StructureArrayConstPtr createEnumeratedArray();
    StructureArrayConstPtr createTimeStampArray();
    StructureArrayConstPtr createAlarmArray();
};

where

isEnumerated
Is the field an enumerated structure?
isTimeStamp
Is the field an timeStamp structure?
isAlarm
Is the field an alarm structure?
isDisplay
Is the field an display structure?
isAlarmLimit
Is the field an alarmLimit structure?
isControl
Is the field an control structure?
createEnumerated
Create an introspection interface for an enumerated structure.
createTimeStamp
Create an introspection interface for a timeStamp structure.
createAlarm
Create an introspection interface for an alarm structure.
createDisplay
Create an introspection interface for a display structure.
createControl
Create an introspection interface for a control structure.
createEnumeratedArray
Create an introspection interface for an structureArray of enumerated structures.
createTimeStampArray
Create an introspection interface for an structureArray of timeStamp structures.
createAlarmArray
Create an introspection interface for an structureArray of alarm structures.

Property Field Definitions

Definition: value

Often a property field is associated with another field. This other field is referred to as the value field. Usually the value field will have the field name "value". An example is:

structure parent
    double    value
    structure alarm

In this example the alarm field reports alarms for the value field.

alarm

An alarm structure is used to report alarms and other problems to the client. An alarm may be associated with a value field or can be used by a server to report problems to the client. An alarm attached to a substructure of the top-level structure is normally associated with a value field. An alarm field attached to the top-level structure can be used for either:

  1. If the top-level structure has a value field then it is an alarm for that field.
  2. To report other problems to the client.

If alarms do appear at multiple levels then an alarm is always provided at the top-level. It uses "maximize severity" to report the highest level severity of all alarms, i.e. the top-level severity is the maximum severity of all the alarms.

An example is:

structure top
   structure alarm
   structure power
       double value
       structure alarm
   structure voltage
       double value
       structure alarm
   structure current
       double value
       structure alarm

In this example power, voltage, and current all have an associated alarm. The top-level alarm would have a severity that matches the highest level severity of power, voltage, an current.

A alarm structure has the following fields:

structure alarm
    int severity
    int status
    string message

Clients and Servers should use alarm.h and pvAlarm.h which are provided by pvDataCPP instead of directly using the alarm structure itself. In particular severity and status are defined as:

enum AlarmSeverity {
 noAlarm,minorAlarm,majorAlarm,invalidAlarm,undefinedAlarm
};

enum AlarmStatus {
    noStatus,deviceStatus,driverStatus,recordStatus,
    dbStatus,confStatus,undefinedStatus,clientStatus
};

timeStamp

A timeStamp provides the time when the server executes or the time when a the data for a value field was collected. There can be multiple timeStamp fields. A timeStamp associated with a substructure is usually associated with a value field. An timeStamp field attached to the top-level structure can be used for either:

  1. If the top-level structure has a value field then it can be the timeStamp for that field.
  2. The time when the server executed.

NTNDArray is an example that has two top-level timeStamp fields with different field names because it wants to report both.

A timeStamp structure has the following fields:

structure timeStamp
    long secondsPastEpoch
    int nanoseconds
    int userTag

Clients and Servers should use timeStamp.h and pvTimeStamp.h which are provided by pvDataCPP instead of directly using the timeStamp structure itself. Note that timeStamp.h provides many methods for manipulating time.

The meaning of the fields is:

secondsPastEpoch
seconds since the posix epoch, i.e. Jan 1, 1970 00:00:00 UTC.
nanoseconds
nanoseconds since the secondsPastEpoch.
userTag
service specific.

control

This is used to specify operational limits for a numeric scalar value field.

structure control
    double limitLow
    double limitHigh
    double minStep

Servers should use control.h and pvControl.h which are provided by pvDataCPP instead of directly using the control structure itself. Note that control.h provides many methods for manipulating time.

display

This is used to specify display limits and other information for a numeric scalar value field.

structure display
    double limitLow
    double limitHigh
    string description
    string format
    string units

Note that the format should be a simplified version of the standard C formatting conventions.

enumerated

This is used to specify a set of choices and an index that selects one of the choices. For readers familiar with EPICS core this is like the ENUM types.

structure
    int index
    string[] choices

alarmLimit

This is used to specify alarm limits for a double scalar value field. It can be used by plotting tools to show alarm limits and associated severities.

structure 
    boolean active
    double lowAlarmLimit
    double lowWarningLimit
    double highWarningLimit
    double highAlarmLimit
    int lowAlarmSeverity
    int lowWarningSeverity
    int highWarningSeverity
    int highAlarmSeverity
    double hysteresis

NOTE: NTField, described above, has support for checking to see if a structure is an alarmLimit structure but no other support for alarmLimit.

pvData has support named valueAlarm instead of alarmLimit (alarmLimit is identical to valueAlarm for type double). For numeric types the field names are the same but the type for lowAlarmLimit, lowWarningLimit, highWarningLimit, and highAlarmLimit is based on the scalarType. pvData also defines valueAlarm for a scalar boolean value field and for an enumerated structure. For these completely different field names are defined. valueAlarm is more for use by servers than for clients. Thus normative types only defines alarmLimit since this is what clients like plot tools use. If the valueAlarm fields, including alarmLimit, are desired than the standardField support from pvData can be used to generate a valueAlarm field as an extra field.

Normative Type Common Features

Each normative type has two classes: a builder and a class for the normative type itself.

Normative Type Builder

This is a class that can create one of the following:

Structure
The introspection instance for the data structure associated with the type.
PVStructure
The data instance for the data structure associated with the type.
NTType
The instance for the NT type. For example NTScalar

Each builder also has a number of additional methods for optional fields and a method to add extra fields.

Normative Type Class

This has methods to do the following:

Create instance
A instance of a object can be created via a builder or from an existing PVStructure
Attach a Property
For the following optional fields an object to manipulate the fields can be attached: alarm, timeStamp, display, and control.
Get Data Interfaces
Each type has a method getPVStructure to get the entire data structure. In addition there is a method to get the data interface for each mandatory and optional field.

Normative Type NTScalar

This has the following fields:

epics:nt/NTScalar:1.0
    double value                        // mandatory and can be any numeric type
    string descriptor                   // optional
    alarm_t alarm                       // optional
        int severity
        int status 
        string message
    time_t timeStamp                    // optional
        long secondsPastEpoch
        int nanoseconds
        int userTag
    display_t display                   // optional
        double limitLow
        double limitHigh
        string description
        string format
        string units
    control_t control                   // optional
        double limitLow
        double limitHigh
        double minStep
    string extra1                       // extra
    string[] extra2                     //

NTScalarBuilder

This is a class that creates the introspection and data instances for NTScalar and an a NTScalar instance itself.

ntscalar.h defines the following:

class NTScalar;
typedef std::tr1::shared_ptr<NTScalar> NTScalarPtr;

class NTScalarBuilder
{
public:
    POINTER_DEFINITIONS(NTScalarBuilder);
    shared_pointer value(ScalarType scalarType);
    shared_pointer addDescriptor();
    shared_pointer addAlarm();
    shared_pointer addTimeStamp();
    shared_pointer addDisplay();
    shared_pointer addControl();
    StructureConstPtr createStructure();
    PVStructurePtr createPVStructure();
    NTScalarPtr create();
    shared_pointer add(
         string const & name,
         FieldConstPtr const & field);
private:
}
where
value
This determines the scalar type for the value field. This must be specified or createStructure will throw an exception.
addDescriptor
Add optional field descriptor.
addAlarm
Add optional field alarm.
addTimeStamp
Add optional field timeStamp.
addDisplay
Add optional field display.
addControl
Add optional field control.
createStructure
Create an introspection instance.
createPVStructure
Create the data instance.
create
create a PVScalar instance.
add
Add an extra field. As many fields as desired can be added but each must have a unique name that is not the name of any mandatory or possible optional field.

An NTScalarBuilder can be used to create multiple PVStructure and/or NTScalar instances. Each time createPVScalar is called it clears all internal data after the PVStructure is created.

NTScalarBuilder Examples

An example of creating an NTScalar instance is:

NTScalarBuilderPtr builder = NTScalar::createBuilder();
NTScalarPtr ntScalar = builder->
    value(pvInt)->
    addDescriptor()->
    addAlarm()->
    addTimeStamp()->
    addDisplay()->
    addControl()->
    create();

The same results could be done by:

NTScalarBuilderPtr builder = NTScalar::createBuilder();
builder->value(pvInt);
builder->addDescriptor();
builder->addAlarm();
builder->addTimeStamp();
builder->addDisplay();
builder->addControl();
NTScalarPtr ntScalar = builder->create();

NTScalar

ntscalar.h defines the following:

class NTScalar;
typedef std::tr1::shared_ptr<NTScalar> NTScalarPtr;

class NTScalar
{
public:
    POINTER_DEFINITIONS(NTScalar);
    ~NTScalar() {}
    static shared_pointer wrap(PVStructurePtr const & structure);
    static shared_pointer wrapUnsafe(PVStructurePtr const & structure);
    static bool is_a(StructureConstPtr const & structure);
    static bool isCompatible(PVStructurePtr const &pvStructure);
    static NTScalarBuilderPtr createBuilder();

    bool attachTimeStamp(PVTimeStamp &pvTimeStamp) const;
    bool attachAlarm(PVAlarm &pvAlarm) const;
    bool attachDisplay(PVDisplay &pvDisplay) const;
    bool attachControl(PVControl &pvControl) const;
    PVStructurePtr getPVStructure() const;
    PVStructurePtr getTimeStamp() const;
    PVStructurePtr getAlarm() const;
    PVStructurePtr getDisplay() const;
    PVStructurePtr getControl() const;
    PVFieldPtr getValue() const;
    template<typename PVT>
    std::tr1::shared_ptr<PVT> getValue() const
private:
}
where
wrap
Given a PVStructure this creates an NTScalar that wraps it. It calls isCompatible. It returns a null PVScalar if isCompatible returns false.
The primary use of wrap is by pvAccess client code. The server creates a PVStructure that is valid for an NTScalar and passes it to the client. The client can call wrap to create an NTScalar for it's own use. An example is:
void myCallback(PVStructurePtr const & PVStructure)
{
     NTScalarPtr ntscalar = NTScalar::wrap(PVStructure);
     if(!ntscalar) {
       // not a valid NTScalar
     }
     ...
}
wrapUnsafe
Given a PVStructure this creates an NTScalar that wraps it. It does not check that the introspection interface is compatible. This method is dangerous.
is_a
This method checks to see if the structure has an ID that is correct for NTScalar.
isCompatible
This method checks to see if the PVStructure has appropriate fields to be an NTScalar.
createBuilder
This method creates an NTScalarBuilder.
attachTimeStamp
The timeStamp field of the NTScalar is attached to pvTimeStamp.
An example is:
PVTimeStamp pvTimeStamp;
TimeStamp timeStamp;

ntscalar->attachTimeStamp(pvTimeStamp);
pvTimeStamp.get(timeStamp);
TimeStamp current;
current.getCurrent();
double diff = TimeStamp::diff(timeStamp,current); // timeStamp - current
attachAlarm
The alarm field of the NTScalar is attached to pvAlarm. If alarm is not selected as an optional field false is returned. If this is successful then the pvAlarm can be used to access that alarm fields.
An example is:
PVAlarm pvAlarm;
Alarm alarm;

ntscalar->attachAlarm(pvAlarm);
pvAlarm.get(alarm);
int severity = alarm.getSeverity();
int status = alarm.getStatus();
string message = alarm.getMessage();
attachDisplay
The display field of the NTScalar is attached to pvDisplay. Used similar to attachAlarm.
attachControl
The control field of the NTScalar is attached to pvControl. Used similar to attachAlarm.
getPVStructure
Returns the PVStructure that NTScalar wraps.
getDescriptor
Get the descriptor.
getTimeStamp
Returns the top-level timeStamp. If the timeStamp was not selected as an optional field a null PVStructure is returned.
getAlarm
Returns the top-level alarm. If the alarm was not selected as an optional field a null PVStructure is returned.
getDisplay
Returns the top-level display. If the display was not selected as an optional field a null PVStructure is returned.
getControl
Returns the top-level control. If the control was not selected as an optional field a null PVStructure is returned.
getValue
Returns the value field.

Normative Type NTScalarArray

This class is similar to NTScalar except that the value field is a scalar array field instead of just a scalar.

This has the following fields:

epics:nt/NTScalarArray:1.0
    double[] value                      // mandatory and can be any numeric type
    string descriptor                   // optional
    alarm_t alarm                       // optional
        int severity
        int status 
        string message
    time_t timeStamp                    // optional
        long secondsPastEpoch
        int nanoseconds
        int userTag
    display_t display                   // optional
        double limitLow
        double limitHigh
        string description
        string format
        string units
    control_t control                   // optional
        double limitLow
        double limitHigh
        double minStep
    string extra1                       // extra
    string[] extra2                     //

NTScalarArrayBuilder

ntscalarArray.h defines the following:

class NTScalarArray;
typedef std::tr1::shared_ptr<NTScalarArray> NTScalarArrayPtr;

class NTScalarArrayBuilder
{
public:
    POINTER_DEFINITIONS(NTScalarArrayBuilder);
    shared_pointer arrayValue(ScalarType elementType);
    shared_pointer addDescriptor();
    shared_pointer addAlarm();
    shared_pointer addTimeStamp();
    shared_pointer addDisplay();
    shared_pointer addControl();
    StructureConstPtr createStructure();
    PVStructurePtr createPVStructure();
    NTScalarArrayPtr create();
    shared_pointer add(
         string const & name,
         FieldConstPtr const & field);
private:
}
where
arrayValue
This determines the element type for the value field. This must be specified or createStructure will throw an exception.
addDescriptor
Add optional field descriptor.
addAlarm
Add optional field alarm.
addTimeStamp
Add optional field timeStamp.
addDisplay
Add optional field display.
addControl
Add optional field control.
createStructure
Create an introspection instance.
createPVStructure
Create the data instance.
create
create a PVScalar instance.
add
Add an extra field. As many fields as desired can be added but each must have a unique name that is not the name of any mandatory or possible optional field.

NTScalarArray

ntscalarArray.h defines the following:

class NTScalarArray;
typedef std::tr1::shared_ptr<NTScalarArray> NTScalarArrayPtr;

class NTScalarArray
{
public:
    POINTER_DEFINITIONS(NTScalarArray);
    ~NTScalarArray() {}
    static shared_pointer wrap(PVStructurePtr const & structure);
    static shared_pointer wrapUnsafe(PVStructurePtr const & structure);
    static bool is_a(StructureConstPtr const & structure);
    static bool isCompatible(PVStructurePtr const &pvStructure);
    static NTScalarArrayBuilderPtr createBuilder();

    bool attachTimeStamp(PVTimeStamp &pvTimeStamp) const;
    bool attachAlarm(PVAlarm &pvAlarm) const;
    bool attachDisplay(PVDisplay &pvDisplay) const;
    bool attachControl(PVControl &pvControl) const;
    PVStructurePtr getPVStructure() const;
    PVStructurePtr getTimeStamp() const;
    PVStructurePtr getAlarm() const;
    PVStructurePtr getDisplay() const;
    PVStructurePtr getControl() const;
    PVFieldPtr getValue() const;
    template<typename PVT>
    std::tr1::shared_ptr<PV> getValue() const
private:
}
where
wrap
Given a PVStructure this creates an NTScalarArray that wraps it. It calls isCompatible and returns a null PVScalarArray if isCompatible returns false.
wrapUnsafe
Given a PVStructure this creates an NTScalarArray that wraps it. It does not check that the introspection interface is compatible. This method is dangerous.
is_a
This method checks to see if the structure has an ID that is correct for NTScalarArray.
isCompatible
This method checks to see if the PVStructure has appropriate fields to be an NTScalarArray.
createBuilder
This method creates a NTScalarArrayBuilder.
attachTimeStamp
The timeStamp field of the NTScalarArray is attached to pvTimeStamp.
attachAlarm
The alarm field of the NTScalarArray is attached to pvAlarm. If alarm is not selected as an optional field false is returned. If this is successful then the pvAlarm can be used to access that alarm fields.
attachDisplay
The display field of the NTScalarArray is attached to pvDisplay. Used similar to attachAlarm.
attachControl
The control field of the NTScalarArray is attached to pvControl. Used similar to attachAlarm.
getPVStructure
Returns the PVStructure that NTScalarArray wraps.
getDescriptor
Get the descriptor.
getTimeStamp
Returns the top-level timeStamp. If the timeStamp was not selected as an optional field a null PVStructure is returned.
getAlarm
Returns the top-level alarm. If the alarm was not selected as an optional field a null PVStructure is returned.
getDisplay
Returns the top-level display. If the display was not selected as an optional field a null PVStructure is returned.
getControl
Returns the top-level control. If the control was not selected as an optional field a null PVStructure is returned.
getValue
Returns the value field.

Normative Type NTNameValue

epics:nt/NTNameValue:1.0
    string[] name                 // mandatory
    double[] value                // mandatory, can be any type, must be same length as name
    string descriptor             // optional
    alarm_t alarm                 // optional
        int severity
        int status
        string message
    time_t timeStamp              // optional
        long secondsPastEpoch
        int nanoseconds
        int userTag
    string extra1                 // extra
    string[] extra2               // extra

NTNameValueBuilder

ntnameValue.h defines the following:

class NTNameValue;
typedef std::tr1::shared_ptr<NTNameValue> NTNameValuePtr;

class NTNameValueBuilder
{
public:
    POINTER_DEFINITIONS(NTNameValueBuilder);
    shared_pointer value(ScalarType scalarType);
    shared_pointer addDescriptor();
    shared_pointer addAlarm();
    shared_pointer addTimeStamp();
    StructureConstPtr createStructure();
    PVStructurePtr createPVStructure();
    NTNameValuePtr create();
    shared_pointer add(
         string const & name,
         FieldConstPtr const & field);
private:
}
where
value
This determines the element type for the value field. This must be specified or createStructure will throw an exception.
addDescriptor
Add optional field descriptor.
addAlarm
Add optional field alarm.
addTimeStamp
Add optional field timeStamp.
createStructure
Create an introspection instance.
createPVStructure
Create the data instance.
create
create a PVScalar instance.
add
Add an extra field. As many fields as desired can be added but each must have a unique name that is not the name of any mandatory or possible optional field.

NTNameValue

class NTNameValue;
typedef std::tr1::shared_ptr<NTNameValue> NTNameValuePtr;

class NTNameValue
{
public:
    POINTER_DEFINITIONS(NTNameValue);
    ~NTNameValue() {}
    static shared_pointer wrap(PVStructurePtr const & structure);
    static shared_pointer wrapUnsafe(PVStructurePtr const & structure);
    static bool is_a(StructureConstPtr const & structure);
    static bool isCompatible(PVStructurePtr const &pvStructure);
    static NTNameValueBuilderPtr createBuilder();

    bool attachTimeStamp(PVTimeStamp &pvTimeStamp) const;
    bool attachAlarm(PVAlarm &pvAlarm) const;
    PVStringPtr getDescriptor() const;
    PVStructurePtr getPVStructure() const;
    PVStructurePtr getTimeStamp() const;
    PVStructurePtr getAlarm() const;
    PVStringArrayPtr getName() const;
    PVFieldPtr getValue() const;
    template<typename PVT>
    std::tr1::shared_ptr<PV> getValue() const
private:
}
where
wrap
Given a PVStructure this creates an NTNameValue that wraps it. It calls isCompatible and returns a null NTNameValue if isCompatible returns false.
wrapUnsafe
Given a PVStructure this creates an NTNameValue that wraps it. It does not check that the introspection interface is compatible. This method is dangerous.
is_a
This method checks to see if the structure has an ID that is correct for NTNameValue.
isCompatible
This method checks to see if the PVStructure has appropriate fields to be an NTNameValue.
createBuilder
This method creates an NTNameValueBuilder.
attachTimeStamp
The timeStamp field of the NTNameValue is attached to pvTimeStamp.
attachAlarm
The alarm field of the NTNameValue is attached to pvAlarm. If alarm is not selected as an optional field false is returned. If this is successful then the pvAlarm can be used to access that alarm fields.
getPVStructure
Returns the PVStructure that NTNameValue wraps.
getDescriptor
Get the descriptor.
getTimeStamp
Returns the top-level timeStamp. If the timeStamp was not selected as an optional field a null PVStructure is returned.
getAlarm
Returns the top-level alarm. If the alarm was not selected as an optional field a null PVStructure is returned.
getName
Returns field name.
getValue
Returns field value.

Normative Type NTTable

epics:nt/NTTable:1.0 
    string[] labels [column0,column1,column2]    // mandatory
    structure value                              // mandatory
        double[] column0 []                      // can be any scalar type
        string[] column1 []                      // can be any scalar type
        int[] column2 []                         // can be any scalar type
    string descriptor                            // optional
    alarm_t alarm                                // optional
        int severity 
        int status 
        string
    time_t timeStamp                             // optional
        long secondsPastEpoch
        int nanoseconds 498486530
        int userTag
    string extra1                                // extra

NTTableBuilder

nttable.h defines the following:

class NTTable;
typedef std::tr1::shared_ptr<NTTable> NTTablePtr;

class NTTableBuilder
{
public:
    POINTER_DEFINITIONS(NTTableBuilder);
    shared_pointer addColumn(string const & name,ScalarType scalarType);
    shared_pointer addDescriptor();
    shared_pointer addAlarm();
    shared_pointer addTimeStamp();
    StructureConstPtr createStructure();
    PVStructurePtr createPVStructure();
    NTTablePtr create();
    shared_pointer add(
         string const & name,
         FieldConstPtr const & field);
private:
}
where
addColumn
This is the name and elementType for the next column
addDescriptor
Add optional field descriptor.
addAlarm
Add optional field alarm.
addTimeStamp
Add optional field timeStamp.
createStructure
Create an introspection instance.
createPVStructure
Create the data instance.
create
create a PVScalar instance.
add
Add an extra field. As many fields as desired can be added but each must have a unique name that is not the name of any mandatory or possible optional field.

NTTable

class NTTable;
typedef std::tr1::shared_ptr<NTTable> NTTablePtr;

class NTTable
{
public:
    POINTER_DEFINITIONS(NTTable);
    ~NTTable() {}
    static shared_pointer wrap(PVStructurePtr const & structure);
    static shared_pointer wrapUnsafe(PVStructurePtr const & structure);
    static bool is_a(StructureConstPtr const & structure);
    static bool isCompatible(PVStructurePtr const &pvStructure);
    static NTTableBuilderPtr createBuilder();

    bool attachTimeStamp(PVTimeStamp &pvTimeStamp) const;
    bool attachAlarm(PVAlarm &pvAlarm) const;
    PVStructurePtr getPVStructure() const;
    PVStringPtr getDescriptor() const;
    PVStructurePtr getTimeStamp() const;
    PVStructurePtr getAlarm() const;
    PVStringArrayPtr getLabels() const;
    PVFieldPtr getColumn(string const & columnName) const;
    template<typename PVT>
    std::tr1::shared_ptr<PV> getColumn(string const & columnName) const;
private:
}
where
wrap
Given a PVStructure this creates an NTTable that wraps it. It calls isCompatible and returns a null NTTable if isCompatible returns false.
wrapUnsafe
Given a PVStructure this creates an NTTable that wraps it. It does not check that the introspection interface is compatible. This method is dangerous.
is_a
This method checks to see if the structure has an ID that is correct for NTTable.
isCompatible
This method checks to see if the PVStructure has appropriate fields to be an NTTable.
createBuilder
This method creates an NTTableBuilder.
attachTimeStamp
The timeStamp field of the NTTable is attached to pvTimeStamp.
attachAlarm
The alarm field of the NTTable is attached to pvAlarm. If alarm is not selected as an optional field false is returned. If this is successful then the pvAlarm can be used to access that alarm fields.
getPVStructure
Returns the PVStructure that NTTable wraps.
getDescriptor
Get the descriptor.
getTimeStamp
Returns the top-level timeStamp. If the timeStamp was not selected as an optional field a null PVStructure is returned.
getAlarm
Returns the top-level alarm. If the alarm was not selected as an optional field a null PVStructure is returned.
getLabels
Returns the labels field.
getColumn
Returns the column with the specified name.

Normative Type NTMultiChannel

structure NTMultiChannel
  union_t[] value            // mandatory
  string[]  channelName      // mandatory; must be same length as value
  time_t    timeStamp        // optional; time when data collected
  alarm_t   alarm            // optional; alarm associated with data collection
  int[]     severity         // optional; alarm severity for each value
  int[]     status           // optional; alarm status for each value
  string[]  message          // optional; alarm message for each value
  long[]    secondsPastEpoch // optional; seconds for each value.
  int[]     nanoseconds      // optional; nanoseconds for each value
  string    descriptor       // optional; descriptor data

NTMultiChannelBuilder

ntmultiChannel.h defines the following:

class NTMultiChannel;
typedef std::tr1::shared_ptr<NTMultiChannel> NTMultiChannelPtr;

class NTMultiChannelBuilder
{
public:
    POINTER_DEFINITIONS(NTMultiChannelBuilder);
    shared_pointer value(UnionConstPtr valuePtr);
    shared_pointer addDescriptor();
    shared_pointer addAlarm();
    shared_pointer addTimeStamp();
    shared_pointer addSeverity();
    shared_pointer addStatus();
    shared_pointer addMessage();
    shared_pointer addSecondsPastEpoch();
    shared_pointer addNanoseconds();
    shared_pointer addUserTag();
    StructureConstPtr createStructure();
    PVStructurePtr createPVStructure();
    NTMultiChannelPtr create();
    shared_pointer add(
         string const & name,
         FieldConstPtr const & field);
private:
}
where
value
This determines the element type for the value field. If not specified the type will be a variant union.
addDescriptor
Add optional field descriptor.
addAlarm
Add optional field alarm.
addTimeStamp
Add optional field timeStamp.
addSeverity
Add a field that has the alarm severity for each channel.
addStatus
Add a field that has the alarm status for each channel.
addMessage
Add a field that has the alarm message for each channel.
addSecondsPastEpoch
Add a field that has the secondsPastEpoch for each channel.
addNanoseconds
Add a field that has the nanoseconds for each channel.
addUserTag
Add a field that has the userTag for each channel.
createStructure
Create an introspection instance.
createPVStructure
Create the data instance.
create
create a PVScalar instance.
add
Add an extra field. As many fields as desired can be added but each must have a unique name that is not the name of any mandatory or possible optional field.

NTMultiChannel

class NTMultiChannel;
typedef std::tr1::shared_ptr<NTMultiChannel> NTMultiChannelPtr;

class NTMultiChannel
{
public:
    POINTER_DEFINITIONS(NTMultiChannel);
    ~NTMultiChannel() {}
    static shared_pointer wrap(PVStructurePtr const & structure);
    static shared_pointer wrapUnsafe(PVStructurePtr const & structure);
    static bool is_a(StructureConstPtr const & structure);
    static bool isCompatible(PVStructurePtr const &pvStructure);
    static NTMultiChannelBuilderPtr createBuilder();

    bool attachTimeStamp(PVTimeStamp &pvTimeStamp) const;
    bool attachAlarm(PVAlarm &pvAlarm) const;
    PVStringPtr getDescriptor() const;
    PVStructurePtr getPVStructure() const;
    PVStructurePtr getTimeStamp() const;
    PVStructurePtr getAlarm() const;
    PVUnionArrayPtr getValue() const;
    PVStringArrayPtr getChannelName() const;
    PVBooleanArrayPtr getIsConnected() const;
    PVIntArrayPtr getSeverity() const;
    PVIntArrayPtr getStatus() const;
    PVStringArrayPtr getMessage() const;
    PVLongArrayPtr getSecondsPastEpoch() const;
    PVIntArrayPtr getNanoseconds() const;
    PVIntArrayPtr getUserTag() const;
private:
}
where
wrap
Given a PVStructure this creates an NTMultiChannel that wraps it. It calls isCompatible and returns a null NTMultiChannel if isCompatible returns false.
wrapUnsafe
Given a PVStructure this creates an NTMultiChannel that wraps it. It does not check that the introspection interface is compatible. This method is dangerous.
is_a
This method checks to see if the structure has an ID that is correct for NTMultiChannel.
isCompatible
This method checks to see if the PVStructure has appropriate fields to be an NTMultiChannel.
createBuilder
This method creates an NTMultiChannelBuilder.
attachTimeStamp
The timeStamp field of the NTMultiChannel is attached to pvTimeStamp.
attachAlarm
The alarm field of the NTMultiChannel is attached to pvAlarm. If alarm is not selected as an optional field false is returned. If this is successful then the pvAlarm can be used to access that alarm fields.
getPVStructure
Returns the PVStructure that NTMultiChannel wraps.
getDescriptor
Get the descriptor.
getTimeStamp
Returns the top-level timeStamp. If the timeStamp was not selected as an optional field a null PVStructure is returned.
getAlarm
Returns the top-level alarm. If the alarm was not selected as an optional field a null PVStructure is returned.
getValue
Returns the value field.
getChannelName
Returns the name of each channel.
getIsConnected
Returns connection state of each channel.
getSeverity
Returns the severity of each channel.
getStatus
Returns the status of each channel.
getMessage
Returns the message of each channel.
getSecondsPastEpoch
Returns the secondsPastEpoch of each channel.
getNanoseconds
Returns the nanoseconds of each channel.
getUserTag
Returns the userTag of each channel.

Normative Type NTNDArray

epics:nt/NTNDArray:1.0 
    union value                                 // mandatory
    codec_t codec                               // mandatory
        string name 
        any parameters
    long compressedSize                         // mandatory
    long uncompressedSize                       // mandatory
    dimension_t[] dimension                     // mandatory
        dimension_t[]
            dimension_t
                int size
                int offset
                int fullSize
                int binning
                boolean reverse
    int uniqueId                                // mandatory
    time_t dataTimeStamp                        // mandatory
        long secondsPastEpoch
        int nanoseconds
        int userTag
    epics:nt/NTAttribute:1.0[] attribute        // mandatory
        epics:nt/NTAttribute:1.0[]
            epics:nt/NTAttribute:1.0
                string name
                any value
                string description
                int sourceType
                string source
    string descriptor                           // optional
    time_t timeStamp                            // optional
        long secondsPastEpoch
        int nanoseconds
        int userTag
    alarm_t alarm                               // optional
        int severity
        int status
        string message 
    display_t display                           // optional
        double limitLow
        double limitHigh
        string description 
        string format 
        string units 
    string extra1                               // extra

NTNDArrayBuilder

ntndArray.h defines the following:

class NTNDArray;
typedef std::tr1::shared_ptr<NTNDArray> NTNDArrayPtr;

class NTNDArrayBuilder
{
public:
    POINTER_DEFINITIONS(NTNDArrayBuilder);
    shared_pointer addDescriptor();
    shared_pointer addAlarm();
    shared_pointer addTimeStamp();
    shared_pointer addDisplay();
    StructureConstPtr createStructure();
    PVStructurePtr createPVStructure();
    NTNDArrayPtr create();
    shared_pointer add(
         string const & name,
         FieldConstPtr const & field);
private:
}
where
addDescriptor
Add optional field descriptor.
addAlarm
Add optional field alarm.
addTimeStamp
Add optional field timeStamp.
addDisplay
Add optional field display.
createStructure
Create an introspection instance.
createPVStructure
Create the data instance.
create
create a PVScalar instance.
add
Add an extra field. As many fields as desired can be added but each must have a unique name that is not the name of any mandatory or possible optional field.

NTNDArray

class NTNDArray;
typedef std::tr1::shared_ptr<NTNDArray> NTNDArrayPtr;

class NTNDArray
{
public:
    POINTER_DEFINITIONS(NTNDArray);
    ~NTNDArray() {}
    static shared_pointer wrap(PVStructurePtr const & structure);
    static shared_pointer wrapUnsafe(PVStructurePtr const & structure);
    static bool is_a(StructureConstPtr const & structure);
    static bool isCompatible(PVStructurePtr const &pvStructure);
    static NTNDArrayBuilderPtr createBuilder();

    PVStringPtr getDescriptor() const;
    bool attachTimeStamp(PVTimeStamp &pvTimeStamp) const;
    bool attachDataTimeStamp(PVTimeStamp &pvTimeStamp) const;
    bool attachAlarm(PVAlarm &pvAlarm) const;
    PVStructurePtr getPVStructure() const;
    PVUnionPtr getValue() const;
    PVStructurePtr getCodec() const;
    PVLongPtr getCompressedDataSize() const;
    PVLongPtr getUncompressedDataSize() const;
    PVStructureArrayPtr getAttribute() const;
    PVStructureArrayPtr getDimension() const;
    PVIntPtr getUniqueId() const;
    PVStructurePtr getDataTimeStamp() const;
    PVStringPtr getDescriptor() const;
    PVStructurePtr getTimeStamp() const;
    PVStructurePtr getAlarm() const;
    PVStructurePtr getDisplay() const;
private:
}
where
wrap
Given a PVStructure this creates an NTNDArray that wraps it. It calls isCompatible and returns a null NTNDArray if isCompatible returns false.
wrapUnsafe
Given a PVStructure this creates an NTNDArray that wraps it. It does not check that the introspection interface is compatible. This method is dangerous.
is_a
This method checks to see if the structure has an ID that is correct for NTNDArray.
isCompatible
This method checks to see if the PVStructure has appropriate fields to be an NTNDArray.
createBuilder
This method creates an NTNDArrayBuilder.
attachTimeStamp
The timeStamp field of the NTNDArray is attached to pvTimeStamp.
attachDataTimeStamp
The dataTimeStamp field of the NTNDArray is attached to pvTimeStamp.
attachAlarm
The alarm field of the NTNDArray is attached to pvAlarm. If alarm is not selected as an optional field false is returned. If this is successful then the pvAlarm can be used to access that alarm fields.
getPVStructure
Returns the PVStructure that NTNDArray wraps.
getValue
Returns the value field.
getCodec
Returns the severity of each channel.
getCompressedDataSize
Returns the name of each channel.
getUncompressedDataSize
Returns connection state of each channel.
getAttribute
Returns the status of each channel.
getDimension
Returns the message of each channel.
getUniqueId
Returns the secondsPastEpoch of each channel.
getDataTimeStamp
Returns the data timeStamp.
getDescriptor
Get the descriptor.
getTimeStamp
Returns the top-level timeStamp. If the timeStamp was not selected as an optional field a null PVStructure is returned.
getAlarm
Returns the top-level alarm. If the alarm was not selected as an optional field a null PVStructure is returned.
getDisplay
Returns the top-level display. If the display was not selected as an optional field a null PVStructure is returned.