PntClient Methods

The PntClient object contains the following methods:

Some of the automation calls in this API support multithreading. If supported it is noted below. If multithreading is not noted, the call is single-threaded.

AddPointRecord

The AddPointRecord method adds a point record to the PNT.

Syntax

AddPointRecord(PointXML as String)

Parameters

Remarks

All point attributes are not required for the AddPointRecord method; any unspecified attributes will be left blank. The XML should be in the same format that ReadPointRecord returns.

1
<CygNetPointRecord description="Vol Gas Today" pointid="00000123" pointidlong="CYG_DEMO_VGT" site="CYGDEMO" service="UIS" facilityid="CYGDEMO_GAS" ... />

Example

The following example adds a new point to the PNT. In the example below edtRecord.Text contains the points attributes in XML format.

1
2
3
4
Sub AddPoint()
    PntClient.AddPointRecord edtRecord.Text
    MsgBox "Point added
End Sub

CancelPointRecordLock

The CancelPointRecordLock method cancels the edit lock on a point record.

Syntax

CancelPointRecordLock(PointTag as String, PointXML as String)

Parameters

Remarks

The XML used should be the same as the XML obtained from the ReadPointRecordLock method.

Example

The following method unlocks a point so it can be edited by another user.

1
2
3
4
Sub CancelLock()
    PntClient.CancelPointRecordLock edtTag.Text, edtXML.Text
    MsgBox "Point unlocked"
End Sub

Connect

The Connect method connects the object to a service.

Syntax

Connect(DomainSiteService As String)

Parameters

Remarks

Returns 0 if successful and a non-zero value if the connection failed.

Example

The following example connects the Client object to the CYGDEMO.<SVC> on domain 5410:

1
2
3
4
5
6
7
8
Sub PntConnect()

    'Connect to a PNT
    Dim PntClient
    Set PntClient = CreateObject("CxPnt.PntClient")
    PntClient.Connect("[5410]CYGDEMO.PNT")

End Sub

DeletePointRecord

The DeletePointRecord method deletes a point record.

Syntax

DeletePointRecord(PointTag as String)

Parameters

Remarks

PointTag must be in one of the following formats:

• SITE.SERVICE.POINTID
• SITE.SERVICE:POINTIDLONG
• SITE.SERVICE::FACILITY.UDC

If SITE.SERVICE::FACILITY.UDC is not unique the point will not be deleted.

Example

The following example illustrates the DeletePointRecord method using all three PointTag formats.

1
2
3
4
5
6
7
8
9
10
11
12
Sub DeletePoint()
    'Delete a point using the specified method
    If delMethod = 0 Then
        PntClient.DeletePointRecord("CYGDEMO.UIS.00000240")
    Elseif delMethod = 1 Then
        PntClient.DeletePointRecord("CYGDEMO.UIS:CYG_METER_VGT")
    Elseif delMethod = 2
        PntClient.DeletePointRecord("CYGDEMO.UIS::CYG _METER.VGT")
    End If
 
    MsgBox "Done"
End Sub

Disconnect

The Disconnect method disconnects from the connected service.

Syntax

Disconnect() As Integer

Remarks

The Disconnect method returns 0 if successful and a non-zero value if the disconnect failed.

Example

The following example disconnects the Client object from the connected service, and pops a message box if it is unsuccessful:

1
2
3
4
5
6
7
8
9
10
11
Sub Svc.Disconnect()
 
    <SvcClient>.Disconnect()
    MsgBox "Service has disconnected."
    
    If <SvcClient>.Disconnect <> 0 
    Then
        MsgBox "Failed to disconnect."
    End If

End Sub

FinishBulkUpdates

The FinishBulkUpdates method disables bulk updating. Call this function after StartBulkUpdates once all updates have been completed.

Syntax

FinishBulkUpdates()

Remarks

This method disables bulk updating and makes the PNT flush changes to the disk after every point is updated. See the StartBulkUpdates method for more information about enabling bulk updating.

Example

The following example stops bulk updating.

1
2
3
Sub FinishBulk()
    PntClient.FinishBulkUpdates
End Sub

GetActiveServices

The GetActiveServices method retrieves a list of active PNT services running on the domain. The Connect function is not required.

Syntax

GetActiveServices(Servicelist)

Parameters

Example

The following example gets a list of PNT services running on your network, and displays them in a listbox.

1
2
3
4
5
6
7
8
9
10
11
12
Sub GetActiveServices()
    Dim ServiceList
    Dim service
 
    'Get a list of running services
    PntClient.GetActiveServices ServiceList
 
    'Display the services in a listbox
    For Each service In ServiceList
        lboServiceList.AddString(service)
    Next
End Sub

GetAttributeTable

The GetAttributeTable method returns the TRS table name of a table point attribute.

Syntax

GetAttributeTable(PointAttribute as String) As String

Parameters

Example

The following method retrieves the TRS table associated with a given attribute.

1
2
3
4
5
Sub GetAttributeTable()
    Dim attTable
    attTable = PntClient.GetAttributeTable(edtAtt.Text)
    edtMessageBox.Text = attTable
End Sub

GetCommentsForPoint

The GetCommentsForPoint method retrieves the comments for the point represented by the given PointTag. Supports the PNT Comment (COMMENT) extended security event. Also see Configuring Alarm Settings for more information.

Syntax

GetCommentsForPoint(PointTag As String) As String

Parameters

Example

The following example gets the comments for the point 00000239 and then prints the comments to the console.

1
2
3
4
5
6
7
8
9
10
Sub GetComments()
    Dim PointTag
    Dim Comments
 
    PointTag = "CYGDEMO.UIS.00000239"
    'Make the call to GetCommentsForPoint.
    Comments = PntClient.GetCommentsForPoint(PointTag)
 
    Call WScript.Echo(Comments)
End Sub

GetConsoleData

The GetConsoleData method returns the console text and display attributes as two 25x80 arrays of unsigned characters.

Syntax

GetConsoleData(ByRef pText, ByRef pAttr) As Integer

Parameters

Remarks

This method returns 0 if successful.

Example

The following example writes the console text and display attributes to a CSV file.

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
26
27
28
29
30
31
32
33
34
35
Sub
    Dim aryText, aryAttr, nRet
    nRet = <NameofServiceClientObject>.GetConsoleData(aryText, aryAttr)
 
    ' Write text attributes to CSV file
    Dim i, j, strMsg
        For i = 0 To UBound(aryText, 1)
        For j = 0 To UBound(aryText, 2)
            strMsg = strMsg + CStr(aryText(i, j)) + ","
        Next
            strMsg = strMsg + vbCr
    Next
 
    dim fso, file
    Set fso = CreateObject("Scripting.FileSystemObject")
    Set file = fso.OpenTextFile("c:\console_text_attrs.csv", 2, True)
    file.WriteLine(strMsg)
    file.Close 
 
    strMsg = ""
 
    ' Write display attributes to CSV file
        For i = 0 To UBound(aryAttr, 1)
        For j = 0 To UBound(aryAttr, 2)
            strMsg = strMsg + CStr(aryAttr(i, j)) + ","
        Next
            strMsg = strMsg + vbCr
    Next
 
    Set file = fso.OpenTextFile("c:\console_disp_attrs.csv", 2, True)
    file.WriteLine(strMsg)
    file.Close 
 
    MsgBox nRet
End Sub

GetCvsServiceList

The GetCvsServiceList method returns the service names of all the current value services that are referenced by point records.

Syntax

GetCvsServiceList(ServiceList as Array)

Parameters

Remarks

The returned service names will be in Site.Service format.

Example

The following example retrieves all the current value services the point records are associated with and stores them in a list box.

1
2
3
4
5
6
7
8
9
10
11
12
Sub GetCvsList()
    Dim CvsList
    Dim cvs
 
    'Get a list of CVSes associated with the PNT service
    PntClient.GetCvsServiceList CvsList
 
    'Store each CVS in a list box
    For Each cvs In CvsList
        lboCvs.AddString(cvs)
    Next
End Sub

GetDefaultPointRecord

The GetDefaultPointRecord method returns the default point record in XML format.

Syntax

GetDefaultPointRecord() As String

Remarks

The string is returned as XML. The following is an example of an excerpt of the XML returned by this method.

1
<CygNetPointRecord lock_user="" lock_time="0" description="" pointid="" pointidlong="" site="" service="" facilityid="" uniformdatacode="" systemname="N/A" pointdatatype="AI" initialtype="R" initialvalue="" minsetpoint="0" ... />

Example

The following example retrieves the default point record and saves it to an XML document.

1
2
3
4
5
6
7
8
9
10
Sub GetDefaultRecord()
    'Get point record
    Dim strInfo
    strInfo = PntClient.GetDefaultPointRecord
 
    'Save XML
    Set xmlDoc = CreateObject("Msxml2.DOMDocument")
    xmlDoc.loadXML(strInfo)
    xmlDoc.save("C:\DefaultPointRecord.xml")
End Sub

GetDefaultPointScheme

The GetDefaultPointScheme method returns the default Point Scheme. See Point Scheme for more information.

Syntax

GetDefaultPointScheme() As Integer

Remarks

The method returns the numeric identifier for the default Point Scheme that will be used in the creation of all points if not specified in the PointXML string. If the SetDefaultPointScheme method has not been called, the GetDefaultPointScheme method will return the Point Scheme from the CVS Metadata file with the lowest numeric identifier.

Example

The following example retrieves the default Point Scheme number and displays it in an edit box.

1
2
3
4
5
Sub GetDefaultScheme()
    Dim iScheme
    iScheme = PntClient.GetDefaultPointScheme
    edtScheme.Text = "The default Point Scheme is " & iScheme
End Sub

GetEmptyPointXml

The GetEmptyPointXml method returns the XML for an empty point.

Syntax

GetEmptyPointXml() As String

Remarks

This method can be used in the process of creating a new point. After the empty record XML is retrieved, use the SetPointXMLAttribute method to set the new point record values. Then use the UpdatePointRecord method to created the new facility from the XML string created by the SetPointXMLAttribute method.

The string is returned as XML. The following is an example of what this method will return.

1
<CygNetPointRecord/>

Example

The following example retrieves the XML for an empty point and saves it to an XML document.

1
2
3
4
5
6
7
8
9
10
Sub GetEmptyXml()
    'Get point xml
    Dim strInfo
    strInfo = PntClient.GetEmptyPointXml
 
    'Save XML
    Set xmlDoc = CreateObject("Msxml2.DOMDocument")
    xmlDoc.loadXML(strInfo)
    xmlDoc.save("C:\EmptyPoint.xml")
End Sub

GetFacilitiesList

The GetFacilitiesList method returns the list of facilities associated with the specified CVS.

Syntax

GetFacilitiesList(SiteService as String, FacilityList as Array)

Parameters

Example

The following example retrieves the list of facilities associated with CYGDEMO.UIS and displays it in a list box.

1
2
3
4
5
6
7
8
9
10
11
12
Sub GetFacilities()
    Dim FacList
    Dim fac
 
    'Get a list of facilities associated with the PNT
    PntClient.GetFacilitiesList "CYGDEMO.UIS", FacList
 
    'Store the facilites in a listbox
    For Each fac In FacList
        lboFac.AddString(fac)
    Next
End Sub

GetPointAttributeList

The GetPointAttributeList method returns an array of point attributes and their descriptions. If IsConnected property is used, the descriptions are based on the PNT metadata.

Syntax

GetPointAttributeList(Attributes as Object)

Parameters

Example

The following example retrieves the list of point attributes and displays it in a list box.

1
2
3
4
5
6
7
8
9
10
11
12
13
Sub GetAttributeList()
    Dim AttList
    Dim att
 
    'Get a list of point attributes
    PntClient.GetPointAttributeList AttList
 
    'Display attributes in a list box
    ''Set ListBox "VerticalScroll" to "1 - Always"
    For Each att In AttList
        lboAttributes.AddString(att)
    Next
End Sub

GetPointTagList

The GetPointTagList retrieves a list of point tags for the specified criteria. The criteria can use the simplified 'key1=value1;key2=value2' form or the XML rules form.

Syntax

GetPointTagList(ByVal bstrFilter As String, ByVal eTagFormat As PointTagType, ByRef pvTagList)

Parameters

Remarks

Returns a list of point tags for the specified criteria.

GetPointXMLAttribute

The GetPointXMLAttribute method returns the value of an attribute from a point record.

Syntax

GetPointXMLAttribute(PointXML as String, PointAttribute as String) As String

Parameters

Remarks

See GetPointAttributeList method, which returns listing of all point attributes.

Example

The following example retrieves a point attribute and displays it in an edit box.

1
2
3
4
5
Sub GetXMLAttribute()
    Dim Attribute
    Attribute = PntClient.GetPointXMLAttribute(edtXML.Text, edtAtt.Text)
    edtMessageBox.Text = Attribute
End Sub

GetQuestionableStateAndLastChangeDateTimeForPoint

The GetQuestionableStateAndLastChangeDateTimeForPoint method gets Questionable State and the last time the questionable state changed for the given Point. Supports the PNT Questionable State (QUESTION) extended security event.

See Questionable flag and Configuring Alarm Settings for more information.

Syntax

GetQuestionableStateAndLastChangeDateTimeForPoint (PointTag As String, ByRef PointIsQuestionable As Boolean, ByRef LastQuestionableChangeDateTime As Date)

Parameters

Example

The following example checks if point 00000239 is in a questionable state and when the state was last changed. If point 00000239 is in a questionable state a message is printed to the console.

1
2
3
4
5
6
7
8
9
10
11
Sub GetQuestionableStateAndLastChangeDateTimeForPoint()
    Dim PointTag : PointTag = "CYGDEMO.UIS.00000239"
    Dim PointIsQuestionable, LastQuestionableChangeDateTime
 
    'Make the call to GetQuestionableStateAndLastChangeDateTimeForPoint
    Call PntClient.GetQuestionableStateAndLastChangeDateTimeForPoint(PointTag, PointIsQuestionable, LastQuestionableChangeDateTime)
 
    If (PointIsQuestionable) Then
        Call WScript.Echo("Point with PointTag " & PointTag & " is in a Questionable State!")
    End If
End Sub

GetQuestionableStateForPoint

The GetQuestionableStateForPoint method retrieves whether or not the point represented by the given PointTag is in a questionable state. Supports the PNT Questionable State (QUESTION) extended security event.

See Questionable flag and Configuring Alarm Settings for more information.

Syntax

GetQuestionableStateForPoint(PointTag As String) As Boolean

Parameters

Example

The following example checks if point 00000239 is in a questionable state. If point 00000239 is in a questionable state a message is printed to the console.

1
2
3
4
5
6
7
8
9
10
11
12
13
Sub GetQuestionableState()
    Dim PointTag
    Dim IsPointQuestionable
 
    PointTag = "CYGDEMO.UIS.00000239"
 
    'Make the call to GetQuestionableStateForPoint.
    IsPointQuestionable = PntClient.GetQuestionableStateForPoint(PointTag)
 
    If (IsPointQuestionable) Then
        Call WScript.Echo("Point with PointTag " & PointTag & " is in a questionable state!")
    End If
End  Sub

GetQuestionableStateLastChangeDateTimeForPoint

The GetQuestionableStateLastChangeDateTimeForPoint method retrieves the DateTime when the questionable state last changed for the point represented by the given PointTag. Returns 0 if no change was ever made to questionable state for the given point. Supports the PNT Questionable State (QUESTION) extended security event.

See Questionable flag and Configuring Alarm Settings for more information.

Syntax

GetQuestionableStateLastChangeDateTimeForPoint(PointTag As String) As Date

Parameters

Example

The following example retrieves the questionable state last change DateTime for point 00000239. If point 00000239 ever had it’s questionable state changed, then a message is printed to the console.

1
2
3
4
5
6
7
8
9
10
11
12
13
Sub GetQuestionableStateLastChangeDateTime()
    Dim PointTag
    Dim QuestionableStateLastChangeDateTime
 
    PointTag = "CYGDEMO.UIS.00000239"
 
    'Make the call to GetQuestionableStateLastChangeDateTimeForPoint.
    QuestionableStateLastChangeDateTime = PntClient.GetQuestionableStateLastChangeDateTimeForPoint(PointTag)
 
    If (QuestionableStateLastChangeDateTime <> 0) Then
        Call WScript.Echo("The questionable state flag was last changed on " & QuestionableStateLastChangeDatetime & " for Point with Point Tag " & PointTag)
    End If
End Sub

GetReferences

The GetReferences method refreshes the list of services referenced by the connected service.

Syntax

GetReferences() As Integer

Return Values

This method returns all references for the connected service.

Example

The following example refreshes the connected services:

1
2
3
4
5
6
Sub GetReferences()
 
    <NameofServiceClientObject>.GetReferences
    MsgBox "Services references retrieved"

End Sub

GetSuppressAlarmsAndEndConditionsForPoint

The GetSuppressAlarmsAndEndConditionsForPoint method gets whether or not to suppress alarms for the given point along with the current end conditions for the given point. Supports the PNT Alarm Suppression (ALMSUPP) extended security event.

See Suppressing Alarms and Configuring Alarm Settings for more information.

Syntax

GetSuppressAlarmsAndEndConditionsForPoint (PointTag As String, ByRef SuppressAlarms as Boolean, ByRef SuppressAlarmsEndOnNormal As Boolean, ByRef SuppressAlarmsEndDateTime As Date)

Parameters

Example

The following example retrieves the current end conditions for alarm suppression for point 00000239. If point 00000239 has alarm suppression ending on point state of 'Normal' and/or there is an end DateTime configured for point 00000239, then a message is printed to the console.

1
2
3
4
5
6
7
8
9
10
11
Sub GetSuppressAlarmsAndEndConditionsForPoint()
    Dim PointTag : PointTag = "CYGDEMO.UIS.00000239"
    Dim SuppressAlarms, SuppressAlarmsEndOnNormal, SuppressAlarmsEndDateTime
 
    'Make the call to GetSuppressAlarmsAndEndConditionsForPoint
    Call PntClient.GetSuppressAlarmsAndEndConditionsForPoint(PointTag, SuppressAlarms, SuppressAlarmsEndOnNormal, SuppressAlarmsEndDateTime)
 
    If (SuppressAlarms) Then
        Call WScript.Echo("Alarm Suppression is enabled for Point with PointTag: " & PointTag)
    End If
End Sub 

GetSuppressAlarmsEndDateTimeForPoint

The GetSuppressAlarmsEndDateTimeForPoint method retrieves the DateTime when alarm suppression ends for the point represented by the given PointTag. Returns 0 if an end DateTime was never configured for this Point. Supports the PNT Alarm Suppression (ALMSUPP) extended security event.

See Suppressing Alarms and Configuring Alarm Settings for more information.

Syntax

GetSuppressAlarmsEndDateTimeForPoint(PointTag As String) As Date

Parameters

Example

The following example retrieves the end DateTime for alarm suppression for point 00000239. If there is an end DateTime configured for point 00000239, then a message is printed to the console.

1
2
3
4
5
6
7
8
9
10
11
12
13
Sub  GetSuppressAlarmsEndDateTime()
    Dim PointTag
    Dim SuppressAlarmsEndDateTime
 
    PointTag = "CYGDEMO.UIS.00000239"
 
    'Make the call to GetSuppressAlarmsEndDateTimeForPoint.
    SuppressAlarmsEndDateTime = PntClient.GetSuppressAlarmsEndDateTimeForPoint(PointTag)
 
    If (SuppressAlarmsEndDateTime <> 0) Then
        Call WScript.Echo("Suppressed alarms end at DateTime " & SuppressAlarmsEndDateTime & " for Point with PointTag " & PointTag)
    End If
End Sub 

GetSuppressAlarmsEndOnNormalForPoint

The GetSuppressAlarmsEndOnNormalForPoint method retrieves whether or not alarm suppression ends when a point's state becomes 'Normal' for the point represented by the given PointTag. Supports the PNT Alarm Suppression (ALMSUPP) extended security event.

See Suppressing Alarms and Configuring Alarm Settings for more information.

Syntax

GetSuppressAlarmsEndOnNormalForPoint(PointTag As String) As Boolean

Parameters

Example

The following example checks if point 00000239 has alarm suppression ending on point state of 'Normal'. If point 00000239 has alarm suppression ending on point state of 'Normal', then a message is printed to the console.

1
2
3
4
5
6
7
8
9
10
11
12
13
Sub GetSuppressAlarmsEndOnNormal()
    Dim PointTag
    Dim SuppressAlarmsEndOnNormal
 
    PointTag = "CYGDEMO.UIS.00000239"
 
    'Make the call to GetSuppressAlarmsEndOnNormalForPoint.
    SuppressAlarmsEndOnNormal = PntClient.GetSuppressAlarmsEndOnNormalForPoint(PointTag)
 
    If (SuppressAlarmsEndOneNormal) Then
        Call WScript.Echo("Suppressed alarms end on point state of 'Normal' for point with PointTag " & PointTag)
    End If
End Sub

GetSuppressAlarmsForPoint

The ReadAlarmSettingsForPoint method retrieves whether alarms are suppressed for the point represented by the given PointTag. Supports the PNT Alarm Suppression (ALMSUPP) extended security event.

See Suppressing Alarms and Configuring Alarm Settings for more information.

Syntax

GetSuppressAlarmsForPoint(PointTag As String) As Boolean

Parameters

Example

The following example checks if point 00000239 has alarm suppression enabled. If alarm suppression is enabled, then a message is printed to the console.

1
2
3
4
5
6
7
8
9
10
11
12
13
Sub GetSuppressAlarms()
    Dim PointTag
    Dim SuppressAlarms
 
    PointTag = "CYGDEMO.UIS.00000239"
 
    'Make the call to GetSuppressAlarmsForPoint.
    SuppressAlarms = PntClient.GetSuppressAlarmsForPoint(PointTag)
 
    If (SuppressAlarms) Then
        Call WScript.Echo("Alarms are being suppressed for point with PointTag " & PointTag)
    End If
End Sub

GetTableDrivenAttributeList

The GetTableDrivenAttributeList method retrieves a list of the point attributes whose legal values are derived from TRS tables.

Syntax

GetTableDrivenAttributeList(Attributes)

Parameters

Remarks

Associated table names are returned by the GetAttributeTable method.

Example

The following example retrieves the list of table-driven attributes.

1
2
3
4
5
6
7
8
9
10
Sub GetTableDrivenAttributes
    Dim TDList
    Dim attribute
 
    PntClient.GetTableDrivenAttributeList TDList
 
    For Each attribute In TDList
        lboTD.AddString(attribute)
    Next
End Sub

IsPointIdLongAvailable

The IsPointIdLongAvailable method returns true if a point ID is available and unique to the given Site and Service.

Syntax

IsPointIdLongAvailable(SiteService as String, PointIDLong as String) As Boolean

Parameters

Example

The following example returns a Boolean value indicating whether or not a Point ID is available.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
Sub isLongIDAvailable()
    'Get data for the needed variables
    Dim siteService
    Dim PointIDLong
    siteService = "CYGDEMO.UIS"
    PointIDLong = edtLongId.Text  'ex. CYG_METER_TGAS
 
    'Test to see if the point is available
    If PntClient.IsPointIdLongAvailable(siteService, PointIDLong) <> True Then
        edtMessageBox.Text = "Long ID: " & PointIDLong & " is already in use."
    Else
        edtMessageBox.Text = "Long ID: " & PointIDLong & " is available." 
    End If
End Sub

IsValidPointXML

The IsValidPointXML method validates the given PointXML. Returns true if the given PointXML is valid. Returns false and the first error encountered if the validation fails.

Syntax

IsValidPointXML(PointXML As String, Error As Object) As Boolean

Parameters

Example

The following example sets up an invalid point xml string and then checks if the point xml is valid. Since the point xml is invalid, a message will be printed to the console.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Sub ValidatePointXML()
    Dim PointXML
    Dim ReturnedError
    Dim IsValidPointXml
 
    PointXML = PntClient.GetDefaultPointRecord()
    PointXML = PntClient.SetPointXMLAttribute(PointXML, "pointdatatype", "ThisWillFailValidation")
 
    'Make the call to IsValidPointXML.
    IsValidPointXML = PntClient.IsValidPointXML(PointXML, ReturnedError)
 
    If (Not IsValidPointXML) Then
        Call WScript.Echo("PointXML Validation failed with error: " & ReturnedError)
    End If
End Sub

ReadAlarmSettingsForPoint

The ReadAlarmSettingsForPoint method retrieves the alarm settings specific PointXML for the Point represented by the given PointTag. Supports the PNT Alarm Settings (ALARMSET) and Alarm Settings CfgBits (CFGBITxx) extended security events.

Also see Configuring Alarm Settings for more information.

Syntax

ReadAlarmSettingsForPoint(PointTag As String) As String

Parameters

Example

The following example retrieves the alarm settings specific point xml. If the alarm category is set to a value in the point xml, then a message is printed to the console.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Sub ReadAlarmSettings()
    Dim PointTag
    Dim PointXML
    Dim AlarmCategory
 
    PointTag = "CYGDEMO.UIS.00000239"
 
    "Make the call to ReadAlarmSettingsForPoint.
    PointXML = PntClient.ReadAlarmSettingsForPoint(PointTag)
    AlarmCategory = PntClient.GetPointXMLAttribute(PointXML, "alarmcategory")
 
    If (AlarmCategory <> "") Then
        Call WScript.Echo("The AlarmCategory is " & AlarmCategory & " for Point with PointTag " & PointTag)
    End If
End Sub

ReadEnhancedAlarmConfig

The ReadEnhancedAlarmConfig method reads the enhanced alarm configuration for the Point represented by the given PointTag.

Also see Enhanced Alarm Configuration for more information.

Syntax

ReadEnhancedAlarmConfig(ByVal PointTag As String) As String

Parameters

Remarks

If the provided PointTag is invalid or the specified point does not exist, a script error is generated with details of the problem. Connect() must be called prior to calling this function. The User ID must have READ permissions to the point record via the ACCESS and/or ALARMSET security events. See Point Service (PNT) Security for more information.

Example

The following example reads a point’s enhanced alarm configuration XML and displays it on a message box. If a script error is generated, the reason for the error is displayed.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Dim cxPnt
Set cxPnt = createobject("CxPnt.PntClient")
 
Dim iRet
iRet = cxPnt.Connect("CYGNET.PNT")
If iRet <> 0 Then
    MsgBox "Connect failed with " & iRet
Else
    On Error Resume Next
    Dim strXml
    strXml = cxPnt.ReadEnhancedAlarmConfig("CYGNET.UIS:FAC01_UDC01")
 
    If err.number <> 0 Then
        MsgBox "ReadEnhancedAlarmConfig failed: " & err.description
    Else
        MsgBox strXml
    End If
    On Error Goto 0
End If

ReadPointRecord

The ReadPointRecord method returns the XML record for a point, wihtout locking the record for update. By default, the attributes are in lowercase when reading the XML using ReadPointRecord, and the first value for an attribute, regardless of its case, is used in the functions that modify the point records. When manipulating a point record XML directly (i.e. by not using SetPointXMLAttribute), make sure the attributes always use lowercase.

Syntax

ReadPointRecord(PointTag as String) As String

Parameters

Remarks

PointTag must be SITE.SERVICE.POINTID, SITE.SERVICE:POINTIDLONG, or SITE.SERVICE::FACILITY.UDC

The record will be returned in XML. The following is an example of an excerpt of the XML returned by this method.

1
<CygNetPointRecord description="Vol Gas Today" pointid="00000123" pointidlong="CYG_DEMO_VGT" site="CYGDEMO" service="UIS" facilityid="CYGDEMO_GAS" ... />

Example

The following example retrieves the record for a point and saves it to an XML file.

1
2
3
4
5
6
7
8
9
10
Sub GetXML()
    'Get point xml
    Dim Record
    Record = PntClient.ReadPointRecord(edtTag.Text)
 
    'Save XML
    Set xmlDoc = CreateObject("Msxml2.DOMDocument")
    xmlDoc.loadXML(Record)
    xmlDoc.save("C:\PointRecord.xml")
End Sub

ReadPointRecordLock

The ReadPointRecordLock method returns the XML record for a point including lock information and locks the record for update.

Syntax

ReadPointRecordLock(PointTag as String) As String

Parameters

Remarks

The XML string returned by this function can be used to cancel a record lock using the CancelPointRecordLock method.

Example

The following method stores the XML of a point, including information about the point lock.

1
2
3
4
Sub ReadRecordLock()
    Dim Record
    Record = PntClient.ReadPointRecordLock(edtTag.Text)
End Sub

ReadScriptText

The ReadScriptText method returns the script text of a point.

Syntax

ReadScriptText(PointTag as String) As String

Parameters

Example

The following example retrieves the script text from a point and stores it in a variable.

1
2
3
4
Sub ReadScript()
    Dim Script
    Script = PntClient.ReadScriptText(edtTag.Text)
End Sub

SaveEnhancedAlarmConfig

The SaveEnhancedAlarmConfig method saves the enhanced alarm configuration for the Point represented by the given PointTag.

Also see Enhanced Alarm Configuration for more information.

Syntax

SaveEnhancedAlarmConfig(ByVal PointTag As String, ByVal ConfigXml As String)

Parameters

Remarks

Calling SaveEnhancedAlarmConfig() with an empty string (e.g., ConfigXml = "") clears the Enhanced Alarm Configuration stored for a point. If the provided PointTag is invalid or the specified point does not exist, a script error is generated with details of the problem. If the format or content of the XML string is invalid, an error is generated summarizing the number or errors and warnings encountered. Call ValidateEnhancedAlarmConfigXml() to retrieve details of the errors and warnings. Connect() must be called prior to calling this function. The CygNet user ID must have UPDATE permissions to the point record via the ACCESS and/or ALARMSET security events. See Point Service (PNT) Security for more information.

Example

The following example reads one point’s enhanced alarm configuration XML and copies it to another point. If a script error is generated, the reason for the error is displayed.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
Dim cxPnt
    Set cxPnt = createobject("CxPnt.PntClient")
 
Dim iRet
iRet = cxPnt.Connect("CYGNET.PNT")
If iRet <> 0 Then
    MsgBox "Connect failed with " & iRet
Else
    On Error Resume Next
    Dim strXml
    strXml = cxPnt.ReadEnhancedAlarmConfig("CYGNET.UIS:FAC01_UDC01")
 
    If err.number <> 0 Then
        MsgBox "ReadEnhancedAlarmConfig failed: " & err.description
    Else
        Call cxPnt.SaveEnhancedAlarmConfig("CYGNET.UIS:FAC02_UDC01", strXml)
        If err.number <> 0 Then
            MsgBox "SaveEnhancedAlarmConfig failed: " & err.description
        Else
            MsgBox "SaveEnhancedAlarmConfig succeeded"
        End if
    End If
    On Error Goto 0
End If

SaveScriptText

The SaveScriptText method saves the specified HyperPoint script to a specified point.

Syntax

SaveScriptText(PointTag as String, ScriptText as String) As String

Parameters

Remarks

This method will fail if the specified PointTag does not resolve to a HyperPoint.

The following is an example of a script that can be saved to a point. {{HYPERPOINT}} is translated to the long point ID when the script is loaded. If the long point ID is changed, the function won’t be called anymore.

1
2
3
4
5
6
7
Sub {{HYPERPOINT}}_OnInitializeEx(This)
    Timer.Set this, 300
End Sub
 
Sub {{HYPERPOINT}}_OnTimer(This)
    This.value = formatdatetime(now(), 3)
End Sub

Example

The following example saves a HyperPoint script to a point.

1
2
3
4
Sub SaveScript()
    PntClient.SaveScriptText edtTag.Text, strScript
    MsgBox "Script saved!"
End Sub

SetCommentsForPoint

The SetCommentsForPoint method sets the comments for the point represented by the given PointTag. Supports the PNT Comment (COMMENT) extended security event. Also see Configuring Alarm Settings for more information.

Syntax

SetCommentsForPoint(PointTag As String, PointComments As String)

Parameters

Example

The following example sets the comments for the specified point.

1
2
3
4
5
6
7
8
9
10
Sub SetComments()
    Dim PointTag
    Dim Comments
 
    PointTag = "CYGDEMO.UIS.00000239"
 
    Comments = "This is a test Comments string."
    'Make the call to SetCommentsForPoints.
        Call PntClient.SetCommentsForPoint(PointTag, Comments)
End Sub

SetDefaultPointScheme

The SetDefaultPointScheme method sets the default Point Scheme used to create new points (for the current instance of the object) when creating a new point via the CxPNT automation interface. See Point Scheme for more information.

Syntax

SetDefaultPointScheme(PointScheme as Integer)

Parameters

Remarks

This method will fail if the specified PointScheme is not in the CVS Metadata file.

Example

The following example sets the default Point Scheme.

1
2
3
4
5
Sub SetPointScheme()
    Dim iPointScheme
    iPointScheme = edtScheme.Text
    PntClient.SetDefaultPointScheme()
End Sub

SetPointXMLAttribute

The SetPointXMLAttribute method sets an attribute value of a specified point record.

Syntax

SetPointXMLAttribute(PointXML as String, PointAttribute as String, AttributeValue as String) As String

Parameters

Remarks

This method creates a new XML string containing updated point attribute values to be used either by the UpdatePointRecord method for a single point record or the UpdateAttributesForPoints method for updating multiple point records.

See GetPointAttributeList method, which returns listing of all point attributes. SetPointXMLAttribute sets the attribute name to lowercase before modifying the XML.

Example

The following example creates a new XML string with the new point attribute value, but doesn’t update the point itself.

1
2
3
4
5
Sub SetPointXML()
    Dim newPoint
    newPoint = PntClient.SetPointXMLAttribute (XML, edtAtt.Text, edtValue.Text)
    edtMessageBox.Text = newPoint
End Sub

SetQuestionableStateForPoint

The SetQuestionableStateForPoint method sets whether or not the point represented by the given PointTag is in a questionable state. Supports the PNT Questionable State (QUESTION) extended security event.

See Questionable flag and Configuring Alarm Settings for more information.

Syntax

SetQuestionableStateForPoint(PointTag As String, PointIsQuestionable As Boolean, [ReasonForChange As String])

Parameters

Example

The following example puts point 00000239 into a questionable state.

1
2
3
4
5
6
7
8
9
10
11
12
13
Sub SetQuestionableState()
    Dim PointTag
    Dim IsPointQuestionable
    Dim ReasonForChange
 
    PointTag = "CYGDEMO.UIS.00000239"
 
    IsPointQuestionable = True
    ReasonForChange = "This is just a test."
 
    'Make the call to SetQuestionableStateForPoint.
        Call PntClient.SetQuestionableStateForPoint(PointTag, IsPointQuestionable, ReasonForChange)
End Sub

StartBulkUpdates

The StartBulkUpdates method enables faster updating by increasing the performance of several updates in a row.

Syntax

StartBulkUpdates()

Remarks

Normally, the PNT will flush the changes to the disk after each point is updated. If Bulk Updating is enabled, it will only flush every thirty seconds. This decreases the update time but increases the likelihood that data will be lost if a bad shutdown occurs. CygNet recommends that this feature only be turned on while bulk updating occurs and then turned off when finished.

Example

The following example enables Bulk Updating.

1
2
3
4
Sub StartBulkUpdates()
    PntClient.StartBulkUpdates()
    MsgBox "PNT Client has started bulk updating."
End Sub

SuppressAlarmsAndSetEndConditionsForPoint

The SuppressAlarmsAndSetEndConditionsForPoint method suppress alarms for the given point with the given end conditions. If the SuppressAlarmsEndOnDateTime parameter is false, then the SuppressAlarmsEndDateTime parameter is ignored. Supports the PNT Alarm Suppression (ALMSUPP) extended security event.

See Suppressing Alarms and Configuring Alarm Settings for more information.

Syntax

SuppressAlarmsAndSetEndConditionsForPoint(PointTag As String, SuppressAlarmsEndOnNormal As Boolean, SuppressAlarmsEndOnDateTime As Boolean, SuppressAlarmsEndDateTime As Date)

Parameters

Example

The following example suppresses alarms for the point 00000239, ends the suppression when the point state becomes 'Normal', or ends the suppression one day from now, whichever comes first.

Sub SuppressAlarmsAndSetEndConditionsForPoint()
    Dim PointTag : PointTag = "CYGDEMO.UIS.00000239"
    Dim SuppressAlarmsEndOnNormal : SuppressAlarmsEndOnNormal = True
    Dim SuppressAlarmsEndOnDateTime : SuppressAlarmsEndOnDateTime = True
    Dim SuppressAlarmsEndDateTime : SuppressAlarmsEndDateTime = DateAdd("d", 1, Now()) 'End 1 day from now.
 
    'Make the call to SuppressAlarmsAndSetEndConditionsForPoint
        Call PntClient.SuppressAlarmsAndSetEndConditionsForPoint(PointTag, SuppressAlarmsEndOnNormal, SuppressAlarmsEndOnDateTime, SuppressAlarmsEndDateTime)
End Sub

SuppressAlarmsAndSetEndOnDateTimeForPoint

The SuppressAlarmsAndSetEndOnDateTimeForPoint method suppress alarms until the given date time for the given Point. If SuppressAlarmsEndOnDateTime is false, then the SuppressAlarmsEndDateTime parameter is ignored. Supports the PNT Alarm Suppression (ALMSUPP) extended security event.

See Suppressing Alarms and Configuring Alarm Settings for more information.

Syntax

SuppressAlarmsAndSetEndOnDateTimeForPoint (PointTag As String, SuppressAlarmsEndOnDateTime As Boolean, SuppressAlarmsEndDateTime As Date)

Parameters

Example

The following example suppresses alarms for the point 00000239, ending the suppression one day from now.

1
2
3
4
5
6
7
8
Sub SuppressAlarmsAndSetEndOnDateTimeForPoint()
    Dim PointTag : PointTag = "CYGDEMO.UIS.00000239"
    Dim SuppressAlarmsEndOnDateTime : SuppressAlarmsEndOnDateTime = True
    Dim SuppressAlarmsEndDateTime : SuppressAlarmsEndDateTime = DateAdd("d", 1, Now()) 'End 1 day from now.
 
    'Make the call to SuppressAlarmsAndSetEndOnDateTimeForPoint
        Call PntClient.SuppressAlarmsAndSetEndOnDateTimeForPoint(PointTag, SuppressAlarmsEndOnDateTime, SuppressAlarmsEndDateTime)
End Sub

SuppressAlarmsAndSetEndOnNormalForPoint

The SuppressAlarmsAndSetEndOnNormalForPoint method suppresses alarms and set whether or not to suppress alarms until Point State of 'Normal' for the given Point. Supports the PNT Alarm Suppression (ALMSUPP) extended security event.

See Suppressing Alarms and Configuring Alarm Settings for more information.

Syntax

SuppressAlarmsAndSetEndOnNormalForPoint (PointTag As String, SuppressAlarmsEndOnNormal As Boolean)

Parameters

Example

The following example suppresses alarms for the point 00000239, ending the suppression when the point state becomes 'Normal.'

1
2
3
4
5
6
7
Sub SuppressAlarmsAndSetEndOnNormalForPoint()
    Dim PointTag : PointTag = "CYGDEMO.UIS.00000239"
    Dim SuppressAlarmsEndOnNormal : SuppressAlarmsEndOnNormal = True
 
    'Make the call to SuppressAlarmsAndSetEndOnNormalForPoint
        Call PntClient.SupppressAlarmsAndSetEndOnNormalForPoint(PointTag, SuppressAlarmsEndOnNormal)
End Sub

UnsuppressAlarmsForPoint

The UnsuppressAlarmsForPoint method removes all alarm suppression for the point represented by the given PointTag. Supports the PNT Alarm Suppression (ALMSUPP) extended security event.

See Suppressing Alarms and Configuring Alarm Settings for more information.

Syntax

UnsuppressAlarmsForPoint(PointTag As String)

Parameters

Example

The following example removes all alarm suppression for the point 00000239.

1
2
3
4
5
6
7
8
Sub UnsuppressAlarms()
    Dim PointTag
 
    PointTag = "CYGDEMO.UIS.00000239"
 
    'Make the call to UnSuppressAlarmsForPoint.
        Call PntClient. UnSuppressAlarmsForPoint(PointTag)
End Sub

UpdateAlarmSettingsForPoint

The UpdateAlarmSettingsForPoint method updates the alarm settings for the point represented by the given PointTag with the specified PointXML. The PointXML must only contain changes to alarm settings. Supports the PNT Alarm Settings (ALARMSET) and Alarm Settings CfgBits (CFGBITxx) extended security events.

Also see Configuring Alarm Settings for more information.

Syntax

UpdateAlarmSettingsForPoint(PointTag As String, PointXML As String)

Parameters

Example

The following example gets an empty point xml string. An alarm settings specific point xml attribute is then added to the previously empty point xml string (alarm category). The alarm category for point 00000239 is then updated by the call to UpdateAlarmSettingsForPoint.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
Sub UpdateAlarmSettings()
    Dim PointTag
    Dim PointXML
    Dim AlarmCategory
 
    PointTag = "CYGDEMO.UIS.00000239"
 
    AlarmCategory = "TEST CAT"
    PointXML = PntClient.GetEmptyPointXML()
    PointXML = PntClient.SetPointXMLAttribute(PointXML, "alarmcategory", AlarmCategory)
 
    'Make the call to UpdateAlarmSettingsForPoint.
        Call PntClient.UpdateAlarmSettingsForPoint(PointTag, PointXML)
End Sub

UpdateAttributesForPoints

The UpdateAttributesForPoints method updates multiple point records with new values from an XML string.

Syntax

UpdateAttributesForPoints(Tags as Object, PointXML as String, Errors as Object) As Integer

Parameters

Remarks

This method updates multiple point records using the XML string returned by the SetPointXMLAttribute method.

For the PointXML used in this method, do not include an entire point record since the method updates multiple point records. The update would fail as a result of trying to create multiple instances of an identical point record. The XML string should only contain the attributes that you want to be set the same on all the points that are to be updated. The attributes that are not included in the XML string will not be updated when the method is called.

Example

The following example updates an array of points with given XML and displays the list of errors encountered in a list box.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
Sub UpdateAttributes()
    Dim Tags(1)
    Dim Errors(1)
    Dim error
 
    Tags(0) = "CYGDEMO.UIS.00000239"
    Tags(1) = "CYGDEMO.UIS.00000240"
 
    PntClient.UpdateAttributesForPoints Tags, XML, errors
 
    For Each error In Errors
        lboErrors.AddString(errors)
    Next
End Sub

UpdatePointRecord

The UpdatePointRecord method updates a single point record from an XML string.

Syntax

UpdatePointRecord(PointTag as String, PointXML as String)

Parameters

Remarks

This method updates a single point record using the XML string returned by the SetPointXMLAttribute method.

PointTag must be SITE.SERVICE.POINTID, SITE.SERVICE:POINTIDLONG, or SITE.SERVICE::FACILITY.UDC

PointXM does not need to contain an entire point record. If an attribute is left out, it will not be updated when this method is called.

Example

The following example updates a point record with the modified XML stored in edtXML.

1
2
3
4
Sub UpdatePntRecord()
    PntClient.UpdatePointRecord Tag, edtXML.Text
    MsgBox "Point Updated"
End Sub

ValidateEnhancedAlarmConfigXml

The ValidateEnhancedAlarmConfigXml method checks that the provided enhanced alarm configuration XML is valid in the context of the provided PointTag.

Also see Enhanced Alarm Configuration for more information.

Syntax

ValidateEnhancedAlarmConfigXml(ByVal PointTag As String, ByVal ConfigXml As String, ByRef pvErrorList, ByRef pvWarningList) As Boolean

Parameters

Remarks

Returns True if the enhanced alarm configuration XML string provided is valid. Otherwise, False is returned and the error and warning string arrays are filled in accordingly. If the provided PointTag is invalid or the specified point does not exist, the function returns False and the details are stored in the list of errors. Connect() must be called prior to calling this function. There are no CygNet security checks performed when calling this function.

Example

The following example reads one point’s enhanced alarm configuration XML and validates it in the context of another point. If a script error is generated, the reason for the error is displayed. If errors or warnings are returned in the array variables, they are displayed one by one.

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
26
27
28
29
30
31
32
33
34
35
36
37
38
Dim cxPnt
Set cxPnt = createobject("CxPnt.PntClient")
 
Dim iRet
iRet = cxPnt.Connect("CYGNET.PNT")
If iRet <> 0 Then
    MsgBox "Connect failed with " & iRet
Else
    On Error Resume Next
    Dim strXml
    strXml = cxPnt.ReadEnhancedAlarmConfig("CYGNET.UIS:FAC01_UDC01")
 
    If err.number <> 0 Then
        MsgBox "ReadEnhancedAlarmConfig failed: " & err.description
    Else
        Dim bIsValid
        Dim errorsOut
        Dim warningsOut

        bIsValid = cxPnt.ValidateEnhancedAlarmConfigXml("CYGNET.UIS:FAC02_TBOARD", strXml, errorsOut, warningsOut)
            MsgBox "Validate() returned " & bIsValid & ": err(" & ubound(errorsOut)+1 & "), wrn(" & ubound(warningsOut)+1 & ")"
        iErrCnt = 1
        Dim strError
        For Each strError In errorsOut
            MsgBox "Error " & iErrCnt & "of " & ubound(errorsOut)+1 & ": " & strError
            iErrCnt = iErrCnt + 1
        Next
 
        iWarnCnt = 1
        Dim strWarn
        For Each strWarn In warningsOut
            MsgBox "Warning " & iWarnCnt & "of " & ubound(warningsOut)+1 & ": " & strWarn
            iWarnCnt = iWarnCnt + 1
        Next
    End If
    On Error Goto 0
 
End If