Technical Reference > CtAPI Functions > Function Reference > TrnQuery


Provides a powerful interface into the trend achive from external applications, replacing the old CtAPITrend query. TrnQuery performs significantly better than CtAPITrend.

TrnQuery is performed through the same mechanism as CtAPITrend. To establish the query and return the first record, you call ctFindFirst. Then, to browse the remaining records, you call ctFindNext. To access the data of the current record, ctGetProperty is called for each field of the record.

ctFindFirst is called with the following parameters:

The szTableName is the command string for the query. It contains the parameters for the query.



Note: Arguments needs to be comma-separated. Spaces between arguments are supported but not necessary. We recommend no spaces between arguments as they require more processing and take up more space in the query string.


End time of the trend query in seconds since 1970 as an integer. This time is expected to be a UTC time (Universal Time Coordinates).


Millisecond portion of the end time as an integer, expected to be a number between 0 and 999.


Time period in seconds between the samples returned as a floating point value. The only decimal separator supported is the `.'.


Number of samples requested as an integer. The start time of the request is calculated by multiplying the Period by NumSamples - 1, then subtracting this from the EndTime.

The actual maximum amount of samples returned is actually NumSamples + 2. This is because we return the previous and next samples before and after the requested range. This is useful as it tells you where the next data is before and after where you requested it.


The name of the trend tag as a string. This query only supports the retrieval of trend data for one trend at a time.


Specifies the different options for formatting and calculating the samples of the query as an unsigned integer. See Display Mode for information.


Mode of this request as an integer. 1 if you want the timestamps to be returned with their full precision and accuracy. Mode 1 does not interpolate samples where there were no values. 0 if you want the timestamps to be calculated, one per period. Mode 0 does interpolate samples, where there was no values.


An integer specifying whether the query is for an instant trend. 1 if for an instant trend. 0 if not.


An integer specifying the requested sample period in milliseconds for the instant trend's tag value.

Return Value

See Returned Data for return values.