ValueIterator Methods
The ValueIterator object contains the following methods:
Initialize
The Initialize method initializes a ValueIterator Object.
Syntax
Initialize(VhsSiteService As String, TagString As String, TimeStampEarliest As Date, TimeStampLatest As Date,_ IncludeDeleted As Long) As Long
Parameters
| Parameter | Required | Description |
|---|---|---|
|
VhsSiteService |
Yes |
The site and service name of the VHS point tag, in "site.service" format. |
|
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 |
Yes |
Indicates whether to include deleted records (1) or not (0). |
Remarks
Returns a value based on whether the initialization was successful or not (1 = Success; 0 = Failure). The cursor is placed at the first (earliest) value by default. Note that some timestamps outside the specified time period may be returned by the iterator if the value continues into the time period.
Example
The following subroutine demonstrates the use of the Initialize, MoveFirst, and GetForward methods of the ValueIterator object. It displays all values (with timestamps) for a given point.
Sub DisplayAllValues (tagString)
Dim vhsValueIter, histEntry
lstValues.ResetContent
Set vhsValueIter = CreateObject("CxVhsLib.ValueIterator")
Set histEntry = CreateObject("CxVhsLib.HistoryEntryEx")
'Initialize value iterator
vhsValueIter.Initialize "CYGDEMO.VHS", tagString, 0, 0, 0
vhsValueIter.MoveFirst
'Show all points in a list box
While (vhsValueIter.GetForward(histEntry))
lstValues.AddString CStr(histEntry.TimeStamp) & " "& CStr(histEntry.Value)
Wend
End Sub
GetBackwardEx
The GetBackwardEx method retrieves information about the previous value in the iteration list. Returns a ValueEntryEx object in the pVal variable.
Syntax
GetBackwardEx(pVal As Variant) As Long
Parameters
| Parameter | Required | Description | Variant |
|---|---|---|---|
|
pVal |
Yes |
Returns the timestamp, status, user status, value, time ordinal, and rollup information for the value entry. |
Remarks
The GetBackwardEx function retrieves information for a value and moves the cursor backward to the previous value. The return value is 1 while there are still values in the list. When TimeStampEarliest (as specified during initialization) or the beginning of the list is reached, 0 is returned.
Example
The following subroutine demonstrates the use of the Initialize, MoveLast, and GetBackwardEx methods of the ValueIterator object. It displays up to numValues of the most recent values for the point, POINT1.
Sub DisplayLatestValues (numValues)
Dim vhsValueIter, valueEntry, counter
lstValues.ResetContent
counter = 0
Set vhsValueIter = CreateObject("CxVhsLib.ValueIterator")
Set valueEntry = CreateObject("CxVhsLib.ValueEntryEx")
'Initialize value iterator
vhsValueIter.Initialize "CYGDEMO.VHS", "CYGDEMO.UIS:POINT1", 0, 0, 0
vhsValueIter.MoveLast
'Show all points in a list box
While ((vhsValueIter.GetBackwardEx(valueEntry)) And (counter < numValues))
lstValues.AddString CStr(valueEntry.TimeStamp) & " "& CStr(valueEntry.Value)
counter = counter + 1
Wend
End Sub
GetForwardEx
The GetForwardEx method retrieves information about the next value in the iteration list. Returns a ValueEntryEx object in the pVal variable.
Syntax
GetForwardEx(pVal As Variant) As Long
Parameters
| Parameter | Required | Description | Variant |
|---|---|---|---|
|
pVal |
Yes |
Returns the timestamp, status, user status, value, time ordinal, and rollup information for the value entry. |
Remarks
The GetForwardEx function retrieves information for the next value and moves the cursor forward to the value. The return value is 1 while there are still values in the list. When TimeStampLatest (as specified during initialization) or the end of the list is reached, 0 is returned.
Example
The following subroutine demonstrates the use of the Initialize, MoveFirst, and GetForwardEx methods of the ValueIterator object. It displays all values (with timestamps) for a given point.
Sub DisplayAllValues (tagString)
Dim vhsValueIter, valueEntry
lstValues.ResetContent
Set vhsValueIter = CreateObject("CxVhsLib.ValueIterator")
Set valueEntry = CreateObject("CxVhsLib.ValueEntryEx")
'Initialize value iterator
vhsValueIter.Initialize "CYGDEMO.VHS", tagString, 0, 0, 0
vhsValueIter.MoveFirst
'Show all points in a list box
While (vhsValueIter.GetForwardEx(valueEntry))
lstValues.AddString CStr(valueEntry.TimeStamp) & " "& CStr(valueEntry.Value)
Wend
End Sub
MoveFirst
The MoveFirst method moves to the first value in the iteration list.
Syntax
MoveFirst() As Long
Remarks
Returns a value based on whether the method was successful or not (1 = Success; 0 = Failure).
Example
The following subroutine demonstrates the use of the Initialize, MoveFirst, and GetForward methods of the ValueIterator object. It displays all values (with timestamps) for a given point.
Sub DisplayAllValues (tagString)
Dim vhsValueIter, histEntry
lstValues.ResetContent
Set vhsValueIter = CreateObject("CxVhsLib.ValueIterator")
Set histEntry = CreateObject("CxVhsLib.HistoryEntryEx")
'Initialize value iterator
vhsValueIter.Initialize "CYGDEMO.VHS", tagString, 0, 0, 0
vhsValueIter.MoveFirst
'Show all points in a list box
While (vhsValueIter.GetForward(histEntry))
lstValues.AddString CStr(histEntry.TimeStamp) & " "& CStr(histEntry.Value)
Wend
End Sub
MoveLast
The MoveLast method moves to the last value in the iteration list.
Syntax
MoveLast() As Long
Remarks
Returns a value based on whether the method was successful or not (1 = Success; 0 = Failure).
Example
The following subroutine demonstrates the use of the Initialize, MoveLast, and GetBackward methods of the ValueIterator object. It displays up to numValues of the most recent values for the point, POINT1.
Sub DisplayLatestValues (numValues)
Dim vhsValueIter, histEntry, counter
lstValues.ResetContent
counter = 0
Set vhsValueIter = CreateObject("CxVhsLib.ValueIterator")
Set histEntry = CreateObject("CxVhsLib.HistoryEntryEx")
'Initialize value iterator
vhsValueIter.Initialize "CYGDEMO.VHS", "CYGDEMO.UIS:POINT1", 0, 0, 0
vhsValueIter.MoveLast
'Show all points in a list box
While ((vhsValueIter.GetBackward(histEntry)) And (counter < numValues))
lstValues.AddString CStr(histEntry.TimeStamp) & " "& CStr(histEntry.Value)
counter = counter + 1
Wend
End Sub
