FmsClient Methods
The FmsClient object contains the following methods.
Note: Some of the examples in this topic use the WScript.Sleep statement, which is not available for use when scripting in CygNet Studio. If you are scripting in CygNet Studio, use TheView EventTimer instead.
Connect
The Connect method connects the object to a service.
Syntax
Connect(DomainSiteService As String)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DomainSiteService |
Yes |
The [Domain]Site.Service to which to connect. The domain is optional. The service must be a valid one. |
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:
Connect
Sub FmsConnect()
'Connect to an FMS
Dim FmsClient
Set FmsClient = CreateObject("CxFms.FmsClient")
FmsClient.Connect("[5410]CYGDEMO.FMS")
End Sub
CreateDevice
Creates a new device in the connected FMS.
Syntax
CreateDevice(FmsDevice As FmsDevice, eDeviceType As Integer)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
FmsDevice |
CxFms.FmsDevice |
Yes |
An object containing all the properties of the new device |
|
eDeviceType |
Integer |
Yes |
The type of device Possible values are as follows:
|
Remarks
This method will fail if a device with the same name already exists in the connected FMS.
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example creates a device.
Sub
Err.Clear
On Error Resume Next
Dim FmsDevice
Set FmsDevice = CreateObject("CxFms.FmsDevice")
FmsDevice.BeginActiveDate = CDate("May 10, 2023")
FmsDevice.EndActiveDate = 0 'Indefinite end time
FmsDevice.DeviceInstallDate = CDate("May 10, 2023")
FmsDevice.Name = "New_Device"
FmsDevice.Description = "My new device"
FmsDevice.TimezoneKey = 64
FmsClient.CreateDevice FmsDevice, 1
If Err.Number <> 0 Then
MsgBox (Err.Number And &HFFFF&)
MsgBox Err.Description
Exit Sub
End If
On Error Goto 0
End Sub
CreateGeneralGroup
Creates a new general group in the connected FMS.
Syntax
CreateGeneralGroup(FmsGroup As FmsGeneralGroup)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
FmsGroup |
CxFms.FmsGeneralGroup |
Yes |
An object containing the properties of the new group |
Remarks
This method will fail if a group with the same name already exists in the connected FMS.
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example creates a general group containing a single Node.
Sub
Err.Clear
On Error Resume Next
Dim FmsGroup
Set FmsGroup = CreateObject("CxFms.FmsGeneralGroup")
FmsGroup.BeginActiveDate = CDate("May 10, 2023")
FmsGroup.EndActiveDate = 0 'Indefinite end time
FmsGroup.Name = "New_General_Group"
FmsGroup.Description = "My new general group"
FmsGroup.SetNode CDate("May 10, 2023"), 0, 5
FmsClient.CreateGeneralGroup(FmsGroup)
If Err.Number <> 0 Then
MsgBox (Err.Number And &HFFFF&)
MsgBox Err.Description
Exit Sub
End If
On Error Goto 0
End Sub
CreateStationGroup
Creates a new station group in the connected FMS.
Syntax
CreateStationGroup(FmsGroup As FmsStationGroup)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
FmsGroup |
CxFms.FmsStationGroup |
Yes |
An object containing the properties of the new group |
Remarks
This method will fail if a group with the same name already exists in the connected FMS.
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example creates a station group containing a single Node.
Sub
Err.Clear
On Error Resume Next
Dim FmsGroup
Set FmsGroup = CreateObject("CxFms.FmsStationGroup")
FmsGroup.BeginActiveDate = CDate("May 10, 2023")
FmsGroup.EndActiveDate = 0 'Indefinite end time
FmsGroup.Name = "New_Station_Group"
FmsGroup.Description = "My new station group"
FmsGroup.StationContribution = 0 'Receipt
FmsGroup.SetNode CDate("May 10, 2023"), 0, 5, 1, 2, False, 40.5, 0
FmsClient.CreateStationGroup(FmsGroup)
If Err.Number <> 0 Then
MsgBox (Err.Number And &HFFFF&)
MsgBox Err.Description
Exit Sub
End If
On Error Goto 0
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:
Sub Svc.Disconnect()
<SvcClient>.Disconnect()
MsgBox "Service has disconnected."
If <SvcClient>.Disconnect <> 0
Then
MsgBox "Failed to disconnect."
End If
End Sub
GetActiveServices
Returns the list of active FMS services on the current domain.
Syntax
GetActiveServices(ServiceList As Variant)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
ServiceList |
Variant |
Yes |
The list of active FMS services returned by this method |
Example
The following example retrieves the list of active FMS services and displays them in a message box.
Sub
Dim aryActiveServices
FmsClient.GetActiveServices aryActiveServices
Dim i, strMsg
If UBound(aryActiveServices) < 0 Then
MsgBox "No active services"
Else
For i = 0 To UBound(aryActiveServices)
strMsg = strMsg + aryActiveServices(i) + vbCr
Next
MsgBox strMsg
End If
End Sub
GetAllGroups
Returns a list of all group Nodes that are present in the connected FMS.
Syntax
GetAllGroups(SmartGroupInclusion As Integer, GroupList As Variant)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
SmartGroupInclusion |
Integer |
Yes |
The option to include/exclude smart groups in the results This parameter can be one of the following values:
|
|
GroupList |
Variant |
Yes |
The returned list of group Nodes |
Remarks
This method will fail if supplied parameters are out of range.
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example retrieves a list of all groups present in the FMS.
Sub
Err.Clear
On Error Resume Next
'Retrieve all groups, including smart groups
Dim FmsGroups
FmsClient.GetAllGroups 0, FmsGroups
If Err.Number <> 0 Then
MsgBox (Err.Number And &HFFFF&)
MsgBox Err.Description
Exit Sub
End If
On Error Goto 0
Dim Index
For index = 0 To UBound(FmsGroups)
MsgBox FmsGroups(index)
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
| Parameter | Required | Description |
|---|---|---|
|
pText |
Yes |
A two-dimensional 25x80 array of console text attributes returned by this method. |
|
pAttr |
Yes |
A two-dimensional 25x80 array of console display attributes returned by this method. |
Remarks
This method returns 0 if successful.
Example
The following example writes the console text and display attributes to a CSV file.
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
GetDevice
Returns an object containing all the properties of the specified device.
Syntax
GetDevice(DeviceName As String) As FmsDevice
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
DeviceName |
String |
Yes |
The name of the device to retrieve |
Remarks
Return Value: CxFms.FmsDevice object, containing all the properties of the specified device.
This method will fail if a device with the specified name does not exist in the FMS.
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example retrieves a device object and displays some of its properties.
Sub
Err.Clear
On Error Resume Next
Dim FmsDevice
Set FmsDevice = FmsClient.GetDevice("Emerson107")
If Err.Number <> 0 Then
MsgBox (Err.Number And &HFFFF&)
MsgBox Err.Description
Exit Sub
End If
On Error Goto 0
Dim strMsg
strMsg = "Device Name: " + FmsDevice.Name + vbCr
strMsg = strMsg + "Description: " + FmsDevice.Description + vbCr
strMsg = strMsg + "Node ID: " + CStr(FmsDevice.NodeId) + vbCr
strMsg = strMsg + "Begin Active Date: " + CStr(FmsDevice.BeginActiveDate) + vbCr
strMsg = strMsg + "End Active Date: " + CStr(FmsDevice.EndActiveDate) + vbCr
MsgBox strMsg
End Sub
GetFacTagsFromNodes
Retrieves a list of facility tags associated with the specified Nodes.
Syntax
GetFacTagsFromNodes (NodeNameOrList As Variant, FacTagList As Variant)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
NodeNameOrList |
String |
Yes |
A single Node name or a list of Node names for which to retrieve facility tags |
| FacTagList | String | Yes | The returned list of associated facility tags |
Remarks
This method will fail if a Node with the specified name does not exist in the connected FMS.
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example retrieves facility tags for three specified Nodes.
Sub
Err.Clear
On Error Resume Next
Dim aryNodeNames(2)
aryNodeNames(0) = "Node001"
aryNodeNames(1) = "Node002"
aryNodeNames(2) = "Node003"
Dim aryFacTags(0)
FmsClient.GetFacTagsFromNodes aryNodeNames, aryFacTags
If Err.Number <> 0 Then
MsgBox Err.Description
Else
Dim index
For index = 0 To UBound(aryFacTags)
MsgBox "The polling facility for Node" & aryNodeNames(index) & "is: " & aryFacTags(index)
Next
End If
On Error Goto 0
End Sub
GetGeneralGroup
Retrieves the specified general group from the connected FMS.
Syntax
GetGeneralGroup(GroupName As String) As FmsGeneralGroup
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
GroupName |
String |
Yes |
The name of the general group to retrieve |
Remarks
This method will fail if a group with the specified name does not exist in the connected FMS.
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example retrieves a general group and outputs some of its properties.
Sub
Err.Clear
On Error Resume Next
Dim FmsGeneralGroup
Set FmsGeneralGroup = FmsClient.GetGeneralGroup("GeneralGroup001")
If Err.Number <> 0 Then
MsgBox (Err.Number And &HFFFF&)
MsgBox Err.Description
Exit Sub
End If
On Error Goto 0
Dim strMsg
strMsg = "Group Name: " + FmsGeneralGroup.Name + vbCr
strMsg = strMsg + "Description: " + FmsGeneralGroup.Description + vbCr
strMsg = strMsg + "Node ID: " + CStr(FmsGeneralGroup.NodeId) + vbCr
strMsg = strMsg + "Begin Active Date: " + CStr(FmsGeneralGroup.BeginActiveDate) + vbCr
strMsg = strMsg + "End Active Date: " + CStr(FmsGeneralGroup.EndActiveDate) + vbCr
MsgBox strMsg
End Sub
GetGroupList
Returns a list of all group Nodes of the specified type that are present in the connected FMS.
Syntax
GetGroupList(GroupType As Integer, SmartGroupInclusion As Integer, GroupList As Variant)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
GroupType |
Integer |
Yes |
The group Node type to return This parameter can be one of the following values:
|
|
SmartGroupInclusion |
Integer |
Yes |
The option to include/exclude smart groups in the results This parameter can be one of the following values:
|
|
GroupList |
Variant |
Yes |
The returned list of group Nodes |
Remarks
This method will fail if supplied parameters are out of range.
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example retrieves a list of all groups present in the FMS.
Sub
Err.Clear
On Error Resume Next
'Retrieve general groups, excluding smart groups
Dim FmsGroups
FmsClient.GetGroupList 4, 1, FmsGroups
If Err.Number <> 0 Then
MsgBox (Err.Number And &HFFFF&)
MsgBox Err.Description
Exit Sub
End If
On Error Goto 0
For index = 0 To UBound(FmsGroups)
MsgBox FmsGroups(index)
Next
End Sub
GetNodeId
Retrieves the ID of the specified Node from the connected FMS.
Syntax
GetNodeId(NodeName As String) As Long
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
NodeName |
String |
Yes |
The name of the Node for which to retrieve an ID |
Remarks
This method will fail if a Node with the specified name does not exist in the connected FMS.
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example retrieves and outputs the ID of a Node.
Sub
Err.Clear
On Error Resume Next
MsgBox "Node Id:"&CStr(FmsClient.GetNodeId(Meter001"))
If Err.Number <> 0 Then
MsgBox (Err.Number And &HFFFF&)
MsgBox Err.Description
Exit Sub
End If
On Error Goto 0
End Sub
GetNodeName
Retrieves the name of the specified Node from the connected FMS.
Syntax
GetNodeName(NodeId As Long) As String
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
NodeId |
Long |
Yes |
The ID of the Node for which to retrieve a name |
Remarks
This method will fail if a Node with the specified ID does not exist in the connected FMS.
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example retrieves and outputs the name of a Node.
Sub
Err.Clear
On Error Resume Next
MsgBox "Node Name:"&FmsClient.GetNodeName(1)
If Err.Number <> 0 Then
MsgBox (Err.Number And &HFFFF&)
MsgBox Err.Description
Exit Sub
End If
On Error Goto 0
End Sub
GetNodesFromFacTags
Retrieves a list of Node names associated with the specified facility tags. If multiple Nodes are associated with the same facility tag, only the first matching Node found in the database is returned. If no Nodes are associated with a listed facility tag, a blank value is returned in the array.
Syntax
GetNodesFromFacTags (FacilityTagOrList As Variant, NodeNameList As Variant)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
FacilityTagOrList |
String |
Yes |
A single facility tag or a list of facility tags for which to retrieve Node names |
|
NodeNameList |
String |
Yes |
The returned list of Node names |
Remarks
This method will fail if a facility tag with the specified name does not exist in the connected FMS.
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example retrieves Node names associated with three specified facility tags.
Sub
Err.Clear
On Error Resume Next
Dim aryFacTags(2)
aryFacTags(0) = "CYGDEMO.UIS::FACILITY1"
aryFacTags(1) = "CYGDEMO.UIS::FACILITY2"
aryFacTags(2) = "CYGDEMO.UIS::FACILITY3"
Dim aryNodeNames(0)
FmsClient.GetNodesFromFacTags aryFacTags, aryNodeNames
If Err.Number <> 0 Then
MsgBox Err.Description
Else
Dim index
For index = 0 To UBound(aryFacTags)
MsgBox "The Node for polling facility" & aryFacTags(index) & "is: " & aryNodeNames(index)
Next
End If
On Error Goto 0
End Sub
GetNodesInGroup
Retrieves a list of Node names associated with the specified group Node.
Syntax
GetNodesInGroup (GroupName As String, bRecursive As Boolean) As Variant
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
GroupName |
String |
Yes |
A single group Node name for which to retrieve a list of member Node names |
|
bRecursive |
Boolean |
Yes |
Recursive search level for group Nodes If this parameter is set to True, the method will recursively search and return the children of any group Nodes in the hierarchy. If set to False, the method will only return the immediate children of the specified group Node. |
Remarks
This method will fail if a group Node with the specified name does not exist in the connected FMS.
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example retrieves Node names associated with the specified group name.
Sub
Err.Clear
On Error Resume Next
Dim aryNodeNames(0)
aryNodeNames = FmsClient.GetNodesInGroup ("NewGroup", True)
If Err.Number <> 0 Then
MsgBox (Err.Number And &HFFFF&)
MsgBox Err.Description
Exit Sub
End If
On Error Goto 0
Dim strNodeNames, i
For i = 0 To UBound (aryNodeNames)
strNodeNames = strNodeNames & aryNodeNames(i) & " "
Next
MsgBox strNodeNames
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:
Sub GetReferences()
<NameofServiceClientObject>.GetReferences
MsgBox "Services references retrieved"
End SubRemarks
It is no longer necessary to call this method to populate the service-related properties of the client. However, GetReferences must still be called to update the cache if the services referenced by the connected FMS have changed.
GetReportInfo
Retrieves information about the report command associated with the specified report name retrieved from the connected FMS. Results include the report type, whether or not the command has an associated unit set, and the Node resolution category of the command. To retrieve report names, use GetReportNames.
Syntax
GetReportInfo(ReportName as String, pvReportType as String, pvHasUnitSet as Boolean, pvNodeResolutionCategory as Integer) As Boolean
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
ReportName |
String |
Yes |
The name of the report |
|
pvReportType |
String |
Yes |
The returned report type |
|
pvHasUnitSet |
Boolean |
Yes |
The returned value indicating whether or not the command has an associated unit set If the value is True, the command has an associated unit set; if False, there is no associated unit set. |
|
pvNodeResolutionCategory |
Integer |
Yes |
The returned Node resolution category This parameter can be one of the following values:
|
Remarks
Return value: True if the report name is found in the connected FMS service; otherwise False.
This method will fail if the FmsClient object is not connected to an FMS.
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example retrieves information associated with a specified report name.
Sub
Err.Clear
On Error Resume Next
Dim strReportName
strReportName = cboReportNames.GetText(cboReportNames.Selection)
Dim bRoundReport, StrReportType, bHasUnitSet, eNodeResolutionCategory
bFoundReport = FmsClient.GetReportInfo(strReportName, strReportType, bHasUnitSet, eNodeResolutionCategory)
If Not(bFoundReport) Then
MsgBox "Report not found"
End If
If Err.Number <> 0 Then
MsgBox (Err.Number And &HFFFF&)
MsgBox Err.Description
Exit Sub
End If
On Error Goto 0
eboReportType.SetWindowText strReportType
eboNodeCategory.SetWindowText CStr(eNodeResolutionCategory)
checkUnitSet.Check = bHasUnitSet
End Sub
GetReportNames
Retrieves a list of available report names associated with the connected FMS.
Syntax
GetReportNames() as Variant
Remarks
Return value: A list of report names. To retrieve report command information associated with a report name, use GetReportInfo.
This method will fail if the FmsClient object is not connected to an FMS.
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example retrieves a list of available report names and populates a drop-down menu with the results.
Sub
Err.Clear
On Error Resume Next
cboReportNames.ResetContent
Dim aryReports
Redim aryReports(0)
aryReports = FmsClient.GetReportNames
If Err.Number <> 0 Then
MsgBox (Err.Number And &HFFFF&)
MsgBox Err.Description
Exit Sub
End If
Dim i
For i = 0 To UBound(aryReports)
cboReportNames.AddString aryReports(i)
Next
End Sub
GetStationGroup
Retrieves the specified station group from the connected FMS.
Syntax
GetStationGroup(GroupName As String) As FmsStationGroup
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
GroupName |
String |
Yes |
The name of the station group to retrieve |
Remarks
This method will fail if a group with the specified name does not exist in the connected FMS.
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example retrieves a station group and outputs some of its properties.
Sub
Err.Clear
On Error Resume Next
Dim FmsStationGroup
Set FmsStationGroup = FmsClient.GetStationGroup("StationGroup001")
If Err.Number <> 0 Then
MsgBox (Err.Number And &HFFFF&)
MsgBox Err.Description
Exit Sub
End If
On Error Goto 0
Dim strMsg
strMsg = "Group Name: " + FmsStationGroup.Name + vbCr
strMsg = strMsg + "Description: " + FmsStationGroup.Description + vbCr
strMsg = strMsg + "Node ID: " + CStr(FmsStationGroup.NodeId) + vbCr
strMsg = strMsg + "Begin Active Date: " + CStr(FmsStationGroup.BeginActiveDate) + vbCr
strMsg = strMsg + "End Active Date: " + CStr(FmsStationGroup.EndActiveDate) + vbCr
MsgBox strMsg
End Sub
GetUnitSetId
The GetUnitSetId method returns the ID for the specified unit set defined in your system.
Syntax
GetUnitSetId(UnitSetName As String) As Integer
Parameter
| Parameter | Required | Description |
|---|---|---|
|
UnitSetName |
Yes |
The unit set name |
Remarks
Return Value: The ID of the given unit set.
Example
Sub
Dim FmsClient
Set FmsClient = CreateObject ("CxFms.FmsClient")
FmsClient.Connect "EXAMPLE.FMS"
Dim UnitSetId
UnitSetId = FmsClient.GetUnitSetId("Metric")
MsgBox UnitSetId
FmsClient.Disconnect
End Sub
GetUnitSetName
The GetUnitSetName method returns the name for the specified unit set defined in your system.
Syntax
GetUnitSetName(UnitSetId As Integer) As String
Parameter
| Parameter | Required | Description |
|---|---|---|
|
UnitSetId |
Yes |
The unit set ID |
Remarks
Return Value: The name of the given unit set.
Example
Sub
Dim FmsClient
Set FmsClient = CreateObject ("CxFms.FmsClient")
FmsClient.Connect "EXAMPLE.FMS"
Dim UnitSetName
UnitSetName = FmsClient.GetUnitSetName(1)
MsgBox UnitSetName
FmsClient.Disconnect
End Sub
IsTransactionComplete
Returns true if the transaction with the specified ID has completed.
Syntax
IsTransactionComplete(TransactionId As Long) As Boolean
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
TransactionId |
Long |
Yes |
The ID of the transaction to check for completion |
Remarks
Return Value: True if the transaction has completed, otherwise false.
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example sends a command and waits for it to complete.
Sub
Err.Clear
On Error Resume Next
Dim strRet, lTransId
lTransId = FmsClient.SendFmsCommand("Emerson107", "REQCONFIG", 1, 1, "", strRet)
If Err.Number <> 0 Then
MsgBox (Err.Number And &HFFFF&)
MsgBox Err.Description
Exit Sub
End If
On Error Goto 0
If (lTransId = 0) Then
MsgBox strRet
Else
While Not(FmsClient.IsTransactionComplete(lTransId))
WScript.Sleep(500)
WEnd
MsgBox "Transaction Completed"
End If
End Sub
SendFmsCommand
Sends a command to the FMS.
Syntax
SendFmsCommand(NodeName As String, Command As String, Priority As Integer, LoggingLevel As Integer, Parameters As String, ResultString As Variant) As Long
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
NodeName |
String |
Yes |
The name of the group or device to which to send the command |
|
Command |
String |
Yes |
The command to execute This parameter can be one of the following values: Device Communication
*Note: Flow-Cal commands are provided as optional system features, in REPOSITORY mode only, and additional requirements must be met for the commands to function. See the FMS Commands topic for each Flow-Cal command for more information. Export EXPX - Export file: X, where X describes the specific registered file type, as follows:
*Note: Flow-Cal and PGAS export commands are provided as optional system features, and additional requirements must be met for the commands to function. See the FMS Commands topic for each optional export command for more information. **Note: Operates in conjunction with CygNet Dispatch. See CygNet Dispatch for more information. Import IFX - Import file: X, where X describes the specific registered file type, as follows:
Reports RPTX - Build report: X, where X is determined by the report type defined in its report template file (for example, RPTBR for a Batch report called "BR"). The default report command names appearing in the sample report template files are as follows. Note: Each report (RPTX) command is user-defined in its associated report template file, where the report can be customized and/or renamed as desired. If you rename a ticket report (for example, RPTTR) in its report template file, then the new name would become its specific command name (for example, RPTNEW). See Managing Report Template Files for more information about using and customizing report template files.
**Note: Operates in conjunction with CygNet Dispatch. See CygNet Dispatch for more information. System
*Note: If enabled in the FMS configuration file. See Archive Data for more information. **Note: Operates in conjunction with CygNet Dispatch. See CygNet Dispatch for more information. User
See FMS Commands for more information. |
|
Priority |
Integer |
Yes |
The processing priority of the command This parameter can be one of the following values:
|
|
LoggingLevel |
Integer |
Yes |
The logging level of the command This parameter can be one of the following values:
|
|
Parameters |
String |
Yes |
A semicolon-delimited string of key/value-pair parameters for the command See FMS Commands for a list of expected parameters for each command. |
|
ResultString |
String |
Yes |
A text string returned by this method, containing any error messages generated while processing the command |
Remarks
Return Value: A numeric token which can be used in conjunction with IsTransactionComplete to determine if the command has completed. A return value of zero indicates that the command failed.
The format of datetime parameters will be Device time. To specify a different format, use SendFmsCommandWithTimeFormat.
Additional script has been included in the example that will catch an error and populate the Err object upon failure.
Example
The following example sends a command and waits for it to complete.
Sub
Err.Clear
On Error Resume Next
Dim strRet, lTransId
lTransId = FmsClient.SendFmsCommand("Emerson107", "REQCONFIG", 1, 1, "", strRet)
If Err.Number <> 0 Then
MsgBox (Err.Number And &HFFFF&)
MsgBox Err.Description
Exit Sub
End If
On Error Goto 0
If (lTransId = 0) Then
MsgBox strRet
Else
While Not(FmsClient.IsTransactionComplete(lTransId))
WScript.Sleep(500)
WEnd
MsgBox "Transaction Completed"
End If
End Sub
SendFmsCommandWithTimeFormat
Sends a command to the FMS service, and specifies the date/time format (for example, Device time).
Syntax
SendFmsCommandWithTimeFormat(NodeName As String, Command As String, Priority As Integer, LoggingLevel As Integer, Parameters As String, TimeFormat As TimeFormatType, ResultString As Variant) As Long
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
NodeName |
String |
Yes |
The name of the group or device to which to send the command |
|
Command |
String |
Yes |
The command to execute This parameter can be one of the following values: Device Communication
*Note: Flow-Cal commands are provided as optional system features, in REPOSITORY mode only, and additional requirements must be met for the commands to function. See the FMS Commands topic for each Flow-Cal command for more information. Export EXPX - Export file: X, where X describes the specific registered file type, as follows:
*Note: Flow-Cal and PGAS export commands are provided as an optional system feature, and additional requirements must be met for the commands to function. See the FMS Commands topic for each optional export command for more information. **Note: Operates in conjunction with CygNet Dispatch. See CygNet Dispatch for more information. Import IFX - Import file: X, where X describes the specific registered file type, as follows:
Reports RPTX - Build report: X, where X is determined by the report type defined in its report template file (for example, RPTBR for a Batch report called "BR"). The default report command names appearing in the sample report template files are as follows. Note: Each report (RPTX) command is user-defined in its associated report template file, where the report can be customized and/or renamed as desired. If you rename a ticket report (for example, RPTTR) in its report template file, then the new name would become its specific command name (for example, RPTNEW). See Managing Report Template Files for more information about using and customizing report template files.
**Note: Operates in conjunction with CygNet Dispatch. See CygNet Dispatch for more information. System
*Note: If enabled in the FMS configuration file. See Archive Data for more information. **Note: Operates in conjunction with CygNet Dispatch. See CygNet Dispatch for more information. User
See FMS Commands for more information. |
|
Priority |
Integer |
Yes |
The processing priority of the command This parameter can be one of the following values:
|
|
LoggingLevel |
Integer |
Yes |
The logging level of the command This parameter can be one of the following values:
|
|
Parameters |
String |
Yes |
A semicolon-delimited string of key/value-pair parameters for the command |
|
TimeFormat |
TimeFormatType |
Yes |
The format of datetime parameters specified in Parameters Possible values for this property are as follows:
|
|
ResultString |
String |
Yes |
A text string returned by this method, containing any error messages generated while processing the command |
Remarks
Return Value: A numeric token which can be used in conjunction with IsTransactionComplete to determine if the command has completed. A return value of zero indicates that the command failed.
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example sends a command and waits for it to complete.
Sub
Err.Clear
On Error Resume Next
Dim strRet, lTransId
lTransId = FmsClient.SendFmsCommandWithTimeFormat("Emerson107", "REQCONFIG", 1, 2, "", 1, strRet)
If Err.Number <> 0 Then
MsgBox (Err.Number And &HFFFF&)
MsgBox Err.Description
Exit Sub
End If
On Error Goto 0
If (lTransId = 0) Then
MsgBox strRet
Else
While Not(FmsClient.IsTransactionComplete(lTransId))
WScript.Sleep(500)
WEnd
MsgBox "Transaction Completed"
End If
End Sub
SetDataQualitySetting
Modifies various data quality settings for the connected FMS.
Syntax
SetDataQualitySetting(Setting As Integer, RecordId As Long, bForceUnlock As Boolean)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
Setting |
Integer |
Yes |
The specific data quality setting to modify Possible values are as follows:
*Note: This setting is applicable only for systems operating in FULL mode. In FULL mode, it is used only if the Close period options require that the data quality meets the minimum requirement. See Close period on the Admin System Options window for more information. |
|
RecordId |
Long |
Yes |
The ID (influence) of the quality to use for the selected setting. |
|
bForceUnlock |
Boolean |
Yes |
If this parameter is set to True, the method will attempt to force unlock the data quality system setting if it is locked. |
Remarks
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example retrieves a list of Node Ids for a selected Site.Service.
Sub
Err.Clear
On Error Resume Next
FmsClient.SetDataQualitySetting 0,5, True
If Err.Number <> 0 Then
MsgBox (Err.Number And &HFFFF&)
MsgBox Err.Description
Exit Sub
End If
On Error Goto 0
End Sub
UpdateDevice
Updates an existing device in the connected FMS.
Syntax
UpdateDevice(FmsDevice As FmsDevice)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
FmsDevice |
CxFms.FmsDevice |
Yes |
An object containing the properties of the device to update |
Remarks
Prior to using this method, issue a call to FmsClient.GetDevice in order to retrieve the current state of the device before modifying properties.
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example updates the description property of a device.
Sub
Err.Clear
On Error Resume Next
Dim FmsDevice
Set FmsDevice = FmsClient.GetDevice("Meter001")
FmsDevice.Description = "New Description"
FmsClient.UpdateDevice FmsDevice
If Err.Number <> 0 Then
MsgBox (Err.Number And &HFFFF&)
MsgBox Err.Description
Exit Sub
End If
On Error Goto 0
End Sub
UpdateGasStation
Sends a Gas Station record to the FMS.
Syntax
UpdateGasStation(NodeName As String, BeginDateTime As Date, Influence As Integer, ProcessVariables As String, AuditComments As String, GasQualityId As Long, Errors As Variant) As Variant
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
NodeName |
String |
Yes |
The name of the group representing the Gas Station This group must be a physical station. |
|
BeginDateTime |
Date |
Yes |
The beginning active date of the record |
|
Influence |
Integer |
Yes |
The value of the Influence of the data quality record to associate with the Gas Station record This value must match the Influence column of an existing Data Quality record. |
|
ProcessVariables |
String |
Yes |
A semicolon-delimited string of key/value-pair parameters for the command The following is a list of possible keys for this set of parameters:
|
|
AuditComments |
String |
Yes |
The comment to be added to the transaction’s audit record |
|
GasQualityId |
Long |
No |
The ID of the Gas Quality record associated with this Gas Station This parameter is optional. |
|
Errors |
Variant |
No |
An array of error codes returned by this method This parameter is optional. |
Remarks
Return Value: An array of errors if the command fails, or an empty array if the command succeeds.
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example sends a Gas Station record to the FMS.
Sub
Err.Clear
On Error Resume Next
Dim strParams, aryErrors
strParams = "Mass=3.56;Energy=2.291;Temperature=34.3;Pressure=43.2;Volume=291.3"
aryErrors = FmsClient.UpdateGasStation("PSTATION", CDate("June 28, 2023"),
1, strParams, "My Comment")
If Err.Number <> 0 Then
MsgBox (Err.Number And &HFFFF&)
MsgBox Err.Description
Exit Sub
End If
On Error Goto 0
If (UBound(aryErrors) >=0) Then
Dim i, strErrs
For i = 0 To UBound(aryErrors)
strErrs = strErrs & CStr(aryErrors(i)) & vbCr
Next
strErrs = "UpdateGasStation failed:" & vbCr & strErrs
MsgBox strErrs
Else
MsgBox "UpdateGasStation succeeded"
End If
End Sub
UpdateGeneralGroup
Updates an existing general group in the connected FMS.
Syntax
UpdateGeneralGroup(FmsGroup As FmsGeneralGroup)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
FmsGroup |
CxFms.FmsGeneralGroup |
Yes |
An object containing the properties of the group to update |
Remarks
Prior to using this method, issue a call to FmsClient.GetGeneralGroup in order to retrieve the current state of the group before modifying properties.
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example updates the description property of a general group.
Sub
Err.Clear
On Error Resume Next
Dim FmsGroup
Set FmsGroup = FmsClient.GetGeneralGroup("GeneralGroup001")
FmsGroup.Description = "New Description"
FmsClient.UpdateGeneralGroup FmsGroup
If Err.Number <> 0 Then
MsgBox (Err.Number And &HFFFF&)
MsgBox Err.Description
Exit Sub
End If
On Error Goto 0
End Sub
UpdateStationGroup
Updates an existing station group in the connected FMS.
Syntax
UpdateStationGroup(FmsGroup As FmsStationGroup)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
|
FmsGroup |
CxFms.FmsStationGroup |
Yes |
An object containing the properties of the group to update |
Remarks
Prior to using this method, issue a call to FmsClient.GetStationGroup in order to retrieve the current state of the group before modifying properties.
Additional script has been included in the example to catch an error and populate the Err object upon failure.
Example
The following example updates the description property of a station group.
Sub
Err.Clear
On Error Resume Next
Dim FmsGroup
Set FmsGroup = FmsClient.GetStationGroup("StationGroup001")
FmsGroup.Description = "New Description"
FmsClient.UpdateStationGroup FmsGroup
If Err.Number <> 0 Then
MsgBox (Err.Number And &HFFFF&)
MsgBox Err.Description
Exit Sub
End If
On Error Goto 0
End Sub
