The FmsClient object contains the following methods.
Note: Some of the examples in this topic use the WScript.Sleep statement, which is not recommended for use when scripting in CygNet Studio. If you are scripting in CygNet Studio, use TheView EventTimer instead.
The Connect method connects the object to a service.
Connect(DomainSiteService As String)
| Parameter | Required | Description |
|---|---|---|
|
DomainSiteService |
Yes |
The [Domain]Site.Service to which to connect. A domain is optional. The service must be a valid FMS. |
Returns 0 if successful and a non-zero value if the connection failed.
Example
The following example connects the FmsClient object to the CYGDEMO.FMS on domain 5410:
|
Sub FmsConnect() 'Connect to an FMS Dim FmsClient Set FmsClient = CreateObject("CxFms.FmsClient") FmsClient.Connect("[5410]CYGDEMO.FMS") End Sub |
Creates a new device in the connected FMS service.
CreateDevice(FmsDevice As FmsDevice, eDeviceType As Integer)
| Parameter | Type | Required | Description |
|---|---|---|---|
|
FmsDevice |
CxFms.FmsDevice |
Yes |
An object containing all the properties of the new device. |
|
eDeviceType |
Integer |
Yes |
Possible values are as follows.
|
This method will fail if a device with the same name already exists in the connected FMS service.
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, 2011") FmsDevice.EndActiveDate = 0 'Indefinite end time FmsDevice.DeviceInstallDate = CDate("May 10, 2011") 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 |
Creates a new general group in the connected FMS service.
CreateGeneralGroup(FmsGroup As FmsGeneralGroup)
| Parameter | Type | Required | Description |
|---|---|---|---|
|
FmsGroup |
CxFms.FmsGeneralGroup |
Yes |
An object containing the properties of the new group. |
This method will fail if a group with the same name already exists in the connected FMS service.
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, 2011") FmsGroup.EndActiveDate = 0 'Indefinite end time FmsGroup.Name = "New_General_Group" FmsGroup.Description = "My new general group" FmsGroup.SetNode CDate("May 10, 2011"), 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 |
Creates a new station group in the connected FMS service.
CreateStationGroup(FmsGroup As FmsStationGroup)
| Parameter | Type | Required | Description |
|---|---|---|---|
|
FmsGroup |
CxFms.FmsStationGroup |
Yes |
An object containing the properties of the new group. |
This method will fail if a group with the same name already exists in the connected FMS service.
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, 2011") 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, 2011"), 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 |
The Disconnect method disconnects from the service.
Disconnect() As Integer
Return Value: Returns 0 if successful and a non-zero value if the disconnect failed.
Example
The following example attempts to disconnect the client, and pops a message box if it is unsuccessful.
|
Sub If FmsClient.Disconnect <> 0 Then MsgBox "Failed to disconnect" End If End Sub |
Returns the list of active FMS services on the current domain.
GetActiveServices(ServiceList As Variant)
| 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 |
Returns a list of all group Nodes that are present in the connected FMS service.
GetAllGroups(SmartGroupInclusion As Integer, GroupList As Variant)
| 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. |
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 service.
|
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 |
The GetConsoleData method returns the console text and display attributes as two 25x80 arrays of unsigned characters.
GetConsoleData(ByRef pText, ByRef pAttr) As Integer
| 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. |
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 = FmsClient.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 |
Returns an object containing all the properties of the specified device.
GetDevice(DeviceName As String) As FmsDevice
| Parameter | Type | Required | Description |
|---|---|---|---|
|
DeviceName |
String |
Yes |
The name of the device to retrieve. |
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 |
Retrieves a list of facility tags associated with the specified Nodes.
GetFacTagsFromNodes (NodeNameOrList As Variant, FacTagList As Variant)
| 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. |
This method will fail if a Node with the specified name does not exist in the connected FMS service.
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 |
Retrieves the specified general group from the connected FMS service.
GetGeneralGroup(GroupName As String) As FmsGeneralGroup
| Parameter | Type | Required | Description |
|---|---|---|---|
|
GroupName |
String |
Yes |
The name of the general group to retrieve. |
This method will fail if a group with the specified name does not exist in the connected FMS service.
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 |
Returns a list of all group Nodes of the specified type that are present in the connected FMS service.
GetGroupList(GroupType As Integer, SmartGroupInclusion As Integer, GroupList As Variant)
| 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. |
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 service.
|
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 |
Retrieves the ID of the specified Node from the connected FMS service.
GetNodeId(NodeName As String) As Long
| Parameter | Type | Required | Description |
|---|---|---|---|
|
NodeName |
String |
Yes |
The name of the Node for which to retrieve an ID. |
This method will fail if a Node with the specified name does not exist in the connected FMS service.
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 |
Retrieves the name of the specified Node from the connected FMS service.
GetNodeName(NodeId As Long) As String
| Parameter | Type | Required | Description |
|---|---|---|---|
|
NodeId |
Long |
Yes |
The ID of the Node for which to retrieve a name. |
This method will fail if a Node with the specified ID does not exist in the connected FMS service.
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 |
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.
GetNodesFromFacTags (FacilityTagOrList As Variant, NodeNameList As Variant)
| 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. |
This method will fail if a facility tag with the specified name does not exist in the connected FMS service.
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 |
Retrieves a list of Node names associated with the specified group Node.
GetNodesInGroup (GroupName As String, bRecursive As Boolean) As Variant
| 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 |
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. |
This method will fail if a group Node with the specified name does not exist in the connected FMS service.
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 |
Retrieves data for the services referenced by the FMS client.
GetReferences() As Integer
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.
Example
The following example retrieves referenced service data.
|
Sub FmsClient.GetReferences End Sub |
Retrieves information about the report command associated with the specified report name retrieved from the connected FMS service. 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.
GetReportInfo(ReportName as String, pvReportType as String, pvHasUnitSet as Boolean, pvNodeResolutionCategory as Integer) As Boolean
| 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.
|
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 service.
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 |
Retrieves a list of available report names associated with the connected FMS service.
GetReportNames() as Variant
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 service.
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 |
Retrieves the specified station group from the connected FMS service.
GetStationGroup(GroupName As String) As FmsStationGroup
| Parameter | Type | Required | Description |
|---|---|---|---|
|
GroupName |
String |
Yes |
The name of the station group to retrieve. |
This method will fail if a group with the specified name does not exist in the connected FMS service.
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 |
The GetUnitSetId method returns the ID for the specified unit set defined in your system.
GetUnitSetId(UnitSetName As String) As Integer
| Parameter | Required | Description |
|---|---|---|
|
UnitSetName |
Yes |
The unit set name |
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 |
The GetUnitSetName method returns the name for the specified unit set defined in your system.
GetUnitSetName(UnitSetId As Integer) As String
| Parameter | Required | Description |
|---|---|---|
|
UnitSetId |
Yes |
The unit set ID |
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 |
Returns true if the transaction with the specified ID has completed.
IsTransactionComplete(TransactionId As Long) As Boolean
| Parameter | Type | Required | Description |
|---|---|---|---|
|
TransactionId |
Long |
Yes |
The ID of the transaction to check for completion. |
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 |
Sends a command to the FMS service.
SendFmsCommand(NodeName As String, Command As String, Priority As Integer, LoggingLevel As Integer, Parameters As String, ResultString As Variant) As Long
| 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. |
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 |
Sends a command to the FMS service, and specifies the date/time format (for example, Device time).
SendFmsCommandWithTimeFormat(NodeName As String, Command As String, Priority As Integer, LoggingLevel As Integer, Parameters As String, TimeFormat As TimeFormatType, ResultString As Variant) As Long
| 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. |
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 |
Modifies various data quality settings for the connected FMS service.
SetDataQualitySetting(Setting As Integer, RecordId As Long, bForceUnlock As Boolean)
| 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. |
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 |
Updates an existing device in the connected FMS service.
UpdateDevice(FmsDevice As FmsDevice)
| Parameter | Type | Required | Description |
|---|---|---|---|
|
FmsDevice |
CxFms.FmsDevice |
Yes |
An object containing the properties of the device to update. |
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 |
Sends a Gas Station record to the FMS service.
UpdateGasStation(NodeName As String, BeginDateTime As Date, Influence As Integer, ProcessVariables As String, AuditComments As String, GasQualityId As Long, Errors As Variant) As Variant
| 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. |
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 service.
|
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, 2011"), 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 |
Updates an existing general group in the connected FMS service.
UpdateGeneralGroup(FmsGroup As FmsGeneralGroup)
| Parameter | Type | Required | Description |
|---|---|---|---|
|
FmsGroup |
CxFms.FmsGeneralGroup |
Yes |
An object containing the properties of the group to update. |
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 |
Updates an existing station group in the connected FMS service.
UpdateStationGroup(FmsGroup As FmsStationGroup)
| Parameter | Type | Required | Description |
|---|---|---|---|
|
FmsGroup |
CxFms.FmsStationGroup |
Yes |
An object containing the properties of the group to update. |
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 |
|
|
|
