DdsClient Methods

Scripting > CxDds > DdsClient Object > DdsClient Methods

DdsClient Methods

The DdsClient object contains the following methods:

AddDataGroupElementMappings
CompareTemplatesFile
CompareTemplatesFileDlg
CompareTemplatesXml
CompareTemplatesXmlDlg
Connect
CreateDataGroup
CreateUISCommand
CreateUISCommandComponent
DeleteDataGroup
DeleteDataGroupElementMappings
DeleteDevice
DeleteDevTemplate
DeleteRemoteCommOverrideProperty
DeleteRemoteDestinationOverrideProperty
DeleteUISCommand
DeleteUISCommandComponent
Disconnect
ExportDevices
ExtractDevTemplateToFile
GetActiveCommLine
GetAssociatedUisName

GetBinaryHexFromText
GetCommDevProperty
GetCommFailoverEnabled
GetConsoleData
GetDataGroupElementMappings
GetDataGroupInfo
GetDataGroupProperty
GetDataGroupTransactionData
GetDataGroupTransactions
GetDataGroupTransactionsByKey
GetDataGroupTxDataWithRefs
GetDataGroupTxHeader
GetDeviceIdFromFacilityId
GetDeviceIdListFromFacilityId
GetDeviceIdsByCategory
GetDeviceIdsByPrimaryCommId
GetDeviceProperty
GetDeviceTemplate
GetFacilityLinks
GetMappedDGElementInfo
GetRecentSuccessfulDataGroupsTXs

GetReferences
GetRemoteCommOverrideProperty
GetRemoteDestinationOverrideProperty
GetTextFromBinaryHex
GetUisCommandInfo
GetUisCommandInfoDetails
ImportDevices
InstallDevTemplateFromFile
InstallDevTemplateFromXml
ReadUisCmdItem
SetActiveCommLine
SetCommDevProperty
SetCommFailoverAndActiveLine
SetCommFailoverEnabled
SetDataGroupProperty
SetDeviceProperty
SetRemoteCommOverrideProperty
SetRemoteDestinationOverrideProperty
UpdateUisCmdItem
UpdateUISCommandComponent
ValidateDevTemplateFromFile

AddDataGroupElementMappings

The AddDataGroupElementMappings method is used to add UDC mapping 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), duplicate mapping is not added.

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

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

CompareTemplatesFile

The CompareTemplatesFile method compares two device templates from file and returns the comparison as XML.

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 returned XML contains a line-by-line comparison of the template files. The following is an example of two template files, and the XML which results from their comparison.

File 1:

</dgElements>

</SysInfo>

</dataGroups>

</defUisCmds>

</deviceDefinition>

File 2:

</dgElements>

</SysInfo>

</dataGroups>

</defUisCmds>

</deviceDefinition>

Result XML:

</DG1>

</dgElements>

</SysInfo>

</dataGroups>

</deviceDefinition>

Example

The following example compares two device templates 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 templates from file and pops the standard comparison dialog.

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.

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 returned XML contains a line-by-line comparison of the template files. The following is an example of two template XMLs, and the XML which results from their comparison.

Template XML 1:

</dgElements>

</SysInfo>

</dataGroups>

</defUisCmds>

</deviceDefinition>

Template XML 2:

</dgElements>

</SysInfo>

</dataGroups>

</defUisCmds>

</deviceDefinition>

Result XML:

</DG1>

</dgElements>

</SysInfo>

</dataGroups>

</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 pops the standard comparison dialog.

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.

Sub

DdsClient.CompareTemplatesFileDlg g_strXml1, g_strXml2

End Sub

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. A domain is optional. The service must be a valid DDS.

Remarks

Returns 0 if successful and a non-zero value if the connection failed.

Example

The following example connects the DdsClient object to the CYGDEMO.DDS on domain 5410:

Sub DdsConnect()

'Connect to a DDS

Dim DdsClient

Set DdsClient = CreateObject("CxDds.DdsClient")

DdsClient.Connect("[5410]CYGDEMO.DDS")

End Sub

CreateDataGroup

The CreateDataGroup method is used to create a data group, including its data group elements.

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. 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 JJJ"

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

Syntax

CreateUISCommand(DeviceId As String, CommandName As String, CommandDescription As String,FacilityId As String) As String

Parameters

Parameter	Required	Description
DeviceId	Yes	The device ID 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 for that component.

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 of the UIS command associated with the new component.
ComponentType	Yes	The component type identifier of the UIS component being added.
DataGroupType	Yes	The data group type identifier of 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.

Example

The following script creates a UIS command component and adds it to the UIS command that has a database key 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.

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 created.
DataGroupType	Yes	The unique data group identifier. 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 constant password required to enable DeleteDataGroup. It is used as a precaution to keep a data group from being accidentally deleted. The string value is DeleteDataGroup_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 JJJ"

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.

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

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

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

DeleteDevice

The DeleteDevice method deletes a device. There is NO "undo" if a device is deleted, so use this function with extreme caution.

Syntax

DeleteDevice(DeviceId As String, SecuritySentinel As String)

Parameters

Parameter	Required	Description
DeviceId	Yes	The ID of the device to delete.
SecuritySentinel	Yes	A string sentinel (static password) to ensure a device isn’t accidentally deleted. The sentinel is DeleteDevice_ThereIsNoUndo.

Remarks

There is NO "undo" for deleting a device.

Example

The following example deletes a device with the Device ID of MYDEVICE.

Sub

DdsClient.DeleteDevice "MYDEVICE", "DeleteDevice_ThereIsNoUndo"

End Sub

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.

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	A string sentinel (static password) to ensure a device template isn’t accidentally deleted. The sentinel is DeleteDevTemplate_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 ID of the device 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:

"MCON"	Maintain connection
"CONI"	Connect interval
"CIDL"	Close on idle
"MIDL"	Maximum idle time
"DOKA"	Do keep alive
"KACHR"	Keep-alive character
"KAFRQ"	Keep-alive frequency

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.

Syntax

DeleteUISCommand(CommandDbKey As String)

Parameters

Parameter	Required	Description
CommandDbKey	Yes	Database key of the command being deleted.

Example

The following script deletes the UIS command that has a database key of dbCommandKey.

ddsClient.DeleteUISCommand dbCommandKey

DeleteUISCommandComponent

The DeleteUISCommandComponent method deletes a component of a UIS command.

Syntax

DeleteUISCommand(ComponentDbKey As String)

Parameters

Parameter	Required	Description
ComponentDbKey	Yes	The database key of the component being deleted.

Example

The following script deletes the UIS command component that has a component key of dbComponentKey.

ddsClient.DeleteUISCommandComponent dbComponentKey

Disconnect

The Disconnect method disconnects from the service.

Syntax

Disconnect() As Integer

Remarks

Returns 0 if successful and a non-zero value if the disconnect failed.

Example

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.

Syntax

ExportDevices(DeviceIdArray As Variant) As String

Parameters

Parameter	Required	Description
DeviceIdArray	Yes	An array of IDs of devices 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.

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.

Syntax

GetActiveCommLine(DeviceId As String, Value As Variant) As Boolean

Parameters

Parameter	Required	Description
DeviceId	Yes	The ID of the device.
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.

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

Function GetUISName (ddsName)

'Return the UIS name

GetUISName = DdsClient.GetAssociatedUisName()

End Function

GetBinaryHexFromText

The GetBinaryHexFromText method converts ascii text into binary hex string values.

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

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 ID of the device.
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 = DdsClient.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)) + ","

strMsg = strMsg + vbCr

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)) + ","

strMsg = strMsg + vbCr

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.

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

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

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

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.

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

Syntax

GetDataGroupProperty(DeviceId As String, DataGroupType As String, DataGroupOrdinal As Integer, PropID As String)

Parameters

Parameter	Required	Description
DeviceId	Yes	The ID of the device.
DataGroupType	Yes	The data group type. 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: datagroupspecificdata dbKey desc facility metadata sysFlags sysFlags.appReserved1 sysFlags.txScrubIndexBased sysFlags.userDefined txFailMax txRepl txRetType txSuccDays txSuccMax txSuccMin visible webEnabled

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 key.

Syntax

GetDataGroupTransactionData(TransactionKey As String) As String

Parameters

Parameter	Required	Description
TransactionKey	Yes	The key 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>

Example

The following subroutine takes a transaction key, 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 ID of the device.
DataGroupType	Yes	The data group type of the data group. 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.

<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 data group’s database key. This key is retrieved in the dbkey field 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.

<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 for the Basic Poll data group on the METER206 facility, then gets its transaction data and saves it to a file.

<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 the data group transaction data in XML format with reference information for the specified transaction key.

Syntax

GetDataGroupTxDataWithRefs(TransactionKey As String) As String

Parameters

Parameter	Required	Description
TransactionKey	Yes	The level three transaction key for the desired data group. Transaction key is 26 digits.

Example

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 Sub

GetDataGroupTxHeader

The GetDataGroupTxHeader method gets the data group transaction header in XML format for the specified transaction key.

Syntax

GetDataGroupTxHeader(TransactionKey As String) As String

Parameter

Parameter	Required	Description
TransactionKey	Yes	The key 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 transaction key 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 Sub

The data group transaction header XML might look like this:

<txHdr dbKey="0000001039B0000001C0000001" timestamp="2/3/2014 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.

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.

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)

End Sub

GetDeviceIdsByCategory

The GetDeviceIdsByCategory method gets all devices IDs in the specified category.

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)

End Sub

GetDeviceIdsByPrimaryCommId

The GetDeviceIdsByPrimaryCommId method gets all devices IDs on the specified primary comm ID.

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)

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 device ID 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:

comm_failover_enabled
comm_selection
comm_specific_info
CommAddr
CommPort
cryout_enabled
DevAddr
DevCat
DevCommId
DevCommId1
DevCommId2
DevCommId3
DevDesc
DevEnabled
device_class
device_manufacturer
device_model
device_rev
device_specific_info
DevID
DevType
failback_on_failure
failover_available2
failover_available3
failover_control_msgs
failover_restore_secs
failover_restore_secs2
failover_restore_secs3

failover_secs
failover_secs_subs1
failover_secs_subs2
failover_secs_subs3
failover_secs1
failover_secs2
failover_secs3
failover_seq
HostMode
message_delay
message_delay1
message_delay2
message_delay3
message_timeout
message_timeout1
message_timeout2
message_timeout3
MsgDelay
MsgRetries
MsgTmOut
polling_attempt_limit
polling_attempt_limit1
polling_attempt_limit2
polling_attempt_limit3
SecAppl
SecEvent
timezone_key
wake_enabled

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.

Syntax

GetDeviceTemplate(DeviceId As String) As String

Parameters

Parameter	Required	Description
DeviceId	Yes	The ID of the device.

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.

Syntax

GetFacilityLinks(DeviceId As String, FacilityLinkInfo As Variant)

Parameters

Parameter	Required	Description
DeviceId	Yes	The ID of the device.
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))

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.

</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 ID of the device.
DataGroupType	Yes	The data group type.
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.

<DGTx0 device="BART-SOCK" facility="BART-SOCK" dgType="Exceptions" ordinal="0" _

dbKey="0000000008B0000005C0000026" timestamp="2/24/2006 17:23:31.655" txType="G" _

txTypeTxt="Get" userId="VSI\alex.tyler" statusCode="3" statusCodeTxt="Succeeded" _

statusMsg="Succeeded" ver="1.1" dataSize="1708" hdrDataSize="300" idx="" _

cmprsSize="547" blobCnt="1"/>

</dgTxList>

Example

'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 gets data for the services the DDS client references.

Syntax

GetReferences() As Integer.

Example

The 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 ID of the device 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 :

"TCONR"	Number of connect retries
"THPNA"	Alternate telephone number
"THUAM"	Hang up after messages
"TIDLE"	Maximum idle time
"TMDIS"	Minimum disconnect time
"TMIDL"	Minimum idle time
"TMINI"	Modem initialization string
"TPHN"	Telephone number
"TTCON"	Maximum time to connect

The following values for the PropId parameter are supported for the TcpMp and Udp Device Property:

"DSTA"	Destination address
"DSTP"	Destination port

The following values for the PropId parameter are supported for the BsapIp Device Property:

"DSTA"	Destination address
"DSTPS"	Destination standard port
"DSTPT"	Destination time sync port

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:

"CIDL"	Close on idle
"CONI"	Connect interval
"DOKA"	Do keep alive
"KACHR"	Keep-alive character
"KAFRQ"	Keep-alive frequency
"MCON"	Maintain connection
"MIDL"	Maximum idle time

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.

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.

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.

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.

Sub

DdsClient.InstallDevTemplateFromFile "C:\mytemplate.xml"

End Sub

InstallDevTemplateFromXml

The InstallDevTemplateFromXml method installs a device template from an XML string.

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 key. This function will return exactly one command.

Syntax

ReadUisCmdItem(DbKey As String) As String

Parameters

Parameter	Required	Description
DbKey	Yes	The level 2 database key of the desired UIS Command.

Example

The following method gets information relating to a UIS Command using a database key. 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.

Syntax

SetActiveCommLine(DeviceId As String, Value As Integer) As Boolean

Parameters

Parameter	Required	Description
DeviceId	Yes	The ID of the device.
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.

Syntax

SetCommFailoverAndActiveLine(DeviceId As String, ValueFailover As Variant, ValueActiveLine As Variant) As Boolean

Parameters

Parameter	Required	Description
DeviceId	Yes	The ID of the device.
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 - Device 2, 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 ID of the device.
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 device ID.
DataGroupType	Yes	The data group type. 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: datagroupspecificdata desc facility metadata sysFlags sysFlags.appReserved1 sysFlags.txScrubIndexBased sysFlags.userDefined txFailMax txRepl txRetType txSuccDays txSuccMax txSuccMin visible webEnabled
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 device ID 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:

comm_failover_enabled
comm_selection
comm_specific_info
CommAddr
CommPort
cryout_enabled
DevAddr
DevCat
DevCommId
DevCommId1
DevCommId2
DevCommId3
DevDesc
DevEnabled
device_class
device_manufacturer
device_model
device_rev
device_specific_info
DevID
DevType
failback_on_failure
failover_available2
failover_available3
failover_control_msgs
failover_restore_secs
failover_restore_secs2
failover_restore_secs3

failover_secs
failover_secs_subs1
failover_secs_subs2
failover_secs_subs3
failover_secs1
failover_secs2
failover_secs3
failover_seq
HostMode
message_delay
message_delay1
message_delay2
message_delay3
message_timeout
message_timeout1
message_timeout2
message_timeout3
MsgDelay
MsgRetries
MsgTmOut
polling_attempt_limit
polling_attempt_limit1
polling_attempt_limit2
polling_attempt_limit3
SecAppl
SecEvent
timezone_key
wake_enabled

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.

Sub

DdsClient.SetDeviceProperty "FLOWAUTOAP15", "DevDesc", "New Desc"

End Sub

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 ID of the device 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 :

"TCONR"	Number of connect retries
"THPNA"	Alternate telephone number
"THUAM"	Hang up after messages
"TIDLE"	Maximum idle time
"TMDIS"	Minimum disconnect time
"TMIDL"	Minimum idle time
"TMINI"	Modem initialization string
"TPHN"	Telephone number
"TTCON"	Maximum time to connect

The following values for the PropId parameter are supported for the TcpMp and Udp Device Property:

"DSTA"	Destination address
"DSTP"	Destination port

The following values for the PropId parameter are supported for the BsapIp Device Property:

"DSTA"	Destination address
"DSTPS"	Destination standard port
"DSTPT"	Destination time sync port

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:

"CIDL"	Close on idle
"CONI"	Connect interval
"DOKA"	Do keep alive
"KACHR"	Keep-alive character
"KAFRQ"	Keep-alive frequency
"MCON"	Maintain connection
"MIDL"	Maximum idle time

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

UpdateUisCmdItem

The UpdateUisCmdItem method updates UIS command info from XML format for the specified key.

Syntax

UpdateUisCmdItem(DbKey As String, UisCmdInfoXml As String)

Parameters

Parameter	Required	Description
DbKey	Yes	Level 2 database key.
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.

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 of the UIS command component being modified.
ComponentType	Yes	The component type identifier of the UIS command component.
DataGroupType	Yes	The data group type identifier 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.

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.

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