OPC Historian .NET Server Toolkit Reference
IAppPlugin Interface Methods

For a list of all members of this type, see IAppPlugin members.

Public Methods
 NameDescription
 MethodAdviseProcessedThis method computes the aggregate values, qualities, and timestamps from the history database from the specified start time at the interval for one or more items. This method is intended to be used to update the client software with new data as it becomes available; e.g., update a trend with new data on a periodic basis. The results are returned via the client's IOPCHDA_DataCallback::OnDataChange method.  
 MethodAdviseRawThis method reads the values, qualities, and timestamps from the history database from the specified start time at the update interval for one or more items. This method is intended to be used to update the client software with new data as it becomes available; e.g., update a trend with new data on a periodic basis. The results are returned via the client's IOPCHDA_DataCallback::OnDataChange method.  
 MethodCancelAnnotationsProfessional Edition only.
This method cancels the outstanding operation. The actual implementation is server specific, but the server shall respond via the client's IOPCHDA_DataCallback::OnCancelComplete method.  
 MethodCancelAsyncReadThis method cancels outstanding asynchronous read or advise requests. The server shall respond via the client's IOPCHDA_DataCallback::OnCancelComplete method unless a FAILED error code is returned from the call. If a FAILED error code is returned, there will be no callback to the client's IOPCHDA_DataCallback::OnCancelComplete method.  
 MethodCancelPlaybackProfessional Edition only.
This method cancels the outstanding operation and executes an OPCHDA_CancelComplete callback.  
 MethodCancelUpdateProfessional Edition only.
This method cancels the outstanding operation. The actual implementation is server specific, but the server shall respond via the client's IOPCHDA_DataCallback::OnCancelComplete method.  
 MethodGetAggregatesThis method returns the list of aggregates supported by the server. The OPC defined aggregates are defined in Definitions.Aggregates array. Vendor specific aggregates also are supported. The vendor supplied aggregates are made available to allow the client to use all the methods available to their specific server. If no aggregates are supported, the method shall return a count of 0 and NULL pointers.  
 MethodGetHistorianStatusThis method returns the information on the current status of the server.  
 MethodGetItemAttributesThis method returns the item attributes supported by the server. The OPC defined attribute types are defined in the Definitions.ItemAttr array. Vendor specific attributes also are supported. The vendor supplied attributes are made available to allow the client to access and display vendor specific information. Attribute data types are intended to allow query filtering when browsing item ids. If no attributes are supported by the server, the method shall return a count of 0 and NULL pointers.  
 MethodGetItemHandlesGiven a list of ItemIDs and client handles, this method returns the server handles for each item. The returned server handles must be used in all requests to read or update history. The supplied client handles are included in the returns of all read and update requests.  
 MethodGetServerRegistryDef

This method is called from the generic server at startup for normal operation or for registration. It provides server registry information for this application required for DCOM registration.
Each server needs to have unique registration definions. Unique CLSIDs can be generated with the Visual Studio GuidGen utility.

The sample implementation initializes default values and tries to read the configuration definitions from the file HDANSrv.exe.config. The config file reads can be deleted to prevent the definition from being changed without a recompilation.

 
 MethodInsertAnnotationsOverloaded. Professional Edition only.
This method inserts annotations into the history database. This method is intended to insert annotations by users to document observations for a value at a specified timestamp.  
 MethodPlaybackProcessedProfessional Edition only.
This method initially retrieves data from the start time to the end time. After the initial response it periodically (every updateInterval) responds with an updateDuration amount of data. The time of the last value returned in the initial response is used as the start time for the first update. After that, the time of the last value returned in an update is used as the start time for the next update. The results are returned via the client's OnPlayback method. The domain of the initial request is defined by startTime, endTime, and resampleInterval. All three must be specified. endTime must be greater than startTime. The resampleInterval determines how many subintervals the complete interval is divided into. The specified function is calculated at each subinterval beginning with htStartTime and selecting the data within the next resampleInterval, a value will be calculated according to the aggregate at each subinterval. For MinimumActualTime and MaximumActualTime used with aggregate values, if more than one instance of the value exists within a time range, which instance (time stamp) of the value is returned is server dependent. In any case, the server may set the OPCHDA_EXTRADATA quality flag to let the caller know that there are other timestamps with that value. A resampleInterval of 0 is illegal resulting in a return status of E_INVALIDARG. If only an initial set of data is desired, the dwNumIntervals should be set to 0 The request must still be cancelled. The updateInterval can not be less than the resampleInterval. The order of the data returned will match the order of the ItemIDs in the request.  
 MethodPlaybackRawProfessional Edition only.
This method initially retrieves data from the start time to the end time. After the initial response it periodically (every updateInterval) responds with an updateDuration amount of data. The time of the last value returned in the initial response is used as the start time for the first update. After that, the time of the last value returned in an update is used as the start time for the next update. The results are returned via the client's IOPCHDA_DataCallback::OnPlayback method. Playback is only supported in the forward direction. The domain of the initial request is defined by startTime, endTime, and numValues The value of startTime must be defined. If endTime is not specified (DateTime.MinValue), the request shall be for all data from the startTime for the requested number of values. Then further data shall be sent according to the updateDuration and updateInterval from the time of the last value returned. Implementation of the operation is server dependent.  
 MethodQueryAnnotationsCapabilitiesProfessional Edition only.
This method specifies the update methods that the server supports.  
 MethodQueryUpdateCapabilitiesProfessional Edition only.
This method specifies the update methods that the server supports.  
 MethodReadAnnotationsOverloaded. Professional Edition only.
This function reads the annotations from the history database in the specified time domain for the specified item IDs. This method is intended to read annotations for an item at specified timestamps. The time domain of the request is defined by htStartTime and htEndTime. If htEndTime is less than htStartTime the data shall be returned in reverse order, with later data coming first. OPC_S_NODATA is returned only if no annotations exist over the time domain.  
 MethodReadAtTimeOverloaded. Synchronous ReadAtTime.
This method reads the values and qualities from the history database for the specified timestamps for one or more items. This method is intended to provide values to correlate with other values with a known timestamp. For example, the values of sensors when lab samples were collected. The order of the values and qualities returned shall match the order of the time stamps supplied in the request. When no value exists for a specified timestamp, a value shall be interpolated from the surrounding values to represent the value at the specified timestamp. The interpolation will follow the same rules as the standard Intpolated aggregate as outlined in Section 2.9 of the OPC HDA specification. The OPCHDA_ITEM structure will return OPCHDA_NOAGGREGATE in the aggregate field. If a value is found for the specified timestamp, the server will set the OPCHDA_RAW bit in the quality. If the value is interpolated from the surrounding values, the server will set the OPCHDA_INTERPOLATED bit in the quality.  
 MethodReadAttributeOverloaded. Synchronous ReadAttribute.
This method reads the attribute values and timestamps from the history database for the specified time domain for an item. If the current values for the attributes are desired, endTime is MinValue time. This method is intended to be used to retrieve attributes that have changed to correlate the values of these attributes with the values of their data. For example, the recalibration of a sensor may have required the normal maximum and minimum attributes to be changed. If the only attribute values available for the item are the current values, these shall be returned and errors set to OPC_S_CURRENTVALUE. Except for the case where current values are requested (endTime = MinValue), the server shall always return a beginning bounding value. Thus, if the client requests attribute values for Jan1, 1997 to October 1, 1997, the server shall return a value for the attribute on Jan 1, 1997, rather than the first value returned being the first new value for the attribute after Jan 1, 1997. Likewise, the timestamp for that first value shall be Jan 1, 1997, regardless of when the attribute actually took that value. All other timestamps shall be for the time when the value of the attribute changed. Note that while the client can query the server for the native datatype of an ItemID, the client cannot assume that all data sent from the server will be that datatype. The datatype of a given ItemID may have changed over the life of the Item, and thus clients should be able to handle receiving data of a different datatype than that returned from this call.  
 MethodReadModifiedOverloaded. Synchronous ReadModified.
This method reads the values, qualities, timestamps, user ID, and timestamp of the modification from the history database for the specified time domain for one or more items. The purpose of This method is to read values from history that have been modified/replaced. If ReadRaw, ReadProcessed, or ReadAtTime has returned a quality of OPCHDA_EXTRADATA, indicating that there are values which have been superseded, This method reads those values which were superseded. Only values that have been modified/replaced or deleted are read by this method.

The domain of the request is defined by startTime, endTime, and numValues; at least two of these must be specified. If endTime is less than startTime, or endTime and numValues alone are specified, the data shall be returned in reverse order, with later data coming first. If all three are specified, the call shall return up to numValues results going from startTime to endTime, in either ascending or descending order depending on the relative values of startTime and endTime. If more than numValues results exist within that time range, the errors entry for that ItemID shall be OPC_S_MOREDATA. If numValues is 0, then all the values in the range are returned. If a value has been modified multiple times, all values for the time are returned. This means that a timestamp can appear in the array more than once. The order of the returned values with the same timestamp should be from most recent to oldest modified value. It is server dependent whether multiple modifications are kept or only the most recent.  
 MethodReadProcessedOverloaded. Synchronous ReadProcessed.
This method computes aggregate values, qualities, and timestamps from data in the history database for the specified time domain for one or more items. The time domain is divided into subintervals of duration resampleInterval. The specified aggregate is calculated for each subinterval beginning with startTime by using the data within the next resampleInterval. This method is intended to provide values calculated with respect to the resample interval. For example, This method can provide hourly statistics such as Maximum, Minimum, Average, etc. for each item during the specified time domain when resampleInterval is 1 hour.  
 MethodReadRawOverloaded. Synchronous ReadRaw.
This method reads the values, qualities, and timestamps from the history database for the specified time domain for one or more items. When bBounds is TRUE, the bounding values for the time domain are returned. This method is intended for use by clients wanting the actual data saved within the historian. The actual data may be compressed or may be all data collected for the item depending on the historian and the storage rules invoked when the item values were saved. The optional bounding values are provided to allow clients to interpolate values for the start and end times when trending the actual data on a display.  
 MethodReleaseItemHandlesThis method releases associations between server handles and client handles for specific HDA items.  
 MethodShutdownSignalThis method is called from the generic server when a Shutdown is executed.
To ensure proper process shutdown, any communication channels should be closed and all threads terminated before this method returns.  
 MethodUpdateDeleteAtTimeOverloaded. Professional Edition only.
This method deletes the values and qualities in the history database for the specified timestamps for one or more items. This method is intended to be used to delete specific data from the history database; e.g., lab data that is incorrect and cannot be correctly reproduced.  
 MethodUpdateDeleteRawOverloaded. Professional Edition only.
This method deletes the values, qualities, and timestamps from the history database for the specified time domain for one or more items. This method is intended to be used to delete data that has been accidentally entered into the history database; e.g., deletion of data from a source with incorrect timestamps. If no data is found in the time range for a particular item, a success status of S_FALSE is returned and the error code for that item is OPC_S_NODATA.  
 MethodUpdateInsertOverloaded. Professional Edition only.
This method inserts values and qualities into the history database at the specified timestamps for one or more items. If a value exists at the specified timestamp, the new value shall not be inserted; instead errors shall indicate an error. This method is intended to insert new values at the specified timestamps; e.g., the insertion of lab data to reflect the time of data collection. The serverHnd, timeStamps, dataValues and qualities are arrays of equal size. To insert a value for a number of different items at a single time, then timeStamp array would have the same time for each item. To insert a stream of values, timestamps and qualities for a single item, set the size of the item array to the number of values to be inserted and put the same ItemID in each element.  
 MethodUpdateInsertReplaceOverloaded. Professional Edition only.
This method inserts or replaces values and qualities in the history database for the specified timestamps for one or more items. If the item has a value at the specified timestamp, the new value and quality will replace the old one. If there is no value at that timestamp, the method will insert the new data. The method runs to completion before returning. This method is intended to unconditionally insert/replace values and qualities; e.g., correction of values for bad sensors. The serverHnd, timeStamps, dataValues and qualities are arrays of equal size. To set values and qualities for a number of different items at a single time, then ftTimeStamp array would have the same time for each item. To set a stream of values, timestamps and qualities for a single item, set the size of the item array to the number of values to be inserted/replaced and put the same ItemID in each element. S_OK as a errors return code for an individual value is allowed when the HDA server is unable to say whether there was already a value at that timestamp. If the HDA server can determine whether the new value replaces a value that was already there, it should use OPC_S_INSERTED or OPC_S_REPLACED to return that information.  
 MethodUpdateReplaceOverloaded. Professional Edition only.
This method replaces the values and qualities in the history database at the specified timestamps for one or more items. If no value exists at the specified timestamp, the new value shall not be inserted; instead errors shall indicate an error. This method is intended to replace existing values at the specified timestamp; e.g., correct lab data that was improperly processed, but inserted into the history database. The serverHnd, timeStamps, dataValues and qualities are arrays of equal size. To replace the values for a number of different items at a single time, then timeStamps array would have the same time for each item. To replace a stream of values, timestamps and qualities for a single item, set the size of the item array to the number of values to be replaced and put the same ItemID in each element.  
 MethodValidateItemIDsThis method validates that specific HDA item IDs are known to the server.  
Top
See Also

Reference

IAppPlugin Interface
I_HDAPlugin Namespace

 

 


Copyright © 2004-2019 Advosol Inc. All rights reserved

Send Feedback