Archiver Backup/Restore Functions
You can use Archive Backup/Restore functions to backup archive data.
There are synchronous and asynchronous calls for loading archives, making a backup and removing an archive. The synchronous functions are typically used for smaller archives because the operation completes in a few seconds. The asynchronous functions are typically used for larger archives because the operation can takes longer, one minute or more, to complete.
Archive Backup/Restore functions are as follows:
ihArchiveBackup
This function is used to back up archive (.iha) files. If you are storing alarms and events data in Historian, an IHA backup also backs up any alarms.
Prototype
ihArchiveBackup {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect
ihArchiveDescriptor *ArchiveDescriptor,
ihString BackupFileName
);Remarks
This function is used to back up the archive (.iha) files residing on the server specified. The ArchiveDescriptor specifies the archive name that you want to add and the DataStore name to which it should be added. The BackupFileName has the backup of the IHA file with the name and the file location that you specified. For example: C:\Program Files\Historian Data\Archives\myarchive.iha.
Returns
| Returns Status | Message |
|---|---|
ihSTATUS_OK | If the option was successfully read. |
ihSTATUS_ACCESS_DENIED | If you are not allowed to perform the operations. For most options you need to be a member of the ihArchiveAdmins group |
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. |
ihArchiveBackupEx
This function is used to back up the archive (.iha) files and process Windows messages at the same time.
Prototype
ihArchiveBackupEx {
ihServerHandle hServer,// server handle returned from previous call to ihServerConnect
ihArchiveDescriptor *ArchiveDescriptor,
ihString BackupFileName, long hWnd);
Remarks
This function is used to back up the archive (.iha) files residing on the server specified. The ArchiveDescriptor specifies the archive name that you want to add and the DataStore name to which it should be added. The BackupFileName has the backup of the IHA file with the name and the file location that you specified. For example: C:\Program Files\Historian Data\Archives\myarchive.iha.
Returns
| Returns Status | Message |
|---|---|
ihSTATUS_OK | If the option was successfully read. |
ihSTATUS_ACCESS_DENIED | If you are not allowed to perform the operations. For most options you need to be a member of the ihArchiveAdmins group |
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. |
ihArchiveRegisterBackupCallBack
This function is used to register a callback which should be called after the ihArchiveBackup() function completes. Archive backup can take several minutes. By using this callback, your System API program can know that the backup is complete.
Prototype
ihArchiveRegisterBackupCallBack {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect
ihArchiveBackupCallbackFunction CallbackFunction,
void *UserParameter
);Remarks
The register callback will be performed when the Archive backup is completed on Historian.
Returns
| Returns Status | Message |
|---|---|
ihSTATUS_OK | If the option was successfully read. |
ihSTATUS_ACCESS_DENIED | If you are not allowed to perform the operations. For most options you need to be a member of the ihArchiveAdmins group |
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. |
ihArchiveRemove
This function is used to delete or unload an archive file. You can unload a file if you no longer need it at the current time but may need it later or in another archive. You can delete a file if you do not expect to need it again or if you have made a backup.
Prototype
ihArchiveRemove {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect
ihArchiveDescriptor *ArchiveDescriptor,
ihBoolean ShouldDeleteFile
)Remarks
This function is used to delete or unload the archive file residing on the server specified. The ArchiveDescriptor specifies the archive name that you want to add and the DataStore name to which it should be added. ShouldDeleteFile determines whether the file should be deleted or not.
ihArchiveRemove() function:| If ShouldDeleteFile is: | ZipRegistry enabled | Zip successful | Then... |
|---|---|---|---|
| TRUE | YES | YES | Archive file is deleted. |
| TRUE | YES | NO | The archive file is not deleted but unloaded. |
| FALSE | YES | YES | The archive file is not deleted. |
| FALSE | YES | NO | The archive file is not deleted. |
| Returns Status | Message |
|---|---|
ihSTATUS_OK | If the option was successfully read. |
ihSTATUS_ACCESS_DENIED | If you are not allowed to perform the operations. For most options you need to be a member of the ihArchiveAdmins group |
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. |
ihArchiveRemoveEx
This function is used to delete or unload the archive files and process Windows messages at the same time.
Prototype
ihArchiveRemoveEx {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect
ihArchiveDescriptor *ArchiveDescriptor,
ihBoolean ShouldDeleteFile,
long hWnd
);Remarks
This function is used to delete or unload the archive file residing on the server specified. The ArchiveDescriptor specifies the archive name that you want to add and the DataStore name to which it should be added. ShouldDeleteFile determines whether the file should be deleted or not.
The following are the scenarios which you can use with ihArchiveRemoveEX() function:
| If ShouldDeleteFile is: | ZipRegistry enabled | Zip successful | Then... |
|---|---|---|---|
| TRUE | YES | YES | Archive file is deleted. |
| TRUE | YES | NO | The archive file is not deleted but unloaded. |
| FALSE | YES | YES | The archive file is not deleted. |
| FALSE | YES | NO | The archive file is not deleted. |
Returns
| Returns Status | Message |
|---|---|
ihSTATUS_OK | If the option was successfully read. |
ihSTATUS_ACCESS_DENIED | If you are not allowed to perform the operations. For most options you need to be a member of the ihArchiveAdmins group |
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. |
ihArchiveRegisterRemoveCallback
This function allows you to register a callback for removing an archive. This callback function is called when you remove the archive from Proficy Historian.
Prototype
ihArchiveRegisterRemoveCallback {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect
ihArchiveRemoveCallbackFunction CallbackFunction,
void *UserParamter
);Remarks
To register a function as a callback, you must have a callback or a function with the same signature as ihArchiveRemoveCallback function, and then pass it to ihArchiveRegisterRemoveCallback.
Returns
| Returns Status | Message |
|---|---|
ihSTATUS_OK | If the option was successfully read. |
ihSTATUS_ACCESS_DENIED | If you are not allowed to perform the operations. For most options you need to be a member of the ihArchiveAdmins group |
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. |
ihArchiveAdd
This function is used to create a new archive or load an existing one.
Prototype
ihArchiveAdd {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect
ihArchiveDescriptor *ArchiveDescriptor,
ihString FileLocation, ihBoolean ShouldCreateFile,
ihUNSIGNED long FileSize
);
Remarks
This function is used to create or load the archive file residing on the server specified. The ArchiveDescriptor specifies the archive name that you want to add and the DataStore name to which it should be added. Then, specify the FileLocation. To determine whether the file should be created or not with the specified FileSize, use ShouldCreateFile.
Returns
| Returns Status | Message |
|---|---|
ihSTATUS_OK | If the option was successfully read. |
ihSTATUS_ACCESS_DENIED | If you are not allowed to perform the operations. For most options you need to be a member of the ihArchiveAdmins group |
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. |
ihArchiveAddEx
This function is used to create a new archive or load an existing one.
Prototype
ihArchiveAddEx {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect
ihArchiveDescriptor *ArchiveDescriptor,
ihString FileLocation,
ihBoolean ShouldCreateFile,
ihUNSIGNED long FileSize,
long hWnd
);
Remarks
This function is used to create or load the archive file residing on the server specified. The ArchiveDescriptor specifies the archive name that you want to add and the DataStore name to which it should be added. Then, specify the FileLocation. To determine whether the file should be created or not with the specified FileSize, use ShouldCreateFile.
Returns
| Returns Status | Message |
|---|---|
ihSTATUS_OK | If the option was successfully read. |
ihSTATUS_ACCESS_DENIED | If you are not allowed to perform the operations. For most options you need to be a member of the ihArchiveAdmins group |
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. |
ihArchiveRegisterLoadCallback
This function allows you to register a callback for adding an archive file. That registered callback is called when you add the archive file in Historian. It can take several minutes to load large archive files, so by using callbacks your System API program can be notified when the archives finish loading.
Prototype
ihArchiveRegisterLoadCallback {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect
ihArchiveLoadCallbackFunction CallbackFunction,
void *UserParameter
);Remarks
You need to have a callback or a function with the same signature as ihArchiveLoadCallback function, and then pass it to ihArchiveRegisterLoadCallback to register that function as a callback.
Returns
| Returns Status | Message |
|---|---|
ihSTATUS_OK | If the option was successfully read. |
ihSTATUS_ACCESS_DENIED | If you are not allowed to perform the operations. For most options you need to be a member of the ihArchiveAdmins group |
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. |