ihuWriteData

Use the high-performance ihuWriteData function to write multiple samples for multiple tags.

Prototype

ihuWriteData {
  in long serverhandle,
  in int number_of_samples,
  in IHU_DATA_SAMPLE *data_values,
  in ihuErrorCode *error_returns ,
  in bool wait_for_reply,
  in bool error_on_replace
};

Remarks

The Historian archiver has the following strict data-write rules that apply to all applications and collectors:

1. No application is allowed to write data with a time stamp older than now minus the "Data is read only after" active hours setting. Such writes fail.
2. No application is allowed to write data with a time stamp before the start time of the first archive, even if the write satisfies the previous rule.
3. No application can write data to a read-only archive.
4. No application can write data with a time stamp more than 15 minutes in the future.

The write function has two Boolean parameters to control optional behavior:

• wait_for_reply: When set to TRUE, write operations are blocked until the values are acknowledged by the archiver. This allows you to check the error returns to reach a degree of confidence that the data was written successfully. You cannot check error codes unless you wait for the reply.

  If it is important to return control to your program so that collection can be performed, consider setting wait_for_reply=FALSE. You might also want to set wait_for_reply=FALSE if you have no specific error-handling strategy, or if you are using data readbacks to verify write success.

  If you are using store and forward in the User API, set wait_for_reply=FALSE.

  Note: If you set wait_for_reply=FALSE, you must pass a NULL error array for the ihuErrorCode *error_returns value.
• error_on_replace: This parameter has no effect on performance. Use it to specify how the archiver behaves when an existing archived sample has the same time stamp as a new sample being written. Set error_on_replace=TRUE to discard the new sample and return an error that you can see when wait_ for_reply=TRUE. Set error_on_replace=FALSE to overwrite the existing sample with the new sample.

Time Stamps

You can use this function to specify a time stamp or pass a time stamp of 0 seconds to use the current system time on the written sample. Pass a time stamp structure where seconds=0, and do not pass NULL. All samples in the group with a 0 time stamp specified use the system time at the time of the write as a time stamp. Values are in microseconds.

Values

Values to be written are not required to have matching data types as the Historian tags. The archiver converts written data types to tag data types if needed.

Qualities

You are required to specify the data quality and subquality for the sample when you use this function. There are no default values.

Error Handling

The User API does not provide store and forward or retry functionality for failed writes. That is the responsibility of the application. You can write User API programs that perform retries or use store and forward.

If you get a timeout back from a write, the write may be waiting in a write queue on the data archiver.

Security

Historian has audited and unaudited write security groups and a security administration group. To perform writes, you must be a member of one of these groups. Otherwise, you get an ihuSTATUS_ACCESS_DENIED error.

Returns

This function returns ihuSTATUS_OK when values are successfully written.

Errors are returned on timeouts, when you are not a member of the necessary security group, or when tags are not found.