FieldReference Object

The FieldReference object is a simple ApplicationObject used for reading and writing data from an external field device.

Overview

The FieldReference object is a simple ApplicationObject that can act as both the field input and the field output object. It can be configured into three basic access modes:

The process value (PV) can be historized. In addition, the FieldReference object can be configured to log an application data change event to event history when the PV changes. The FieldReference object has no built-in alarm capabilities; however, you can extend the object by creating user-defined attributes (UDAs) and scripts that provide alarming. Alternatively, you could use the the DiscreteDevice, AnalogDevice, and Switch objects, since they provide configurable alarm behavior without the need for extensions.

The PV data type for the FieldReference object can be configured to be one of a variety of supported data types, including:

In a Galaxy application, the size of an attribute of data type string may be more than 512 characters. The Wonderware Historian, however, will only store the first 512 characters for a string. Thus, you will need to limit strings in the Galaxy application to 512 characters to prevent data loss when the values are historized to the Wonderware Historian.

The data type can only be configured at the derived template level, and not for individual instances. Therefore, the data type is always automatically locked in the derived template and cannot be configured as unlocked. For convenience, the following templates, derived from the Field Reference, are provided with a pre-configured data type. (For example, the Boolean template is configured to use the Boolean data type.)

For general information on objects, including relationships, deployment, and alarm distribution, see the Integrated Development Environment (IDE) documentation.

For information on configuration options for object information, scripts, user-defined attributes (UDAs), or attribute extensions, click Extensions Help in the Help file header.

Run-Time Behavior

Run-time behavior is limited to the state of an individual FieldReference object. Once deployed and operating, FieldReference objects can assume one of the following states:


State Change	Behavior
Startup	If the FieldReference object has only an output, the default value will be read into the object, stored internally, and then used to write to the output when the object goes onscan. When the object starts up after being deployed, the time stamp is set to the time when the attribute is initialized with a deployed value. Otherwise, the checkpointed value and time stamp is set into PV. The time stamp is also restored from checkpoint when the object restarts after shut down.
Going onscan	If the access mode is ReadOnly or ReadWrite, then the process value (PV) quality is set to INITIALIZING. If the access mode is WriteOnly, the stored PV value is written to the field. Subsequent transitions from offscan to onscan set the output value to the last PV value. The value quality is GOOD. The time stamp is updated to the current time if the quality of PV changes because of a scan state change. The time stamp of the PV is written to the output with the PV value.
Execute	If the access mode is ReadOnly or ReadWrite, read the new input value, quality, and time stamp and set it into PV. If a new PV output is requested, and the access mode is ReadWrite or WriteOnly, the requested new PV value is written to the output location.
Going offscan	If the access mode is ReadOnly or ReadWrite, then the PV quality is set to BAD. If the access mode is WriteOnly, the PV quality is GOOD. The time stamp is updated to the current time if the quality of PV changes because of a scan state change.
Shutdown	If a reference to PV was registered and suspended at startup, that reference is activated and unregistered.

Special Set Handling

PV is the only attribute that can be written to at run time. If the object has feedback, then the feedback value, time stamp, and quality is transferred into the PV attribute. If the object has an output, then the value is transferred to output.value. Only when the object does not have feedback will an external write to PV be transferred directly into the attribute.

If you configure the object as WriteOnly or ReadWrite, the original time stamp associated with the value provided by the set request is always forwarded to the output. If only the Time property of the PV is set, the current value of PV and the requested time stamp is forwarded to the output. In WriteOnly mode, the PV time stamp is updated to the current time if the set request contains a zero time stamp or the provided time stamp of the set request contains a non-zero time stamp.

Continuous Execution

If the object has a feedback, then transfer feedback value, time stamp, and quality into PV.

If you configure the object to have input or input/output and advisement of active items is enabled globally, both the reference count and suspend count for the PV attribute is incremented when the object starts up. This puts the object into a suspended state and propagates a suspend message to the input source.

When the object is in a suspended state, no input scanning occurs, because no new input values are being sent by the input source. The quality of the suspended attribute is INITIALIZING.

Time Propagation

If you configure the object as ReadOnly or ReadWrite, the input value is used to compute the PV value, and the input time stamp is used to update the PV time stamp.

Configuration

The following section describes the object editor options for configuration and the associated attributes:

For general information on objects, including relationships, deployment, and alarm distribution, see the Integrated Development Environment (IDE) documentation.

For information on configuration options for object information, scripts, user-defined attributes (UDAs), or attribute extensions, click Extensions Help in the Help file header.

General Configuration

Use the General tab to configure general options for the FieldReference object.


Editor Option	Associated Attribute	Description	Run-Time Access (Supervisory, User, Read-Only, None)
Data type	Datatype	The data type of the reference. Valid values are: Boolean, Double, Float, Integer, Time, ElapsedTime, or String. The data type can only be configured for templates derived from the FieldReference template, not for instances of the FieldReference template. The following templates have been derived from the FieldReference template, and you can use them as the basis for your FieldReference objects of a particular type: Boolean, Double, Float, Integer, String. If the data type for the object is Boolean or String, the Value deadband, Trend High, and Trend Low options will not be available.	None
Access mode	AccessMode	The read/write capabilities for the object. Valid values are ReadOnly, ReadWrite, and WriteOnly.	None
Initial PV	PV	The initial PV value for WriteOnly mode. If you specified String for the data type, the maximum string length of the process variable (PV) is 1024 characters. For extra quality handling, see Quality Handling.	Supervisory, User
Engineering units	PV.EngUnits	The name of the engineering units. For example, PSI. The maximum number of characters is 32.	Read-Only
Generate event upon PV change	PV.LogDataChangeEvent	If enabled, data change events for the PV will be logged to event history.	Supervisory, User
Historize PV	PV.Historized	If enabled, the system will historize the initial PV value for WriteOnly mode.	None
Force storage period	PV.ForceStoragePeriod	See History Attributes.	Supervisory, User
Value deadband	PV.ValueDeadband	See History Attributes.	Supervisory, User
Trend High	PV.TrendHi	See History Attributes.	Supervisory, User
Trend Low	PV.TrendLo	See History Attributes.	Supervisory, User
Interpolation Type	PV.InterpolationType	See History Attributes.	Supervisory, User
Sample Count	PV.SampleCount	See History Attributes.	Supervisory, User
Rollover Value	PV.RolloverValue	See History Attributes.	Supervisory, User
Enable Swinging Door	PV.EnableSwingingDoor	See History Attributes.	Supervisory, User
Rate DeadBand	PV.RateDeadBand	See History Attributes.	Supervisory, User
PV input source	PV.Input.InputSource	The target source from which the value (plus quality) is to be read. Click the ellipse button to access the Attribute Browser.	Supervisory, User
Output destination differs from input source	DiffOutputDest	If enabled, the output destination is different from the input source.	None
PV output destination	PV.Output.OutputDest	The target location to which the output value will be written. Click the ellipse button to access the Attribute Browser.	Supervisory, User

Run-Time Object Attributes

Note Configurable run-time attributes are described in the configuration sections. For more information, see Configuration.

For a list of common object attributes, click Extensions Help in the Help file header.


Attribute	Description	Run-Time Access (Supervisory, User, Read-Only, None)
PV.Input.DataType	The expected data type of the value.	Read-Only
PV.Input.ReadStatus	The cause of any errors that have occurred when data is read from the target feedback reference (object and attribute). This is the Message Exchange status and not the status of the communication to external systems or devices such as Programmable Logic Controllers (PLCs).	Read-Only
PV.Input.Value	The value that is "calculated" using data received via Message Exchange.	Read-Only
PV.Output.DataType	The expected data type of the value.	Read-Only
PV.Output.WriteStatus	The cause of any errors when writing data to the target location (object and attribute), or, in the case where that location is in a DeviceIntegration Object, the actual field I/O status. This status is the Message Exchange status and, when OutputDest is a DeviceIntegration Object, the status of the communication to external systems or devices such as Programmable Logic Controllers (PLCs).	Read-Only
PV.Output.Value	A placeholder for values that will be written to the target location.	Read-Only

History Attributes

If a historization attribute is enabled, then the following additional history-related attributes become available. None of these attributes can be alarmed.


Attributes	Description
<Attribute>.ForceStoragePeriod	The time interval, in milliseconds, at which the value must be stored, even if the value has not changed. A value of 0 disables this feature. As an example, a setting of 3600000 indicates the value must be stored once per hour (measured from the time the object was last put onscan). If this value is less than the scan period of the host object, forced storage will occur every scan period (effectively equivalent to setting a value deadband of 0).
<Attribute>.TrendHi	The default top of the trend scale for clients. This value must be greater than or equal to the low value for the trend. If this value is changed at run time, the maximum engineering unit change is not reflected in the historian until you redeploy the object. This attribute only applies to numeric data types.
<Attribute>.TrendLo	The default bottom of the trend scale for clients. This value must be less than or equal to the high value for the trend. If this value is changed at run time, the minimum engineering unit change is not reflected in the historian until you redeploy the object. This attribute only applies to numeric data types.
<Attribute>.ValueDeadBand	The amount in engineering units by which a value referenced by the attribute must change to force a storage. A value of 0 means it is unused, and thus any value change forces a storage. Also, a quality change in the attribute always forces a storage regardless of this setting. This attribute only applies to numeric data types.
<Attribute>.Description	The brief description for the attribute that is stored to history. You can use descriptive text or a reference to another string attribute containing the history description. If an attribute reference is used, it must be in the form: "me.AttrName". If you do not provide a description, the object description is used.
<Attribute>.InterpolationType	The method used by the Historian to interpolate analog historical data. The interpolation type determines which analog value is selected during a Historian data retrieval cycle. Interpolation types include System Default, Stairstep, or Linear. The default interpolation type is System Default. For Stairstep, the last known value is returned with the given cycle time. If no valid value can be found, a NULL is returned to the Historian. For Linear, Historian calculates a new value at the given cycle time by interpolating between the last known value prior to the cycle time and the first value after the cycle time. For System Default, the Wonderware Historian system-wide interpolation setting is used. The system-wide setting must be either stairstep or linear interpolated.
<Attribute>.SampleCount	An integer that indicates the number of samples the Historian should store in the active image for an attribute value. Acceptable range of values is from 0 to 9999. The Historian enforces a sample count of 65 for the active image. If the current sample count for the active image is 65, and you set the sample count to a value less than or equal to 65, the new sample count setting is not saved to the Historian database, and the active image count remains at 65. If the current sample count for the active image is greater than 65, and you set the sample count to a value less than or equal to 65, the new sample count is saved to the Historian database and 65 is used by the active image. Regardless of the current sample count for the active image, if you set the sample count to a value greater than 65, the new sample count is saved to the Historian database and used by the active image.
<Attribute>.RolloverValue	A positive integer value that represents a tag’s reset limit when the Historian operates in counter retrieval mode. In counter retrieval mode the Historian uses a tag's rollover value to calculate and return the delta change between consecutive retrieval cycles. The default value is 0.0. The rollover value applies only to numeric attributes. The rollover value is disabled if the historical attribute data type is Boolean or a string.
<Attribute>.EnableSwingingDoor	Enables or disables the swinging door rate deadband. The default is disabled. The swinging door deadband is not applicable to Boolean or a string data types. If you provide a valid swinging door rate deadband, the force storage period is sent as a time deadband to the historian.
<Attribute>.RateDeadBand	The percentage rate of change deadband based on the change in the slope of incoming data values to the Historian. For example, specifying a swinging door rate deadband of 10 percent means that data is saved to the Historian if the percentage change in slope of consecutive data values exceeds 10 percent. The default is 0.0, which indicates a swinging door rate deadband is not applied. Any percentage greater than 0.0 can be assigned to the rate deadband.

Quality Handling

Attributes that have extra quality values (other than GOOD) are listed in the following table: