Facilities Methods

The Facilities object contains the following methods:

AddFacilitiesArray

The AddFacilitiesArray method adds the facilities in given array to the cache.

Syntax

AddFacilitiesArray(ArrTag As Variant)

Parameters

Remarks

This method is typically used in a HyperPoint’s OnInitializeEx event, and rarely applies to contexts other than the HSS. When a facility is added to the Facilities object, its attributes are cached, enabling use of the GetFacilityAttribute method.

Example

The following example assigns two facilities to the Facilities object to cache.

1
2
3
4
5
6
7
8
Sub addArray()
    Dim arrNames, objFacility
    Set objFacility = CreateObject("CxScript.Facilities")
     
    arrNames = Array("CYGDEMO.UIS::BILL305", "CYGDEMO.UIS::LUMBERGH123")
    objFacility.AddFacilitiesArray arrNames
    edtMessageBox.Text = "Facility array added"
End Sub

AddFacility

The AddFacility method adds a facility specified by the tag into the cache.

Syntax

AddFacility(FacilityTag As String)

Parameters

Remarks

This method is typically used in a HyperPoint’s OnInitializeEx event, and rarely applies to contexts other than the HSS. When a facility is added to the Facilities object, its attributes are cached, enabling use of the GetFacilityAttribute method.

Example

This example uses the STATUS HyperPoint’s OnInitializeEx event to assign two facilities to the Facilities object to cache.

1
2
3
4
5
Sub STATUS_OnInitializeEx(This) 
    'Add JONES45, METER206, facility tags to the Facilities object
    Facilities.AddFacility "CYGDEMO.UIS::JONES45"
    Facilities.AddFacility "CYGDEMO.UIS::METER206"
End Sub

AddFacilityTagListHint

The AddFacilityTagListHint method tells the Facilities object that you will request the given filter with GetFacilityTagList. When you call GetFacilityTagList, the Facilities object checks to see if it can resolve the queries requested with AddFacilityTagListHint optimally. If it can, it resolves all those other queries at the same time. This makes subsequent calls to GetFacilityTagList much faster since the query results are already cached. For a large number of queries, this can vastly improve performance. Filter types can be any one of the following:

• Parameterized list of FAC attributes
• FAC rules XML
• FAC expression

Syntax

AddFacilityTagListHint(FacOrCvsSiteService As String, Filter As String)

Parameters

Example

See the filter examples in GetFacilityTagList.

ChooseFacilities

The ChooseFilter method displays a Facility Chooser dialog box and returns the selected facilities in an array.

Syntax

ChooseFacilities(Title As String, SiteService As String, FilterSiteService As String, SelectedFacilities As String, FullFilter As String, EnableServiceFilter As Boolean, EnableServiceChooser As Boolean, MultipleSelect As Boolean, EnableFacEditor As Boolean, DestinationTagList As Variant)

Parameters

Example

The following example invokes a Facility Chooser dialog box. It is connected to CYGDEMO.UIS, displays only facilities with a type of meter, and the facility BOBFAC is selected. After the user selects their facilities, they are displayed in a list box.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
Sub chooseFac()
    Dim objFacilities
    Set objFacilities = CreateObject("CxScript.Facilities")
     
    Dim arrFacList, item
     
    'Select facilities
    objFacilities.ChooseFacilities "Choose facilities", "CYGDEMO.UIS", "CYGDEMO.UIS", "CYGDEMO.UIS::BOBFAC", "facility_type=meter", True, True, True, True, arrFacList
        
    'Display selected facilities in list box
    For Each item In arrFacList
        lstFacilities.AddString(item)
    Next
End Sub

EnableUpdate

The EnableUpdate method enables or disables auto refreshing of the Facilities object.

Syntax

EnableUpdate(Enable As Boolean)

Parameters

Remarks

By default, the Facilities object is updated when cached facility attributes are changed. If updating is disabled, auto refresh of the Facilities object is prevented. This value is true by default in the HSS. Changing the EnableUpdate property in one HyperPoint script will change it for all scripts (it is a global property). The method is not generally used except in more complex situations.

Example

The following example disables updating.

1
2
3
4
5
6
7
Sub chooseFac()
    Dim objFacilities
    Set objFacilities = CreateObject("CxScript.Facilities")
     
    objFacilities.EnableUpdate(False)
    edtMessageBox.Text = "Updating disabled"
End Sub

FilterFacilityTagList

The FilterFacilityTagList method filters a source list based on filter criteria and fills a destination list. Filter types can be any one of the following:

• Parameterized list of FAC attributes
• FAC rules XML
• FAC expression

Syntax

FilterFacilityTagList(SourceTagList As Variant, Filter As String, DestinationTagList As Variant)

Parameters

Example

See the filter examples in GetFacilityTagList.

The following example returns a list of all facilities on a UIS.

1
2
3
4
5
6
7
8
9
10
11
12
Sub filterFacTag(arrTagList)
    Dim objFacs
    Set objFacs = CreateObject("CxScript.Facilities")
     
    Dim arrNewTags, item
    objFacs.FilterFacilityTagList arrTagList, "FACILITY_SERVICE=UIS", arrNewTags
     
    lstFacilities.ResetContent
    For Each item In arrNewTags
        lstFacilities.AddString(item)
    Next
End Sub

GetFacilityAttribute

The GetFacilityAttribute method gets the value of an attribute for a specified facility tag.

Syntax

GetFacilityAttribute(FacilityTag As String, FacilityAttribute As String)

Parameters

Remarks

In the HSS, a facility tag must first be added to the Facilities object using the AddFacility or AddFacilityArray methods before GetFacilityAttribute can retrieve cached attribute values. When using the Facilities object outside the HSS, attribute value can be retrieved without first adding facilities to the Facilities object.

Example

The following method lists several properties for a given facility in a list box. Any or all of the properties can be added to the arrAttrs array.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Sub ListFacilityAttributes (facName)
    Dim objFacs, arrAttrs, i
    Set objFacs = CreateObject("CxScript.Facilities")
    lstAttributes.ResetContent
     
    'Create array of attributes to display
    Redim arrAttrs(2)
    arrAttrs(0) = "FACILITY_ID"
    arrAttrs(1) = "FACILITY_DESC"
    arrAttrs(2) = "FACILITY_TYPE"
     
    'List attributes in list box
    For i=lbound(arrAttrs) To ubound(arrAttrs)
        lstAttributes.AddString (arrAttrs(i) & ": " & objFacs.GetFacilityAttribute(facName, arrAttrs(i)))
    Next
End Sub

GetFacilityAttributeName

The GetFacilityAttributeName method returns a facility attribute name given an index.

Syntax

GetFacilityAttributeName(Index As Long)

Parameters

Remarks

Facility attribute indexes range from 0 to 57. The returned value is the name of the index. This method is useful for listing names of attributes with their corresponding indexes.

Example

The following function lists the names of the first 25 facility attributes in a list box.

1
2
3
4
5
6
7
8
9
10
Sub ListAttributes ()
    Dim objFacs, i
    Set objFacs = CreateObject("CxScript.Facilities")
    lstAttributes.ResetContent
     
    'List attributes in list box
    For i=0 To 24
        lstAttributes.AddString objFacs.GetFacilityAttributeName(i)
    Next
End Sub

GetFacilityTagList

The GetFacilityTagList method gets an array of facility tags in a service based on specified filter criteria. Filter types can be any one of the following:

• Parameterized list of FAC attributes
• FAC rules XML
• FAC expression

Use in conjunction with AddFacilityTagListHint for performance optimization.

Syntax

GetFacilityTagList(FacOrCvsSiteService As String, Filter As String, TagList As Variant)

Parameters

Remarks

See CxScript.GlobalFunctions.GetFacilityInfo to return list of FACs using a set of descriptors.

Examples

The first three examples show the types of filters that can be used with GetFacilityTagList.

Parameterized List Filter

1
"facility_desc=Station 1;facility_type=Meter Station"

FAC Rules XML Filter

1
2
3
4
5
6
7
8
"<ExportedRules exportTime="26/06/2023 13:38:59.267" ruleDataIdentifier="FAC Rules">
    <Rules enabled="true" inverted="false" op="1" name="">
        <Rule enabled="true" name="FACDESC" referenceAttr="0" compareToType="0" externalData="" value="Station 1" operator="=" qualifer="Case Sensitive"><compareItem attr="facility_desc"/>
        </Rule>
        <Rule enabled="true" name="FACTYPE" referenceAttr="0" compareToType="0" externalData="" value="Meter Station" operator="=" qualifer="Case Sensitive"><compareItem attr="facility_type"/>
        </Rule>
    </Rules>
</ExportedRules>"

See SetFacilityFilter and ShowFacilityRulesDialog for other FAC Rules XML examples.

FAC Expression Filter

1
"facility_desc = 'Station 1' AND facility_type = 'Meter Station'"

Code Example

The following function lists all facilities of type "DEVICE" on the "UIS" service.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
Sub ListUISDevices ()
    Dim objFacs, arrTagList, strFilter, i
    Set objFacs = CreateObject("CxScript.Facilities")
    lstFacilities.ResetContent
     
    'Get tag list
    strFilter = "FACILITY_TYPE=DEVICE;FACILITY_SERVICE=UIS"
    objFacs.GetFacilityTagList "CYGDEMO.FAC", strFilter, arrTagList
     
    'List attributes in list box
    For i=lbound(arrTagList) To ubound(arrTagList)
        lstFacilities.AddString(arrTagList(i))
    Next
End Sub

ResolveNow

The ResolveNow method immediately gets data for all unresolved facilities in the cache.

Syntax

ResolveNow()

Remarks

Whereas the UpdateNow method updates all facilities in a Facilities 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 facilities before you need to retrieve their data.

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

UpdateNow

The UpdateNow method immediately updates all data for all facilities in the cache.

Syntax

UpdateNow()

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 Facilities objects, so updating can be achieved using the UpdateNow or ResolveNow methods rather than enabling updates.