System API Programming

Unicode

String tag names, string tag properties such as description, and string data values are all Unicode strings.

Memory

You should never free memory allocated in the API. The API provides many functions to free memory or clear record sets and structures and you should use them as demonstrated in sample programs.

String Length

In the API you will notice that most string fields such as tag names or descriptions are just pointers and this is because they do not have a maximum length. They must be allocated and freed.

Networking between the System API and the Data Archiver

The communication between the ihapi DLL and the Data Archiver is TCP/IP networking which sends proprietary packet streams via Winsock calls. The details are not documented.

Multithread Programming

You can have multiple threads reading and writing data, even sharing the same connection.

Multitag Functions

In most cases you can simply act on one tag at a time when reading data or adding tags. These calls are less frequent than writing data. But there are API calls that can handle multiple tags in one round trip and your design should decide if they are needed for performance reasons.

Timestamps

You will see that the timestamp structure is in seconds and subseconds. It is implied that the time zone of the seconds is in GMT+0 Universal Time Coordinated time zone. The System API gives utility functions to convert timestamps to and from local time zones.

Running as a Service

You can develop programs that run as GUI programs, console programs, or services.

Timeouts and Throttles in the System API and the Data Archiver

The Data Archiver will try to protect the system against unintentional large data queries. There are Data Archiver enforced, configurable throttles for queries that return too many samples or take too long to execute. Use the ihArchiverMaxIntervalRetrievalCount and ihArchiverMaxQueryTime archiver options to increase the limits if you occasionally get the ihSTATUS_DATA_RETRIEVAL_COUNT_EXCEEDED error from intentional large queries.

On the System API side there is a configurable timeout set via ihServerSetTimeout() and defaults to 90 seconds. Data writes and setting of options must complete within this time period or the API will return an error to the application. The Data Archiver may have queued the work and will still perform the request even if a timeout is returned to the application.

Reads and tag browses can take longer than 90 seconds and this is because the API needs to receive only a partial response every 90 seconds. Large reads and tag browses are streamed back to the API in pieces as the read or browse is still being performed in the Data Archiver. If we do not receive at least one piece every 90 seconds, a timeout error is returned to application but the Data Archiver will continue working until it hits the limit in ihArchiverMaxQueryTime archiver option.