DdsClient Methods
The DdsClient object contains the following methods:
Some of the automation calls in this API support multithreading. If supported it is noted below. If multithreading is not noted, the call is single-threaded.
AddDataGroupElementMappings
The AddDataGroupElementMappings method is used to add UDC mappings for specified data group elements in an existing data group. If a specified data group element is already mapped to a UDC (by means of the device template file, for example), the duplicate mapping is not added.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
AddDataGroupElementMappings(MappingsToAdd As Array)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
MappingsToAdd |
Yes |
Specifies an array of data group element objects, each of which maps a data group element to a UDC. The data group element object is called DGEMapping. |
Example
The following example creates an array and populates that array with DGEMapping objects. Then it adds data group mappings to a specified remote device and data group. Next it gets an array of DGEMapping items from the specified AI data group. Finally it deletes two DGEMapping objects.
Set ddsClient = CreateObject("CxDds.DdsClient")
ddsClient.Connect "MYDDS.DDS"
ReDim arrMappings(2)
Dim mapping
Set mapping = CreateObject("CxDds.DGEMapping")
mapping.DeviceID = "MY_RTU"
mapping.DataGroupType = "AI"
mapping.DataGroupOrdinal = 3
mapping.FacilityID = "MY_RTU"
mapping.DataGroupElementID = "ACHiAlrm"
mapping.UDC = "MYUDC1"
Set arr Mappings(0) = mapping
Set mapping = CreateObject("CxDds.DGEMapping")
mapping.DeviceID = "MY_RTU"
mapping.DataGroupType = "AI"
mapping.DataGroupOrdinal = 3
mapping.FacilityID = "MY_RTU"
mapping.DataGroupElementID = "ACPtFl"
mapping.UDC = "MYUDC2"
Set arrMappings(1) = mapping
Set mapping = CreateObject("CxDds.DGEMapping")
mapping.DeviceID = "MY_RTU"
mapping.DataGroupType = "AI"
mapping.DataGroupOrdinal = 3
mapping.FacilityID = "MY_RTU"
mapping.DataGroupElementID = "AlrmCd"
mapping.UDC = "MYUDC3"
Set arrMappings(2) = mapping
ddsClient.AddDataGroupElementMappings arrMappings
Dim objMappings
objMappings = ddsClient.GetDataGroupElementMappings("MY_RTU", "AI", 3)
WScript.Echo "Added data group element mappings:"
Dim i
For i = LBound(objMappings) To UBound(objMappings)
Set mapping = objMappings(i)
Dim strMapping
strMapping = "DGE Mapping for " & mapping.DeviceID & " " & mapping.DataGroupType & ":" & mapping.DataGroupOrdinal
strMapping = strMapping & " - " & mapping.DataGroupElementID & " = " & mapping.FacilityID & "." & mapping.UDC
WScript.Echo strMapping
Next
ReDim arrDeleteMappings(1)
Set arrDeleteMappings(0) = objMappings(0)
Set arrDeleteMappings(1) = objMappings(1)
ddsClient.DeleteDataGroupElementMappings arrDeleteMappings
objMappings = ddsClient.GetDataGroupElementMappings("MY_RTU", "AI", 3)
WScript.Echo "Remaining mappings after deletion:"
For i = LBound(objMappings) To UBound(objMappings)
Set mapping = objMappings(i)
strMapping = "DGE Mapping for " & mapping.DeviceID & " " & mapping.DataGroupType & ":" & mapping.DataGroupOrdinal
strMapping = strMapping & " - " & mapping.DataGroupElementID & " = " & mapping.FacilityID & "." & mapping.UDC
WScript.Echo strMapping
Next
AddDataGroupTransaction
The AddDataGroupTransaction method adds a single transaction to a data group defined by the database key (DbKey) in the data group transaction header in XML format.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
AddDataGroupTransaction(strDataGroupTxHdrIn, strDataGroupTxDataIn, strDataGroupTxHdrOut)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DataGroupTxHdrIn |
Yes |
The data group transaction's header. A string containing an XML segment. |
|
DataGroupTxDataIn |
Yes |
The data group transaction's data. A string containing an XML segment. |
|
DataGroupTxHdrOut |
Yes |
The data group's newly added transaction's header. A string containing an XML segment. |
Example
The following example adds a single transaction to a device's data group defined by the database key in the transaction header.
AddDataGroupTransaction
Sub AddDataGroupTransaction()
Dim hdr As String =
"<txHdr dbKey=""0000000116B0000004C0000013"" timestamp=""3/3/2022 14:18:56.909"" txType=""G"" txTypeTxt=""Get"" userId=""user.name"" statusCode=""3"" statusCodeTxt=""Succeeded"" statusMsg=""Succeeded"" ver=""1.1"" dataSize=""290"" hdrDataSize=""290"" idx=""00111"" appdef1=""0"" appdef2=""0"" appdef3=""0"" appdef4=""0"" quality=""U"" qualityTxt=""Unknown"" partialData=""0"" cmprsSize=""0"" blobCnt=""0""/>"
Dim dta As String =
"<dgData xmlns:dt=""urn:schemas-microsoft-com:datatypes"">" & vbCrLf & vbTab & "<RegNum dt:dt=""ui4"" desc=""Register Number"" type=""ui4"">111</RegNum>" & vbCrLf & vbTab & "<DataType desc=""Data Type"" type=""string"">ui2</DataType>" & vbCrLf & vbTab & "<Desc desc=""Description"" type=""string""/>" & vbCrLf & vbTab & "<FacUdc desc=""Facility.UDC for Point Processing"" type=""string""/>" & vbCrLf & vbTab & "<Value dt:dt=""ui2"" desc=""Value"" type=""vrnt"">100</Value>" & vbCrLf & vbTab & "<UISCMDPRMS>DataType=ui2;DGORD=0;DGTYPE=SnglRegRw2;RegNum=111;</UISCMDPRMS>" & vbCrLf & vbTab & "<UISCMDTYPE>DG_F_DEV</UISCMDTYPE>" & vbCrLf & "</dgData>" & vbCrLf
Dim res = ddsClient.AddDataGroupTransaction(hdr, dta)
End Sub
AddDataGroupTransactionByFile
The AddDataGroupTransactionByFile method adds a transaction to a data group defined by a device ID, data group, and an ordinal using an XML file containing the transaction.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
AddDataGroupTransactionByFile(ByVal strDeviceID, ByVal strDataGroupType, ByVal iOrdinal, ByVal strFilePath, ByRef strDataGroupTxHdrOut)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DeviceID |
Yes |
The user-defined, unique device identifier. |
|
DataGroupType |
Yes |
The unique data group identifier. Case sensitive. |
|
Ordinal |
Yes |
The ordinal or instance of the data group type specified. Should be within the range defined by applicable device template file attributes, like baseOrd and maxCnt, which constrain the number of ordinals possible for a data group type. |
|
FilePath |
Yes |
The path to the file containing the transaction in XML format. |
|
DataGroupTxHdrOut |
Yes |
The data group's newly added transaction's header. A string containing an XML segment. |
Example
The following example adds the transaction specified in test.xml file to the SnglRegRo2 data group for the MOD_ENG_RTU_0000 device.
AddDataGroupTransactionByFile
Sub AddDataGroupTransactionByFile ()
Dim strDeviceId As String = "MOD_ENG_RTU_0000"
Dim DataGroupType As String = "SnglRegRo2"
Dim iOrd As Integer = 0
Dim filepath As String = "C:\temp\test.xml"
Dim res = ddsClient.AddDataGroupTransactionByFile(strDeviceId, DataGroupType, iOrd, filepath)
End Sub The following example shows a sample test.xml file containing the transaction in XML format.
<dgTxInfo>
<dgInfo desc="Single Read-Only 2-Byte Reg" type="SnglRegRo2" dgType="SnglRegRo2" ordinal="0" facility="MOD_ENG_RTU_0000" visible="1" webEnabled="0" txRepl="0" dbKey="0000000116B0000004" device="MOD_ENG_RTU_0000"/>
<txHdr dbKey="0000000116B0000004C0000013" timestamp="3/4/2022 12:12:49.172" txType="G" txTypeTxt="Get" userId="WFT\E261111" statusCode="3" statusCodeTxt="Succeeded" statusMsg="Succeeded" ver="1.1" dataSize="293" hdrDataSize="293" idx="08204" appdef1="0" appdef2="0" appdef3="0" appdef4="0" quality="U" qualityTxt="Unknown" partialData="0" cmprsSize="0" blobCnt="0"/>
<dgData xmlns:dt="urn:schemas-microsoft-com:datatypes">
<RegNum dt:dt="ui4" desc="Register Number" type="ui4">8204</RegNum>
<DataType desc="Data Type" type="string">ui2</DataType>
<Desc desc="Description" type="string"/>
<FacUdc desc="Facility.UDC for Point Processing" type="string"/>
<Value dt:dt="ui2" desc="Value" type="vrnt">8204</Value>
<UISCMDPRMS>DataType=ui2;DGORD=0;DGTYPE=SnglRegRo2;RegNum=8204;</UISCMDPRMS>
<UISCMDTYPE>DG_F_DEV</UISCMDTYPE>
</dgData>
</dgTxInfo>
AddDataGroupTransactionByID
The AddDataGroupTransactionByID method adds a transaction to a data group defined by device ID, data group type, and the ordinal triple. The database key (DbKey) in the DataGroupTxHdrIn is ignored.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
AddDataGroupTransactionByID(ByVal strDeviceID, ByVal strDataGroupType, ByVal iOrdinal, ByVal strDataGroupTxHdrIn, ByVal strDataGroupTxDataIn, ByRef strDataGroupTxHdrOut)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DeviceID |
Yes |
The user-defined, unique device identifier. |
|
DataGroupType |
Yes |
The unique data group identifier. Case sensitive. |
|
Ordinal |
Yes |
The ordinal or instance of the data group type specified. Should be within the range defined by applicable device template file attributes, like baseOrd and maxCnt, which constrain the number of ordinals possible for a data group type. |
|
DataGroupTxHdrIn |
Yes |
The data group transaction's header. A string containing an XML segment. |
|
DataGroupTxDataIn |
Yes |
The data group transaction's data. A string containing an XML segment. |
|
DataGroupTxHdrOut |
Yes |
The data group's newly added transaction's header. A string containing an XML segment. |
Example
The following example adds a transaction specified in the header string to the SnglRegRo2 data group for the MOD_ENG_RTU_0000 device.
AddDataGroupTransactionByID
Sub AddDataGroupTransactionByID()
Dim strDeviceId As String = "MOD_ENG_RTU_0000"
Dim DataGroupType As String = "SnglRegRo2"
Dim iOrd As Integer = 0
Dim hdr As String = "<txHdr dbKey=""0000099999B0009999C0000999"" txType=""G"" txTypeTxt=""Get"" userId=""WFT\E261311"" statusCode=""3"" statusCodeTxt=""Succeeded"" statusMsg=""Succeeded"" ver=""1.1"" dataSize=""3381"" hdrDataSize=""300"" idx="""" appdef1=""0"" appdef2=""0"" appdef3=""0"" appdef4=""0"" quality="""" qualityTxt=""Unknown"" partialData=""0"" cmprsSize=""932"" blobCnt=""1""/>"
Dim dta As String = "<dgData xmlns:dt=""urn:schemas-microsoft-com:datatypes"">" & vbCrLf & vbTab & "<RegNum dt:dt=""ui4"" desc=""Register Number"" type=""ui4"">111</RegNum>" & vbCrLf & vbTab & "<DataType desc=""Data Type"" type=""string"">ui2</DataType>" & vbCrLf & vbTab & "<Desc desc=""Description"" type=""string""/>" & vbCrLf & vbTab & "<FacUdc desc=""Facility.UDC for Point Processing"" type=""string""/>" & vbCrLf & vbTab & "<Value dt:dt=""ui2"" desc=""Value"" type=""vrnt"">111</Value>" & vbCrLf & vbTab & "<UISCMDPRMS>DataType=ui2;DGORD=0;DGTYPE=SnglRegRw2;RegNum=201;</UISCMDPRMS>" & vbCrLf & vbTab & "<UISCMDTYPE>DG_F_DEV</UISCMDTYPE>" & vbCrLf & "</dgData>" & vbCrLf
Dim res = ddsClient.AddDataGroupTransactionByID(strDeviceId, DataGroupType, iOrd, hdr, dta)
End Sub
CompareTemplatesFile
The CompareTemplatesFile method compares two device template files and returns the comparison as XML.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
CompareTemplatesFile(TemplateFilepath1 As String, TemplateFilepath2 As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
TemplateFilepath1 |
Yes |
The path to the first template file in the comparison. |
|
TemplateFilepath2 |
Yes |
The path to the second template file in the comparison. |
Remarks
The following is an example of two template files, and the XML which results from their comparison. The returned XML contains a line-by-line comparison of the template files.
<deviceDefinition deviceType="SimpleDeviceSys" eieType="SimpleDevice" category="4098" mfg="CygNet Software, Inc." model="Simple" desc="A simple device template">
<dataGroups udcCat="~UDCALL" canSend="false" canRecv="true" uccSend="false" uccRecv="true" udcDefFac="true" devDG="false" baseOrd="0" maxCnt="1">
<SysInfo niceName="System Info">
<dgElements>
<DG1 desc="Datagroup1" type="ui4"/>
</dgElements>
</SysInfo>
</dataGroups>
<defUisCmds visible="true" canBeScheduled="true" clientCanInvoke="true" inheritsSecurity="false">
</defUisCmds>
</deviceDefinition>
<deviceDefinition deviceType="SimpleDeviceSys" eieType="SimpleDevice" category="4098" mfg="CygNet Software, Inc." model="Simple" desc="A simple device template">
<dataGroups udcCat="~UDCALL" canSend="false" canRecv="true" uccSend="false" uccRecv="true" udcDefFac="true" devDG="false" baseOrd="0" maxCnt="1">
<SysInfo niceName="System Info">
<dgElements>
<DG1 desc="Datagroup1" type="string"/>
<DG2 desc="Datagroup2" type="ui4"/>
</dgElements>
</SysInfo>
</dataGroups>
<defUisCmds visible="true" canBeScheduled="true" clientCanInvoke="true" inheritsSecurity="false">
</defUisCmds>
</deviceDefinition>
<deviceDefinition deviceType="SimpleDeviceSys" eieType="SimpleDevice" category="4098" mfg="CygNet Software, Inc." model="Simple" desc="A simple device template">
<dataGroups udcCat="~UDCALL" canSend="false" canRecv="true" uccSend="false" uccRecv="true" udcDefFac="true" devDG="false" baseOrd="0" maxCnt="1">
<SysInfo niceName="System Info">
<dgElements>
<DG1 desc="Datagroup1" type="ui4">
<diff type="Attribute Value" element="type" val1="ui4" val2="string"/>
</DG1>
<diff type="Child 1" element="DG2" val1="(Missing)" val2="DG2"/>
<DG2 desc="Datagroup2" type="ui4"/>
</dgElements>
</SysInfo>
</dataGroups>
<defUisCmds visible="true" canBeScheduled="true" clientCanInvoke="true" inheritsSecurity="false"/>
</deviceDefinition>Example
The following example compares two device template files and saves the result XML to a file.
Sub
Dim strXml
strXml = DdsClient.CompareTemplatesFile("C:\My\Path\MyTemplate1.dtf", "C:\My\Path\MyTemplate2.dtf")
dim fso, txtFile
Set fso = CreateObject("Scripting.FileSystemObject")
Set txtFile = fso.CreateTextFile("c:\file.txt", True)
txtFile.WriteLine(strXml)
txtFile.Close
End Sub
CompareTemplatesFileDlg
The CompareTemplatesFileDlg method compares two device template files and displays the standard comparison dialog box.
Syntax
CompareTemplatesFileDlg(TemplateFilepath1 As String, TemplateFilepath2 As String)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
TemplateFilepath1 |
Yes |
The path to the first template file in the comparison. |
|
TemplateFilepath2 |
Yes |
The path to the second template file in the comparison. |
Example
The following example compares two device templates and saves the result XML to a file.
Sub
DdsClient.CompareTemplatesFileDlg "C:\My\Path\MyTemplate1.dtf", "C:\My\Path\MyTemplate2.dtf"
End Sub
CompareTemplatesXml
The CompareTemplatesXml method compares two device templates as XML strings and returns the comparison as XML.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
CompareTemplatesXml(TemplateXml1 As String, TemplateXml2 As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
TemplateXml1 |
Yes |
The XML of the first template file in the comparison. |
|
TemplateXml2 |
Yes |
The XML of the second template file in the comparison. |
Remarks
The following is an example of two template XMLs, and the XML which results from their comparison. The returned XML contains a line-by-line comparison of the template files.
<deviceDefinition deviceType="SimpleDeviceSys" eieType="SimpleDevice" category="4098" mfg="CygNet Software, Inc." model="Simple" desc="A simple device template">
<dataGroups udcCat="~UDCALL" canSend="false" canRecv="true" uccSend="false" uccRecv="true" udcDefFac="true" devDG="false" baseOrd="0" maxCnt="1">
<SysInfo niceName="System Info">
<dgElements>
<DG1 desc="Datagroup1" type="ui4"/>
</dgElements>
</SysInfo>
</dataGroups>
<defUisCmds visible="true" canBeScheduled="true" clientCanInvoke="true" inheritsSecurity="false">
</defUisCmds>
</deviceDefinition>
<deviceDefinition deviceType="SimpleDeviceSys" eieType="SimpleDevice" category="4098" mfg="CygNet Software, Inc." model="Simple" desc="A simple device template">
<dataGroups udcCat="~UDCALL" canSend="false" canRecv="true" uccSend="false" uccRecv="true" udcDefFac="true" devDG="false" baseOrd="0" maxCnt="1">
<SysInfo niceName="System Info">
<dgElements>
<DG1 desc="Datagroup1" type="string"/>
<DG2 desc="Datagroup2" type="ui4"/>
</dgElements>
</SysInfo>
</dataGroups>
<defUisCmds visible="true" canBeScheduled="true" clientCanInvoke="true" inheritsSecurity="false">
</defUisCmds>
</deviceDefinition>
<deviceDefinition deviceType="SimpleDeviceSys" eieType="SimpleDevice" category="4098" mfg="CygNet Software, Inc." model="Simple" desc="A simple device template">
<dataGroups udcCat="~UDCALL" canSend="false" canRecv="true" uccSend="false" uccRecv="true" udcDefFac="true" devDG="false" baseOrd="0" maxCnt="1">
<SysInfo niceName="System Info">
<dgElements>
<DG1 desc="Datagroup1" type="ui4">
<diff type="Attribute Value" element="type" val1="ui4" val2="string"/>
</DG1>
<diff type="Child 1" element="DG2" val1="(Missing)" val2="DG2"/>
<DG2 desc="Datagroup2" type="ui4"/>
</dgElements>
</SysInfo>
</dataGroups>
<defUisCmds visible="true" canBeScheduled="true" clientCanInvoke="true" inheritsSecurity="false"/>
</deviceDefinition>Example
The following example compares two device templates and saves the result XML to a file.
Sub
Dim strXml
strXml = DdsClient.CompareTemplatesXml(g_strXml1, g_strXml2)
dim fso, txtFile
Set fso = CreateObject("Scripting.FileSystemObject")
Set txtFile = fso.CreateTextFile("c:\file.txt", True)
txtFile.WriteLine(strXml)
txtFile.Close
End Sub
CompareTemplatesXmlDlg
The CompareTemplatesXmlDlg method compares two device templates as XML strings and displays the standard comparison dialog box.
Syntax
CompareTemplatesXmlDlg(TemplateXml1 As String, TemplateXml2 As String)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
TemplateXml1 |
Yes |
The XML of the first template file in the comparison. |
|
TemplateXml2 |
Yes |
The XML of the second template file in the comparison. |
Example
The following example compares two device templates and saves the result XML to a file.
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:
CreateDataGroup
The CreateDataGroup method is used to create a data group, including its data group elements.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
CreateDataGroup(DeviceId As String, DataGroupType As String, DataGroupOrdinal As Integer, FacilityId As String, Description As String)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DeviceId |
Yes |
The user-defined, unique device identifier. Make sure the device exists before the data group is created. |
|
DataGroupType |
Yes |
The unique data group identifier. Case sensitive. A data group of the same data group type must be defined in the applicable device template file in order for a new instance to be created. |
|
DataGroupOrdinal |
Yes |
The ordinal or instance of the data group type specified. Should be within the range defined by applicable device template file attributes, like baseOrd and maxCnt, which constrain the number of ordinals possible for a data group type. |
|
FacilityId |
Yes |
The facility identifier to be associated with the new data group. Make sure the facility exists before the data group is created. |
|
Description |
Yes |
The user-defined, human-readable description of the data group. It can vary from data group ordinal to data group ordinal, if useful. |
Example
The following example creates and deletes a data group.
Dim ddsClient1
Set ddsClient1 = CreateObject("CxDds.DdsClient")
ddsClient1.Connect("TEST.DDS")
Dim strDeviceId, strDgType, iDgOrd, strFacId, strDesc, iDgOrdBase, strError
strDeviceId = "TestDevice"
strDgType = "MyTestDG"
iDgOrdBase = 777
strFacId = "TESTFAC"
strDesc = strDgType + " Description"
On Error Resume Next
Err.Clear
Call ddsClient1.CreateDataGroup(strDeviceId, strFacId, strDgType, iDgOrd, strDesc)
If (Err.Number <> 0) Then
strError = Err.Description
End If
On Error goto 0
strError = ""
On Error Resume Next
Err.Clear
Call ddsClient1.DeleteDataGroup(strDeviceId, strDgType, iDgOrd, "DeleteDataGroup_ThereIsNoUndo")
If (Err.Number <> 0) Then
strError = Err.Description
End If
On Error goto 0
CreateUISCommand
The CreateUISCommand method adds a new UIS command and returns its database key (DbKey).
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
CreateUISCommand(DeviceId As String, CommandName As String, CommandDescription As String,FacilityId As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DeviceId |
Yes |
The user-defined, unique device identifier. The DeviceID associated with the UIS command being added. |
|
CommandName |
Yes |
A name for the new UIS command. |
|
CommandDescription |
Yes |
A description of the new UIS command. (This parameter is required, however, you may send an empty string.) |
|
FacilityId |
Yes |
The ID of the facility associated with the UIS command. |
Example
The following script creates a UIS command named TESTCMD.
Dim dbCommandKey,dbComponentKey
dbCommandKey = ddsClient.CreateUISCommand("TESTDEVICE", "TESTCMD", "Test UIS Command", "TESTFAC")
CreateUISCommandComponent
The CreateUISCommandComponent method adds a new component to a UIS command and returns the database key(DbKey) for that component.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
CreateUISCommandComponent(CommandDbKey As String, ComponentType As String, DataGroupType As String,DataGroupOrdinal As Integer,ComponentParams As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
CommandDbKey |
Yes |
The database key (DbKey) of the UIS command associated with the new component. |
|
ComponentType |
Yes |
The component type identifier of the UIS component being added. |
|
DataGroupType |
Yes |
The unique data group identifier. Case sensitive. The DataGroupType for the UIS command component being added. |
|
DataGroupOrdinal |
Yes |
The ordinal or instance of the data group type specified. Should be within the range defined by applicable device template file attributes, like baseOrd and maxCnt, which constrain the number of ordinals possible for a data group type. |
|
ComponentParams |
Yes |
A semicolon-delimited list of parameter name/value pairs for the UIS command component. Note: The maximum length of the command parameter string for a Send UIS Command message is 1200 characters. CygNet Software will report if a UIS Command message exceeds the maximum parameter length of 1200 characters. |
Example
The following script creates a UIS command component and adds it to the UIS command that has a database key (DbKey) of dbCommandKey. The script provides the component type, data group type, ordinal, and parameters for the new component.
dbComponentKey = ddsClient.CreateUISCommandComponent(dbCommandKey, "DG_F_DEV", "DynaCard", 0, "Cnt=1;")
DeleteDataGroup
The DeleteDataGroup method is used to delete a data group, including its data group elements.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
DeleteDataGroup(DeviceId As String, DataGroupType As String, DataGroupOrdinal As Integer, SecuritySentinel As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DeviceId |
Yes |
The user-defined, unique device identifier. Make sure the device exists before the data group is deleted. |
|
DataGroupType |
Yes |
The unique data group identifier. Case sensitive. A data group of the same data group type must be defined in the applicable device template file in order for a new instance to be created. |
|
DataGroupOrdinal |
Yes |
The ordinal or instance of the data group type specified. Should be within the range defined by applicable device template file attributes, like baseOrd and maxCnt, which constrain the number of ordinals possible for a data group type. |
|
SecuritySentinel |
Yes |
The static password required to enable this method. It is used as a precaution to keep the data group, device, or device template from being accidentally deleted. The string value is <method_name>_ThereIsNoUndo. |
Example
The following example creates and deletes a data group.
Dim ddsClient1
Set ddsClient1 = CreateObject("CxDds.DdsClient")
ddsClient1.Connect("TEST.DDS")
Dim strDeviceId, strDgType, iDgOrd, strFacId, strDesc, iDgOrdBase, strError
strDeviceId = "TestDevice"
strDgType = "MyTestDG"
iDgOrdBase = 777
strFacId = "TESTFAC"
strDesc = strDgType + " Description"
On Error Resume Next
Err.Clear
Call ddsClient1.CreateDataGroup(strDeviceId, strFacId, strDgType, iDgOrd, strDesc)
If (Err.Number <> 0) Then
strError = Err.Description
End If
On Error goto 0
strError = ""
On Error Resume Next
Err.Clear
Call ddsClient1.DeleteDataGroup(strDeviceId, strDgType, iDgOrd, "DeleteDataGroup_ThereIsNoUndo")
If (Err.Number <> 0) Then
strError = Err.Description
End If
On Error goto 0
DeleteDataGroupElementMappings
The DeleteDataGroupElementMappings method is used to delete UDC mapping for specified data group elements in an existing data group.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
DeleteDataGroupElementMappings(MappingsToDelete As Array)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
MappingsToDelete |
Yes |
Specifies an array of data group element objects, each of which is mapped from a data group element to a UDC. The data group element object is called DGEMapping. |
Example
The following example creates an array and populates that array with DGEMapping objects. Then it adds data group mappings to a specified remote device and data group. Next it gets an array of DGEMapping items from the specified AI data group. Finally it deletes two DGEMapping objects.
Set ddsClient = CreateObject("CxDds.DdsClient")
ddsClient.Connect "MYDDS.DDS"
ReDim arrMappings(2)
Dim mapping
Set mapping = CreateObject("CxDds.DGEMapping")
mapping.DeviceID = "MY_RTU"
mapping.DataGroupType = "AI"
mapping.DataGroupOrdinal = 3
mapping.FacilityID = "MY_RTU"
mapping.DataGroupElementID = "ACHiAlrm"
mapping.UDC = "MYUDC1"
Set arrMappings(0) = mapping
Set mapping = CreateObject("CxDds.DGEMapping")
mapping.DeviceID = "MY_RTU"
mapping.DataGroupType = "AI"
mapping.DataGroupOrdinal = 3
mapping.FacilityID = "MY_RTU"
mapping.DataGroupElementID = "ACPtFl"
mapping.UDC = "MYUDC2"
Set arrMappings(1) = mapping
Set mapping = CreateObject("CxDds.DGEMapping")
mapping.DeviceID = "MY_RTU"
mapping.DataGroupType = "AI"
mapping.DataGroupOrdinal = 3
mapping.FacilityID = "MY_RTU"
mapping.DataGroupElementID = "AlrmCd"
mapping.UDC = "MYUDC3"
Set arrMappings(2) = mapping
ddsClient.AddDataGroupElementMappings arrMappings
Dim objMappings
objMappings = ddsClient.GetDataGroupElementMappings("MY_RTU", "AI", 3)
WScript.Echo "Added data group element mappings:"
Dim i
For i = LBound(objMappings) To UBound(objMappings)
Set mapping = objMappings(i)
Dim strMapping
strMapping = "DGE Mapping for " & mapping.DeviceID & " " & mapping.DataGroupType & ":" & mapping.DataGroupOrdinal
strMapping = strMapping & " - " & mapping.DataGroupElementID & " = " & mapping.FacilityID & "." & mapping.UDC
WScript.Echo strMapping
Next
ReDim arrDeleteMappings(1)
Set arrDeleteMappings(0) = objMappings(0)
Set arrDeleteMappings(1) = objMappings(1)
ddsClient.DeleteDataGroupElementMappings arrDeleteMappings
objMappings = ddsClient.GetDataGroupElementMappings("MY_RTU", "AI", 3)
WScript.Echo "Remaining mappings after deletion:"
For i = LBound(objMappings) To UBound(objMappings)
Set mapping = objMappings(i)
strMapping = "DGE Mapping for " & mapping.DeviceID & " " & mapping.DataGroupType & ":" & mapping.DataGroupOrdinal
strMapping = strMapping & " - " & mapping.DataGroupElementID & " = " & mapping.FacilityID & "." & mapping.UDC
WScript.Echo strMapping
Next
DeleteDataGroupTransaction
The DeleteDataGroupTransaction method deletes a single transaction from a data group defined by the database key (DbKey) in the data group transaction header in XML format.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
DeleteDataGroupTransaction(ByVal strDataGroupTxHdrIn)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DataGroupTxHdrIn |
Yes |
The data group transaction's header. A string containing an XML segment. |
Example
The following example a transaction defined by the database key in the data group transaction header.
Sub DeleteDataGroupTransaction()
Dim hdr As String = "<txHdr dbKey=""0000000116B0000004C0000013"" timestamp=""3/3/2022 14:18:56.909"" txType=""G"" txTypeTxt=""Get"" userId=""WFT\E261111"" statusCode=""3"" statusCodeTxt=""Succeeded"" statusMsg=""Succeeded"" ver=""1.1"" dataSize=""290"" hdrDataSize=""290"" idx=""00111"" appdef1=""0"" appdef2=""0"" appdef3=""0"" appdef4=""0"" quality=""U"" qualityTxt=""Unknown"" partialData=""0"" cmprsSize=""0"" blobCnt=""0""/>"
ddsClient.DeleteDataGroupTransaction(hdr)
End Sub
DeleteDataGroupTransactionByDbKey
The DeleteDataGroupTransactionByDbKey method deletes a data group transaction defined by database key (DbKey).
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
DeleteDataGroupTransactionByDbKey(ByVal dbKey)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DbKey |
Yes |
The database key (DbKey) of the data group transaction being deleted. |
Example
The following example deletes a data group transaction defined by the specified dbKey.
Sub DeleteDataGroupTransactionByDbKey()
Dim dbkey As String = "0000000116B0000004C0000013"
ddsClient.DeleteDataGroupTransactionByDbKey(dbkey)
End Sub
DeleteDataGroupTransactionByFile
The DeleteDataGroupTransactionByFile method deletes a data group transaction as defined by an XML file containing the transaction.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
DeleteDataGroupTransactionByFile(ByVal strFilePath)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
FilePath |
Yes |
The path to the file containing the transaction in XML format. |
Example
The following example deletes the transaction specified in test.xml file. See AddDataGroupTransactionByFile for an example XML file.
Sub DeleteDataGroupTransactionByFile()
ddsClient.DeleteDataGroupTransactionByFile("C:\temp\1.xml")
End Sub
DeleteDevice
The DeleteDevice method deletes a device. There is NO "undo" if a device is deleted, so use this function with extreme caution.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
DeleteDevice(DeviceId As String, SecuritySentinel As String)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DeviceId |
Yes |
The user-defined, unique device identifier. |
|
SecuritySentinel |
Yes |
The static password required to enable this method. It is used as a precaution to keep the data group, device, or device template from being accidentally deleted. The string value is <method_name>_ThereIsNoUndo. |
Remarks
There is NO "undo" for deleting a device.
Example
The following example deletes a device with the Device ID of MYDEVICE.
Since there is no explicit return message for this method, verify the deletion of the device by other means.
DeleteDevTemplate
The DeleteDevTemplate method deletes a device template. There is NO "undo" if a device template is deleted, so use this function with extreme caution.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
DeleteDevTemplate(DevType As String, SecuritySentinel As String)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DevType |
Yes |
The device type for which to delete the template. |
|
SecuritySentinel |
Yes |
The static password required to enable this method. It is used as a precaution to keep the data group, device, or device template from being accidentally deleted. The string value is <method_name>_ThereIsNoUndo. |
Remarks
There is NO "undo" for deleting a device template.
Example
The following example deletes a template that has the device type of FlowAutoNative.
Sub
DdsClient.DeleteDevTemplate "FlowAutoNative", "DeleteDevTemplate_ThereIsNoUndo"
End Sub
DeleteRemoteCommOverrideProperty
The DeleteRemoteCommOverrideProperty method deletes a remote device comm override property.
Syntax
DeleteRemoteCommOverrideProperty(DevId As Variant, PropId As Variant, CommLine As Integer) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DevId |
Yes |
The user-defined, unique device identifier. The DeviceID for which to delete a property. |
|
PropId |
Yes |
The ID of the property to delete. |
|
CommLine |
Yes |
The number of the comm device for which to delete a property. This value can be 1 (for Primary), 2 (for Device 2), or 3 (for Device 3). If an invalid value is specified, it will default to 1. |
Example
The following example deletes the TPHN property from the primary comm device of the remote device that has a property ID of FLOWAUTOAP15.
Sub
DdsClient.DeleteRemoteCommOverrideProperty "FLOWAUTOAP15", "TPHN", 1
End Sub
DeleteRemoteDestinationOverrideProperty
The DeleteRemoteDestinationOverrideProperty method deletes a remote destination override property for a TCP/IP MultiPoint device.
Syntax
DeleteRemoteDestinationOverrideProperty(CommId As Variant, DestNetAddr As Variant, DestNetPort As Integer, PropId As Variant) As Boolean
Parameters
| Parameter | Required | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
CommId |
Yes |
The ID of the comm device for which to delete a property. |
||||||||||||||
|
DestNetAddr |
Yes |
The destination IP address. |
||||||||||||||
|
DestNetPort |
Yes |
The destination port. |
||||||||||||||
|
PropId |
Yes |
The ID of the property to delete. The following values for the TcpIpMp Device Property are supported:
|
Example
The following example deletes the KAFRQ (Keep-alive frequency) property from a comm device with Com ID of TCPMULTI.
Sub
DdsClient.DeleteRemoteDestinationOverrideProperty "TCPMULTI", "127.0.0.1",_3000, "KAFRQ"
End Sub
DeleteUISCommand
The DeleteUISCommand method deletes a UIS command by database key (DbKey).
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
DeleteUISCommand(CommandDbKey As String)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
CommandDbKey |
Yes |
The database key (DbKey) of the command being deleted. |
Example
The following script deletes the UIS command that has a database key (DbKey) of dbCommandKey.
DeleteUISCommandComponent
The DeleteUISCommandComponent method deletes a component of a UIS command by database key (ComponentDbKey).
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
DeleteUISCommand(ComponentDbKey As String)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
ComponentDbKey |
Yes |
The database key (DbKey) of the component being deleted. |
Example
The following script deletes the UIS command component that has a component database key of dbComponentKey.
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 SubThe following example disconnects from the DDS when the button is clicked.
Sub btnButton_EventClick()
Dim This : Set This = btnButton
Dim iTest
iTest = DdsClient.Disconnect()
If iTest <> 0 Then
MsgBox "Error in disconnecting"
End If
End Sub
ExportDevices
The ExportDevices method exports devices to an XML string.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
ExportDevices(DeviceIdArray As Variant) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DeviceIdArray |
Yes |
An array of device IDs to export. |
Example
The following example exports the device that has a Device ID array of FLOWAUTOAP15 to a file.
Sub
Dim aryDeviceIds
ReDim aryDeviceIds(1)
aryDeviceIds(0) = "FLOWAUTOAP15"
Dim strXml
strXml = DdsClient.ExportDevices(aryDeviceIds)
dim fso, txtFile
Set fso = CreateObject("Scripting.FileSystemObject")
Set txtFile = fso.CreateTextFile("c:\file.txt", True)
txtFile.WriteLine(strXml)
txtFile.Close
End Sub
ExtractDevTemplateToFile
The ExtractDevTemplateToFile method extracts a device template to a file.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
ExtractDevTemplateToFile(DevType As String, FileName As String) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DevType |
Yes |
The device type for the template being extracted. |
|
FileName |
Yes |
A name for the extracted device template file. |
Remarks
The DevType parameter refers to the deviceType attribute in the template’s device definition. This is the same value that appears in the Device Type column in CExplore’s DDS view.
Example
The following example extracts the device template of a device type FlowAutoNative to a file.
Sub
dsClient.ExtractDevTemplateToFile "FlowAutoNative", "C:\file.txt"
End Sub
GetActiveCommLine
The GetActiveCommLine method gets active communication line.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
GetActiveCommLine(DeviceId As String, Value As Variant) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DeviceId |
Yes |
The user-defined, unique device identifier. |
|
Value |
Yes |
The value that represents the active communication line. Values are 1 - Primary, 2 - Device2, 3 - Device3. |
Example
The following method returns whether the Active Comm Line is set to primary, secondary, or tertiary.
Sub GetCommLine()
'Get Device ID
Dim DeviceId
DeviceId = edtDeviceID.Text
'Get the active comm line, store in edit box
Dim iVal
DdsClient.GetActiveCommLine DeviceId, iVal
edtCommLine.Text = iVal
End Sub
GetAssociatedUisName
The GetAssociatedUisName method gets the Universal Interface Service name associated with the current DDS.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
GetAssociatedUisName() As String
Remarks
Returns the UIS name in Site.Service format. Each DDS has exactly one associated UIS. The CxUis library has a similar method, GetAssociatedDdsName, for getting a DDS name based on a UIS. If an error occurs, such as in connecting to the service, the error description will be returned.
Example
The following example retrieves the UIS name associated with the current DDS.
Function GetUISName (ddsName)
'Return the UIS name
GetUISName = DdsClient.GetAssociatedUisName()
End Function
GetBinaryHexFromText
The GetBinaryHexFromText method converts ascii text into binary hex string values.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
GetBinaryHexFromText(AsciiText As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
AsciiText |
Yes |
The ascii text to be converted into a binary hex string value. |
GetCommDevProperty
The GetCommDevProperty method gets a communications device parameter by data group element ID (DEID).
Syntax
GetCommDevProperty(CommDev As String, Deid As String, Value As Variant) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
CommDev |
Yes |
The name of the communication device. |
|
Deid |
Yes |
The data group element ID (DEID) of the property to retrieve. See Standard DEID Handles for a list. |
|
Value |
Yes |
The value of the property. This variant will have a subtype relevant to the property being set. |
Remarks
The return value is a Boolean indicating the success of the method. Use SetCommDevProperty to set communications device parameters in a similar manner.
Example
The following method lists each communications device on the CYGDEMO.DDS in a list box with its enabled state. The GetFacilityInfo global function is used to retrieve the list of facilities.
Sub ListDeviceEnabledStates()
Dim strUisName
Dim i, valEnabled, arrDevices, strDevId
lstDevices.ResetContent
'Get an array of all comm devices from the UIS
strUisName = DdsClient.GetAssociatedUisName()
GetFacilityInfo strUisName, "DEVICE_CATEGORY=CD", arrDevices
'Loop through the array and list enabled states
On Error Resume Next
For i = lbound(arrDevices) To ubound(arrDevices)
strDevId = arrDevices(i, 0)
DdsClient.GetCommDevProperty strDevId, "DevEnabled", valEnabled
lstDevices.AddString(strDevId + " - Enabled: " + CStr(valEnabled))
Next
On Error GoTo 0
End Sub
GetCommFailoverEnabled
The GetCommFailoverEnabled method gets communication failover enabled state.
Syntax
GetCommFailoverEnabled(DeviceId As String, Value As Boolean) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DeviceId |
Yes |
The user-defined, unique device identifier. |
|
Value |
Yes |
Stores the result of the method. |
Example
The following method gets whether or not failover is enabled and stores it in the Boolean bValue.
Sub GetFailoverStatus()
'Get strDevice ID
Dim strDeviceId
DeviceId = edtDeviceId.Text
'Get whether or not Failover is enabled
Dim bValue
DdsClient.GetCommFailoverEnabled DeviceId, bValue
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
GetDataGroupElementMappings
The GetDataGroupElementMappings method gets an array of UDC-mapped data group elements from an existing data group.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
GetDataGroupElementMappings(DeviceId As String, DataGroupType As String, DataGroupOrdinal As Integer) As Array()
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DeviceId |
Yes |
The user-defined, unique device identifier. Make sure the device exists before getting data group elements. |
|
DataGroupType |
Yes |
The unique data group identifier. Case sensitive. A data group of the same data group type must be defined in the applicable device template file before getting data group elements. |
|
DataGroupOrdinal |
Yes |
The ordinal or instance of the data group type specified. Should be within the range defined by applicable device template file attributes, like baseOrd and maxCnt, which constrain the number of ordinals possible for a data group type. |
Return Values
This method gets an array of all DGEMapping objects from an existing data group.
Example
The following example creates an array and populates that array with DGEMapping objects. Then it adds data group mappings to a specified remote device and data group. Next it gets an array of DGEMapping items from the specified AI data group. Finally it deletes two DGEMapping objects.
Set ddsClient = CreateObject("CxDds.DdsClient")
ddsClient.Connect "MYDDS.DDS"
ReDim arrMappings(2)
Dim mapping
Set mapping = CreateObject("CxDds.DGEMapping")
mapping.DeviceID = "MY_RTU"
mapping.DataGroupType = "AI"
mapping.DataGroupOrdinal = 3
mapping.FacilityID = "MY_RTU"
mapping.DataGroupElementID = "ACHiAlrm"
mapping.UDC = "MYUDC1"
Set arrMappings(0) = mapping
Set mapping = CreateObject("CxDds.DGEMapping")
mapping.DeviceID = "MY_RTU"
mapping.DataGroupType = "AI"
mapping.DataGroupOrdinal = 3
mapping.FacilityID = "MY_RTU"
mapping.DataGroupElementID = "ACPtFl"
mapping.UDC = "MYUDC2"
Set arrMappings(1) = mapping
Set mapping = CreateObject("CxDds.DGEMapping")
mapping.DeviceID = "MY_RTU"
mapping.DataGroupType = "AI"
mapping.DataGroupOrdinal = 3
mapping.FacilityID = "MY_RTU"
mapping.DataGroupElementID = "AlrmCd"
mapping.UDC = "MYUDC3"
Set arrMappings(2) = mapping
ddsClient.AddDataGroupElementMappings arrMappings
Dim objMappings
objMappings = ddsClient.GetDataGroupElementMappings("MY_RTU", "AI", 3)
WScript.Echo "Added data group element mappings:"
Dim i
For i = LBound(objMappings) To UBound(objMappings)
Set mapping = objMappings(i)
Dim strMapping
strMapping = "DGE Mapping for " & mapping.DeviceID & " " & mapping.DataGroupType & ":" & mapping.DataGroupOrdinal
strMapping = strMapping & " - " & mapping.DataGroupElementID & " = " & mapping.FacilityID & "." & mapping.UDC
WScript.Echo strMapping
Next
ReDim arrDeleteMappings(1)
Set arrDeleteMappings(0) = objMappings(0)
Set arrDeleteMappings(1) = objMappings(1)
ddsClient.DeleteDataGroupElementMappings arrDeleteMappings
objMappings = ddsClient.GetDataGroupElementMappings("MY_RTU", "AI", 3)
WScript.Echo "Remaining mappings after deletion:"
For i = LBound(objMappings) To UBound(objMappings)
Set mapping = objMappings(i)
strMapping = "DGE Mapping for " & mapping.DeviceID & " " & mapping.DataGroupType & ":" & mapping.DataGroupOrdinal
strMapping = strMapping & " - " & mapping.DataGroupElementID & " = " & mapping.FacilityID & "." & mapping.UDC
WScript.Echo strMapping
Next
GetDataGroupInfo
The GetDataGroupInfo method gets data group information in XML format for the specified facility.
Syntax
GetDataGroupInfo(FacilityId As String, SelectionMask As Variant) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
FacilityId |
Yes |
The facility ID from which to retrieve information. |
|
SelectionMask |
Yes |
Indicates which subset of commands to retrieve. The available flags are enumerated in the DGSelectionBits table. |
Remarks
The XML is returned as a string, which can be parsed with an XML parser. The following example uses Microsoft XML v5. Each data group will be listed in a DGRec tag with the parameters displayed in the format shown below.
<dgInfoList>
<DGRec0 desc="Basic Poll" type="BasicPoll" ordinal="0" facility="METER206" visible="1" webEnabled="0" dbKey="0000000002B00005" device="METER206" />
<DGRec1 ...
</dgInfoList>Example
The following function retrieves data group information for the METER206 facility and saves it to a file. The selection mask enables retrieval of parent and hidden data group information (1 + 4 = 5 = 00000101, see Data Group Selection Bits).
Sub SaveDataGroupInfo ()
Dim strInfo, xmlDoc
strInfo = DdsClient.GetDataGroupInfo("METER206", 5)
'Save XML
Set xmlDoc = CreateObject("Msxml2.DOMDocument")
xmlDoc.loadXML(strInfo)
xmlDoc.save("C:\DataGroupInfo.xml")
End Sub
GetDataGroupProperty
The GetDataGroupProperty method gets a data group property based on a property ID.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
GetDataGroupProperty(DeviceId As String, DataGroupType As String, DataGroupOrdinal As Integer, PropID As String)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DeviceId |
Yes |
The user-defined, unique device identifier. |
|
DataGroupType |
Yes |
The unique data group identifier. Case sensitive. |
|
DataGroupOrdinal |
Yes |
The ordinal or instance of the data group type specified. Should be within the range defined by applicable device template file attributes, like baseOrd and maxCnt, which constrain the number of ordinals possible for a data group type. |
|
PropID |
Yes |
The ID of the data group property to get or set. The following keyword values are supported:
|
Remarks
The return value is a variant containing the returned property. A value must be of the proper type for the PropID.
Example
The following function returns a data group description based on the data group type and ordinal for the METER206 facility.
Function GetDataGroupDesc (dgType, dgOrdinal)
'Return the data group’s description
GetDataGroupDesc = DdsClient.GetDataGroupProperty("METER206", dgType, _dgOrdinal, "desc")
End Function
GetDataGroupTransactionData
The GetDataGroupTransactionData method gets data group transaction data in XML format for a specified transaction database key (DbKey).
Syntax
GetDataGroupTransactionData(TransactionKey As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
TransactionKey |
Yes |
The database key (DbKey) of the transaction. This can be parsed from the GetDataGroupTransactions method. |
Remarks
The XML is returned as a string, which can be parsed with an XML parser. The following example uses Microsoft XML v5.
<dgData xmlns:dt="urn:schemas-microsoft-com:datatypes">
<Year dt:dt="ui2">2023</Year>
<Mon dt:dt="ui2">7</Mon>
<Day dt:dt="ui2">2</Day>
<Hour dt:dt="ui2">14</Hour>
<Min dt:dt="ui2">54</Min>
<Sec dt:dt="ui2">0</Sec>
<DOW dt:dt="ui2">5</DOW>
<UISCMDPRMS>attrRegNum=1;DGORD=8;DGTYPE=CfgMB;</UISCMDPRMS>
<UISCMDTYPE>DG_UPD</UISCMDTYPE>
</dgData>Example
The following subroutine takes a transaction database key (DbKey), gets the transaction data based on the key, and saves it to a file.
Sub SaveDataGroupTransactionData (key)
Dim strTransData, xmlDoc
strTransData = DdsClient.GetDataGroupTransactionData(key)
'Save XML
Set xmlDoc = CreateObject("Msxml2.DOMDocument")
xmlDoc.loadXML(strTransData)
xmlDoc.save("C:\TransactionData.xml")
End Sub
GetDataGroupTransactions
The GetDataGroupTransactions method gets a list of transactions in XML format for a specified data group.
Syntax
GetDataGroupTransactions(DeviceId As String, DataGroupType As String, DataGroupOrdinal As Integer) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DeviceId |
Yes |
The user-defined, unique device identifier. |
|
DataGroupType |
Yes |
The unique data group identifier. Case sensitive. These types can be found in the data group’s properties in CygNet Explorer. |
|
DataGroupOrdinal |
Yes |
The ordinal or instance of the data group type specified. Should be within the range defined by applicable device template file attributes, like baseOrd and maxCnt, which constrain the number of ordinals possible for a data group type. |
Remarks
The XML is returned as a string, which can be parsed with an XML parser. The following example uses Microsoft XML v5. Each transaction will be listed in a DGTx tag with the parameters displayed in the format shown below.
<dgTxList>
<DGTx0 timestamp="6/17/2004 15:53:15.828" txType="G" userId="COMPUTER07\USER" statusCode="3" statusCodeTxt="Succeeded" statusMsg="Succeeded" dbKey="0000000002B0000001C000004" />
<DGTx1 ...
</dgTxList>The format of the return XML is identical to that returned by the GetDataGroupTransactionsByKey method.
Example
The following function retrieves transaction data for the Basic Poll data group on the METER206 facility and saves it to a file.
Sub SaveDataGroupInfo ()
Dim strTransInfo, xmlDoc
strTransInfo = DdsClient.GetDataGroupTransactions("METER206", "BasicPoll", 0)
'Save XML
Set xmlDoc = CreateObject("Msxml2.DOMDocument")
xmlDoc.loadXML(strTransInfo)
xmlDoc.save("C:\TransactionData.xml")
End Sub
GetDataGroupTransactionsByKey
The GetDataGroupTransactionsByKey method gets the data group transaction information in XML format for a specified data group.
Syntax
GetDataGroupTransactionsByKey(DataGroupKey As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DataGroupKey |
Yes |
The database key (DbKey) of the data group. This key is retrieved in the database key (DbKey) of the GetDataGroupInfo method or directly with the GetDataGroupProperty method (shown in the example). |
Remarks
The XML is returned as a string, which can be parsed with an XML parser. The following example uses Microsoft XML v5. Each transaction will be listed in a "DGTx" tag with the parameters displayed in the format shown below.
<dgTxList>
<DGTx0 timestamp="6/17/2004 15:53:15.828" txType="G" userId="COMPUTER07\USER" statusCode="3" statusCodeTxt="Succeeded" statusMsg="Succeeded" dbKey="0000000002B0000001C000004" />
<DGTx1 ...
</dgTxList>The format of the return XML is identical to that returned by the GetDataGroupTransactions method.
Example
The following function retrieves the database key (DbKey) for the Basic Poll data group on the METER206 facility, then gets its transaction data and saves it to a file.
<dgTxList>
<DGTx0 timestamp="6/17/2004 15:53:15.828" txType="G" userId="COMPUTER07\USER" statusCode="3" statusCodeTxt="Succeeded" statusMsg="Succeeded" dbKey="0000000002B0000001C000004" />
<DGTx1 ...
</dgTxList>
GetDataGroupTxDataWithRefs
The GetDataGroupTxDataWithRefs method gets data group transaction data in XML format for a specified transaction database key (DbKey). It also calculates and includes the values of non-array reference data group elements. It does not provide values for data group elements that represent arrays of references.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
GetDataGroupTxDataWithRefs(TransactionKey As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
TransactionKey |
Yes |
The database key (DbKey) (Level 3) for the desired data group. Transaction key is 26 digits. |
Examples
The following function retrieves data group transaction data and displays it in a rich text box.
Sub GetTxData()
Dim strDdsName
'Display transaction data in a rich text box
Dim strTKey
strTKey = "0000000002B0000001C000004"
rtbTxData.Text = DdsClient.GetDataGroupTxDataWithRefs(TKey)
End SubIn this example, DateS and DOWT are reference data group elements; their values are not stored in the database, but are calculated on the fly.
<dgData xmlns:dt="urn:schemas-microsoft-com:datatypes">
<Year dt:dt="ui2" desc="Year" type="ui2">2023</Year>
<Mon dt:dt="ui2" desc="Month" type="ui2">7</Mon>
<Day dt:dt="ui2" desc="Day" type="ui2">2</Day>
<Hour dt:dt="ui2" desc="Hour" type="ui2">14</Hour>
<Min dt:dt="ui2" desc="Minute" type="ui2">54</Min>
<Sec dt:dt="ui2" desc="Second" type="ui2">0</Sec>
<DOW dt:dt="ui2" desc="Day of Week #" type="ui2">5</DOW>
<UISCMDPRMS>attrRegNum=1;DGORD=8;DGTYPE=CfgMB;</UISCMDPRMS>
<UISCMDTYPE>DG_UPD</UISCMDTYPE>
<DateS desc="Datetime" isRef="1" type="string">02-Jul-21 14:54:00</DateS>
<DOWT desc="Day of Week" mapVal="RefOpt" ref="DOW" type="string">5-Friday</DOWT>
</dgData>
GetDataGroupTxHeader
The GetDataGroupTxHeader method gets the data group transaction header in XML format for the specified transaction database key (DbKey).
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
GetDataGroupTxHeader(TransactionKey As String) As String
Parameter
| Parameter | Required | Description |
|---|---|---|
|
TransactionKey |
Yes |
The database key (DbKey) of the transaction. This can be parsed from the GetDataGroupTransactions method. |
Example
The following function retrieves the data group transaction header in XML format for database transaction key (DbKey) 0000001039B0000001C0000001.
Sub GetDataGroupTxHeader()
' The data group transaction key.
Dim DgTxDbKey : DgTxDbKey = "0000001039B0000001C0000001"
' Retrieve the data group transaction header xml using the transaction key.
Dim XmlDgTxHdr : XmlDgTxHdr = DdsClient.GetDataGroupTxHeader(DgTxDbKey)
'Load the data group transaction header xml into an xml parser.
Dim XmlDoc : Set XmlDoc = CreateObject("Msxml2.DOMDocument")
XmlDoc.loadXML(XmlDgTxHdr)
'Save the xml to the hard drive.
XmlDoc.save("C:\TransactionHeader.xml")
End SubThe data group transaction header XML might look like this:
<txHdr dbKey="0000001039B0000001C0000001" timestamp="2/3/2023 16:08:57.232" txType="S" txTypeTxt="Send" userId="VSI\user" statusCode="2" statusCodeTxt="Failed" statusMsg="FAILED: Comm Unable to Connect" ver="1.1" dataSize="194" hdrDataSize="194" idx="Cryout Ack" appdef1="0" appdef2="0" appdef3="0" appdef4="0" cmprsSize="0" blobCnt="0" device="METER" facility="FAC" dgType="CmdMsg" ordinal="0" />
GetDeviceIdFromFacilityId
The GetDeviceIdFromFacilityId method gets a device ID for a specified facility ID.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
GetDeviceIdFromFacilityId(FacilityId As String) As String
Parameter
| Parameter | Required | Description |
|---|---|---|
|
FacilityId |
Yes |
The ID of the facility for which to retrieve a device ID. |
Example
The following function returns a device ID given a facility ID, serving as a wrapper for the GetDeviceIdFromFacilityId method.
Function GetDeviceId (facilityId)
Dim strTransInfo, strDbKey, xmlDoc
'Return the device Id
GetDeviceId = DdsClient.GetDeviceIdFromFacilityId(CStr(facilityId))
End Sub
GetDeviceIdListFromFacilityId
The GetDeviceIdListFromFacilityId method gets the device ID list for a specified facility ID.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
GetDeviceIdListFromFacilityId(FacilityId As String, DeviceIdList As Variant)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
FacilityId |
Yes |
The facility ID for which to retrieve the device ID list. |
|
DeviceIdList |
Yes |
The list of device IDs returned by this method. |
Example
The following example retrieves the list of device IDs associated with facility ID FLOWAUTOAP15.
Sub
Dim aryDeviceIds
DdsClient.GetDeviceIdListFromFacilityId "FLOWAUTOAP15", aryDeviceIds
Dim i
For i = 0 To UBound(aryDeviceIds)
MsgBox aryDeviceIds(i)
Next
End Sub
GetDeviceIdsByCategory
The GetDeviceIdsByCategory method gets all devices IDs in the specified category.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
GetDeviceIdsByCategory(Category As String) As Variant
Parameters
| Parameter | Required | Description |
|---|---|---|
|
FacilityId |
Yes |
The facility ID for which to retrieve the device ID list. |
Example
The following example retrieves all device IDs in the RD category.
Sub
Dim aryDeviceIds
aryDeviceIds = DdsClient.GetDeviceIdsByCategory("RD")
Dim i
For i = 0 To UBound(aryDeviceIds)
MsgBox aryDeviceIds(i)
Next
End Sub
GetDeviceIdsByPrimaryCommId
The GetDeviceIdsByPrimaryCommId method gets all devices IDs on the specified primary comm ID.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
GetDeviceIdsByPrimaryCommId(CommId As String) As Variant
Parameters
| Parameter | Required | Description |
|---|---|---|
|
CommId |
Yes |
The primary comm ID for which to retrieve devices. |
Example
The following example retrieves all device IDs on the comm device that has a Comm ID of TCP210-3001.
Sub
Dim aryDeviceIds
aryDeviceIds = DdsClient.GetDeviceIdsByPrimaryCommId("TCP210-3001")
Dim i
For i = 0 To UBound(aryDeviceIds)
MsgBox aryDeviceIds(i)
Next
End Sub
GetDeviceProperty
The GetDeviceProperty method retrieves a device property from a specified data group element (DataGroupElement).
Syntax
GetDeviceProperty(DevId As String, Deid As String, Value As Variant) As Boolean
Parameters
| Parameter | Required | Description | ||||
|---|---|---|---|---|---|---|
|
DevId |
Yes |
The user-defined, unique device identifier. The DeviceID for which to retrieve a property. |
||||
|
Deid |
Yes |
The data group element ID (DEID) representing the property to retrieve. This property must be one of the following values:
|
||||
|
Value |
Yes |
The value of the property returned by this method. |
Example
The following example retrieves the DevType property value for a device that has a Device ID of FLOWAUTOAP15.
Sub
Dim vValue
DdsClient.GetDeviceProperty "FLOWAUTOAP15", "DevType", vValue
MsgBox vValue
End Sub
GetDeviceTemplate
The GetDeviceTemplate method gets a device template for a specified device.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
GetDeviceTemplate(DeviceId As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DeviceId |
Yes |
The user-defined, unique device identifier. |
Remarks
The device template is returned in XML format. If the device does not have a template, an error indicates that the template record was not found on the DDS.
Example
The following method displays the device template for a given device in a rich text box ActiveX control.
Sub ShowDeviceTemplate (deviceName)
Dim strTemplate
RichText.Text = ""
'Get the template XML string and display in text box
strTemplate = DdsClient.GetDeviceTemplate(deviceName)
RichText.Text = strTemplate
End Sub
GetFacilityLinks
The GetFacilityLinks method gets facility links for a specified Device ID.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
GetFacilityLinks(DeviceId As String, FacilityLinkInfo As Variant)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DeviceId |
Yes |
The user-defined, unique device identifier. |
|
FacilityLinkInfo |
Yes |
The two dimensional array that the data will be stored in. |
Example
The following method gets the Facility IDs and Facility Ordinals from a device and stores them in a list box.
Sub FacilityLinks()
'Get DeviceId
Dim strDeviceId
strDeviceId = edtDeviceId.Text
'Get facility links and store in the array arrFacilityLinks
Dim arrFacilityLinks
DdsClient.GetFacilityLinks strDeviceId, arrFacilityLinks
'Display the results in a list box
Dim i
For i = lbound(arrFacilityLinks) To ubound(arrFacilityLinks)
lboResults.AddString(arrFacilityLinks(i,0) & " --> " & arrFacilityLinks(i,1))
Next
End Sub
GetMappedDGElementInfo
The GetMappedDGElementInfo method gets mapped data group element information for a specified facility.
Syntax
GetMappedDGElementInfo(Facility As String, Filter As String, SelectionMask As Variant, DataGroupXml As String, ErrorOut As String) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
Facility ID |
Yes |
The Facility of the mapping of the Data Group Element. |
|
Filter |
Yes |
A semicolon delimited list of possible parameters value pairs to match. The possible values are: DGTYPE, UDC, and DGE. Example 1: DGTYPE=BasicPoll;UDC=VGY;DGE=GasYday Filters on only data groups of DataGroupType = BasicPoll with a mapped UDC of VGY on Group Elements named GasYday Example 2: UDC=VGY; Filters on all data groups with a mapped UDC of VGY |
|
SelectionMask |
Yes |
Indicates which subset of data groups to search for mappped Data Group Elements. The available flags are listed in the Data Group Selection Bits enumeration. For all data groups, use 0. |
|
DataGroupXml |
Yes |
Output. The returned XML string of data group element information. |
|
ErrorOut |
Yes |
Output. The returned error string or empty string on success. |
Remarks
GetMappedDGElementInfo returns a Boolean value indicating the method’s success or failure. The XML in the DataGroupXml parameter is returned as a string, which can be parsed with an XML parser. The following example uses Microsoft XML v5. Each data group will be listed in a DGRec# tag with the parameters displayed in the format shown below. Each data group tag will include a dgeInfoList tag that includes its data group elements (mapped UDCs). Only data groups that include mapped UDCs are returned.
<dgInfoList>
<DGRec0 desc="Basic Poll" type="BasicPoll" ordinal="0" facility="METER206" visible="1" webEnabled="0" dbKey="0000000002B000001" device="">
<dgeInfoList>
<Dge0 dge="AO17" facility="METER206" udc="VLVCTLPO" />
<Dge1 dge="DI23" facility="METER206" udc="SCOMP" />
<Dge2 dge="DiagPnt65" facility="METER206" udc="VOLTIB" />
</dgeInfoList>
</DGRec0>
<DGRec1 ...
</dgInfoList>Example
The following method gets the mapped data group element information for all data groups in the METER206 device and saves the returned XML string to a file.
Sub SaveDGElementInfo ()
Dim bSuccess, strXML, strError, xmlDoc
'Get the data group info XML string in strXML
DdsClient.GetMappedDGElementInfo("METER206", "", 0, strXML, strError)
'Save XML
Set xmlDoc = CreateObject("Msxml2.DOMDocument.5.0")
xmlDoc.loadXML(strXML)
xmlDoc.save("C:\DGElementInfo.xml")
End Sub
GetRecentSuccessfulDataGroupsTXs
The GetRecentSuccessfulDataGroupsTXs method gets data group transaction information in XML format for the specified data group.
Syntax
GetRecentSuccessfulDataGroupTXs(DeviceId As String, DataGroupType As String, DataGroupOrdinal As Integer, NewerThan As Date) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DeviceId |
Yes |
The user-defined, unique device identifier. |
|
DataGroupType |
Yes |
The unique data group identifier. Case sensitive. |
|
DataGroupOrdinal |
Yes |
The ordinal or instance of the data group type specified. Should be within the range defined by applicable device template file attributes, like baseOrd and maxCnt, which constrain the number of ordinals possible for a data group type. |
|
NewerThan |
Yes |
All successful transactions newer than this date will be returned. |
Remarks
This method returns the transaction information in XML format. The following is an example of what is returned.
<dgTxList txCount="1">
<DGTx0 device="BART-SOCK" facility="BART-SOCK" dgType="Exceptions" ordinal="0" dbKey="0000000008B0000005C0000026" timestamp="2/24/2023 17:23:31.655" txType="G" txTypeTxt="Get" userId="VSI\alex.james" statusCode="3" statusCodeTxt="Succeeded" statusMsg="Succeeded" ver="1.1" dataSize="1708" hdrDataSize="300" idx="" cmprsSize="547" blobCnt="1"/>
</dgTxList>Example
The following example retrieves data group transaction information for the specified data group.
'Connect to DDS
'Dim DeviceId
Dim strDeviceId
strDeviceId = lboDevices.GetText(lboDevices.Selection)
'Dim DataGroupType
'If possible, use a group type that the user has specified
Dim strDataGroupType
strDataGroupType = ""
If (edtDataGroupType.Text <> "") Then
strDataGroupType = edtDataGroupType.Text
End If
'Dim DataGroupOrdinal
'If possible, use a group ordinal that the user has specified
Dim iDataGroupOrdinal
iDataGroupOrdinal = 9999
If (edtDataGroupOrdinal.Text <> "") Then
iDataGroupOrdinal = cint(edtDataGroupOrdinal.Text)
End If
'Dim NewerThan
'If possible, use a date that the user has specified
Dim dtNewerThan
dtNewerThan = 0
If (edtNewerThan.Text <> "") Then
dtNewerThan = cdate(edtNewerThan.Text)
End If
Dim strDataGroupTxListXml
strDataGroupTxListXml = g_DdsClient.GetRecentSuccessfulDataGroupTXs(strDeviceId, strDataGroupType, iDataGroupOrdinal, dtNewerThan)
edtBox.Text = StrDataGroupTxListXml
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 SubThe following example refreshes the list of referenced services, retrieves the data stored in the DDS client’s AccessControlService property, and displays it in an edit box.
Sub GetReferences()
'Call GetReferences and store a referenced service in an edit box
DdsClient.GetReferences()
edtResults.Text = DdsClient.AccessControlService
End Sub
GetRemoteCommOverrideProperty
The GetRemoteCommOverrideProperty method retrieves a remote device comm override property.
Syntax
GetRemoteCommOverrideProperty(DevId As Variant, PropId As Variant, CommLine As Integer, Value As Variant) As Boolean
Parameters
| Parameter | Required | Description | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
DevId |
Yes |
The user-defined, unique device identifier. The DeviceID for which to retrieve a property. |
||||||||||||||||||||||
|
PropId |
Yes |
The ID of the property to retrieve. The following values for the PropId parameter are supported for a Modem Device Property :
The following values for the PropId parameter are supported for the TcpMp and Udp Device Property:
|
||||||||||||||||||||||
|
CommLine |
Yes |
The number of the comm device for which to retrieve a property. This value can be 1 (for Primary), 2 (for Device 2), or 3 (for Device 3). If an invalid value is specified, it will default to 1. |
||||||||||||||||||||||
|
Value |
Yes |
The property value returned by this method. |
Example
The following example retrieves the TPHN property from the primary comm device of a remote device that has a Device ID of FLOWAUTOAP15.
Sub
Dim vValue
DdsClient.GetRemoteCommOverrideProperty "FLOWAUTOAP15", "TPHN", 1, vValue
MsgBox vValue
End Sub
GetRemoteDestinationOverrideProperty
The GetRemoteDestinationOverrideProperty method retrieves a remote destination override property for a TCP/IP MultiPoint device.
Syntax
GetRemoteDestinationOverrideProperty(CommId As Variant, DestNetAddr As Variant, DestNetPort As Integer, PropId As Variant, Value As Variant) As Boolean
Parameters
| Parameter | Required | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
CommId |
Yes |
The ID of the comm device for which to retrieve a property. |
||||||||||||||
|
DestNetAddr |
Yes |
The destination IP address. |
||||||||||||||
|
DestNetPort |
Yes |
The destination port. |
||||||||||||||
|
PropId |
Yes |
The ID of the property to retrieve. The following values for the PropId parameter are supported for the TcpIpMp Device Property:
|
||||||||||||||
|
Value |
Yes |
The property value returned by this method. |
Example
The following example retrieves the KACHR property from the comm device that has a Comm Device ID of TCPMULTI.
Sub
Dim vValue
DdsClient.GetRemoteDestinationOverrideProperty "TCPMULTI", "127.0.0.1", 3000,"KACHR", vValue
MsgBox vValue
End Sub
GetTextFromBinaryHex
The GetTextFromBinaryHex method converts binary hex string values into a human-readable string format.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
GetTextFromBinaryHex(BinHex As String) As String
Parameters
| Parameter | Description |
|---|---|
|
BinHex |
The binary hex string value to be converted into a human-readable string format. |
Return Values
This method has no return value.
Example
The following example converts the sample binary hex value into the human-readable message: You have converted binhex!
Dim objDdsClient : Set objDdsClient = CreateObject("CxDds.DdsClient")
Dim strBinHex
Dim strOutput
strBinHex = "596f75206861766520636f6e7665727465642062696e68657821"
strOutput = objDdsClient.GetTextFromBinaryHex(strBinHex)
WScript.Echo strOutput
GetUisCommandInfo
The GetUisCommandInfo method gets UIS command info in XML format for the specified facility and Command Name. This method can return a maximum of one UIS command per parent device specified.
Syntax
GetUisCommandInfo(FacilityId As String, UisCmdName As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
FacilityId |
Yes |
The ID of the facility. |
|
UisCmdName |
Yes |
The name of the UIS Command the information will be retrieved from. |
Example
The following method gets information for a specified UIS Command Name in XML format, and stores it in a rich text box.
Sub GetUisInfo()
Dim strUisInfo
Dim strCommName
'Get facility ID
Dim strFacilityId
strFacilityId = edtFacilityId.Text
'Get Comm info and store in Rich Text Box
strCommName = edtCommName.Text
strUisInfo = DdsClient.GetUisCommandInfo(strFacilityId,strCommName)
rtbXML.Text = strUisInfo
End Sub
GetUisCommandInfoDetails
The GetUisCommandInfoDetails method retrieves UIS Command info with extended details in XML format for the specified facility and Command Name.
Syntax
GetUisCommandInfoDetails(FacilityId As String, UisCmdName As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
FacilityId |
Yes |
The ID of the facility for which to retrieve UIS command info details. |
|
UisCmdName |
Yes |
The name of the command for which to retrieve UIS command info details. |
Remarks
This method can return a maximum of one UIS command per parent device specified.
Example
The following example retrieves UIS command info for the command RTUCFGGET and the facility that has a Facility ID of FLOWAUTOAP15.
Sub
Dim strXml
strXml = DdsClient.GetUisCommandInfoDetails("FLOWAUTOAP15", "RTUCFGGET")
MsgBox strXml
End Sub
ImportDevices
The ImportDevices method imports devices from an XML string into the connected DDS.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
ImportDevices(DeviceIdArray As Variant, Xml As String, PurgeExisting As Boolean) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DeviceIdArray |
Yes |
The array of device IDs to import. The device IDs in this array must match the device IDs in the XML. This method will only import devices from the XML whose IDs exist in this array. |
|
Xml |
Yes |
The XML representing devices to import. The format of this XML must match the format of XMLs generated from device exports. |
|
PurgeExisting |
Yes |
If this property is set to true, the method will delete an existing device if a device with the same is imported. If this property is set to false, devices with existing IDs will not be imported. |
Example
The following example imports a device that has a Device ID of FLOWAUTOAP15 from a device XML file.
Sub
dim fso, txtFile, strText
Set fso = CreateObject("Scripting.FileSystemObject")
Set txtFile = fso.OpenTextFile("C:\mydevice.xml")
strText = txtFile.ReadAll
Dim aryDeviceIds
ReDim aryDeviceIds(1)
aryDeviceIds(0) = "FLOWAUTOAP15"
DdsClient.ImportDevices aryDeviceIds, strText, true
txtFile.Close
End Sub
InstallDevTemplateFromFile
The InstallDevTemplateFromFile method installs a device template from a file.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
InstallDeviceTemplateFromFile(FileName As String) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
FileName |
Yes |
The full path to the file containing the template to be installed. |
Remarks
The format of the template file must match that of the files created by ExtractDevTemplateToFile.
Example
The following example installs a device template from a file.
InstallDevTemplateFromXml
The InstallDevTemplateFromXml method installs a device template from an XML string.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
InstallDeviceTemplateFromXml(Xml As String) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
Xml |
Yes |
The XML representing the template to be installed. |
Remarks
The format of the XML must match that of the XML files created by ExtractDevTemplateToFile.
Example
The following example installs a device template from a file.
Sub
dim fso, txtFile, strXml
Set fso = CreateObject("Scripting.FileSystemObject")
Set txtFile = fso.OpenTextFile("C:\mytemplate.xml")
strXml = txtFile.ReadAll
DdsClient.InstallDevTemplateFromXml strXml
txtFile.Close
End Sub
ReadUisCmdItem
The ReadUisCmdItem method gets UIS command info in XML format for the specific unique database key (DbKey). This function will return exactly one command.
Syntax
ReadUisCmdItem(DbKey As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DbKey |
Yes |
The database key (DbKey) (Level 2) of the desired UIS Command. |
Example
The following method gets information relating to a UIS Command using a database key (DbKey). The info is stored in a rich text box in XML format.
Sub ReadUisInfo()
Dim strUisInfo
Dim strDbKey
'Get facility ID
Dim strFacilityId
strFacilityId = edtFacilityId.Text
'Get Database Key, retrieve cmd info, store in rich text box
strDbKey = edtKey.Text
strUisInfo = DdsClient.ReadUisCmdItem(strDbKey)
rtbXML.Text = strUisInfo
End Sub
SetActiveCommLine
The SetActiveCommLine method sets whether to use the Primary or an alternate communication line.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
SetActiveCommLine(DeviceId As String, Value As Integer) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DeviceId |
Yes |
The user-defined, unique device identifier. |
|
Value |
Yes |
Integer that specifies that sets which communication line to use. 1 - Primary, 2 - Device2, 3 - Device3. |
Example
The following method sets the Active Communication Line of a specific device to the secondary communication line.
Sub SetCommSecondary()
'Get Device ID
Dim strDeviceId
strDeviceId = edtDeviceID.Text
'Set active comm line to secondary
Dim iVal
Dim bSuccess
iVal = 2
bSuccess = DdsClient.SetActiveCommLine (strDeviceId, iVal)
If bSuccess = False Then
msgbox "Error in setting active comm line"
End If
End Sub
SetCommDevProperty
The SetCommDevProperty method sets a communications device parameter by data group element.
Syntax
SetCommDevProperty(CommDev As String, Deid As String, Value As Variant) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
CommDev |
Yes |
The name of the communications device. |
|
Deid |
Yes |
The data group element ID (DEID) of the property to retrieve. |
|
Value |
Yes |
The value of the property. This variant will have a subtype relevant to the property being set. |
Remarks
The return value is a Boolean indicating the success of the value assignment. An error will occur if the value is not of a compatible subtype with the Deid parameter (i.e., a DevType data group element can’t accept a Boolean value).
Example
The following method gets the enabled state for a given device (True or False) using the GetCommDevProperty method. It then toggles the value and sends it back to the DDS using SetCommDevProperty.
Sub ToggleDeviceEnabledState (deviceName)
Dim valEnabled
'Get the current enabled state and toggle it
DdsClient.GetCommDevProperty deviceName, "DevEnabled", valEnabled
If valEnabled = True then
valEnabled = False
ElseIf valEnabled = False Then
valEnabled = True
Else
MsgBox "Unable to retrieve property value from device. "
Exit Sub
End If
'Set enabled state
DdsClient.SetCommDevProperty deviceName, "DevEnabled", valEnabled
End Sub
SetCommFailoverAndActiveLine
The SetCommFailoverAndActiveLine method sets whether communication failover is enabled or disabled, and whether to use the primary or an alternate communication line.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
SetCommFailoverAndActiveLine(DeviceId As String, ValueFailover As Variant, ValueActiveLine As Variant) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DeviceId |
Yes |
The user-defined, unique device identifier. |
|
ValueFailover |
Yes |
Value that represents the state of AutoFailover. 0 = Disabled, 1 = Enabled. |
|
ValueActiveLine |
Yes |
Value that represents the Active Communication Line. 1 - Primary, 2 - Device2, 3 - Device3. |
Example
The following method disables Auto Failover and sets the Active Communication Line to primary for a specified device.
Sub ButtonTool4_EventClick()
Dim This : Set This = ButtonTool4
'Get Device ID
Dim strDeviceId
strDeviceId = edtDeviceID.Text
'Disable Auto Failover, set Active Comm to primary
Dim vValueFailover
Dim vValueActiveLine
vValueFailover = 0
vValueActiveLine = 1
DdsClient.SetCommFailoverAndActiveLine strDeviceId, vValueFailover, vValueActiveLine
End Sub
SetCommFailoverEnabled
The SetCommFailoverEnabled method sets communication failover enabled state.
Syntax
SetCommFailoverEnabled(DeviceId As String, Value As Variant) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DeviceId |
Yes |
The user-defined, unique device identifier. |
|
Value |
Yes |
Value that represents the state of AutoFailover. 0 = Disabled, 1 = Enabled. |
Example
The following method toggles whether Communication Failover is set to True or False.
Sub ChangeFailover()
'Get Device ID
Dim strDeviceId
strDeviceId = edtDeviceId.Text
'Get current value. If True, change to False. If False, change to True
Dim Value
DdsClient.GetCommFailoverEnabled DeviceId, Value
If Value = True Then
DdsClient.SetCommFailoverEnabled strDeviceId, False
Else
DdsClient.SetCommFailoverEnabled strDeviceId, True
End If
End Sub
SetDataGroupProperty
The SetDataGroupProperty method sets a given data group property based on a property ID.
Syntax
SetDataGroupProperty(DeviceId As String, DataGroupType As String, DataGroupOrdinal As Integer, PropID As String, DataGroupPropValue As Variant)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DeviceId |
Yes |
The user-defined, unique device identifier. |
|
DataGroupType |
Yes |
The unique data group identifier. Case sensitive. |
|
DataGroupOrdinal |
Yes |
The ordinal or instance of the data group type specified. Should be within the range defined by applicable device template file attributes, like baseOrd and maxCnt, which constrain the number of ordinals possible for a data group type. |
|
PropID |
Yes |
The ID of the data group property to get or set. The following keyword values are supported:
|
|
DataGroupPropValue |
Yes |
The value of the property. |
Remarks
The Boolean return value indicates the success of the function. A value must be of the proper type for the PropID.
Example
The following function uses GetDataGroupProperty to obtain the current visibility of the Basic Poll data group, then uses SetDataGroupProperty to toggle it. The return value of the function is the success of the SetDataGroupProperty method.
Function ToggleDGVisible ()
Dim bVisible
' Get the current visiblity
bVisible = DdsClient.GetDataGroupProperty("METER206", "BasicPoll", 0, "visible")
'Toggle the visibility
If bVisible = True Then
bVisible = False
Else
bVisible = True
End If
'Set the visibility
ToggleDGVisible = DdsClient.SetDataGroupProperty("METER206", "BasicPoll", 0, "visible", bVisible)
End Function
SetDeviceProperty
The SetDeviceProperty method sets a device property by a specified data group element.
Syntax
SetDeviceProperty(DevId As String, Deid As String, Value As Variant) As Boolean
Parameters
| Parameter | Required | Description | ||||
|---|---|---|---|---|---|---|
|
DevId |
Yes |
The user-defined, unique device identifier. The DeviceID for which to set a property. |
||||
|
Deid |
Yes |
The data group element ID (DEID) representing the property to set. This property must be one of the following values:
|
||||
|
Value |
Yes |
The value of the property to set. |
Example
The following example sets the DevDesc property for a device that has a Device ID of FLOWAUTOAP15.
SetRemoteCommOverrideProperty
The SetRemoteCommOverrideProperty method sets a remote device comm override property.
Syntax
SetRemoteCommOverrideProperty(DevId As Variant, PropId As Variant, CommLine As Integer, Value As Variant) As Boolean
Parameters
| Parameter | Required | Description | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
DevId |
Yes |
The user-defined, unique device identifier. The DeviceId for which to set a property. |
||||||||||||||||||||||
|
PropId |
Yes |
The ID of the property to set. The following values for the PropId parameter are supported for a Modem Device Property :
The following values for the PropId parameter are supported for the TcpMp and Udp Device Property:
|
||||||||||||||||||||||
|
CommLine |
Yes |
The number of the comm device for which to set a property. This value can be 1 (for Primary), 2 (for Device 2), or 3 (for Device 3). If an invalid value is specified, it will default to 1. |
||||||||||||||||||||||
|
Value |
Yes |
The value of the property to set. |
Example
The following example sets the TPHN property of the primary comm device of the remote device that has a Device ID of FLOWAUTOAP15.
Sub
DdsClient.SetRemoteCommOverrideProperty "FLOWAUTOAP15", "TPHN", 1, "867-5309"
End Sub
SetRemoteDestinationOverrideProperty
The SetRemoteDestinationOverrideProperty method sets a remote destination override property for a TCP/IP MultiPoint device.
Syntax
SetRemoteDestinationOverrideProperty(CommId As Variant, DestNetAddr As Variant, DestNetPort As Integer, PropId As Variant, Value As Variant) As Boolean
Parameters
| Parameter | Required | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
CommId |
Yes |
The ID of the comm device for which to set a property. |
||||||||||||||
|
DestNetAddr |
Yes |
The destination IP address. |
||||||||||||||
|
DestNetPort |
Yes |
The destination port. |
||||||||||||||
|
PropId |
Yes |
The ID of the property to set. The following values for the PropId parameter are supported for the TcpIpMp Device Property:
|
||||||||||||||
|
Value |
Yes |
The value of the property to set. |
Example
The following example sets the KAFRQ property for the comm device that has a Comm ID of TCPMULTI.
Sub
DdsClient.SetRemoteDestinationOverrideProperty "TCPMULTI", "127.0.0.1", 3000,"KAFRQ", 60
End Sub
UpdateDataGroupTransaction
The UpdateDataGroupTransaction method modifies a single transaction in a data group defined by the database key (DbKey) in the data group transaction header in XML format.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
UpdateDataGroupTransaction(ByVal strDataGroupTxHdrIn, ByVal strDataGroupTxDataIn, ByRef strDataGroupTxHdrOut)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DataGroupTxHdrIn |
Yes |
The data group transaction's header. A string containing an XML segment. |
|
DataGroupTxDataIn |
Yes |
The data group transaction's data. A string containing an XML segment. |
|
DataGroupTxHdrOut |
Yes |
The data group's newly added transaction's header. A string containing an XML segment. |
Example
The following example updates a data group transaction using the data group header and data in XML string format.
Sub UpdateDataGroupTransaction ()
Dim hdr As String = "<txHdr dbKey=""0000000116B0000004C0000013"" timestamp=""3/3/2022 14:18:56.909"" txType=""G"" txTypeTxt=""Get"" userId=""WFT\E261311"" statusCode=""3"" statusCodeTxt=""Succeeded"" statusMsg=""Succeeded"" ver=""1.1"" dataSize=""290"" hdrDataSize=""290"" idx=""00111"" appdef1=""0"" appdef2=""0"" appdef3=""0"" appdef4=""0"" quality=""U"" qualityTxt=""Unknown"" partialData=""0"" cmprsSize=""0"" blobCnt=""0""/>"
Dim dta As String = "<dgData xmlns:dt=""urn:schemas-microsoft-com:datatypes"">" & vbCrLf & vbTab & "<RegNum dt:dt=""ui4"" desc=""Register Number"" type=""ui4"">111</RegNum>" & vbCrLf & vbTab & "<DataType desc=""Data Type"" type=""string"">ui2</DataType>" & vbCrLf & vbTab & "<Desc desc=""Description"" type=""string""/>" & vbCrLf & vbTab & "<FacUdc desc=""Facility.UDC for Point Processing"" type=""string""/>" & vbCrLf & vbTab & "<Value dt:dt=""ui2"" desc=""Value"" type=""vrnt"">200</Value>" & vbCrLf & vbTab & "<UISCMDPRMS>DataType=ui2;DGORD=0;DGTYPE=SnglRegRw2;RegNum=111;</UISCMDPRMS>" & vbCrLf & vbTab & "<UISCMDTYPE>DG_F_DEV</UISCMDTYPE>" & vbCrLf & "</dgData>" & vbCrLf
Dim res = ddsClient.UpdateDataGroupTransaction(hdr, dta)
End Sub
UpdateDataGroupTransactionByFile
The UpdateDataGroupTransactionByFile methods modifies a transaction in a data group using an XML file containing the transaction.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
UpdateDataGroupTransactionByFile(ByVal strFilePath, ByRef strDataGroupTxHdrOut)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
FilePath |
Yes |
The path to the file containing the transaction in XML format. |
|
DataGroupTxHdrOut |
Yes |
The data group's newly added transaction's header. A string containing an XML segment. |
Example
The following example updates a data group transaction using an XML file containing the transaction.
Sub UpdateDataGroupTransactionByFile()
Dim res = ddsClient.UpdateDataGroupTransactionByFile("C:\temp\2.xml")
End Sub
UpdateUisCmdItem
The UpdateUisCmdItem method updates UIS command info from XML format for the specified database key (DbKey).
Syntax
UpdateUisCmdItem(DbKey As String, UisCmdInfoXml As String)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DbKey |
Yes |
The database key (DbKey) (Level 2) |
|
UisCmdInfoXml |
Yes |
The edited UIS Command information in XML format; the same format that the GetUisCommandInfo method returns. |
Remarks
The UpdateUisCmdItem method is used to update a UIS command's Command State, Command State Comments, Verification Flags 1-4, and Verification Comments. To update the Component Type, Data Group Type, Data Group Ordinal, Component Parameters, or Component Position, use the UpdateUISCommandCommandComponent method.
Example
The following method updates UIS command info with XML stored in a rich text box.
Sub UpdateUis()
'Get Device ID
Dim strDeviceId
strDeviceId = edtDeviceID.Text
'Update UIS info with XML data in a rich text box
Dim DbKey
Dim UisCmdInfoXML
DbKey = edtDbKey.Text
UisCmdInfoXML = rtbXML.Text
DdsClient.UpdateUisCmdItem DbKey, UisCmdInfoXML
End Sub
UpdateUISCommandComponent
The UpdateUISCommandComponent method modifies a component of a UIS command. It can be used to modify the Component Type, Data Group Type, Data Group Ordinal, Component Parameter, or Component Position for that UIS command component.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
UpdateUISCommandComponent(ComponentDbKey As String, ComponentType As String, DataGroupType As String,DataGroupOrdinal As Integer,ComponentParams As String,ComponentPosition As Integer)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
ComponentDbKey |
Yes |
The database key (DbKey) of the UIS command component being modified. |
|
ComponentType |
Yes |
The component type identifier of the UIS command component. |
|
DataGroupType |
Yes |
The unique data group identifier. Case sensitive. The DataGroupType of the UIS command component. |
|
DataGroupOrdinal |
Yes |
The ordinal or instance of the data group type specified. Should be within the range defined by applicable device template file attributes, like baseOrd and maxCnt, which constrain the number of ordinals possible for a data group type. |
|
ComponentParams |
Yes |
A semicolon-delimited list of parameter name/value pairs for the UIS command component. Note:The maximum length of the command parameter string for a Send UIS Command message is 1200 characters. CygNet Software will report if a UIS Command message exceeds the maximum parameter length of 1200 characters. |
Example
The following script updates the UIS command component that has a database key of dbComponentKey, by providing a new Component Type, Data Group Type, Data Group Ordinal, Component Parameters.
ddsClient.UpdateUISCommandComponent dbComponentKey, "DG_F_DEV", "DynaCard", 1, "Cnt=1;"
ValidateDevTemplateFromFile
The ValidateDevTemplateFromFile method validates a device template file.
Note: This method supports multithreading or the concurrent execution of multiple threads.
Syntax
ValidateDevTemplateFromFile(FileName As String) As Boolean
Parameters
| Parameter | Required | Description |
|---|---|---|
|
FileName |
Yes |
The path to the file to be validated. |
Example
The following example validates a device template file.
Sub
Dim bRet
bRet = DdsClient.ValidateDevTemplateFromFile("C:\mytemplate.xml")
MsgBox bRet
End Sub
