Method Reference A-B | Proficy Historian 2024 Documentation

Converts a status ID into a string.

Syntax

object.APIStatusToString(nStatus, bHRESULT)

Table 1. Parameters
Name	Data Type	Description
nStatus	Long	The status ID to be converted.
bHRESULT	Boolean	If true, then the status ID is an HRESULT; otherwise, it is an APIStatus.

Returns

String. The translation of the status code.

Adds a new archive with the specified characteristics to the Historian server. You can also use this method to add an existing archive file to the archives collection to restore an archive.

Specify the FileLocation in the context of the Historian server machine drive and directory structure. If the specified FileLocation points to an existing valid Historian archive, the method effectively re-registers this archive and automatically loads it. Use this method when you return a previously unloaded archive to the system.

Since the Add request is synchronous, it immediately creates a new Archive object on the Historian server and another one in the Archives collection on the client.

Syntax

object.Add(ArchiveName As String, FileLocation As String, FileSize As Long, ArchiveDataStoreName As String)

Table 2. Parameters
Name	Data Type	Description
ArchiveName	String	Name of the archive to add (Read-Only).
FileLocation	String	Fully qualified name of the archive file (Read-Only).
FileSize	Long	Size of archive in MB (Read-Only).
ArchiveDataStoreName	String	Name of the archive data store the archive belongs to. This is an optional parameter.

Returns

Archive. The newly added Archive object or Nothing.

Adds a new collector with the specified name to the Historian server. The collector name must be unique in a given Historian server.

Since the Add request is synchronous, it immediately creates a new Collector Object on the Historian server and another one in the Collectors collection on the client.

Syntax

object.Add(CollectorName)

Table 3. Parameters
Name	Data Type
CollectorName	String	Name of the new collector to add. (Read-only)

Returns

Collector. Returns a reference to the newly created Collector object.

Adds a new blank DataValue record to the current DataRecordset for the specified tag. The DataValue is written to the server when the WriteRecordset method of the DataRecordset object is called. You can optionally specify the value of the record or specify it after creation by operating on the DataValue object.

Syntax

object.Add(Tagname, TimeStamp, [InValue])

Table 4. Parameters
Name	Data Type	Definition
Tagname	String	Tag to which you are adding a new data value (read-only).
TimeStamp	Date	Timestamp to add value at (read-only).
InValue	DataValue	New value (optional).

Returns

DataValue. Returns a reference to the newly created data value.

Adds a data store.

Syntax

object.Add(MyDataStoreName,MyDefaultDS, MyDataStoreType, MyDataStoreDescription)

Table 5. Parameters
Name	Data Type
DataStoreName	String	Indicates the name of the data store.
IsDefault	Boolean	Indicates whether the data store is the default data store.
DataStoreType	String	Indicates the type of the data store: Historical, User, or SCADA buffer.
Description	String	The description provided for the data store.

Returns

DataStore.

Adds an enumerated set to the Enumerated Sets collection. The enumerated set is not added to the Historian Server until the SaveSet Method is called.

Syntax

object.Add(MySet)

Table 6. Parameters
Name	Data Type	Description
MySet	EnumeratedSet	The set that has to be added.

Returns

None.

Adds an enumerated state to the enumerated set collection. The enumerated state is not added to the Historian Server until the SaveSet Method is called.

Syntax

Object.Add(MyState)

Table 7. Parameters
Name	Data Type	Description
MyState	EnumeratedState	The state that has to be added.

Returns

None.

Adds a new blank message record to the current MessageRecordset. The message is written to the server when the WriteRecordset method of the MessageRecordset object is called.

Syntax

object.Add

Parameters

None

Returns

The empty message that was added.

Adds a dependent Tag to the current calculation. The calculation will be triggered when the value of this tag changes.

Syntax

object.Add(Tagname)

Table 8. Parameters
Name	Data Type	Description
Tagname	String	Name of the tag to add

Returns

Boolean. Whether the Add operation succeeded.

Adds a new blank tag record to the current TagRecordset. The tag is written to the server when the WriteRecordset method of the TagRecordset object is called.

Syntax

object.Add(Tagname)

Table 9. Parameters
Name	Data Type	Description
Tagname	String	Name of the tag to add

Returns

Returns a reference to the newly created tag.

Adds multiple fields to the User Defined Type. The User Defined Type is not added to the Historian Server until the SaveSet Method is called.

Syntax

object.Add(MyField)

Table 10. Parameters
Name	Data Type	Description
MyField	UserDefinedTypeField	The field to be added.

Returns

None.

Adds a comment to the current DataValue. If you supply a secondary username and password, the SDK authenticates the username and password before the committing the comment.

Syntax

object.AddComment(Comment, [DataTypeHint], [SecondaryUser], [SecondaryPassword])

Table 11. Parameters
Name	Data Type	Description
Comment	Variant	The comment to add.
DataTypeHint	String	The name of the data type for the comment (optional, read-only).
SecondaryUser	String	Supervisor's username to sign comment (optional, read-only).
SecondaryPassword	String	Supervisor's password to sign comment (optional, read-only).

Returns

Boolean. Returns True if the AddComment Method operation succeeded.

Adds a new archive with the specified characteristics to the Historian server. You can also use this method to add an existing archive file to the archives collection to restore an archive.

Specify the FileLocation in the context of the Historian server machine drive and directory structure. If the specified FileLocation points to an existing valid Historian archive, the method effectively re-registers this archive and automatically loads it. Use this method when you return a previously unloaded archive to the system.

Since the Add request is synchronous, it immediately creates a new Archive object on the Historian server and another one in the Archives collection on the client.

The window pointed to by hWnd is kept alive (messages processed) while the archive is being added.

Syntax

object.AddEx(ArchiveName As String, FileLocation As String, FileSize As Long, hWnd As Long, ArchiveDataStoreName As String)

Table 12. Parameters
Name	Data Type	Description
ArchiveName	String	Name of the archive to add (Read-Only).
FileLocation	String	Fully qualified name of the archive file (Read-Only).
FileSize	Long	Size of archive in MB (Read-Only).
hWnd	Long	The window handle to keep alive.
ArchiveDataStoreName	String	Name of the archive data store the archive belongs to. This is an optional parameter.

Returns

Archive. The newly added Archive object or Nothing.

Registers a new server to the list of registered servers on the client. It makes an attempt to authenticate the connection based on the username and password supplied. If a username and password are not supplied, it assumes the user to be the currently authenticated domain user.

If it cannot authenticate the connection, because of incorrect user information or an invalid ServerName, the AddServer method returns False and does not register the supplied ServerName on the client.

Syntax

object.AddServer(ServerName, [UserName], [Password], [ConnectionTimeout])

Table 13. Parameters
Name	Data Type	Description
ServerName	String	Computer name of the Historian server (read-only).
UserName	String	Username to authenticate (optional, read-only).
Password	String	Password to authenticate (optional, read-only).
ConnectionTimeout	Long	The maximum length of time clients should wait for messages from the server before concluding the server is unavailable (optional, read-only).

Returns

Boolean. Returns True if the AddServer operation succeeded.

Example

Dim MyManager As New iHistorian_SDK.ServerManager
Dim MyServer As iHistorian_SDK.Server
' Try to add the new server
If MyManager.AddServer("USGB014") Then
Set MyServer = MyManager.Servers("USGB014") Else
err.Raise 1, , "Failed to authenticate new server" End If

This function returns a list of all the Vendor Attributes in the Alarm Archiver.

Syntax

object.AlarmAttributesRecordSet

Parameters

None.

Returns

AlarmAttributes. The AlarmAttributes object contains the list of vendor attributes.

This function is used to query alarms or events from the archiver. This function takes one parameter, an AlarmOpenRecordSetInfo object, which specifies the query. The following sections describe how to populate this object to perform an Alarm or Event query.

AlarmOpenRecordSetInfo Parameter

This object contains details on what to select, and any filters for the query. After creating the object, you first specify which fields to select, and which fields to sort (SelectFields), and then specify any criteria/filter to apply (AlarmCriteria).

Create the object: Dim myAlarmOpenRecordSetInfo As New AlarmOpenRecordSetInfo

Alarm Fields

The following is a list of the alarm fields that can be returned in the recordset, or used to sort or filter the recordset. These are used in the SelectFields and AlarmCriteria object (see below for more details).

Table 14.
Option	Data Type	Description
AlarmID	Long	The unique ID of the alarm or event in the Historian alarm database.
ItemID	String	The OPC ItemID of the alarm. This contains the source address of the data access tag the alarm is associated with. This could contain a NULL value if the alarm is not associated with a tag.
Source	String	This is the unique identifier used by the OPC AE Collector for the alarm or event.
DataSource	String	The collector interface name associated with the alarm or event.
Tagname	String	The Historian Tag Name associated with the alarm. The tag name will be NULL unless the tag is also collected by Historian.
EventCategory	String	The OPC event category of the alarm or event.
ConditionName	String	The OPC condition of the alarm. This does not apply to event data. This, combined with the Source, comprises an alarm.
SubConditionName	String	The OPC sub-condition of the alarm. This does not apply to event data. This is the state of the alarm.
StartTime	Date	The start time or time stamp of the alarm or event.
EndTime	Date	The end time of the alarm. This does not apply to event data.
AckTime	Date	The time the alarm was acknowledged. This does not apply to event data.
Timestamp	Date	The time stamp of the alarm or event.
Message	String	The message attached to the alarm or event.
Acked	Boolean	Stores the acknowledgement status of the alarm. If the alarm is acknowledged, this will be set to TRUE.
Severity	Long	The severity of the alarm or event. This is stored as an integer value with a range of 1-1000.
Actor	String	The operator who acknowledged the alarm, or caused the tracking event.
Quality	String	The quality of the alarm or event.

AlarmOpenRecordSetInfo.SelectFields

Each of the fields above can be selected, or used to sort the alarm recordset. Fill in the AlarmOpenRecordSetInfo.SelectFields for each field, according to the following table.


Option	Data Type	Description
Select	Boolean	True to select the field.
OrderBy	Boolean	True to order by the field.
OrderPriority	Integer	Relative priority compared to other field order priorities. Highest first. Ties are random.
Descending	Boolean	True to sort descending. OrderBy must also be True.

Example

Set up SelectFields to select the AlarmId and ItemId. Order by the AlarmId, then the ItemId.

myAlarmOpenRecordSetInfo.SelectFields.AlarmId.Select = TRUE 
myAlarmOpenRecordSetInfo.SelectFields.AlarmId.OrderBy = TRUE 
myAlarmOpenRecordSetInfo.SelectFields.AlarmId.OrderPriority = 10 
myAlarmOpenRecordSetInfo.SelectFields.ItemId.Select = TRUE 
myAlarmOpenRecordSetInfo.SelectFields.ItemId.OrderBy = TRUE 
myAlarmOpenRecordSetInfo.SelectFields.ItemId.OrderPriority = 20

The SelectFields object has one other field, AllFields, which can be used to select all fields.

SelectFields.AllFields = TRUE

Choose Query Type

For all queries, the type of query should be specified. If it is not specified, the default is to return a record set containing the events. The query type is specified by setting the AlarmOpenRecordSetInfo.AlarmCriteria.AlarmType object.

Query Alarms: myAlarmOpenRecordSetInfo.AlarmType = ihALARM_CONDITION 
Query Events: myAlarmOpenRecordSetInfo.AlarmType = ihALARM_TRACKING 
Query Historical Alarm Transitions: myAlarmOpenRecordSetInfo.AlarmType = ihALARM_CONDITION_HIST

Add filters

Similar to the SelectFields object, each field listed above (Alarm Fields) can have criteria associated with it. This criteria is used to filter the record set, so for example, you can ask for all alarms with severity greater than 500. The type of Criteria that can be applied is dependant on the Data Type of the field. The following table lists the available criteria:


Field Data Type	Criteria Types
Integer/Long	Min, Max, Equal, NotEqual
Float	Min, Max, Equal, NotEqual
String	StringMask
Quality	Min, Max, Equal, NotEqual

For example, the Severity field is of type Long. Therefore, Min, Max, Equal, or NotEqual criteria can be specified for the severity. To query where severity is greater than 500:

myAlarmOpenRecordSetInfo.AlarmCriteria.SeverityCriteria.Min = 500

Specify Max Records

An optional criteria, MaxRecords, can be set to set the upper limit size of the recordset.

Example: Return the first 10 records:

myAlarmOpenRecordSetInfo.AlarmCriteria.MaxRecords = 10

Note: To avoid having random rows returned, if you specify a MaxRecords criteria, you should generally also specify an Order By (see SelectFields above).

Syntax

object.AlarmRecordSet(theAlarmOpenRecordSetInfo)

Table 15. Parameters
Name	Data Type	Description
theAlarmOpenRecordSetInfo	Variant	See above for details.

Returns

AlarmRecordset. An AlarmRecordset object, populated according the details specified in the AlarmOpenRecordSetInfo parameter.

Example

Dim MyServer As iHistorian_SDK.Server 
Set MyServer = GetServer 
Dim myAlarmOpenRecordSetInfo As AlarmOpenRecordSetInfo 
' Select the last 100 alarms in the alarm history table 
myAlarmOpenRecordSetInfo.SelectFields.AllFields = True 
myAlarmOpenRecordSetInfo.SelectFields.Timestamp.OrderBy = True 
myAlarmOpenRecordSetInfo.SelectFields.Timestamp.Descending = True 
myAlarmOpenRecordSetInfo.AlarmCriteria.AlarmType = ihALARM_CONDITION_HIST 
myAlarmOpenRecordSetInfo.AlarmCriteria.MaxRecords = 100 
Dim myAlarmRecordSet As AlarmRecordSet 
Set myAlarmRecordSet = MyServer.Alarms.AlarmRecordSet(myAlarmOpenRecordSetInfo)

Specifies that all DataFields should be returned in the DataRecordset query.

Syntax

Syntax object.AllFields

Parameters

None.

Returns

None.

Specifies that all MessageFields should be returned in the MessageRecordset query.

Syntax

object.AllFields

Parameters

None.

Returns

None.

Sets all fields for retrieval in the TagRecordset query.

Syntax

object.AllFields

Parameters

None.

Returns

None.

Backs up or saves a copy of the alarms to an offline file.

Syntax

object.BackupAlarms

Table 16. Parameters
Name	Data Type	Description
BackupFile	String	The file that stores the backup alarm data.
StartTime	Date	Start time of the alarm data.
EndTime	Date	End time of the alarm data.

Returns

Boolean. Returns TRUE if the alarms are backed up.

Example

Dim Status As ihStatus
Dim ReturnStatus As Boolean
Dim AlarmsStartTime As ihTimeStruct 
Dim AlarmsEndTime As ihTimeStruct Status = ihSTATUS_FAILED ReturnStatus = False
AlarmsStartTime = Date_To_UTC(StartTime) AlarmsEndTime = Date_To_UTC(EndTime)
On Error GoTo errc
Status = ihBackupAlarms(MyServer.Handle, BackupFile, AlarmsStartTime, AlarmsEndTime, 0)
If Status <> ihSTATUS_OK Then err.Raise 1, , "Error while performing Backup alarms [" + ErrorDescription(Status) ReturnStatus = True
BackupAlarms = ReturnStatus errc:
zLastError = "Backup Alarms >> " + err.Description
BackupAlarms = ReturnStatusEnd Function

Performs an online backup of the specified archive by stopping inbound data flow and copying an image of the specified archive into the file identified by the BackupFileName parameter.

When the online backup operation completes, the archive returns to normal operation and accepts inbound data flow.

Syntax

object.Backup(BackupFileName As String, Optional DataStoreName As String)

Table 17. Parameters
Name	Data Type	Description
BackupFileName	String	Fully qualified name of the backup file (read-only).
DataStoreName	String	Name of the data store to which the backup file belongs. This is an optional parameter.

Returns

Boolean. Returns whether or not the BackupFile operation succeeded.

Example

Dim BackupFilename As String
BackupFilename = ArchiverLauncher.Archives & "\TheCurrentArchive.ZIP" 
Set MyArchives = GetServer.Archives
' Find The Current Archive, Then Initiate A Backup
With MyArchives
  For I = 1 To .Item.count
    If .Item(I).IsCurrent Then
      If Not .Item(I).Backup(BackupFilename) Then 
        err.Raise 1, "Backup", "Backup Failed"
      End If
    End If
  Next I 
End With

Performs an online backup of the specified archive by stopping inbound data flow and copying an image of the specified archive into the file identified by the BackupFileName parameter.

When the online backup operation completes, the archive returns to normal operation and accepts inbound data flow.

The Ex method will process messages for a client window while waiting for the backup to complete (so clients do not appear to be frozen.

Syntax

object.BackupEx(BackupFileName As String, hWnd As Long, DataStoreName As String)

Table 18. Parameters
Name	Data Type	Description
BackupFileName	String	Fully qualified name of the backup file (read-only)
hWnd	Long	The handle of the window to keep alive.
DataStoreName	String	Name of the data store. This is an optional parameter.

Returns

Boolean. Returns whether or not the BackupFile operation succeeded.

Example

Dim BackupFilename As String
BackupFilename = ArchiverLauncher.Archives & "\TheCurrentArchive.ZIP" Set MyArchives = GetServer.Archives
' Find The Current Archive, Then Initiate A Backup
With MyArchives
  For I = 1 To .Item.count
    If .Item(I).IsCurrent Then
      If Not .Item(I).Backup(BackupFilename) 
        Then err.Raise 1, "Backup", "Backup Failed"
      End If
    End If
  Next I 
End With

Populates the Browse Object with sources and areas for the current browse position.

Syntax

object.Browse(theServer, theCollector)

Table 19. Parameters
Name	Data Type	Description
theServer	Variant	The Server Object for the Historian Server.
theCollector	Variant	The Collector Object for the Collector to Browse.

Returns

Boolean. Returns whether or not the Browse operation succeeded.

Browses a collector for its available tags.

Syntax

object.BrowseCollector(CollectorName, AdditionsOnly, SourceFilter, DescriptionFilter, [BrowsePosition], [Recursive])

Table 20. Parameters
Name	Data Type	Description
CollectorName	String	The name of the collector to browse.
AdditionsOnly	Boolean	Browse only tags that are additions to the Historian server.
SourceFilter	String	The tag source address filter.
DescriptionFilter	String	The tag description filter.
BrowsePosition	String	The browse position when performing an OPC hierarchical browse (optional, default = "").
Recursive	Boolean	Whether to perform an OPC hierarchical browse (optional, default = False).

Returns

Boolean. Success/Failure.

BrowseTags is available for collection in the data source. The tags can then be added to the archiver using the WriteRecordSet Method.

Syntax

object.BrowseTags([AdditionsOnly], [SourceFilter], [DescriptionFilter], [BrowsePosition], [Recursive])

Table 21. Parameters
Name	Data Type	Description
AdditionsOnly	Boolean	Browse only tags that are additions to the Historian server (optional, default = True).
SourceFilter	String	The tag source address filter (optional, default = "").
DescriptionFilter	String	The tag description filter (optional, default = "").
BrowsePosition	String	The browse position when performing an OPC hierarchical browse (optional, default = "").
Recursive	Boolean	Whether to perform an OPC hierarchical browse (optional, default = False).

Returns

TagRecordset. Returns a reference to the tag record that resulted from browsing the selected collector.

Example

Dim MyNewTags As iHistorian_SDK.TagRecordset
' Request The Collector To Browse Its Tag Source
Set MyNewTags = MyCollectors.Item("USIM031_OPC1").BrowseTags
' Modify Tag Records In Recordset To Add Additional Configuration Information
' Go Ahead And Add New Tags To System
If Not MyNewTags.WriteRecordset Then
  err.Raise 1, , "TagRecordset.WriteRecord failed: " + MyNewTags.LastError
End If