OPC HDA 1.20 Specification Errata

[MatrikonOPC]

Errata 8.0 Clarify rules for asynchronous reads that sent multiple callbacks.

An asynchronous ReadRaw/ReadModified operation could result in multiplecallbacks since the client could limit the number of values in a singlecallback with the dwNumValues parameter. The spec needs to clarify how theserver should handle this when there are multiple items and only some of theitems have additional data.Specifically, the server should indicate which items have more data comingin subsequent calls by returning the S_MOREDATA result for the item. Theclient may assume that a transaction is complete when no items in a callbackhave the S_MOREDATA status. In addition, the server should only return thoseitems that have additional data in subsequent callbacks - the client mustuse the client handle (not the index in the array) to associate the valuesin a callback with a particular item.

Portions of the specifications updated:
==========================================================
4.5.1. IOPCHDA_AsyncRead
ppError Codes
Return Code Description
S_OK The item was read successfully.
OPC_S_MOREDATA More data is available in the time range beyond the number of values requested.
OPC_E_BADRIGHTS Insufficient rights for this operation.
OPC_E_INVALIDHANDLE The handle is invalid.
Comments
…
An asynchronous ReadRaw operation could result in multiple callbacks if the clients limits the number of values in a single callback with the dwNumValues parameter. The server should indicate which items have more data coming in subsequent calls by returning the OPC_S_MOREDATA result for the item. The client may assume that a transaction is complete when no items in a callback have the S_MOREDATA status. In addition, the server should only return those items that have additional data in subsequent callbacks - the client must use the client handle (not the index in the array) to associate the values in a callback with a particular item.




==========================================================

4.5.1.6. IOPCHDA_AsyncRead::ReadModified
ppError Codes
Return Code Description
S_OK The item was read successfully.
OPC_S_MOREDATA More data is available in the time range beyond the number of values requested.
OPC_E_BADRIGHTS Insufficient rights for this operation.
OPC_E_INVALIDHANDLE The handle is invalid.
Comments
…
An asynchronous ReadModified operation could result in multiple callbacks if the clients limits the number of values in a single callback with the dwNumValues parameter. The server should indicate which items have more data coming in subsequent calls by returning the OPC_S_MOREDATA result for the item. The client may assume that a transaction is complete when no items in a callback have the S_MOREDATA status. In addition, the server should only return those items that have additional data in subsequent callbacks - the client must use the client handle (not the index in the array) to associate the values in a callback with a particular item.

[MatrikonOPC]

Errata 9.0 OnPlayback usage needs to be clarified.

The existing OnPlayback interface with the OPCHDA_ITEM** is useable for oneor more items.

Portions of the specifications updated:
==========================================================
4.8.1.7. IOPCHDA_DataCallback::OnPlayback
NOTE: There is a discrepancy between the specification and the IDL with respect to the pItemValues parameter. The specification is a single pointer, the IDL has two pointers. The existing OnPlayback interface with the OPCHDA_ITEM** is useable for one or more items. The correct syntax for making the call on the server is:

[MatrikonOPC]

Errata 10.0 Clarify use of Cancel()

The same Cancel() method appears on multiple interfaces. It is possible fora server to use object aggregation and provide a different implementation ofCancel() for each interface. However, it makes most sense for servers to usethe same implementation for all interfaces.The spec should state that servers are not expected reject requests tocancel transactions if the client calls the 'wrong' version of Cancel. Forexample, a client calls ReadRawWithUpdate() and then attempts to cancel theplayback by calling AsyncRead::Cancel() instead of Playback::Cancel(). Theserver should be allowed to process the Cancel() anyways.If possible, servers should be required use CancelIDs that are unique acrossall interfaces and allow clients to use any version of Cancel() to canceltransactions created with any interface.

Portions of the specifications updated:
4.5. Asynchronous Interfaces
…
NOTE: The same Cancel() method appears on multiple interfaces. It is possible for a server to use object aggregation and provide a different implementation of Cancel() for each interface. However, servers may choose to use the same implementation for all interfaces. The servers are not expected to reject requests to cancel transactions if the client calls the 'wrong' version of Cancel. For example, a client calls ReadRawWithUpdate() and then attempts to cancel the playback by calling AsyncRead::Cancel() instead of Playback::Cancel(). The server should be allowed to process this Cancel() request.

[MatrikonOPC]

Errata 11.0 Need to clarify when server should start processing Advise requests for future data.

The way the spec currently reads implies that servers should process adviserequest immediately, even if part of the range is future time. This could result is discontinuities in the trend returned from the advise unless the client picks the 'correct' start time. It makes sense to require that servers defer all advise requests for futuredata until the time 'StartTime + UpdateInterval'. This will eliminate discontinuities in the data returned and make the behavior of the interface more predictable to the client.

Portions of the specifications updated:
==========================================================

4.5.1.2. IOPCHDA_AsyncRead::AdviseRaw
The request will be for all data from the htStartTime into the future, as it is collected, reported at the rate specified by the ftUpdateInterval. Servers should defer processing advise requests for future data until the time 'StartTime + UpdateInterval'. This will eliminate discontinuities in the data returned and make the behavior of the interface more predictable to the client.
Reporting will continue until the request is canceled. Caution should be used in specifying start times prior to the present, as data which is already available will be returned unthrottled, with ftUpdateInterval worth of data in each response. Once all data which has already been collected has been sent, new data will be sent for every ftUpdateInterval.
==========================================================
4.5.1.3. IOPCHDA_AsyncRead::AdviseProcessed
The request will be for all data from the htStartTime into the future, as it is collected, reported at the rate specified by: (dwNumIntervals* ftResampleInterval). Servers should defer processing advise requests for future data until the time 'StartTime + UpdateInterval'. This will eliminate discontinuities in the data returned and make the behavior of the interface more predictable to the client.
The ftResampleInterval determines the subintervals to which the specified functions will be applied. Beginning with htStartTime and selecting the data within the next ftResampleInterval, the values specified by haAggregate will be determined for each subinterval. Reporting shall continue until the request is canceled. Caution should be used in specifying start times prior to the present, as data which is already available will be returned unthrottled, with dwNumIntervals worth of data in each response. Once all data which has already been collected has been sent, new data shall be sent as soon as a full dwNumIntervals worth of data is available.

[MatrikonOPC]

Errata 12.0 When does playback end automatically (e.g. NODATA found?).

The server will know that some playback requests will no longer return any
valid data because there is no more data in archive and the server is not
currently logging new data for the item or because the playback window has
moved into the future.

In these situations, it makes sense to allow the server to automatically
terminate a playback request by returning no values and a status code of
'S_NODATA'. Client would still be able cancel the playback request however
the client will receive no further updates from the server.

Portions of the specifications updated:
==========================================================
4.6.1.1. IOPCHDA_Playback::ReadRawWithUpdate
Comments
…
The server will know that some playback requests will no longer return any valid data because there is no more data in archive and the server is not currently logging new data for the item or because the playback window has moved into the future. In these situations, it is permissible for the server to automatically terminate a playback request by returning no values and a status code of 'S_NODATA'. Client would still be able cancel the playback request however the client will receive no further updates from the server.

4.6.1.2. IOPCHDA_Playback::ReadProcessedWithUpdate
Comments
…
The server will know that some playback requests will no longer return any valid data because there is no more data in archive and the server is not currently logging new data for the item or because the playback window has moved into the future. In these situations, it is permissible for the server to automatically terminate a playback request by returning no values and a status code of 'S_NODATA'. Client would still be able cancel the playback request however the client will receive no further updates from the server.

[MatrikonOPC]

Errata 13.0 Playback EndTime = NULL

Portions of the specifications updated:
==========================================================.

4.6.1.1. IOPCHDA_Playback::ReadRawWithUpdate
Comments
…
If NumValues is specified, but EndTime is not specified., then the timestamp of the last value will be used as the start time for the next read. This means that time domain for each item sent in subsequent updates can be different since it is likely that the timestamp of the last value for each item is different. OPC Clients should be prepared to handle these varying time domains.

[MatrikonOPC]

Errata 14.0 OPC Clients implementing IOPCShutdown.

Add IOPCShutdown information to be consistent with DA spec, and for reference to section 2.4

Portions of the specifications added:
==========================================================.
4.8.2. IOPCShutdown
In order to use this connection point, the client must create an object that supports both the IUnknown and IOPCShutdown Interface. The client would pass a pointer to the IUnknown interface (NOT the IOPCShutdown) to the Advise method of the proper IConnectionPoint in the server (as obtained from IConnectionPointContainer:: FindConnectionPoint or EnumConnectionPoints). The Server will call QueryInterface on the client object to obtain the IOPCShutdown interface. Note that the transaction must be performed in this way in order for the interface marshalling to work properly for Local or Remote servers.
The ShutdownRequest method on this Interface will be called when the server needs to shutdown. The client should release all connections and interfaces for this server.
A client which is connected to multiple OPCServers (for example Data access and/or other servers such as Alarms and events servers from one or more vendors) should maintain separate shutdown callbacks for each object since any server can shut down independently of the others.
4.8.2.1. IOPCShutdown::ShutdownRequest
HRESULT ShutdownRequest (
[in] LPWSTR szReason
);
Description
This method is provided by the client so that the server can request that the client disconnect from the server. The client should UnAdvise all connections, Remove all groups and release all interfaces.

Parameters Description
szReason An optional text string provided by the server indicating the reason for the shutdown. The server may pass a pointer to a NUL string if no reason is provided.

HRESULT Return Codes
Return Code Description
S_OK The client must always return S_OK.

Comments
The shutdown connection point is on a ‘per COM object’ basis. That is, it relates to the object created by CoCreate… If a client connects to multiple COM objects then it should monitor each one separately for shutdown requests.

[MatrikonOPC]

Errata 15.0 Clarification of how to use Relative Timestamps.
The current wording of the specification, section 5.3.4 is confusing... "For the szTime, the time is considered to be a relative time local to the server. This means that all times are given in UTC time, compute from the current time on the server's local clock. The format.." This says both that "times are given in UTC" and "compute from local clock".

Portions of the specifications updated:
==========================================================.
5.3.4 OPCHDA_TIME
…
Comment
For the szTime, the time is considered to be a relative timestamp. The OPC server will convert all relative timestamp strings to UTC timestamps. The format for the relative time is:

[MatrikonOPC]

Errata 16.0 Clarification of time order in Sync DeleteRaw and Aysnc DeleteRaw.
The specification specifically states for Read calls that StartTime > EndTime and EndTime > StartTime are allowed. The DeleteRaw calls do not specifically state this.

Portions of the specifications updated:
==========================================================.
4.4.4.5. IOPCHDA_ SyncUpdate::DeleteRaw
…
Comment
The time domain of the request is defined by htStartTime and htEndTime. It is allowed that htEndTime is less than htStartTime.
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

4.5.2.5. IOPCHDA_ AsyncUpdate::DeleteRaw
…
Comment
The time domain of the request is defined by htStartTime and htEndTime. It is allowed that htEndTime is less than htStartTime.

[MatrikonOPC]

Errata 17.0 ReadRaw where StartTime=EndTime and NumValue = 1 or 2.
The specification does not clearly state the behavior for the case StartTime=EndTime and NumValue = 1 or 2. (It covers cases for StartTime <> EndTime, NumValues = 1 or 2, and the cases for StartTime=EndTime, NumValues = 0, and >2) The current wording states "If bounding values are requested and a non-zero dwNumValues was specified, any bounding values returned are included in the dwNumValues count. If dwNumValues is 1, then only the start bound is returned (the End bound if reverse order is needed). If dwNumValues is 2, then the data point, and the start bound is returned (the End bound if reverse order is needed).".

Portions of the specifications updated:
==========================================================.
4.4.3.1. IOPCHDA_SyncRead::ReadRaw
…
Comment
…
If bounding values are requested and a non-zero dwNumValues was specified, any bounding values returned are included in the dwNumValues count. If dwNumValues is 1, then only the start bound is returned (the End bound if reverse order is needed). If dwNumValues is 2, then the data point, and the start bound is returned (the End bound if reverse order is needed). Cases where htStartTime=htEndTime and dwNumValues =1 or 2, will be treated as if htStartTime < htEndTime.

[MatrikonOPC]

A document outlining the lastest errrata for the the HDA 1.2 specification has been posted to the HDA yahoo group

http://groups.yahoo.com/group/opc-hda/files/HDA%201.2%20Errata/OPC_HIST_Cust1.2_ERRATA_V2.pdf

Plain text versions are also posted in this thread for those who are not part of the OPC HDA Yahoo group.