Archiver Configuration Functions

Menu ihOptions


Option	Description
`ihArchiveDefaultPath`	The default path for new archive creations.
`ihArchiveActiveHours`	Set to a larger number if you need to write data with timestamps in the past older than the "data is read only after” setting in Historian Administrator.
`ihArchiveDefaultSize`	The default size for new archives, when you are not using `ihArchiveDuration` for time based archives.
`ihArchiveAutomaticCreate`,	TRUE if new archives should be created or FALSE if old archives should be reused instead.
`ihArchiveAutomaticFreeSpace`	The amount of disk space to be left free.
`ihArchiveOverwriteOld`	TRUE if you should overwrite old archives instead of refusing incoming data.
`ihArchiveDefaultBaseFileName`	The default base file name which typically matches the computer name but you can update this if you move the Data Archiver to a new computer.
`ihArchiveDefaultBaseArchiveName`	The default base file name which typically matches the computer name but you can update this if you move the Data Archiver to a new computer.
`ihArchiveDefaultBackupPath`	The default location for archive backups; typically this location is the same location as the online archives.
`ihArchiveCreateOfflineArchive`	Set to TRUE if you need to write data with a timestamp before the first archive so that an archive gets created.
`ihMessageOnDataUpdate`	Set to TRUE if you want an audit trail message for every data sample that is overwritten.
`ihArchiverNumReadThreads`	Increase from default if you need more read threads so that you can perform parallel reads.
`ihSecurityUseLocalGroups`	Set to FALSE if you want to use domain security groups.
`ihArchiverMaxIntervalRetrievalCount`	Increase this number if you typically do large queries that return error `ihSTATUS_DATA_RETRIEVAL_COUNT_EXCEEDED`.
`ihArchiverMaxQueryTime`	Increase this number if you typically do large queries that return error `ihSTATUS_DATA_RETRIEVAL_COUNT_EXCEEDED`.
`ihArchiverMaintainAutoRecoveryFiles`	Set to FALSE if you do not want to use this feature.
`ihArchiverAllowDataOverwrites`	Set to FALSE if you don’t want to allow accidental or intentional data overwrites.
`ihArchiverTargetPrivateBytes`	Leave as 0 for system managed unless you have a specific target.
`ihArchiverNumWriteThreads`	Leave as default value.
`ihSecurityStrictClientAuthentication`	True to only permit SSPI-based authentication.
`ihSecurityStrictCollectorAuthentication`	True to only permit collector connections from 5.0 and above.
`ihArchiveTotalDuration`	Number of Hours that the archives for a DataStore can span (only used for trending DataStores).
`ihArchiveDurationType`	The type of archive duration. It is the integer value of `ihArchiveDurationType`.
`ihArchiveDuration`	Number of Units of time an archive can hold. Defined by `ihArchiveDurationType`.
`StructFieldsInBrowsesByDefault`	TRUE if you want each field of a structure to appear as its own tag during tag browse. Useful for legacy clients that are not aware of structures.
`ihOptionMax`	The highest option number for this version of historian. Use this to check for invalid option values.

ihArchiveOpenRecordset

This function is used to get the list of archives listed in the server.

Prototype

ihArchiveOpenRecordset
(
ihServerHandle hServer,
ihArchiveCriteria *Criteria,
ihArchiveRecordset *ArchiveRecordset

);

Remarks

Use the criteria if you only want a specific archive or archives from a specific data store. Otherwise you can get all archives and loop through them to see their start and end times and sizes for example.

Call ihArchiveCloseRecordset() to free the memory when you are done. Do not free memory in your program.

Returns

Returns Status	Message
`ihSTATUS_OK`	On success.
`ihSTATUS_API_TIMEOUT`	If the option could not be read. You can try again later.
`ihSTATUS_NOT_CONNECTED`	If you are not currently connected to the Data Archiver.
`ihSTATUS_FAILED`	For any other type of error.

ihArchiveCloseRecordset

This function is used to free up the memory associated with the ArchiveRecordset.

Prototype

ihArchiveCloseRecordset(

ihArchiveRecordset *ArchiveRecordset
);

Remarks

Use this function to free the memory associated with the ArchiveRecordset that was returned from ihArchiveOpenRecordset(). Do not free the fields in your code.

Returns

Returns Status	Message
`Void`	Void

ihArchiveGetOption

This function retrieves an Archiver option from the data store. This option controls the behavior of the Data Archiver for writes, security and timeouts.

Prototype

ihArchiveGetOption {

ihServerHandle hServer, ihOptionEx *Option, ihChar **OptionValue

);

Remarks

This function retrieves an Archiver option from a data store. You can indicate the data store in the ihOptionEx structure. You can pass NULL as the data store name to use the default data store. You can get an option value to confirm it is set as requested by your application, or you can use this call to verify that a set option call was successful.

Returns

Returns Status	Message
`ihSTATUS_OK`	On success.
`ihSTATUS_API_TIMEOUT`	If the option could not be read. You can try again later.
`ihSTATUS_NOT_CONNECTED`	If you are not currently connected to the Data Archiver.
`ihSTATUS_FAILED`	For any other type of error.

ihArchiveSetOption

This function sets an Archiver option from a data store

Prototype

ihArchiveSetOption {

ihServerHandle hServer, ihOptionEx *Option, ihChar *OptionValue

);

Remarks

This function sets an Archiver option from a data store. You can indicate the data store in the ihOptionEx structure. You can pass NULL as the data store name to use the default data store.

The list of possible options in ihapi.h is listed in the Archiver Configuration Functions. Set an option value when the default does not meet the needs of your application or to confirm that no other application has changed it. Archive option changes are audited in the Historian messages and you can see them using ihMessageOpenRecordset call.

Returns

Returns Status	Message
`ihSTATUS_OK`	On success.
`ihSTATUS_API_TIMEOUT`	If the option could not be read. You can try again later.
`ihSTATUS_NOT_CONNECTED`	If you are not currently connected to the Data Archiver.
`ihSTATUS_FAILED`	For any other type of error.

ihArchiverFreeOption

This function is used to free the memory inside the structure returned from an ihArchiveGetOption().

Prototype

ihArchiveFreeOption{

ihChar *OptionValue // the string returned from ihArchiveGetOption()

);

Remarks

Use this function to free the memory inside the structure. Do not free the fields in your code.

Returns

Returns Status	Message
`Void`	Void.

ihArchiveGetProperties

This function retrieves the properties for an archive in a data store identified by the ArchiveDescriptor.

Prototype

ihArchiveGetProperties (
ihServerHandle hServer, 

ihArchiveDescriptor *ArchiveDescriptor,

ihArchiveProperties *Archive
);

Remarks

You can pass NULL as the data store name to use the default data store.

The ihArchiveProperties contains information such as the StartTime and EndTime and size of the archive.

Make sure to free the archive properties using ihArchiveFreeProperties() function.

Returns

Returns Status	Message
`ihSTATUS_OK`	On success.
`ihSTATUS_API_TIMEOUT`	If the option could not be read. You can try again later.
`ihSTATUS_NOT_CONNECTED`	If you are not currently connected to the Data Archiver.
`ihSTATUS_FAILED`	For any other type of error.

ihArchiveSetProperties

This function sets the properties for an archive.

Prototype

ihArchiveSetProperties {
ihServerHandle hServer,

ihArchiveProperties *Archive
);

Remarks

This is the only archive property set by a user program to make the archive read only.

Returns Status	Message
`ihSTATUS_OK`	On success.
`ihSTATUS_API_TIMEOUT`	If the option could not be read. You can try again later.
`ihSTATUS_NOT_CONNECTED`	If you are not currently connected to the Data Archiver.
`ihSTATUS_FAILED`	For any other type of error.

ihArchiveFreeProperties

This function is used to free up the memory associated with the ArchiveProperties returned from an ihArchiveGetProperties call.

Prototype

ihArchiveFreeProperties {
ihArchiveProperties *ArchiveProperties
);

Remarks

Use this function to free the memory. Do not free the memory by calling operating system functions.

Returns

Returns Status	Message
`Void`	Void.

ihArchiveGetStatistics

This function is used to get performance statistics from the Data Archiver of a particular data store.

Prototype

ihArchiveGetStatistics {
ihServerHandle hServer, ihString DataStoreName, ihArchiveStatistics *Statistics
);

Remarks

This returns the performance statistics about data writes, failed writes, and disk space usage. To get the performance of a particular data store you need pass the data store name.

Returns

Returns Status	Message
`ihSTATUS_OK`	On success.
`ihSTATUS_API_TIMEOUT`	If the option could not be read. You can try again later.
`ihSTATUS_NOT_CONNECTED`	If you are not currently connected to the Data Archiver.
`ihSTATUS_FAILED`	For any other type of error.

ihArchiveBackupResponse

This function is used by the Alarm Archiver only.

Prototype

ihArchiveBackupResponse
(
ihServerHandle hServer, ihCallbackId CallbackId, ihAPIStatus Status, ihBoolean FinalMessage
);

Remarks

None

Returns

None

ihArchiveRemoveResponse

This function is used by the Alarm Archiver only.

Prototype

ihArchiveRemoveResponse {
ihServerHandle hServer, ihCallbackId CallbackId, ihAPIStatus Status, ihBoolean FinalMessage
);

Remarks

None

Returns

None

ihConfigurationGetProperties

This function returns the configuration properties such as the Data Archiver version.

Prototype

ihConfigurationGetProperties {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect

ihConfigurationProperties *Properties // output parameter to contain the properties
);

ihConfigurationFreeProperties

This function is used to free the memory inside the structure.

Prototype

void ihConfigurationFreeProperties {
ihConfigurationProperties *Properties // pointer to the structure filled in by 
ihConfigurationGetProperties
);

Remarks

Use this function to free the memory inside the structure. Do not free the fields within your code.

Returns

Returns Status	Message
`Void`	Void.