The VhsDatastoreInterface object contains the following methods:
Note: A description for each CxVhsLib helper object can be found in VhsClient Helper Objects.
The AddHistoryPoint method adds a new history point to a VHS.
AddHistoryPoint(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters for this method. Type: AddHistoryPointReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: AddHistoryPointResp |
Returns 0 if successful and a non-zero value if an error occurred. Adding a tag that has already been added will not generate an error. Adding a new point to the VHS in this way does not result in the corresponding CVS actually recording new values to the VHS for the point. History must be enabled in the PNT for the CVS to process new values and log them to the VHS. This method is not generally used.
Example
The following example adds a new point to CYGDEMO.UIS and alerts the user of any errors.
|
Sub VhsAddHistoryPoint() Dim VhsDatastoreInterface, req, resp, tag Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface.1") Set req = CreateObject("CxVhsLib.AddHistoryPointReq") Set resp = CreateObject("CxVhsLib.AddHistoryPointResp") Set tag = CreateObject("CxVhsLib.HistoryTagString") VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\")
'The point to be created tag.TagString = "CYGDEMO.UIS.00001235" req.TagString = tag
VhsDatastoreInterface.AddHistoryPoint req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else edtMessageBox.Text = "Completed successfully" End If End Sub |
The Close method closes the VHS service.
Close() As Boolean
Returns 0 if successful and a non-zero value if the closure failed.
Example
The following example closes the VHS.
|
Sub VhsClose() VhsDatastoreInterface.Close End Sub |
The ContinueHistoryRead method is used after StartHistoryRead for successive calls until all history entries have been returned.
ContinueHistoryRead(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters for this method. Type: ContinueHistoryReadReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: HistoryReadResp |
When the Response object’s Error variable is equal to 10, the end of the history values has been reached.
Example
The following example reads two more values from the history. It uses a global variable, g_Restart, that was set in a StartHistoryRead method.
|
Sub VhsContinueHistoryRead() Dim VhsDatastoreInterface, req, resp Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface.1") Set req = CreateObject("CxVhsLib.ContinueHistoryReadReq") Set resp = CreateObject("CxVhsLib.HistoryReadResp") VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\")
req.Count = 2 req.Restart = g_Restart
VhsDatastoreInterface.ContinueHistoryRead req, resp
g_Restart = resp.Restart
If resp.Error = 10 Then edtMessageBox.Text = "End of history has been reached" Elseif resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else edtMessageBox.Text = "Completed successfully" For i = 0 To resp.Count - 1 ListBox2.AddString(i & " - " & _ resp.entry(i).Status & " - " & _ resp.entry(i).TimeStamp & " - " & _ resp.entry(i).Value) Next End If End Sub |
The ContinueHistoryReadEx method is used after StartHistoryReadEx for successive calls until all history entries have been returned.
ContinueHistoryReadEx(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters for this method. Type: ContinueHistoryReadExReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: HistoryReadExResp |
When the Response object’s Error variable is equal to 10, the end of the history values has been reached.
Example
The following example reads two more values from the history. It uses a global variable, g_Restart, that was set in a StartHistoryReadEx method.
|
Sub VhsContinueHistoryReadEx() Dim VhsDatastoreInterface, req, resp Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface.1") Set req = CreateObject("CxVhsLib.ContinueHistoryReadExReq") Set resp = CreateObject("CxVhsLib.HistoryReadExResp") VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\")
req.Count = 3 req.Restart = g_Restart
VhsDatastoreInterface.ContinueHistoryReadEx req, resp
g_Restart = resp.Restart
If resp.Error = 10 Then edtMessageBox.Text = "End of history" Elseif resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else edtMessageBox.Text = "Completed successfully" For i = 0 To resp.Count - 1 ListBox2.AddString(i & " - " & _ resp.entry(i).Status & " - " & _ resp.entry(i).UserStatus & " - " & _ resp.entry(i).TimeStamp & " - " & _ resp.entry(i).Value) Next End If End Sub |
The CreatePointIterator method is used to create a point iterator object specifically for the Datastore that the VhsDatastoreInterface is connected to. You can’t use iterator objects for the VhsDatastoreInterface without using the methods in VhsDatastoreInterface to create the iterators.
CreatePointIterator([OrderByPointIdLong As Boolean = False].[Unused As Boolean = False]) As PointIterator
| Parameter | Required | Description |
|---|---|---|
|
OrderByPointIdLong |
No |
Set to any nonzero number to sort the points alphabetically by Long ID, or zero to leave them unsorted. The default value is False. |
|
Unused |
No |
This can be any number, but it doesn’t affect anything. The default value is False. |
Example
The following example shows how to create a point iterator.
|
Sub VhsDataFileConnect() Dim VhsDatastoreInterface Dim VhsPointIterator Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface") VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\")
Set VhsPointIterator = VhsDatastoreInterface.CreatePointIterator() End Sub |
The CreateValueIterator method creates a Value Iterator specifically tailored for the Datastore opened by this VhsDatastoreInterface.
CreateValueIterator(TagString As String, TimeStampEarliest As Date, TimeStampLatest As Date,[IncludeDeleted As Boolean = False]) As ValueIterator
| Parameter | Required | Description |
|---|---|---|
|
TagString |
Yes |
The point tag from which data is being retrieved in valid CygNet tag string format. |
|
TimeStampEarliest |
Yes |
The starting date of the retrieval period. Enter 0 for the date of the earliest timestamp. |
|
TimeStampLatest |
Yes |
The ending date of the retrieval period. Enter 0 for the date of the latest timestamp. |
|
IncludeDeleted |
No |
Indicates whether to include deleted records (1) or not (0). The default value is False. It should accept (True) or (False), but (1) and (0) also work. |
Example
The following example shows how to create a value iterator.
|
Sub VhsDataFileConnect() Dim VhsDatastoreInterface Dim VhsHistoryTagEx Dim VhsValueIterator
Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface") VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\")
Set VhsHistoryTagEx = CreateObject("CxVhsLib.HistoryTagStringEx") VhsHistoryTagEx.Site = "TEST" VhsHistoryTagEx.Service= "VHS" VhsHistoryTagEx.PointId= "TESTER" VhsHistoryTagEx.PointIdLong= "TESTER_LONG"
Set VhsValueIterator = VhsDatastoreInterface.CreateValueIterator(VhsHistoryTagEx.TagString,0,0) End Sub |
The CreateValueIteratorReverse method creates a Reverse Value Iterator specifically tailored for the Datastore opened by this VhsDatastoreInterface.
CreateValueIteratorReverse(TagString As String, TimeStampEarliest As Date, TimeStampLatest As Date,[IncludeDeleted As Boolean = False]) As ValueIteratorReverse
| Parameter | Required | Description |
|---|---|---|
|
TagString |
Yes |
The point tag from which data is being retrieved in valid CygNet tag string format. |
|
TimeStampEarliest |
Yes |
The starting date of the retrieval period. Enter 0 for the date of the earliest timestamp. |
|
TimeStampLatest |
Yes |
The ending date of the retrieval period. Enter 0 for the date of the latest timestamp. |
|
IncludeDeleted |
No |
Indicates whether to include deleted records (1) or not (0). The default value is False. It should accept (True) or (False), but (1) and (0) also work. |
Example
The following example shows how to create a reverse value iterator.
|
Sub VhsDataFileConnect() Dim VhsDatastoreInterface Dim VhsHistoryTagEx Dim VhsValueIteratorReverse
Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface") VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\")
Set VhsHistoryTagEx = CreateObject("CxVhsLib.HistoryTagStringEx") VhsHistoryTagEx.Site = "TEST" VhsHistoryTagEx.Service= "VHS" VhsHistoryTagEx.PointId= "TESTER" VhsHistoryTagEx.PointIdLong= "TESTER_LONG"
Set VhsValueIteratorReverse = VhsDatastoreInterface.CreateValueIteratorReverse(VhsHistoryTagEx.TagString,0,0) End Sub |
The CreateRollupIterator method creates a Rollup Iterator specifically tailored for the Datastore opened by this VhsDatastoreInterface.
CreateRollupIterator(TagString As String, TimeStampEarliest As Date, TimeStampLatest As Date, RollupType As Integer, RollupUnits As Integer, RollupPeriod As Integer, TopOfDayHour As Integer) As RollupIterator
| Parameter | Required | Description |
|---|---|---|
|
TagString |
Yes |
The point tag from which data is being retrieved in valid CygNet tag string format. |
|
TimeStampEarliest |
Yes |
The starting date of the retrieval period. Enter 0 for the date of the earliest timestamp. |
|
TimeStampLatest |
Yes |
The ending date of the retrieval period. Enter 0 for the date of the latest timestamp. |
|
RollupType |
Yes |
Sets the value entry rollup type. The possible values are listed on the CxRollupType table. |
|
RollupUnits |
Yes |
Sets the rollup units. This refers to time increments, such as seconds, minutes, hours, or days. The possible values are listed on the CxRollupUnits table. |
|
RollupPeriod |
Yes |
Sets the rollup period. Rollup period refers to the quantity of units in a period. For example, to rollup 30 days, the RollupPeriod is 30 and the RollupUnit is "days." |
|
TopOfDayHour |
Yes |
The offset value to use if the subunit to the major unit (i.e. hours to a day) does not start at the time unit expected. For example, to accommodate contract days starting at 5 AM, the TopOfDayHour would be 5 (indicating 5 hours from midnight). |
Example
The following example shows how to create a rollup iterator.
|
Sub VhsDataFileConnect() Dim VhsDatastoreInterface Dim VhsHistoryTagEx Dim VhsRollupIterator
Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface") VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\")
Set VhsHistoryTagEx = CreateObject("CxVhsLib.HistoryTagStringEx") VhsHistoryTagEx.Site = "TEST" VhsHistoryTagEx.Service= "VHS" VhsHistoryTagEx.PointId= "TESTER" VhsHistoryTagEx.PointIdLong= "TESTER_LONG"
Set VhsRollupIterator = VhsDatastoreInterface.CreateRollupIterator(VhsHistoryTagEx.TagString,0,0,0,0,0,0) End Sub |
The DeleteHistoryPoint method deletes a point from the VHS.
DeleteHistoryPoint(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters for this method. Type: DeleteHistoryPointReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: DeleteHistoryPointResp |
Returns 0 if successful and a non-zero value if an error occurred.
Example
The following example deletes CYGDEMO.UIS.00001235 from the VHS.
|
Sub VhsDeleteHistoryPoint() Dim VhsDatastoreInterface, req, resp, tag Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface.1") Set req = CreateObject("CxVhsLib.DeleteHistoryPointReq") Set resp = CreateObject("CxVhsLib.DeleteHistoryPointResp") Set tag = CreateObject("CxVhsLib.HistoryTagString") VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\")
'The point to be deleted tag.TagString = "CYGDEMO.UIS.00001235" req.TagString = tag
VhsDatastoreInterface.DeleteHistoryPoint req, resp
'Error handling If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else edtMessageBox.Text = "Completed successfully" End If End Sub |
The DeleteHistoryValueEx method deletes a history value from a point in the VHS.
DeleteHistoryValueEx(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters for this method. Type: DeleteHistoryValueExReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: DeleteHistoryValueExResp |
Returns 0 if successful and a non-zero value if an error occurred.
Example
The following example deletes a history value obtained from ListHistoryValuesEx (g_ValueEntryEx). It is also possible to manually input the history value.
|
Sub VhsDeleteHistoryValueEx() Dim VhsDatastoreInterface, req, resp, tag Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface.1") Set req = CreateObject("CxVhsLib.DeleteHistoryValueExReq") Set resp = CreateObject("CxVhsLib.DeleteHistoryValueExResp") Set tag = CreateObject("CxVhsLib.HistoryTagStringEx") VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\")
tag.TagString = "CYGDEMO.UIS.00000068:CYG_METER_PDIFF" req.TagStringEx = tag req.ValueEntryEx = g_ValueEntryEx req.Operations = 1
VhsDatastoreInterface.DeleteHistoryValueEx req, resp
'Error handling If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else edtMessageBox.Text = "Completed successfully" End If End Sub |
The GetNamedArrayValues method reads the history entries from multiple points that were in effect for the given date.
GetNamedArrayValues(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters for this method. Type: GetNamedArrayValuesReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: GetNamedArrayValuesResp |
If no history entries exist at the exact start time, the first history entry prior to the start time will be returned.
Example
The following example displays the history entry data for two points in a list box.
|
Sub VhsGetNamedArrayValues() Dim VhsDatastoreInterface, req, resp, tag0, tag1 Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface.1") Set req = CreateObject("CxVhsLib.GetNamedArrayValuesReq") Set resp = CreateObject("CxVhsLib.GetNamedArrayValuesResp") Set tag0 = CreateObject("CxVhsLib.HistoryTagString") Set tag1 = CreateObject("CxVhsLib.HistoryTagString") VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\")
req.count = 2 tag0.TagString = "CYGDEMO.UIS.00000068" req.TagString(0) = tag0 req.TimeStamp(0) = CDate("1/1/2010 15:48:00")
tag1.TagString = "CYGDEMO.UIS.00000069" req.TagString(1) = tag1 req.TimeStamp(1) = CDate("1/1/2010 15:48:00")
VhsDatastoreInterface.GetNamedArrayValues req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else ListBox2.ResetContent Dim i For i = 0 To resp.count - 1 ListBox2.AddString("Status - " & resp.entry(i).Status & _ "; TimeStamp - " & resp.entry(i).Timestamp & _ "; Value - " & resp.entry(i).Value) Next End If End Sub |
The GetNamedArrayValuesEx method reads the history entries from multiple history points that were in effect for the given date.
GetNamedArrayValuesEx(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters for this method. Type: GetNamedArrayValuesExReq |
|
Response |
Yes |
The response object that contains the output of this method. |
If no history entries exist at the exact start time, the first history entry prior to the start time will be returned.
Note: GetNamedArrayValuesExReq objects are limited to 63 total objects within the array. Objects greater than 63 will cause an exception.
Example
The following example displays the history entry data for two points in a list box.
|
Sub VhsGetNamedArrayValuesEx() Dim VhsDatastoreInterface, req, resp, tag0, tag1 Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface.1") Set req = CreateObject("CxVhsLib.GetNamedArrayValuesExReq") Set resp = CreateObject("CxVhsLib.GetNamedArrayValuesExResp") Set tag0 = CreateObject("CxVhsLib.HistoryTagStringEx") Set tag1 = CreateObject("CxVhsLib.HistoryTagStringEx") VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\")
req.count = 2 tag0.TagString = "CYGDEMO.UIS.00000068" req.TagString(0) = tag0 req.TimeStamp(0) = CDate("1/1/2010 15:48:00")
tag1.TagString = "CYGDEMO.UIS.00000069" req.TagString(1) = tag1 req.TimeStamp(1) = CDate("1/1/2010 15:48:00")
VhsDatastoreInterface.GetNamedArrayValuesEx req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else edtMessageBox.text = resp.count ListBox2.ResetContent Dim i For i = 0 To resp.Count - 1 ListBox2.AddString("Status - " & resp.entry(i).Status & _ "; Userstatus - " & resp.entry(i).UserStatus & _ "; TimeStamp - " & resp.entry(i).Timestamp & _ "; Value - " & resp.entry(i).Value) Next End If End Sub |
The GetPointStats method gets statistics for a given history point.
GetPointStats(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters for this method. Type: GetPointStatsReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: GetPointStatsResp |
Returns 0 if successful and a non-zero value if an error occurred.
Example
The following example gets statistics for CYGDEMO.UIS.00000068 and displays them in a list box.
|
Sub VhsGetPointStats() Dim VhsDatastoreInterface, req, resp, tag Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface.1") Set req = CreateObject("CxVhsLib.GetPointStatsreq") Set resp = CreateObject("CxVhsLib.GetPointStatsresp") Set tag = CreateObject("CxVhsLib.HistoryTagString") bjVhs.Close("C:\CygNet\Services\VHS\")
tag.TagString = "CYGDEMO.UIS.00000068" req.TagString = tag
VhsDatastoreInterface.GetPointStats req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else ListBox2.ResetContent ListBox2.AddString("Expiration Date: " & resp.ExpirationDays) ListBox2.AddString("First History Entry: " & resp.TimeStampStart) ListBox2.AddString("Last History Entry: " & resp.TimeStampEnd) ListBox2.AddString("Total History Entries: " & resp.Entrycount) End If End Sub |
The GetPointStatsEx method gets statistics for an array of history points.
GetPointStatsEx(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters for this method. Type: GetPointStatsExReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: GetPointStatsExResp |
Returns 0 if successful and a non-zero value if an error occurred.
Example
The following example gets statistics for CYGDEMO.UIS.00000068 and CYGDEMO.UIS.00000069 and displays them in a list box.
|
Sub VhsGetPointStatsEx() Dim VhsDatastoreInterface, req, resp, bRc, tag1, tag2 Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface.1") Set req = CreateObject("CxVhsLib.GetPointStatsExReq") Set resp = CreateObject("CxVhsLib.GetPointStatsExResp") Set tag0 = CreateObject("CxVhsLib.HistoryTagStringEx") Set tag1 = CreateObject("CxVhsLib.HistoryTagStringEx") bRc = VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\")
req.Count = 2 tag0.TagString = "CYGDEMO.UIS.00000069:CYG_METER_PSTATIC" tag1.TagString = "CYGDEMO.UIS.00000068:CYG_METER_PDIFF" req.TagString(0) = tag0 req.TagString(1) = tag1
VhsDatastoreInterface.GetPointStatsEx req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else ListBox2.ResetContent Dim i For i = 0 To resp.Count - 1 ListBox2.AddString("Point Number: " & i) ListBox2.AddString("Point Error: " & resp.PointError(i)) ListBox2.AddString("Total History Entries: " & _ resp.Statistics(i).EntryCount) ListBox2.AddString("First History Entry: " & _ resp.Statistics(i).TimeStampStart) ListBox2.AddString("Last History Entry: " & resp.Statistics(i).TimeStampEnd) ListBox2.AddString("Expiration Date: " & resp.Statistics(i).ExpirationDays) ListBox2.AddString("") Next End If End Sub |
The GetReferences method updates the list of services the VHS is referencing.
GetReferences() As Integer
Example
The following example refreshes the referenced services.
|
Sub VhsGetReferences() Dim VhsDatastoreInterface Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface.1") VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\")
VhsDatastoreInterface.GetReferences() End Sub |
The ListHistoryPointsEx method lists history points in alphabetic order from the given start index. The ListHistoryPointsEx method has a upper bound array count of 53; the method can only retrieve a maximum of 53 response items per request. The only way to get all points is to iterate through using the last returned item as the new starting point. See the second example below.
ListHistoryPointsEx(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters of this method. Type: ListHistoryPointsExReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: ListHistoryPointsExResp |
Returns 0 if successful and a non-zero value if an error occurred.
Example
The following example gets a list of all history points whose Point ID is greater than 00000123.
|
Sub VhsListHistoryPointsEx() Dim VhsDatastoreInterface, req, resp Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface.1") Set req = CreateObject("CxVhsLib.ListHistoryPointsExReq") Set resp = CreateObject("CxVhsLib.ListHistoryPointsExResp") Set tag = CreateObject("CxVhsLib.HistoryTagStringEx") VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\")
tag.TagString = "CYGDEMO.UIS.00000123:FREEZIE_METER_VET" req.TagString = tag VhsDatastoreInterface.ListHistoryPointsEx req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else ListBox2.ResetContent Dim i For i = 0 To resp.Count - 1 ListBox2.AddString( i & " - " & _ resp.Statistics(i).ExpirationDays & " - " & _ resp.Statistics(i).TimeStampStart & " - " & _ resp.Statistics(i).TimeStampEnd & " - " & _ resp.Statistics(i).Entrycount & " - " & _ resp.TagString(i).TagString) Next End IF End Sub |
The following example iterates through the returned values for ListHistoryPointsEx:
|
' VHS Client Request and Response objects.
Dim objVhsDatastoreInterface : Set objVhsDatastoreInterface = CreateObject("CxVHS.VhsDatastoreInterface") Dim objVHSRequest : Set objVHSRequest = CreateObject("CxVhsLib.ListHistoryPointsExReq") Dim objVHSResponse : Set objVHSResponse = CreateObject("CxVhsLib.ListHistoryPointsExResp") Dim objVHSTag : Set objVHSTag = CreateObject("CxVhsLib.HistoryTagStringEx")
' Connect the Client to the Service. Call objVhsDatastoreInterface.Connect("CYGDEMO.VHS")
' Prepare the Request objVHSTag.TagString = "CYGDEMO.UIS.00000000" ' Let's start at "Zero" to try and get everything. objVHSRequest.TagString = objVHSTag
' Send the Initial Request Call objVhsDatastoreInterface.ListHistoryPointsEx(objVHSRequest, objVHSResponse) Dim blnFlag : blnFlag = True
' Iterate through the response object Dim intX : intX = 0 Dim intY : intY = 0 ' The UB of the return array ReDim aryVHSPoints(intX)
Dim objFSO : Set objFSO = CreateObject("Scripting.FileSystemObject") Dim objFile : Set objFile = objFSO.CreateTextFile("C:\temp\ListHistoryPointsEx.txt", True, -2)
Dim strHeader : strHeader = "******************** ListHistoryValuesEx Results ********************" Dim strFooter : strFooter = "*********************************************************************"
Dim objPoints : Set objPoints = CreateObject("CxScript.Points") Dim objPoint
Call objFile.Write(strHeader & vbCrLf & vbCrLf)
Dim blnStop : blnStop = True
Do While(intY <= objVHSResponse.TotalPointCount)
For intX = 0 To (objVHSResponse.Count -1) ReDim Preserve aryVHSPoints(intY) aryVHSPoints(intY) = objVHSResponse.TagString(intX).TagString intY = intY + 1
Next
' Continue the loop till the end... On Error Resume next Set objPoint = objPoints.Point(aryVHSPoints(intY -1)) objVHSTag.TagString = objPoint.Tag objVHSRequest.TagString = objVHSTag Call objVhsDatastoreInterface.ListHistoryPointsEx(objVHSRequest, objVHSResponse)
Loop
ReDim Preserve aryVHSPoints(intY -1) intY = 0
For Each thing In aryVHSPoints Call objFile.Write(intY+1 & " | " & thing & vbCrLf) intY = intY + 1
Next
Call objFile.Write(strFooter) |
The ListHistoryValuesEx method reads the history values from a point in chronological order based on the given timestamp. The ListHistoryValuesEx has a upper bound array count of 111; the method can only retrieve a maximum of 111 response items per request. The only way to get all values is to iterate through using the last returned item as the new starting point. See the second example below.
ListHistoryValuesEx(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters of this method. Type: ListHistoryValuesExReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: ListHistoryValuesExResp |
Returns 0 if successful, or return codes: NO_HISTORY_FOR_TIME (12) indicating that there is no history for the time requested or END_OF_HISTORY (10) indicating that there is no more history to retrieve.
Note: We recommend avoiding these message wrappers in favor of the more user-friendly iterators, PointIterator, ValueIterator, and ValueIteratorReverse.
Example
The following example gets all the history values for a point after January 1, 2009 and displays them in a list box. It also stores the first history value in a global variable so it can be used by other methods.
|
Sub VhsListHistoryValuesEx() Dim VhsDatastoreInterface, req, resp, tag Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface.1") Set req = CreateObject("CxVhsLib.ListHistoryValuesExReq") Set resp = CreateObject("CxVhsLib.ListHistoryValuesExResp") Set tag = CreateObject("CxVhsLib.HistoryTagStringEx") VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\")
tag.TagString = "CYGDEMO.UIS.00000068:CYG_METER_PDIFF" Req.TagString = tag Req.TimeStampStart = CDate("1/1/2009")
VhsDatastoreInterface.ListHistoryValuesEx req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else Dim i ListBox2.ResetContent For i = 0 To resp.Count - 1 ListBox2.AddString(resp.valueEntry(i).Status & " - " & _ resp.valueEntry(i).UserStatus & " - " & _ resp.valueEntry(i).TimeStamp & " - " & _ resp.valueEntry(i).Value) Next
'Sets a global variable to the first value entry 'so it can be used by other methods Set g_ValueEntryEx = resp.valueEntry(0) End If End Sub |
The following example iterates through the returned values for ListHistoryValuesEx:
|
Sub VhsListHistoryValuesEx(Byval Cur_Tag, Byval Vhs_Site)
Dim request : Set request = CreateObject("CxVhsLib.ListHistoryValuesExReq") Dim response : Set response = CreateObject("CxVhsLib.ListHistoryValuesExResp") Dim strHistTag : Set strHistTag = CreateObject("CxVhsLib.HistoryTagStringEx")
Dim strHistoryEntries : strHistoryEntries = "" Dim intUnreliable : intUnreliable = 0
VhsDatastoreInterface.Connect(strVHSSite)
strHistTag.TagString = strTag request.TagString = strHistTag request.TimeStampStart = CDate("1/1/1985")
Dim loop_until loop_until = True
Dim X : X = 0
Dim Z : Z = 0
While(loop_until)
Z = 0
VhsDatastoreInterface.ListHistoryValuesEx request, response
Dim i : i = 0 Dim j : j = 0
Dim timeEntry Dim valueEntry Dim statusEntry Dim historyEntry Dim checkEntry
Dim checker Dim Rchecker Dim results
If(response.Error <> 0 And response.Error <> 10)Then
' if the response error is 0, there is no error ' if the response error is 10, this means "END_OF_HISTORY" -- we're done
Else
For i = 0 To response.Count - 1
' What can you do with the results?
'objDictionary_Time.SetKeyValue X,response.ValueEntry(i).Value 'objDictionary_Value.SetKeyValue X,response.ValueEntry(i).Timestamp 'objDictionary_Status.SetKeyValue X,response.ValueEntry(i).Status
'timeEntry = objDictionary_Time.FindValue(X) 'valueEntry = objDictionary_Value.FindValue(X) 'statusEntry = objDictionary_Status.FindValue(X)
X = X + 1 Z = Z + 1
Next
End If
If(response.Count = 111)Then
' Let's start at the last timepoint retrieved and move forward. request.TimeStampStart = CDate(response.ValueEntry(Z-1).Timestamp)
Else ' Exit loop_until = False
End if
Wend
End Sub |
The Open method opens a VHS datastore. On an Open() method call, the datastore will be either created or used if they already exist. Only 16 VhsDatastoreInterface objects can be opened at the same time.
Note: You cannot open a datastore being used by a service that is running. However, if the service is shut down you can open the datastore.
Open(DataDirectory As String, [MaxDatastoreSizeMB as Long = 1024], [TxLogsDirectory As String]) As Boolean
| Parameter | Required | Description |
|---|---|---|
|
DataDirectory |
Yes |
The directory where the VHS data files are located. |
|
MaxDatastoreSizeMB |
No |
The max size this datastore can grow to in MB. Maximum is 1024 MB. |
|
TxLogsDirectory |
No |
The transaction logs directory. |
Returns True if successful and False if the open failed.
Example
The following example Closes to C:\CygNet\Services\VHS\.
|
Sub VhsOpen() Dim VhsDatastoreInterface Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface") VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\") End Sub |
The StartHistoryRead method reads the history entries within an inclusive GMT date range.
StartHistoryRead(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters of this method. Type: StartHistoryReadReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: StartHistoryReadResp |
Returns 0 if successful and a non-zero value if an error occurred. If no history entries exist at the exact start time, the first history entry prior to the start time will be returned.
Example
The following example reads two history entries between January 1, 2009 and the current date. It then stores Restart in a global variable so that ContinueHistoryRead can read the next set of entries.
|
Sub VhsStartHistoryRead() Dim VhsDatastoreInterface, req, resp, tag Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface.1") Set req = CreateObject("CxVhsLib.StartHistoryReadReq") Set resp = CreateObject("CxVhsLib.HistoryReadResp") Set tag = CreateObject("CxVhsLib.HistoryTagString") VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\")
tag.TagString = "CYGDEMO.UIS.00000068" req.TagString = tag req.Count = 2 req.TimeStampStart = CDate("01/01/2009")
VhsDatastoreInterface.StartHistoryRead req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else g_restart = resp.Restart
ListBox2.ResetContent For i = 0 To resp.Count - 1 ListBox2.AddString(i & " - " & _ resp.entry(i).Status & " - " & _ resp.entry(i).TimeStamp & " - " & _ resp.entry(i).Value) Next End If End Sub |
The StartHistoryReadEx method reads the history entries within an inclusive GMT date range.
StartHistoryReadEx(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters of this method. Type: StartHistoryReadExReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: HistoryReadExResp |
This method is capable of returning rollups for the given period. By default, raw values are returned. Returns 0 if successful and a non-zero value if an error occurred. If no history entries exist at the exact start time, the first history entry prior to the start time will be returned.
Example
The following example reads the last value entry from each 30 day period. It then stores Restart in a global variable so that ContinueHistoryReadEx can read the next three entries.
|
Sub VhsStartHistoryReadEx() Dim VhsDatastoreInterface, req, resp, tag Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface.1") Set req = CreateObject("CxVhsLib.StartHistoryReadExReq") Set resp = CreateObject("CxVhsLib.HistoryReadExResp") Set tag = CreateObject("CxVhsLib.HistoryTagStringEx") VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\")
tag.TagString = "CYGDEMO.UIS.00000068:CYG_METER_PDIFF" req.TagString = tag req.TimeStampStart = "12/3/2018" req.TimeStampEnd = Now req.RollupType = 9 'Gets the last value entry... req.RollupPeriod = 30 '...from each thirty... req.RollupUnits = 3 '...day period req.Count = 3
VhsDatastoreInterface.StartHistoryReadEx req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else g_restart = resp.Restart
ListBox2.ResetContent For i = 0 To resp.Count - 1 ListBox2.AddString(resp.Entry(i).Status & " - " & _ resp.entry(i).UserStatus & " - " & _ resp.entry(i).TimeStamp & " - " & _ resp.entry(i).Value) Next End If End Sub |
The StoreHistoryList method stores history entries for multiple history points.
StoreHistoryList(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters of this method. Type: StoreHistoryListReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: StoreHistoryListResp |
The entries do not have to be in chronological order because they will be correctly inserted or appended, however performance is better if they are. Returns 0 if successful and a non-zero value if an error occurred.
Example
The following example stores new value entries for two history points.
|
Sub VhsStoreHistoryList() Dim VhsDatastoreInterface, req, resp, entry0, entry1, tag0, tag1 Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface.1") Set req = CreateObject("CxVhsLib.StoreHistoryListReq") Set resp = CreateObject("CxVhsLib.StoreHistoryListResp") Set entry0 = CreateObject("CxVhsLib.HistoryEntry") Set entry1 = CreateObject("CxVhsLib.HistoryEntry") Set tag0 = CreateObject("CxVhsLib.HistoryTagString") Set tag1 = CreateObject("CxVhsLib.HistoryTagString") VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\")
Req.Count = 2
tag0.TagString = "CYGDEMO.UIS.00000068" req.TagString(0) = tag0 entry0.Status = 7 entry0.TimeStamp = Now entry0.Value = 999 req.Entry(0) = entry0
tag1.TagString = "CYGDEMO.UIS.00000069" req.TagString(1) = tag1 entry1.Status = 7 entry1.TimeStamp = Now entry1.Value = 123 Req.Entry(1) = entry1
VhsDatastoreInterface.StoreHistoryList req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else edtMessageBox.Text = "Completed Successfully" End If End Sub |
The StorePointHistory method stores multiple history entries for a single point.
StorePointHistory(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters of this method Type: StorePointHistoryReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: StorePointHistoryResp |
The entries do not have to be in chronological order because they will be correctly inserted or appended, however performance is better if they are. Returns 0 if successful and a non-zero value if an error occurred.
Example
The following example stores two history entries for a point. The first entry is inserted at the appropriate time, while the second entry is appended to the history list to be the latest value.
|
Sub VhsStorePointHistory() Dim VhsDatastoreInterface, req, resp, entry0, entry1, tag Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface.1") Set req = CreateObject("CxVhsLib.StorePointHistoryReq") Set resp = CreateObject("CxVhsLib.StorePointHistoryResp") Set entry0 = CreateObject("CxVhsLib.HistoryEntry") Set entry1 = CreateObject("CxVhsLib.HistoryEntry") Set tag = CreateObject("CxVhsLib.HistoryTagString") VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\")
Req.Count = 2
tag.TagString = "CYGDEMO.UIS.00000068" req.TagString = tag
entry0.Status = 7 entry0.TimeStamp = CDate((01/02/2010") entry0.Value = 123 req.Entry(0) = entry0
entry1.Status = 7 entry1.TimeStamp = Now entry1.Value = 456 req.Entry(1) = entry1
VhsDatastoreInterface.StorePointHistory req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else edtMessageBox.Text = "Completed Successfully" End If End Sub |
The StorePointHistoryEx method stores multiple history entries for a single point.
StorePointHistory(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters of this method. Type: StorePointHistoryExReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: StorePointHistoryExResp |
The entries do not have to be in chronological order because they will be correctly inserted or appended, however performance is better if they are. Returns 0 if successful and a non-zero value if an error occurred.
Example
The following example stores two history entries for a point. The first entry is inserted at the appropriate time, while the second entry is appended to the history list to be the latest value.
|
Sub VhsStorePointHistoryEx() Dim VhsDatastoreInterface, req, resp, entry0, entry1, tag Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface.1") Set req = CreateObject("CxVhsLib.StorePointHistoryExReq") Set resp = CreateObject("CxVhsLib.StorePointHistoryExResp") Set entry0 = CreateObject("CxVhsLib.HistoryEntryEx") Set entry1 = CreateObject("CxVhsLib.HistoryEntryEx") Set tag = CreateObject("CxVhsLib.HistoryTagStringEx") VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\")
req.Count = 2
tag.TagString = "CYGDEMO.UIS.00000068:CYG_METER_PDIFF" req.TagString = tag
entry0.Status = 7 entry0.UserStatus = 0 entry0.TimeStamp = CDate("01/02/2010") entry0.Value = 111 req.Entry(0) = entry0
entry1.Status = 7 entry1.UserStatus = 0 entry1.TimeStamp = Now entry1.Value = 222 req.Entry(1) = entry1
VhsDatastoreInterface.StorePointHistoryEx req, resp
If resp.Error <> 0 Then edtMessageBox.Text = "Error number " & resp.Error Else edtMessageBox.Text = "Completed Successfully" End If End Sub |
The UpdateHistoryValuesEx method updates a point’s history value.
UpdateHistoryValueEx(Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
The request object that contains the parameters for the history value being updated. Type: UpdateHistoryValueExReq |
|
Response |
Yes |
The response object that contains the output of this method. Type: UpdateHistoryValueExResp |
Returns 0 if successful and a non-zero value if an error occurred.
Example
The following example adds a new history value to the end of the history list. The value is the current time.
|
Sub VhsUpdateHistoryValueEx() Dim VhsDatastoreInterface, req, resp, history, value, tag Set VhsDatastoreInterface = CreateObject("CxVhsLib.VhsDatastoreInterface.1") Set req = CreateObject("CxVhsLib.UpdateHistoryValueExReq") Set resp = CreateObject("CxVhsLib.UpdateHistoryValueExResp") Set history = CreateObject("CxVhsLib.HistoryEntryEx") Set value = CreateObject("CxVhsLib.ValueEntryEx") Set tag = CreateObject("CxVhsLib.HistoryTagStringEx") VhsDatastoreInterface.Open("C:\CygNet\Services\VHS\")
tag.TagString = "CYGDEMO.UIS.00000068:CYG_METER_PDIFF" req.TagStringEx = tag
history.TimeStamp = Now history.Value = Time req.ValueEntryNew = history
VhsDatastoreInterface.UpdateHistoryValueEx req, resp
If resp.ErrorType <> 0 Then edtMessageBox.Text = "Error number " & resp.ErrorType Else edtMessageBox.Text = "Completed Successfully" End If End Sub |
|
|
|
