Write Functions

Prototype

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

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.

Use the ihuWriteComment function to write a single comment to a single data sample.

Prototype

ihuWriteComment {
  in long serverhandle,
  in MSO Char *Tagname,
  in IHU_timestamp *time stamp,
  in MSO Char *Comment,
  in MSO Char *SuppliedUser,
  in MSO Char *SuppliedPassword
};

Remarks

Comments can be written with any time stamp that is valid for a data write. See ihuWriteDatafunction for details on valid time stamps. If there is an existing raw sample for the specified tag and time stamp, the comment is attached with no loss of data values stored with that sample. Otherwise, a new raw sample with no value is created to hold the comment.

If a time stamp with 0 seconds is passed in, the current time is used.

Currently, comments written with the User API must be string text.

The SuppliedUser and SuppliedPassword parameters are optional and can be NULL. If set, values must be a valid username and password with write permissions, or the comment write fails.

Returns

• ihuSTATUS_OK on success, error otherwise.