Points Methods

The Points object contains the following methods:

AddPoint

The AddPoint method adds the point specified by the tag to the cache.

Syntax

AddPoint(Tag As String, [NotifyHyperPoint As Variant])

Parameters

Remarks

If the optional NotifyHyperPoint parameter is used and the tag’s real-time record or configuration record is changed, the specified HyperPoint’s OnPointChange event is triggered. The NotifyHyperPoint parameter is typically This, which refers to the current HyperPoint (see the example). The AddPoint method is not typically used in CygNet Studio because points can be referenced without first adding them to a Points object.

Example

The following example uses the STATUSPT HyperPoint’s OnInitializeEx event to assign two points to the Points object. The method passes the current HyperPoint’s name, "STATUSPT," as the HyperPoint to notify when one of these points’ records changes.

1
2
3
4
5
Sub STATUSPT_OnInitializeEx(This) 
    ''Add LTANK, SPUMP tags to the Points Object to notify STATUSPT of real-time record updates
    Points.AddPoint "CYGDEMO.UIS::JONES45.LTANK", This
    Points.AddPoint "CYGDEMO.UIS::JONES45.SPUMP", This
End Sub

The required Tag string can include any of the following optional parameters to indicate that the HyperPoint’s OnPointChange event will run only when the specific property changes, rather than running when any one of them changes:

Example

The following example will include the value and the timestamp:

1
Points.AddPoint "CYGDEMO.UIS:TANK_LEVEL;TIMESTAMP", TANK_LEVEL_CMD

AddPointsArray

The AddPointsArray method adds the points in a given array of tags to the cache.

Syntax

AddPointsArray(ArrTags As Variant, EnableAlarmAck As Boolean, [NotifyHyperPoint As Variant])

Parameters

Remarks

If the optional NotifyHyperPoint parameter is used and the tag’s real-time record or configuration record is changed, the specified HyperPoint’s OnPointChange event is triggered. The NotifyHyperPoint parameter is typically This, which refers to the current HyperPoint (see the example). The AddPointsArray method is not typically used in CygNet Studio because points can be referenced without it. However, it can be useful in situations where the names of the points to be added are stored in an array, or need to be accessed sequentially at a later time.

Example

The following HyperPoint OnInitializeEx event contains an example of adding an array of points to the Points object.

1
2
3
4
5
6
7
8
9
10
11
12
Sub STATUS_OnInitializeEx(This) 
    Dim arrPoints
    Redim arrPoints(2)
     
    'Fill array with some point tags
    arrPoints(0) = "CYGDEMO.UIS:METER206_PSTATIC"
    arrPoints(1) = "CYGDEMO.UIS:METER206_SPUMP"
    arrPoints(2) = "CYGDEMO.UIS:METER206_VOLTIB"
     
    'Add the array to the points object
    Points.AddPointsArray arrPoints, False
End Sub

EnableUpdate

The EnableUpdate method enables or disables updating of the Points object.

Syntax

EnableUpdate(Enable As Boolean)

Parameters

Remarks

If updating is disabled, auto refresh of the Points object is prevented. That is, if a point in the Points object has a value or status change, the OnPointChange event in the HyperPoint will not be triggered even if it is set to receive point updates by the AddPoint method. In the HSS, updates are enabled by default. Changing the EnableUpdate property in one HyperPoint script will change it for all scripts (it is a global property). The use of this function is rare and not generally needed except in more complex situations.

Example

The following example enables updating.

1
2
3
4
Sub enableUpdate()
    Points.EnableUpdate True
    edtMessageBox.Text = "Updating enabled"
End Sub

GetPointStatusAttribute

The GetPointStatusAttribute method returns the requested attribute of the point status.

Syntax

GetPointStatusAttribute(BaseStatus As Integer, UserStatus As Long, Attr As String) As Variant

Parameters

Example

The following example displays the data type "AO" in a message box. See the Point object for more information.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Sub getTagList()
 
    Option Explicit
     
    'Create a Points object
    Dim Points : Set Points = CreateObject("CxScript.Points")
     
    'Define base status and user status values
    'These values will typically come from a point’s Status and UserStatus properties.
    'Refer to the Point Object in CxScript for more information.
     
    Dim base_status : base_status="199"
    Dim user_status : user_status="12648448"
     
    'Specify the attribute to retrieve
    Dim pointAttribute : pointAttribute = "pointstatedescription"
     
    'Issue method to retrieve attribute
    Dim pointAttributeValue : pointAttributeValue = Points.GetPointStatusAttribute(base_status, user_status, pointAttribute)
     
    MsgBox pointAttribute & " = " & pointAttributeValue
 
End Sub

GetPointsXML

The GetPointsXML method returns point data in XML DOM format.

Syntax

GetPointsXML(RequestXML As String) As String

Parameters

Remarks

This method takes an XML string specifying the points and parameters to return and inserts the data in the return XML string. The request string is in the following format:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<cygPtInfo>
    <Parameters>
        <Value format=format />
        <TimeStamp formatUTC=formatUTC />
        <Status format=format />
        <StatusTxt />
        <Units />
        <AlarmAck />
        <Desc />
    </Parameters>
    <Points>
        <node1 cygTag=tag />
        <node2 ...
    </Points>
</cygPtInfo>

Parameters need to be included only for desired fields (names are case sensitive). Any number of points can be specified in the "Points" tag. The parameters listed in the following table comprise some the available options:

Example

The following method saves XML data for the value, timestamp, and status of an inputted array of point tags.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
Function GetXMLData(arrPoints)
    Dim strXMLReq, i
     
    'Add points to the Points object and get current data
    Points.AddPointsArray arrPoints, True
    Points.ResolveNow(2)
     
    'Create XML request string
    strXMLReq = "<cygPtInfo>"
    &"<Parameters>"
    &"<Value/>"
    &"<TimeStamp/>"
    &"<Status/>"
    &"</Parameters>"
    &"<Points>"
     
    For i=lbound(arrPoints) To ubound(arrPoints)
        strXMLReq = strXMLReq & "<node" & CStr(i+1) & " cygTag="& chr(34) & arrPoints(i) & chr(34) & "/>"
    Next
     
    strXMLReq = strXMLReq &"</Points>"&"</cygPtInfo>"
     
    'Get response XML
    GetXMLData = Points.GetPointsXML(strXMLReq)
End Function

See the CxScript Enumeration Attributes table in the Enumeration Constants section.

GetPointTagList

The GetPointTagList method returns a list of point tags for the specified criteria.

Syntax

GetPointTagList(PointCfgOrCvsSiteService As String, Filter As String, GetLongID As Boolean, TagList As Variant)

Parameters

Example

The following example gets the short ID for all points in CYGDEMO.UIS and stores them in a list box.

1
2
3
4
5
6
7
8
9
10
Sub getTagList()
    Dim arrTags, tag
     
    Points.GetPointTagList "CYGDEMO.UIS", "FACILITYID=" & facility, True, arrTags
    lstTags.ResetContent
    For Each tag In arrTags
        lstTags.AddString(tag)
    Next
    edtMessage.Text = "Done"
End Sub

Filter using non-indexed fields from PNT header record

To use any of the PNT header record properties in GetPointTagList, your filter must include at least one of these indexed attributes:

• "SITE"
• "SERVICE"
• "SYSTEMNAME"
• "FACILITYID"
• "UNIFORMDATACODE"
• "INDEXED1"
• "INDEXED2"
• "INDEXED3"

If you include one of those, you can also include other non-indexed fields from the PNT header record. You must include one of the parameter(s) on the left column in the filter. Some of them will allow additional filtering parameters.

This means that when you are using facility as your filter, you can add additional filters like AnyCfgBitEnabled, Activestatus, etc. to get the desired point list.

Examples

The filtering below gives an array of points which have active_flag and AnyCfgBitEnabled set to 1. It works with 1 and 0.

1
Points.GetPointTagList "CYGNET.UIS","FACILITY=WELL00_RD;AnyCfgBitEnabled=1;activestatus=1",True, arrTagList

If you would like to include only a particular UDC points, then you can add UDC to the filter as shown below.

1
Points.GetPointTagList "CYGNET.UIS","FACILITY=WELL00_RD;UDC=TDDOWNT;AnyCfgBitEnabled=1;activestatus=1",True, arrTagList

The arrTagList would contain the list of point for the Facility indicated in the filter for which Any Config Bit is enabled and Active flag is Y.

GetPointTagListForFacilities

The GetPointTagListForFacilities method takes in an array of facility tags and returns an array of objects that have tag information elements.

Syntax

GetPointTagListForFacilities(pvArrFacilityTags As Variant, TagList As Variant)

Parameters

Example

The following example gets the tag information for the points for the facilities CYGDEMO.UIS::WELL and CYGDEMO.UIS::TANK.

1
2
3
4
5
6
7
8
9
10
Dim arrFacs, arrTagObjs, objTag, strTags
    arrFacs = Array("CYGDEMO.UIS::WELL", "CYGDEMO.UIS::TANK")
     
    Points.GetPointTagListForFacilities arrFacs, arrTagObjs
     
    For Each objTag in arrTagObjs
        strTags = strTags & objTag.Tag & vbcr
    Next
 
MsgBox strTags

GetUdcList

The GetUdcList method returns the UDC list for the specified facility tag.

Syntax

GetUdcList(FacilityTag As String, UdcList As Variant)

Parameters

Example

The following example lists all UDCs for the facility "CYGDEMO.UIS::ENTOPS".

1
2
3
4
5
6
7
8
9
10
11
Sub
    Dim aryUdcs
    Points.GetUdcList "CYGDEMO.UIS::ENTOPS", aryUdcs
     
    Dim i, strMsg
    For i = 0 To UBound(aryUdcs)
        strMsg = strMsg + aryUdcs(i) + vbCr
    Next
     
    MsgBox strMsg
End Sub

Point

The Point method returns a Point object representing the point associated with the specified tag.

Syntax

Point(Tag as String) As Point

Parameters

Remarks

The returned reference is a Point object, which is a static snapshot of the point at the current moment. Properties of this Point object are read only. If the Tag parameter is an invalid tag string, an empty Point object will be returned. For more information about the Point object, see Points Object.

Examples

The following function returns the value for a given tag string by declaring a Point object from the Points object.

1
2
3
4
5
6
7
Function GetPointValue (tagString)
    Dim objPoint
     
    'Create a Point object and return its value
    Set objPoint = Points.Point(tagString)
    GetPointValue = objPoint.Value
End Function

The next example gives a HyperPoint used for data thinning. It uses the AddPoint method and sets a timer so that OnTimer is called once an hour. The hourly value of the MYPOINT point is then stored in a separate UIS point, METER206_MYPOINT_THIN, effectively trimming the data to a manageable amount for trending and analysis.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Sub MYPOINT_THIN_OnInitializeEx(This)
    'Add a point to be monitored
    Points.AddPoint "CYGDEMO.UIS:METER206_MYPOINT"
     
    'Set a timer to update every hour
    Timer.Set This, 3600000
    End Sub
     
    Sub MYPOINT_THIN_OnTimer(This)
    'Obtain the Point object
    Set pStaticPoint = Points.Point("CYGDEMO.UIS:METER206_MYPOINT")
     
    'Assign the current MYPOINT value to a separate point
    SetPoint, pStaticPoint.Value
End Sub

ResolveNow

The ResolveNow method updates all points in the points object that have not been resolved with data from the CVS, Point Service, or both.

Syntax

ResolveNow(resolveFlag As ResolveNowType)

Parameters

Remarks

Whereas the UpdateNow method updates all points in a Points object, ResolveNow updates just the subset that have not been resolved. This can be used in cases where you suspect that the script engine has not resolved a set a points before you need to retrieve their data.

In non-HSS environments, EnableUpdate is turned off by default for declared Points objects, so updating can be achieved using the UpdateNow or ResolveNow methods rather than enabling updates.

Example

The following example updates unresolved points for both service types.

1
2
3
4
Sub enableUpdate()
    Points.ResolveNow 2
    edtMessageBox.Text = "Points resolved"
End Sub

UpdateNow

The UpdateNow method forces an immediate update of items in the Points object with data from the CVS, Point Service, or both.

Syntax

UpdateNow(UpdateFlag As UpdateNowType)

Parameters

Remarks

This method can be used in cases where you suspect that the script engine has not resolved the majority of points before you need to retrieve their data.

In non-HSS environments, EnableUpdate is turned off by default for declared Points objects, so updating can be achieved using the UpdateNow or ResolveNow methods rather than enabling updates.

Example

The following example updates all points for both service types.

1
2
3
4
Sub enableUpdate()
    Points.UpdateNow 2
    edtMessageBox.Text = "Points updated"
End Sub