FacClient Methods

The FacClient 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.

AddFacilityRecord

The AddFacilityRecord method adds a new facility from an XML record.

Syntax

AddFacilityRecord(RecordXML as String)

Parameters

Remarks

The XML used to create the facility should be in the same format as the XML returned from ReadFacilityRecord, as in the following example.

1
<CygNetFacilityRecord lock_user="VSI\" lock_time="-1214347123" facility_attr0="" facility_attr1="" facility_category="REMDEV" facility_desc="CYGDEMO_RTU" facility_id="Cyg_RTU" facility_info0="" facility_info1="" facility_is_active="Y" facility_is_ref_any="Y" ... />

Example

The following example creates a new facility using an XML record stored in edtXML.

1
2
3
4
Sub AddRecord()
    FacClient.AddFacilityRecord edtXML.Text
    MsgBox "Facility Added"
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
Sub FacConnect()
    'Connect to a FAC
    Dim FacClient
    Set FacClient = CreateObject("CxFac.FacClient")
    FacClient.Connect("[5410]CYGDEMO.FAC")
End Sub

DeleteFacilityRecord

The DeleteFacilityRecord method deletes a facility.

Syntax

DeleteFacilityRecord(FacTag as String) As Boolean

Parameters

Example

The following example deletes a facility and notifies the user if an error occurs.

1
2
3
4
5
6
7
8
9
10
11
Sub DeleteFacRecord()
    Dim Success
 
    Success = FacClient.DeleteFacilityRecord ("CYGDEMO.UIS::CYG_METER")
 
    If Success = True Then
        MsgBox "Facility deleted"
    Else
        MsgBox "Error in deleting"
    End IF
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

FacilityExists

The FacilityExists methods check to see if the named facility tag exists.

Syntax

FacilityExists(ByVal FacTag As String) As Boolean

Parameters

Remarks

This methods returns true if the specified facility exists.

FinishBulkUpdates

The FinishBulkUpdates method disables bulk updating.

Syntax

FinishBulkUpdates()

Remarks

This method disables bulk updating and makes the FAC flush changes to the disk after every point is updated.

Example

The following example stops bulk updating and restores normal updating.

1
2
3
4
Sub StopBulkUpdates()
    FacClient.FinishBulkUpdates
    MsgBox "Bulk Updating disabled"
End Sub

GetActiveServices

The GetActiveServices method returns a list of active FAC services.

Syntax

GetActiveServices(ServiceList as Array)

Parameters

Example

The following example retrieves a list of active FAC services and stores them in a list box.

1
2
3
4
5
6
7
8
9
10
Sub GetActiveServices()
    Dim activeServices
    Dim fac
 
    FacClient.GetActiveServices activeServices
 
    For Each fac In activeServices
    lboFac.AddString(fac)
    Next
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

GetCvsOnlyFacilities

The GetCvsOnlyFacilities method returns a list of current value service facilities.

Syntax

GetCvsOnlyFacilites(SiteService as String, FacilityList as Array)

Parameters

Remarks

The returned list will not include facilities associated with the DDS, such as remote device or communication device facilities.

Example

The following example retrieves all facilities associated with CYGDEMO.UIS and displays them in a list box.

1
2
3
4
5
6
7
8
9
10
Sub GetCvsFacs()
    Dim CvsList
    Dim fac
 
    FacClient.GetCvsOnlyFacilities "CYGDEMO.UIS", CvsList
 
    For Each fac In CvsList
    lboFac.AddString(fac)
    Next
End Sub

GetCvsServiceList

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

Syntax

GetCvsServiceList(ServiceList as Array)

Parameters

Remarks

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

Example

The following example gets all the current value services that the facilities are associated with and stores them in a list box.

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

GetDeviceCatSpecificFacilities

The GetDeviceCatSpecificFacilities method returns the list of facilities with a specified device category type.

Syntax

GetDeviceCatSpecificFacilities(SiteService as String, DeviceCategory as String, FacilityList as Array)

Parameters

Example

The following example retrieves all facilities with a device category of RD, and displays them in a list box.

1
2
3
4
5
6
7
8
9
10
Sub GetDeviceCatFacs()
    Dim FacList
    Dim fac
 
    FacClient.GetDeviceCatSpecificFacilities "CYGDEMO.UIS", "RD", FacList
 
    For Each fac In FacList
    lboFac.AddString(fac)
    Next
End Sub

GetEmptyRecordXml

The GetEmptyRecordXml method returns an empty facility record XML.

Syntax

GetEmptyRecordXml() As String

Remarks

This method can be used in the process of creating a new facility. After the empty record XML is retrieved, use the SetRecordXMLAttribute method to set the new facilty record attribute values. Then use the AddFacilityRecord method to add the new facility from the XML string created by the SetRecordXMLAttribute method.

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

1
<CygNetFacilityRecord />

Example

The following example gets the XML for an empty facility and saves it to an XML document.

1
2
3
4
5
6
7
8
9
10
Sub GetEmptyRecord()
    'Get facility xml
    Dim strInfo
    strInfo = FacClient.GetEmptyRecordXml
 
    'Save XML
    Set xmlDoc = CreateObject("Msxml2.DOMDocument")
    xmlDoc.loadXML(strInfo)
    xmlDoc.save("C:\EmptyFacility.xml")
End Sub

GetFacilitiesByFacilityType

The GetFacilitiesByFacilityType method returns the list of facilities of a specified facility type.

Syntax

GetFacilitiesByFacilityType(FacilityType as String, SiteService as String, FacilityList as Array)

Parameters

Example

The following example retrieves all facilities with a facility type of "REMDEV" and displays them in a list box.

1
2
3
4
5
6
7
8
9
10
Sub GetByFacilityType()
    Dim FacList
    Dim fac
 
    FacClient.GetFacilitiesByFacilityType "REMDEV", "CYGDEMO.UIS", FacList
 
    For Each fac In FacList
    lboFac.AddString(fac)
    Next
End Sub

GetFacilitiesList

The GetFacilitiesList method returns the list of the facilities associated with a given Site.Service.

Syntax

GetFacilitiesList(SiteService as String, FacilityList as Array)

Parameters

Remarks

The returned list of facilities will be stored and sorted in alphabetical order by facility tag.

Example

The following example retrieves all facilities associated with CYGDEMO.UIS and displays them in a list box.

1
2
3
4
5
6
7
8
9
10
Sub GetFacilitiesList()
    Dim FacList
    Dim facility
 
    FacClient.GetFacilitiesList "CYGDEMO.UIS", FacList
 
    For Each facility In FacList
    lboFac.AddString(fac)
    Next
End Sub

GetFacilityAttributeList

The GetFacilityAttributeList method returns the list of attribute names that can be stored in a facility.

Syntax

GetFacilityAttributeList(FacilityList as Array)

Parameters

Example

The following example retrieves a list of attribute names and displays them in a list box.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
Sub GetFacAttributes()
 
    Dim arrFacAttrs
    FacClient.GetFacilityAttributeList  arrFacAttrs
 
    Dim strFacAttr
 
    Dim iStep
    For iStep = 0 To UBound(arrFacAttrs)
        strFacAttr = arrFacAttrs(iStep, 0) & ", " & 'attribute number
            arrFacAttrs(iStep, 1) & ", " & 'attribute short name
            arrFacAttrs(iStep, 2) & ", " & 'attribute description
            arrFacAttrs(iStep, 3) & ", " & 'attribute category
            arrFacAttrs(iStep, 4) 'attribute in use (True/False)
        lboFac.AddString(strFacAttr)
    Next
 
End Sub

GetFacilityTagList

The GetFacilityTagList retrieves a list of facility tags. The criteria can use the simplified 'key1=value1;key2=value2' form or the XML rules form.

Syntax

GetFacilityTagList(ByVal bstrFilter As String, ByRef pvFacilityTagList)

Parameters

Remarks

Returns a list of facility tags for the specified criteria.

GetFacilityTypeList

The GetFacilityTypeList method returns the list of facility types for the given FAC service.

Syntax

GetFacilityTypeList(SiteService as String, FacilityTypeList As Variant)

Parameters

Example

The following example displays the list of all facility types.

1
2
3
4
5
6
7
8
9
10
11
Sub
    Dim aryFacTypes
    FacClient.GetFacilityTypeList "", aryFacTypes
 
    Dim i, strMsg
    For i = 0 To UBound(aryFacTypes)
    strMsg = strMsg + aryFacTypes(i) + vbCr
    Next
 
    MsgBox strMsg
End Sub

GetRecordXMLAttribute

The GetRecordXMLAttribute method returns the value of an attribute from a facility record.

Syntax

GetRecordXMLAttribute(RecordXML as String, RecordAttribute as String) As String

Parameters

Example

The following example gets the value for the attribute facility_id and displays it in a message box.

1
2
3
Sub GetRecordAttribute()
    edtMessageBox.Test = FacClient.GetRecordXMLAttribute(edtXML.Text, "facility_id")
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

ReadFacilityRecord

The ReadFacilityRecord method returns the XML record for a facility.

Syntax

ReadFacilityRecord(FacTag as String) As String

Parameters

Remarks

The record will be returned in XML format. The following is an example of an excerpt of the returned XML.

1
<CygNetFacilityRecord lock_user="VSI\" lock_time="-1214347123" facility_attr0="" facility_attr1="" facility_category="REMDEV" facility_desc="CYGDEMO_RTU" facility_id="Cyg_RTU" facility_info0="" facility_info1="" facility_is_active="Y" facility_is_ref_any="Y" ... />

Example

The following example retrieves a facility record and saves it to an XML file.

1
2
3
4
5
6
7
8
9
10
Sub ReadFacRecord()
    'Get facility xml
    Dim Record
    Record = FacClient.ReadFacilityRecord("CYGDEMO.UIS::Cyg_RTU")
 
    'Save XML
    Set xmlDoc = CreateObject("Msxml2.DOMDocument")
    xmlDoc.loadXML(Record)
    xmlDoc.save("C:\FacilityRecord.xml")
End Sub

ReadFacilityRecordForUpdate

The ReadFacilityRecordForUpdate method returns a facility record and locks the facility for updates.

Syntax

ReadFacilityRecordForUpdate(FacTag as String) As String

Parameters

Remarks

The ReadFacilityRecordForUpdate method returns a record for the given facility and locks the record for update. When the record is locked for update, other users are prevented from editing it until the lock is released or times out. Follow this method by a call to UpdateFacilityRecord or ReleaseFacilityRecordLock.

Example

The following example displays a facility record in edtXML and locks the facility for updates.

1
2
3
4
Sub ReadFacRecordForUpdate()
    edtXML.Text = FacClient.ReadFacilityRecordForUpdate(Tag)
    MsgBox "Facility locked"
End Sub

ReadFacilityRecords

The ReadFacilityRecords method returns an XML string containing records for each of the given facility tags.

Syntax

ReadFacilityRecords(ArrFacTags as Variant) As String

Parameters

Remarks

The records will be returned in XML format. The following is an example of an excerpt of the returned XML.

1
2
3
4
<CygNetFacilityRecords>
    <CygNetFacilityRecord lock_user="FAC" lock_time="-1298593501" facility_attr0="" facility_attr1="" facility_attr10="" facility_attr11="" facility_attr12="" facility_attr13="" facility_attr14="" facility_attr15="" facility_attr16="" facility_attr17="" .../>
    ...
</CygNetFacilityRecords>

Example

The following example writes facility records to an XML file.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Sub
    Dim aryFacTags
    ReDim aryFacTags(2)
 
    aryFacTags(0) = "CYGDEMO.UIS::20230303"
    aryFacTags(1) = "CYGDEMO.UIS::FLOWAUTOAP15"
    aryFacTags(2) = "CYGDEMO.UIS::FLOWAUTOAP15A"
 
    Dim strXml
    strXml = FacClient.ReadFacilityRecords(aryFacTags)
 
    'Save XML
    Dim xmlDoc
    Set xmlDoc = CreateObject("Msxml2.DOMDocument")
    xmlDoc.loadXML(strXml)
    xmlDoc.save("C:\FacilityRecords.xml")
End Sub

ReleaseFacilityRecordLock

The ReleaseFacilityRecordLock method unlocks a facility record to allow editing.

Syntax

ReleaseFacilityRecordLock(FacTag as String, RecordXML as String)

Parameters

Remarks

This method releases the lock on the facility record created by the ReadFacilityRecordForUpdate method. Once the lock on the record is released, it can then be edited by other users.

Example

The following example unlocks the CYGDEMO_RTU facility record.

1
2
3
4
Sub ReleaseFacLock()
    FacClient.ReleaseFacilityRecordLock Tag, XML
    MsgBox "Facility unlocked"
End Sub

SetRecordXMLAttribute

The SetRecordXMLAttribute method sets an attribute value of a specified facility record.

Syntax

SetRecordXMLAttribute(RecordXML as String, RecordAttribute as String, AttributeValue as String) As String

Parameters

Remarks

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

SetRecordXmlAttribute sets the attribute name to lowercase before modifying the XML.

Example

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

1
2
3
4
5
6
Sub SetRecordAtt()
    Dim newPoint
 
    newPoint = FacClient.SetRecordXMLAttribute (XML, "facility_category" "REMDEV")
    edtMessageBox.Text = newPoint
End Sub

StartBulkUpdates

The StartBulkUpdates method enables faster updating.

Syntax

StartBulkUpdates()

Remarks

Normally, the FAC service will flush the changes to the disk after each facility 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, using FinishBulkUpdates.

Example

The following example enables Bulk Updating.

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

UpdateAttributesForFacilities

The UpdateAttributesForFacilities method updates multiple facility records with new attribute values from an XML string.

Syntax

UpdateAttributeForFacilities(FacTags as Array, RecordXML as String, errors as Array) As Integer

Parameters

Remarks

This method updates multiple facility records using the XML string returned by the SetRecordXMLAttribute method.

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

For example, if the following is stored in RecordXML, only Facility Attribute 0 will be updated:

1
<CygNetFacilityRecord facility_attr0="Bill" />

Example

The following example updates an array of facilities with the attributes from edtXML, and outputs a list of errors in lboerrors.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Sub UpdateAttributes()
    Dim Tags(1)
    Dim errors(1)
    Dim err
 
    Tags(0) = "CYGDEMO.UIS::CYG_RTU"
    Tags(1) = "CYGDEMO.UIS::CYG_METER"
 
    FacClient.UpdateAttributesForFacilities Tags, edtXML.Text, errors
 
    For Each err In errors
        lboerrors.AddString(err)
    Next
    MsgBox "Facilities updated"
End Sub

UpdateFacilityRecord

The UpdateFacilityRecord method updates a single facility record from an XML string.

Syntax

UpdateFacilityRecord(FacTag as String, RecordXML as String)

Parameters

Remarks

This method updates a single facility record using the XML string returned by the SetRecordXMLAttribute method.

RecordXML does not need to contain an entire facility record. If an attribute is left out, it will not be updated when this method is called. For example, if the following is stored in RecordXML, only Facility Attribute 0 will be updated:

1
<CygNetFacilityRecord facility_attr0="Bill" />

Example

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

1
2
3
4
Sub UpdateFacRecord()
    FacClient.UpdateFacilityRecord Tag, edtXML.Text
    MsgBox "Facility Updated"
End Sub