Facilities Methods

Scripting > CxScript > Facilities Object > Facilities Methods

Facilities Methods

The Facilities object contains the following methods:

AddFacilitiesArray
AddFacility
AddFacilityTagListHint
ChooseFacilities
EnableUpdate
FilterFacilityTagList
GetFacilityAttribute
GetFacilityAttributeName
GetFacilityTagList
ResolveNow
UpdateNow

AddFacilitiesArray

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

Syntax

AddFacilitiesArray(ArrTag As Variant)

Parameters

Parameter	Required	Description
ArrTag	Yes	An array of facility tags to add. They must be in 'Site.Service::FacilityName’ format.

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.

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

Parameter	Required	Description
FacilityTag	Yes	The tag string of the facility to add (in valid CygNet tag string format).

Remarks

Example

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

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

Parameter	Required	Description
FacOrCvsSiteService	Yes	The FAC or CVS site service from which to get the facility tags, in "site.service" format.
Filter	Yes	The filter criteria. Three types of filter types are allowed. An example of each type of filter is shown below. Parameterized list — A semicolon-delimited naming filter to select certain facilities, using any of the keywords from the Facility Attributes list. To retrieve all facility tags, set the Filter parameter to "" FAC rules XML — An XML string representing the facility filter to be used. For a complete list of FAC XML property names, see FAC XML Attributes FAC expression — An arithmetic expression representing the facility filter to be used

Parameter

Required

Description

FacOrCvsSiteService

Yes

The FAC or CVS site service from which to get the facility tags, in "site.service" format.

Filter

Yes

The filter criteria. Three types of filter types are allowed. An example of each type of filter is shown below.

Parameterized list — A semicolon-delimited naming filter to select certain facilities, using any of the keywords from the Facility Attributes list. To retrieve all facility tags, set the Filter parameter to ""
FAC rules XML — An XML string representing the facility filter to be used. For a complete list of FAC XML property names, see FAC XML Attributes
FAC expression — An arithmetic expression representing the facility filter to be used

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

Parameter	Required	Description
Title	Yes	The title of the Facility Choose dialog box.
SiteService	Yes	The site and service to connect to, in "site.service" form. If an empty string is passed, a dialog box will display when the Facility Chooser dialog box does, to select a FAC service.
FilterSiteService	Yes	A valid site and service, in "site.service" form. Only facilities connected to this site and service will be displayed. If an empty string is passed, all facilities will show.
SelectedFacilities	Yes	The facility tags of any facilities to be selected by default when the dialog box is opened, in "site.service::facilityid" form. If an empty string is passed, no facilities will be selected.
FullFilter	Yes	A semicolon-delimited naming filter to select certain facilities. The filter can include any of the keywords from the Facility Attributes list.
EnableServiceFilter	Yes	Set to True to enable the user to choose which FAC service to view.
EnableServiceChooser	Yes	Set to True to enable the user to choose which Site.Service to view.
MultipleSelect	Yes	Set to True to enable the user to select more than one facility. This enables/disables the Select All, Deselect All, and Invert buttons.
EnableFacEditor	Yes	Set to True to enable the user to edit facilities in the list. This enables/disables the Add Facility and Edit Facility buttons.
DestinationTagList	Yes	Output. All of the selected facilities are stored in this array.

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.

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)

End Sub

EnableUpdate

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

Syntax

EnableUpdate(Enable As Boolean)

Parameters

Parameter	Required	Description
Enable	Yes	Enables updates if True and disables updates if False.

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

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

Parameter	Required	Description
SourceTagList	Yes	An array of facility tags to be filtered.
Filter	Yes	The filter criteria. Three types of filter types are allowed. An example of each type of filter is shown below. Parameterized list — A semicolon-delimited naming filter to select certain facilities, using any of the keywords from the Facility Attributes list. To retrieve all facility tags, set the Filter parameter to "" FAC rules XML — An XML string representing the facility filter to be used. For a complete list of FAC XML property names, see FAC XML Attributes FAC expression — An arithmetic expression representing the facility filter to be used
DestinationTagList	Yes	Output. The filtered list will be stored in this variable.

Parameter

Required

Description

SourceTagList

Yes

An array of facility tags to be filtered.

Filter

Yes

The filter criteria. Three types of filter types are allowed. An example of each type of filter is shown below.

Parameterized list — A semicolon-delimited naming filter to select certain facilities, using any of the keywords from the Facility Attributes list. To retrieve all facility tags, set the Filter parameter to ""
FAC rules XML — An XML string representing the facility filter to be used. For a complete list of FAC XML property names, see FAC XML Attributes
FAC expression — An arithmetic expression representing the facility filter to be used

DestinationTagList

Yes

Output. The filtered list will be stored in this variable.

Example

See the filter examples in GetFacilityTagList.

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

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)

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

Parameter	Required	Description
FacilityTag	Yes	The tag string of the facility, in valid CygNet tag string format.
FacilityAttribute	Yes	The name of the attribute. The attribute(s) can include any of the keywords from the Facility Attributes list.

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.

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)))

End Sub

GetFacilityAttributeName

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

Syntax

GetFacilityAttributeName(Index As Long)

Parameters

Parameter	Required	Description
Index	Yes	The facility attribute index.

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.

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)

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

Parameter	Required	Description
FacOrCvsSiteService	Yes	The FAC or CVS site service from which to get the facility tags, in "site.service" format.
Filter	Yes	The filter criteria. Three types of filter types are allowed. An example of each type of filter is shown below. Parameterized list — A semicolon-delimited naming filter to select certain facilities, using any of the keywords from the Facility Attributes list. To retrieve all facility tags, set the Filter parameter to "" FAC rules XML — An XML string representing the facility filter to be used. For a complete list of FAC XML property names, see FAC XML Attributes FAC expression — An arithmetic expression representing the facility filter to be used
TagList	Yes	An array of tags returned.

Parameter

Required

Description

FacOrCvsSiteService

Yes

The FAC or CVS site service from which to get the facility tags, in "site.service" format.

Filter

Yes

The filter criteria. Three types of filter types are allowed. An example of each type of filter is shown below.

Parameterized list — A semicolon-delimited naming filter to select certain facilities, using any of the keywords from the Facility Attributes list. To retrieve all facility tags, set the Filter parameter to ""
FAC rules XML — An XML string representing the facility filter to be used. For a complete list of FAC XML property names, see FAC XML Attributes
FAC expression — An arithmetic expression representing the facility filter to be used

TagList

Yes

An array of tags returned.

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

"facility_desc=Station 1;facility_type=Meter Station"

FAC Rules XML Filter

"<ExportedRules exportTime="26/06/2014 13:38:59.267" ruleDataIdentifier="FAC Rules">

</Rule>

</Rule>

</Rules>

</ExportedRules>"

See SetFacilityFilter and ShowFacilityRulesDialog for other FAC Rules XML examples.

FAC Expression Filter

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

Code Example

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

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))

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.