Insert method (C++)

To write a history sample into an existing history tag, use the CreateTags method to create the history tag with a .HDE suffix. You can then use the standard Insert method for the IOPCHDA_SyncUpdate interface in a C++ program; for additional information about the following syntax, refer to section 4.4.4.2 in OPC Historical Data Access Specification Version 1.20:

HRESULT Insert(
        [in] DWORD dwNumItems,
        [in, size_is(dwNumItems)] OPCHANDLE *phServer,
        [in, size_is(dwNumItems)] FILETIME *ftTimeStamps,
        [in, size_is(dwNumItems)] VARIANT *vDataValues,
        [in, size_is(dwNumItems)] DWORD *pdwQualities,
        [out, size_is(, dwNumItems)] HRESULT **ppErrors);

Parameter	Description
`dwNumItems`	The number of history tags to be written to the DeltaV Continuous Historian database.
`phServer`	The list of OPC HDA server item handles for the items to be inserted.
`ftTimeStamps`	An array of the time stamps for the new values.
`vDataValues`	An array of structures which contain the new item values.
`pdwQualities`	An array of the Quality flags of the new values.
`ppErrors`	An array of HRESULTs indicating the success of the individual item. The errors correspond to the handles passed in `phServer`. This indicates whether the data write succeeded.

Important

After a history sample is written to the DeltaV Continuous Historian database using the Insert method, you can use the DeleteAtTime method to remove an item from the history database, but the history tag created with the CreateTags method cannot be deleted.

Rules and operation

The Insert method performs a security check to verify through the DeltaV runtime services that the user has the HISTORICAL_DATA_ENTRY key in order to write a history samples to existing history tags. For applications running locally to the OPC HDA server, the user will be the interactive Windows user. For applications running remotely, a DCOM query is used to determine the user that made the call.⁽¹⁾

After user security is verified, the Insert method validates that all history tags passed contain the following elements as defined by OPC standards:

A valid FILETIME time stamp that can be successfully converted to a SYSTEMTIME that is not in the future at the time the call is made.
A valid VARIANT value must be of variant data type 32-bit float (VT_R4) or string (VT_BSTR). A number that exceeds 32-bit precision is truncated to a float value. Strings are limited to 512 characters.
A valid DWORD Quality flag expressed as an integer in the range of 0 to 255 inclusive. The Quality flag refers to the parameter status (i.e. the .ST OPC status). For a list of valid Quality flags, refer to OPC Data Access Custom Interface Standard Version 2.05A, section 6.8. Any unrecognized Quality flag defaults to B010000XX (Uncertain/Non-specific).

The DeltaV Continuous Historian supports a time resolution of 250 milliseconds. Therefore, the time stamps of history samples written to the DeltaV Continuous Historian database using the Insert method are rounded to the nearest 250 ms, as indicated in the following table:

Time range	Rounded value
0–124 ms	0 ms
125–374 ms	250 ms
375–624 ms	500 ms
625–874 ms	750 ms
875–999 ms	1,000 ms

Note

Because the Insert method must evaluate the correct location for the specified time stamp, execution time increases proportionately to the number of current and active data sets in the DeltaV Continuous Historian database.