Read Functions

You can use read functions to retrieve raw, sampled, and calculated values stored in the Historian server for usage in reporting, plotting, or data analysis applications.

In most cases, multiple tags can be read in a single function call.

Most of the read functions serve the general purpose of retrieving raw, sampled or calculated data. Additionally, targeted functions are exposed to provide easy access to current tag values or values interpolated to a specific date and time stamp.

Comments, if they exist, are returned with retrieved data. See the sample programs for more information.

You can combine read functions with write functions to read back newly written data, which is the most secure way to verify successful data writes.

Read Functions

• ihuReadCurrentValue
• ihuReadInterpolatedValue
• ihuReadInterpolatedValueEx
• ihuReadRawDataByTime
• ihuReadRawDataByTimeEx
• ihuReadMultiTagRawDataByCountEx
• ihuReadRawDataByCount
• ihuReadRawDataByCountEx
• ihuReadMultiTagRawDataByCount
• ihuReadMultiTagRawDataByCountEx
• ihuRetrieveSampledData
• ihuRetrieveSampledDataEx
• ihuRetrieveSampledDataEx2
• ihuRetrieveCalculatedData
• ihuRetrieveCalculatedDataEx
• ihuRetrieveCalculatedDataEx3

Use the ihuReadCurrentValue function to return the current tag value. The current tag value has a specific definition in Historian, but is generally the last raw sample sent to the archiver for that tag.

Prototype

ihuReadCurrentValue {
  in long serverhandle,
  in int number_of_tags,
  in/out IHU_DATA_SAMPLE *pSamples,
  out ihuErrorCode *error_returns
};

Remarks

You can retrieve current values for multiple tags with one call. A single sample for each requested tag is returned.

For each tag, set only the tagname field in IHU_DATA_SAMPLE. All other fields are set by the function.

Data is returned based on the data type of the tag.

Returns

The ihuReadCurrentValue function returns errors in two ways. The function has a return code, and each tag name has an error code. Check function-level errors before you examine tag-level errors.

Both are ihuSTATUS_OK when the current value is successfully retrieved.

The ihuReadCurrentValue function can return errors on read timeouts or when the user is not a member of the ih Readers security group.

For example, each tag can return an error in cases where tags are not found or have no raw samples.

Use the ihuReadInterpolatedValue function to return the value of a tag interpolated to a specified date and time.

Prototype

ihuReadInterpolatedValue {
  in long serverhandle,
  in int number_of_tags,
  in/out IHU_DATA_SAMPLE * pSamples,
  out ihuErrorCode * error_returns
};

Remarks

You can retrieve values for multiple tags with one call. A single sample for each requested tag is returned.

For each tag, set only the tagname and time stamp fields in IHU_DATA_SAMPLE. All other fields are set by the function. The time stamp in the first requested tag is used for all tags.

Data is returned based on the data type of the tag.

The data quality returned is either ihuOPCGood or ihuOPCBad, and the substatus is always ihuOPCNonspecific.

You must specify a time stamp in IHU_DATA_SAMPLE for the first requested tag, for example:

//you only need to populate the time stamp in the first sample
lRet = IHU_timestamp_FromParts(2003,
7,
22,
11,
0,
0,
0,
&(pSamples[0].timestamp));
lRet= ihuReadInterpolatedValue (serverhandle, // handle from connect
number_of_tags, // number of tags, one sample per tag
pSamples, // allocated by caller, value set by API
error_returns); // error code per tag

For an example, refer to the ReportLike sample program.

Returns

The ihuReadInterpolatedValue function returns errors in two ways. The function has a return code, and each tag name has an error code. Check function-level errors before you examine tag-level errors.

Both are ihuSTATUS_OK when the current value is successfully retrieved.

The ihuReadInterpolatedValue function returns errors on read timeouts or when the user is not a member of the ih Readers security group.

For example, each tag can return an error in cases where tags are not found or have no raw samples.

Use the ihuReadInterpolatedValueEx function to return the number of samples of a tag interpolated to a given date and time with filters and query modifiers by using pszFilterExpression and CriteriaString.

Prototype

ihuErrorCode IHUAPI ihuReadInterpolatedValueEx
(
long serverhandle, // [in] used for communication with server
int number_of_tags, // [in] the number of tags to retrieve
IHU_DATA_SAMPLE *pSamples, // [in/out] user fills tagname and timestamp and the API fills other fields
MSO_Char *pszFilterExpression, // [in] Filter Expression e.g. Tag > 20
IHU_FILTER_MODE FilterMode,   // [in] Filter Modes
MSO_Char *CriteriaString, // [in] QueryModifiers to use with data reads
ihuErrorCode *error_returns // [out] populated with per tag error
);

Remarks

To skip filtering, you can pass NULL to pszFilterExpression and ihuExactTime to FilterMode, or you can use ihuReadInterpolatedValue().

Pass NULL to CriteriaString if you do not use a QueryModifier.

You can retrieve values for multiple tags with one call. A single sample for each requested tag is returned.

For each tag, set only the tagname and time stamp fields in IHU_DATA_SAMPLE. All other fields are set by the function. The time stamp in the first requested tag is used for all tags.

Data is returned based on the data type of the tag.

The data quality returned is either ihuOPCGood or ihuOPCBad, and the substatus is always ihuOPCNonspecific.

If you want to specify a time stamp, you must do so in IHU_DATA_SAMPLE for the first requested tag.

Returns

The ihuReadInterpolatedValueEx function returns errors on:

• Read timeouts
• User is not a member of the ih Readers security group
• Tag not found
• Filter criteria or query modifiers cannot be set

Use the ihuReadRawDataByTime function to return multiple raw samples for a single tag in a specified time range.

Prototype

ihuReadRawDataByTime {
  in long serverhandle,
  in MSO Char * tagname,
  in IHU_timestamp * StartTime,
  in IHU_timestamp * EndTime,
  out int * number_of_samples,
  out IHU_DATA_SAMPLE **data_values
};

Remarks

The time stamp, value, and quality of each raw sample are returned.

Returns

The ihuReadRawDataByTime function returns ihuSTATUS_OK when values are successfully retrieved.

Errors are returned on read timeouts, when the user is not a member of the ih Readers security group, or if the tag is not found.

Use the ihuReadRawDataByTimeEx function to return multiple raw samples for a single tag in a specified time range with filters and query modifiers by using pszFilterExpression and CriteriaString.

Prototype

ihuReadRawDataByTimeEx {
long serverhandle, // [in] the serverhandle
MSO_Char *tagname, // [in] the single tagname to fetch data for
MSO_Char *pszFilterExpression, // [in] Filter Expression e.g. Tag > 20
IHU_FILTER_MODE FilterMode,   // [in] Filter Modes
MSO_Char *CriteriaString, // [in] QueryModifiers to use with data reads
IHU_TIMESTAMP * StartTime, // [in] Start time of query
IHU_TIMESTAMP * EndTime, // [in] End Time of query
int * number_of_samples, //[out] the number of samples returned
IHU_DATA_SAMPLE **data_values // [out] the returned data samples, unlimited number
};

Remarks

To skip filtering, you can pass NULL to pszFilterExpression and ihuExactTime to FilterMode, or you can use ihuReadRawDataByTime().

Pass NULL to CriteriaString if you do not use a QueryModifier.

The time stamp, value, and quality of each raw sample are returned.

Returns

The ihuReadRawDataByTimeEx function returns ihuSTATUS_OK on success, or returns errors on:

• Read timeouts
• User is not a member of the ih Readers security group
• Tag not found
• Filter criteria or query modifiers cannot be set

Use the ihuReadRawDataByCount function to return the requested number of raw samples for a single tag going forward or backward in time from a specified time stamp. In cases where the number of samples available is less than the value specified in the number_of_samples parameter, the function stops returning data.

Prototype

ihuReadRawDataByCount {
  in long serverhandle,
  in MSO Char *tagname,
  in IHU_timestamp * StartTime,
  in/out int * number_of_samples,
  in int TimeForward,
  out IHU_DATA_SAMPLE **data_values
};

Remarks

The time stamp, value, and quality of each raw sample are returned.

Returns

The ihuReadRawDataByCount function returns ihuSTATUS_OK when values are successfully retrieved.

Errors are returned on read timeouts, when the user is not a member of the ih Readers security group, or if the tag is not found.

Use the ihuReadRawDataByCountEx function to return the requested number of raw samples for a single tag going forward or backward in time from a specified time stamp by using pszFilterExpression and CriteriaString. In cases where the number of samples available is less than the value specified in the number_of_samples parameter, the function stops returning data.

Prototype

ihuReadRawDataByCountEx {
long serverhandle, // [in] the serverhandle
MSO_Char *tagname, // [in] the single tagname to fetch data for
MSO_Char *pszFilterExpression, // [in] Filter Expression e.g. Tag > 20
IHU_FILTER_MODE FilterMode,   // [in] Filter Modes
MSO_Char *CriteriaString, // [in] QueryModifiers to use with data reads
IHU_TIMESTAMP * StartTime, // [in] Start time of query
IHU_TIMESTAMP * EndTime, // [in] End time of query
int * number_of_samples, // [in/out] the number of samples to return and actually returned
int TimeForward, // [in] TRUE if search should be in forward time order
IHU_DATA_SAMPLE **data_values // [out] the returned data samples, unlimited number
};

Remarks

To skip filtering, you can pass NULL to pszFilterExpression and ihuExactTime to FilterMode, or you can use ihuReadRawDataByCount().

Pass NULL to CriteriaString if you do not use a QueryModifier.

The time stamp, value, and quality of each raw sample are returned.

Returns

The ihuReadRawDataByCountEx function returns ihuSTATUS_OK when values are successfully retrieved, and returns errors on:

• Read timeouts
• User is not a member of the ih Readers security group
• Tag not found
• Filter criteria or query modifiers cannot be set

Use the ihuReadMultiTagRawDataByCount function to return up to the requested number of raw samples for multiple tags.

Prototype

ihuErrorCode IHUAPI ihuReadMultiTagRawDataByCount (
long serverhandle,
int number_of_tags,
IHU_ TIMESTAMP *StartTime,
int *number_of_samples, BOOL TimeForward,
ihuErrorCode **error_returns, IHU_RETRIEVED_RAW_VALUES *pSamples
);

Remarks

The ihuReadMultiTagRawDataByCount function returns per-tag and overall errors.

Returns

The ihuReadMultitagRawDataByCount function returns ihuSTATUS_OK when values are successfully retrieved.

Errors are returned on read timeouts, when the user is not a member of the ih Readers security group, or if the tag is not found.

Use the ihuReadMultiTagRawDataByCountEx function to return up to a requested number of multiple raw samples for multiple tags with filters and query modifiers by using pszFilterExpression and CriteriaString.

Prototype

ihuErrorCode IHUAPI ihuReadMultiTagRawDataByCountEx (
long serverhandle, // [in] the serverhandle 
int number_of_tags, // [in] the number of tags to retrieve
IHU_TIMESTAMP * StartTime, // [in] Start time of query
IHU_TIMESTAMP * EndTime, // [in] End time of query
MSO_Char *pszFilterExpression, // [in] Filter Expression e.g. Tag > 20
MSO_Char *CriteriaString, // [in] QueryModifiers to use with data reads
IHU_FILTER_MODE FilterMode,   // [in] Filter Modes
int * number_of_samples, // [in/out] the number of samples to return and actually returned
BOOL TimeForward, // [in] TRUE if search should be in forward time order ihuErrorCode ** error_returns, // [out] populated with per tag error
IHU_RETRIEVED_RAW_VALUES *pSamples // [in/out] the returned data samples, unlimited number memory is allocated
);

Remarks

To skip filtering, you can pass NULL to pszFilterExpression and ihuExactTime to FilterMode, or you can use ihuReadMultiTagRawDataByCount().

Pass NULL to CriteriaString if you do not use a QueryModifier.

The ihuReadMultiTagRawDataByCount function returns per-tag and overall errors.

Returns

The ihuReadRawDataByCountEx function returns ihuSTATUS_OK when values are successfully retrieved, and returns errors on:

• Read timeouts
• User is not a member of the ih Readers security group
• Tag not found
• Filter criteria or query modifiers cannot be set

Use the ihuRetrieveSampledData function to return sampled data based on the raw samples stored in the archive. Interpolated, Trend, and Lab are example SamplingMode values.

Prototype

ihuRetrieveSampledData {
  in long serverhandle,
  in IHU_timestamp StartTime,
  in IHU_timestamp EndTime,
  in ihuSamplingMode SamplingMode,
  in unsigned long NumberOfSamples,
  in unsigned long IntervalMilliseconds,
  in/out IHU_RETRIEVED_DATA_RECORDS *DataRecords
};

Remarks

To request data, you can specify a number of samples or a time interval. Set one parameter to a non-zero value and the other to 0. To split the duration, divide the time from start to finish into evenly spaced time intervals.

Returns

The ihuRetrieveSampledData function returns ihuSTATUS_OK when values are successfully retrieved.

Errors are returned on read timeouts, when the user is not a member of the ih Readers security group, or if the tag is not found.

Use the ihuRetrieveSampledDataEx function to return sampled data based on the raw samples stored in the archive. Interpolated, Trend, and Lab are example SamplingMode values. Use this function with hybrid sampling modes such as TrendToRaw or InterpolatedToRaw to return the sampling mode that was actually used.

Prototype

ihuRetrieveSampledDataEx {
long serverhandle, // [in] which server to fetch from
IHU_TIMESTAMP StartTime, // [in] Start time for the query
IHU_TIMESTAMP EndTime, // [in] End time for the query
ihuSamplingMode SamplingMode, // [in] The requested sampling mode
unsigned long NumberOfSamples, // [in] 0 or num samples to return
IHU_DATA_INTERVAL Interval, // [in] 0 or sampling interval in units provided by IntervalType
IHU_RETRIEVED_DATA_RECORDS_EX *DataRecords // [in/out] - caller fills in tagnames of the structures and API will
};

Remarks

To request data, you can specify a number of samples or a time interval. Set one parameter to a non-zero value and the other to 0. To split the duration, divide the time from start to finish into evenly spaced time intervals.

If you are not using hybrid sampling modes, use ihuRetrieveSampledData().

Returns

The ihuReadRawDataByTimeEx function returns ihuSTATUS_OK when values are successfully retrieved, and returns errors on:

• Read timeouts
• User is not a member of the ih Readers security group
• Tag not found

Use the ihuRetrieveSampledDataEx2 function to return sampled data based on the raw samples stored in the archive with filters and query modifiers by using pszFilterExpression and CriteriaString. Interpolated, Trend, and Lab are example SamplingMode values. Use this function with hybrid sampling modes such as TrendToRaw or InterpolatedToRaw to return the sampling mode that was actually used.

Prototype

ihuRetrieveSampledDataEx2 {
long serverhandle, // [in] which server to fetch from
IHU_TIMESTAMP StartTime, //[in] Start time for the query
IHU_TIMESTAMP EndTime, //[in] End time for the query
ihuSamplingMode SamplingMode, //Sampling Modes
MSO_Char *pszFilterExpression, // [in] Filter Expression e.g. Tag > 20
IHU_FILTER_MODE FilterMode,   // [in] Filter Modes
MSO_Char *CriteriaString, // [in] QueryModifiers to use with data reads
unsigned long NumberOfSamples, //[in] 0 or number of samples to return
IHU_DATA_INTERVAL Interval, // [in] 0 or sampling interval in units provided by IntervalType
IHU_RETRIEVED_DATA_RECORDS_EX *DataRecords //[in/out] - you fill in tagnames of the structures and API will fil
};

Remarks

To request data, you can specify a number of samples or a time interval. Set one parameter to a non-zero value and the other to 0. To split the duration, divide the time from start to finish into evenly spaced time intervals.

To skip filtering, you can pass NULL to pszFilterExpression and ihuExactTime to FilterMode, or you can use ihuRetrieveSampledData().

Pass NULL to CriteriaString if you do not use a QueryModifier.

Returns

The ihuRetrieveSampledDataEx2 function returns ihuSTATUS_OK when values are successfully retrieved, and returns errors on:

• Read timeouts
• User is not a member of the ih Readers security group
• Tag not found
• Filter criteria or query modifiers cannot be set

Use the ihuRetrieveCalculatedData function to return calculated data based on the raw samples stored in the archive. Average, Minimum, and Count are example CalculationMode values.

Prototype

ihuRetrieveCalculatedData {
  in long serverhandle,
  in IHU_timestamp StartTime,
  in IHU_timestamp EndTime,
  in ihuCalculationMode CalculationMode,
  in unsigned long NumberOfSamples,
  in unsigned long IntervalMilliseconds, 
  in/out IHU_RETRIEVED_DATA_RECORDS *DataRecords
};

Remarks

To request data, you can specify a number of samples or a time interval. Set one parameter to a non-zero value and the other to 0. To split the duration, divide the time from start to finish into evenly spaced time intervals.

Returns

The ihuRetrieveCalculatedData function returns ihuSTATUS_OK when values are successfully retrieved.

Errors are returned on read timeouts, when the user is not a member of the ih Readers security group, or if the tag is not found.

Use the ihuRetrieveCalculatedDataEx function to return calculated data based on the raw samples stored in the archive. Average, Minimum, and Count are example CalculationMode values.

Prototype

ihuRetrieveCalculatedDataEx {
long serverhandle, // [in] which server to fetch from
IHU_TIMESTAMP StartTime, //[in] Start time of query
IHU_TIMESTAMP EndTime, //[in] End time of query
ihuCalculationMode CalculationMode, //[in] Calculation Mode
unsigned long NumberOfSamples, //[in] Number of samples to be returned
IHU_DATA_INTERVAL Interval, // [in] Interval in Milliseconds
IHU_RETRIEVED_DATA_RECORDS_EX *DataRecords //[in/out] - you fill in tagnames of the structures and API will fil
};

Remarks

To request data, you can specify a number of samples or a time interval. Set one parameter to a non-zero value and the other to 0. To split the duration, divide the time from start to finish into evenly spaced time intervals.

Returns

The ihuReadRawDataByTimeEx2 function returns ihuSTATUS_OK when values are successfully retrieved, and returns errors on:

• Read timeouts
• User is not a member of the ih Readers security group
• Tag not found

Use the ihuRetrieveCalculatedDataEx3 function to return sampled data based on the raw samples stored in the archive with filters and query modifiers by using pszFilterExpression and CriteriaString. Average, Minimum, and Count are example CalculationMode values.

Prototype

ihuRetrieveCalculatedDataEx3 {
long serverhandle, // [in] which server to fetch from
IHU_TIMESTAMP StartTime, // [in] Start time of query
IHU_TIMESTAMP EndTime, // [in] End time of query
ihuCalculationMode CalculationMode, //[in] Calculation Mode
MSO_Char *pszFilterExpression, // [in] Filter Expression e.g. Tag > 20
IHU_FILTER_MODE FilterMode,   // [in] Filter Modes
MSO_Char *CriteriaString, // [in] QueryModifiers to use with data reads
ihuDataType StateDataType, // DataType of the StateValue to compare for ihuStateCount calculation mode
ihuValue StateValue, // Value to compare for ihuStateCount calculation mode unsigned long NumberOfSamples, IHU_DATA_INTERVAL Interval, // [in] Interval in Milliseconds
IHU_RETRIEVED_DATA_RECORDS_EX *DataRecords // [in/out] - you fill in tagnames of the structures and API will fil
};

Remarks

To request data, you can specify a number of samples or a time interval. Set one parameter to a non-zero value and the other to 0. To split the duration, divide the time from start to finish into evenly spaced time intervals.

To skip filtering, you can pass NULL to pszFilterExpression and ihuExactTime to FilterMode, or you can use ihuRetrieveCalculatedData().

Pass NULL to CriteriaString if you do not use a QueryModifier.

Returns

The ihuRetrieveCalculatedDataEx3 function returns ihuSTATUS_OK when values are successfully retrieved, and returns errors on:

• Read timeouts
• User is not a member of the ih Readers security group
• Tag not found
• Filter criteria or query modifiers cannot be set