Write Functions

Important: You do not have the latest version of Historian! You are missing out on the newest capabilities and enhanced security. For information on all the latest features, see the Historian product page. For more information on upgrades, contact your GE Digital sales agent or e-mail GE Digital Sales Support. For the most up-to-date documentation, go here.

Write Functions Overview

Write Functions

The write functions are designed for high-performance data write access to the archiver. Groups of data samples are built up in the application and then sent as a whole into the API for transmission to the server. Write errors can be returned to the application, which can then implement its own error handling. Or, the program can write without a wait if there is no error handling.

The application is responsible for all error handling, including retrying failed writes.

ihuWriteData

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
};
Important: You cannot write more than 100,000 samples in each call to this function. It is recommended that you write 1,000 to 10,000 samples per call.

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.

Note: Although the IHU_DATA_SAMPLE function has a field for comments, you cannot call it to write a comment. Use the ihuWriteComment function instead.

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.

Important: The User API passes through any timestamps it is given without adjusting for time offsets. The application is responsible to account for time differences between clients and archivers running on different machines.

ihuWriteComment

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.