Method Reference A-B

APIStatusToString Method (Server Object)

Converts a status ID into a string.

Syntax

object.APIStatusToString(nStatus, bHRESULT)

Table 1. Parameters
NameData TypeDescription
nStatus LongThe status ID to be converted.
bHRESULT BooleanIf true, then the status ID is an HRESULT; otherwise, it is an APIStatus.

Returns

String. The translation of the status code.

Add Method (Archives Object)

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
NameData TypeDescription
ArchiveNameStringName of the archive to add (Read-Only).
FileLocation StringFully qualified name of the archive file (Read-Only).
FileSizeLongSize of archive in MB (Read-Only).
ArchiveDataStoreNameStringName of the archive data store the archive belongs to. This is an optional parameter.

Returns

Archive. The newly added Archive object or Nothing.

Add Method (Collectors Object)

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
NameData Type
CollectorName StringName of the new collector to add. (Read-only)

Returns

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

Add Method (DataRecordset 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
NameData TypeDefinition
Tagname StringTag to which you are adding a new data value (read-only).
TimeStampDateTimestamp to add value at (read-only).
InValueDataValueNew value (optional).

Returns

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

Add Method (DataStores Object)

Adds a data store.

Syntax

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

Table 5. Parameters
NameData Type
DataStoreNameStringIndicates the name of the data store.
IsDefaultBooleanIndicates whether the data store is the default data store.
DataStoreTypeStringIndicates the type of the data store: Historical, User, or SCADA buffer.
DescriptionStringThe description provided for the data store.

Returns

DataStore.

Add Method (EnumeratedSets Object)

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
NameData Type Description
MySetEnumeratedSetThe set that has to be added.

Returns

None.

Add Method (EnumeratedStates Object)

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
NameData Type Description
MyStateEnumeratedStateThe state that has to be added.

Returns

None.

Add Method (MessageRecordset Object)

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.

Add Method (TagDependencies Object)

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
NameData TypeDescription
TagnameStringName of the tag to add

Returns

Boolean. Whether the Add operation succeeded.

Add Method (TagRecordset Object)

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
NameData TypeDescription
TagnameStringName of the tag to add

Returns

Returns a reference to the newly created tag.

Add Method (UserDefinedtypeFields Object)

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
NameData TypeDescription
MyFieldUserDefinedTypeFieldThe field to be added.

Returns

None.

AddComment Method (DataValue Object)

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
NameData TypeDescription
Comment Variant The comment to add.
DataTypeHintStringThe name of the data type for the comment (optional, read-only).
SecondaryUserStringSupervisor's username to sign comment (optional, read-only).
SecondaryPasswordString Supervisor's password to sign comment (optional, read-only).

Returns

Boolean. Returns True if the AddComment Method operation succeeded.

AddEx Method (Archives Object)

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
NameData TypeDescription
ArchiveName String Name of the archive to add (Read-Only).
FileLocationString Fully qualified name of the archive file (Read-Only).
FileSizeLong Size of archive in MB (Read-Only).
hWndLong The window handle to keep alive.
ArchiveDataStoreNameStringName of the archive data store the archive belongs to. This is an optional parameter.

Returns

Archive. The newly added Archive object or Nothing.

AddServer Method (ServerManager Object)

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
NameData TypeDescription
ServerName String Computer name of the Historian server (read-only).
UserName StringUsername to authenticate (optional, read-only).
Password StringPassword to authenticate (optional, read-only).
ConnectionTimeoutLongThe 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

AlarmAttributesRecordSet Method (Alarms Object)

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.

AlarmRecordSet Method (Alarms Object)

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.
OptionData TypeDescription
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 StringThe operator who acknowledged the alarm, or caused the tracking event.
QualityStringThe 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.

OptionData Type Description
Select BooleanTrue to select the field.
OrderByBooleanTrue to order by the field.
OrderPriorityIntegerRelative priority compared to other field order priorities. Highest first. Ties are random.
DescendingBooleanTrue 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 TypeCriteria 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
NameData 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)

AllFields Method (DataFields Object)

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

Syntax

Syntax object.AllFields

Parameters

None.

Returns

None.

AllFields Method (MessageFields Object)

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

Syntax

object.AllFields

Parameters

None.

Returns

None.

AllFields Method (TagFields Object)

Sets all fields for retrieval in the TagRecordset query.

Syntax

object.AllFields

Parameters

None.

Returns

None.

Backup Alarms Method

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

Syntax

object.BackupAlarms

Table 16. Parameters
Name Data TypeDescription
BackupFile String The file that stores the backup alarm data.
StartTime DateStart time of the alarm data.
EndTimeDateEnd 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

Backup Method (Archive Object)

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 StringFully qualified name of the backup file (read-only).
DataStoreName StringName 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

BackupEx Method (Archive Object)

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 StringFully qualified name of the backup file (read-only)
hWnd LongThe handle of the window to keep alive.
DataStoreName StringName 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

Browse Method (OPCBrowse Object)

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 VariantThe Server Object for the Historian Server.
theCollectorVariant The Collector Object for the Collector to Browse.

Returns

Boolean. Returns whether or not the Browse operation succeeded.

BrowseCollector Method (TagRecordset Object)

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 StringThe tag source address filter.
DescriptionFilter StringThe tag description filter.
BrowsePosition StringThe browse position when performing an OPC hierarchical browse (optional, default = "").
RecursiveBooleanWhether to perform an OPC hierarchical browse (optional, default = False).

Returns

Boolean. Success/Failure.

BrowseTags Method (Collector Object)

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 StringThe tag source address filter (optional, default = "").
DescriptionFilterStringThe tag description filter (optional, default = "").
BrowsePositionString The browse position when performing an OPC hierarchical browse (optional, default = "").
RecursiveBooleanWhether 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