The UisClient object contains the following methods:
The CanSendUISCommand checks whether the user has the right security to send a specified UIS command. Include any command components required for the UIS Command to be executed. Also see SendUisCommand for more examples.
CanSendUISCommand(ByVal FacilityID As String, ByVal Command As String, ByVal Parameters As String, ByRef strErrorOut) As Boolean
| Parameter | Required | Description |
|---|---|---|
| FacilityID | Yes |
The ID of the facility that has the UIS command. |
| Command | Yes | The name of the UIS command. |
| Parameters | Yes | Parameters (command components) that may be required for the UIS command. Use an empty string if none are specified. |
Example
The following example will to check if a UISCommand of STATUS is valid and can be sent to UIS or not. Parameters include the Datagroup Ordinal (DGORD parameter) and the Datagroup Type (DGTYPE parameter) which are listed in the UIS definition in the DDS. The method returns True if it succeeded and False if an error occurred.
|
statusStr = uisClient.CanSendUISCommand("WELL_RD_1", "DG_F_DEV", "DGORD=0;DGTYPE=StatusData", errorCode)
msgbox statusStr |
The following example lists multiple parameters separated by semicolons. The method returns True if it succeeded and False if an error occurred.
|
statusStr1 = uisClient.CanSendUISCommand("WELL_RD_1", "DG_T_DEV", "DGORD=0;DGTYPE=CmdCfgMsg;parmID=523;parmID=524", errorCode)
msgbox statusStr1 |
The following example executes both the CanSendUISCommand and SendUISCommand methods.
|
Sub UISCommandButton1_EventClick() Dim This : Set This = UISCommandButton1
Dim GlobalFunctions Set GlobalFunctions = CreateObject("CxScript.GlobalFunctions") Call GlobalFunctions.EnableLiveMode (True)
Dim uisClient Dim statusStr, errorCOde, statusStr1 Set uisClient = CreateObject("CxUis.UisClient") uisClient.Connect("CYGNET.UIS") statusStr = uisClient.CanSendUISCommand("WELL_RD_1", "DG_F_DEV", "DGORD=0;DGTYPE=StatusData", errorCode) msgbox statusStr statusStr1 = uisClient.CanSendUISCommand("WELL_RD_1", "DG_T_DEV", "DGORD=0;DGTYPE=CmdCfgMsg;parmID=523;parmID=524", errorCode) msgbox statusStr1
uisClient.SendUISCommand "WELL_RD_1", "DG_F_DEV", "DGORD=0;DGTYPE=StatusData", "" uisClient.SendUISCommand "WELL_RD_1", "DG_T_DEV", "DGORD=0;DGTYPE=CmdCfgMsg;parmID=523;parmID=524", "" End Sub |
The Connect method connects the object to a service.
Connect(DomainSiteService As String)
| Parameter | Required | Description |
|---|---|---|
|
DomainSiteService |
Yes |
The [Domain]Site.Service to which to connect. A domain is optional. The service must be a valid UIS. |
Returns 0 if successful and a non-zero value if the connection failed.
Example
The following example connects the UisClient object to the CYGDEMO.UIS on domain 5410:
|
Sub UisConnect() 'Connect to a UIS Dim UisClient Set UisClient = CreateObject("CxUis.UisClient") UisClient.Connect("[5410]CYGDEMO.UIS") End Sub |
The CreateDataArray method creates a data array for sending and receiving data (via GetAndSendData).
CreateDataArray(Items As Variant, DataInfoArray As Variant) As Boolean
| Parameter | Required | Description |
|---|---|---|
|
Items |
Yes |
The number of rows in the array. |
|
DataInfoArray |
Yes |
Input/Output. The array that is created. |
CreateDataArray creates a two-dimensional array whose rows can be filled with the UpdateDataArrayRow method. These methods are used for sending multiple data group element or UDC values to a device. One row represents one data group element or UDC.
Example
See the GetAndSendData method for an example.
The DeleteQueueEntry method deletes a queue entry from a pending UIS queue.
DeleteQueueEntry(QueueName As String, UisSessionToken As String, QueueEntryId As String, ErrorOut) As Boolean
| Parameter | Required | Description |
|---|---|---|
|
QueueName |
Yes |
The name of the UIS queue. |
|
UisSessionToken |
Yes |
|
|
QueueEntryId |
Yes |
|
|
ErrorOut |
Yes |
Output. The returned error string or empty string on success. |
The Disconnect method disconnects from the service.
Disconnect() As Integer
Returns 0 if successful and a non-zero value if the disconnect failed.
The GetAndSendData method sends data to and gets data from a device.
GetAndSendData(DataInfoArray As Variant, Items As Variant, OutError As String, [ShowWaitDlg As Variant], [FromDeviceParams As String], [ToDeviceParams As String]) As Boolean
| Parameter | Required | Description |
|---|---|---|
|
DataInfoArray |
Yes |
Input/Output. The data array. |
|
Items |
Yes |
The number of rows from the array to send. |
|
OutError |
Yes |
Stores an error message if an error occurs. |
|
ShowWaitDlg |
Yes |
Indicates whether to show a status dialog box when the method is being executed (True) or not (False). |
|
FromDeviceParams |
Yes |
Parameters that may be required when getting from the device. Usually an empty string is passed. |
|
ToDeviceParams |
Yes |
Parameters that may be required when sending to the device. Usually an empty string is passed. |
This method sends multiple data group element or UDC values, each represented by a single row in DataInfoArray. The array is created using CreateDataArray and filled using UpdateDataArrayRow (see method specifications above).
Example
The following method creates a data array with three rows to be sent to the OpCode data group. Each row represents a data group element, with a value being generated based on the row number (for testing). The row values are viewed using the ParseDataArrayRow method, then the data is sent to the RTU1 device.
|
Sub OpCodeUpdateTest () Dim uisClient, arrData, i, strError, nRows Dim strDEID, strDesc, strSendVal, strRecVal Dim strFacility, strDatagroup, iOrdinal, strUDC
Set uisClient = CreateObject("CxUis.UisClient") uisClient.Connect("CYGDEMO.UIS") uisClient.CreateDataArray 3, arrData nRows = 3
'Update each row in the data array For i = 0 To nRows - 1 strDEID = "TableVal0" & CStr(i + 1) strDesc = "Table Value # " & CStr(i + 1) strSendVal = CStr(i * 10) strRecVal = CStr(i * -10)
uisClient.UpdateDataArrayRow arrData, i, "RTU1", "OpCodes",_ 1, strDEID, "", strDesc, strRecVal, strSendVal,_ True, True, strError Next
'Check the row values For i = 0 To nRows - 1 uisClient.ParseDataArrayRow arrData,i, strFacility, strDatagroup,_ iOrdinal, strDEID, strUDC, strDesc, strRecVal,_ strSendVal, True, True, strError MsgBox "Data Row " & CSTR(i) & " " & strFacility & ", " &_ strDatagroup & ", " & CSTR(iOrdinal) & ", " & strDEID &_ ", " & strUdc & ", " & strDesc & ", " & strRecVal &_ ", " & strSendVal Next
'Send the data uisClient.GetAndSendData arrData, nRows, strError, False, "", "" End Sub |
The GetAssociatedDdsName method gets the Device Definition Service name associated with the current UIS.
GetAssociatedDdsName() As String
Returns the DDS name in "site.service" format. Each UIS has exactly one associated DDS. The CxDds library has a similar method, GetAssociatedUisName(), 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 function returns a DDS name based on a UIS name.
|
Function GetDDSName (uisName) 'Create and initialize the UIS Client Dim uisClient Set uisClient = CreateObject("CxUis.UisClient") uisClient.Connect("CYGDEMO.UIS")
'Return the DDS name GetDDSName = uisClient.GetAssociatedDdsName() End Function |
This method is obsolete. Use DdsClient.GetCommDevProperty instead.
The GetConsoleData method returns the console text and display attributes as two 25x80 arrays of unsigned characters.
GetConsoleData(ByRef pText, ByRef pAttr) As Integer
| Parameter | Required | Description |
|---|---|---|
|
pText |
Yes |
A two-dimensional 25x80 array of console text attributes returned by this method. |
|
pAttr |
Yes |
A two-dimensional 25x80 array of console display attributes returned by this method. |
This method returns 0 if successful.
Example
The following example writes the console text and display attributes to a CSV file.
|
Sub Dim aryText, aryAttr, nRet nRet = UisClient.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 |
The GetDataGroupFromDeviceByKey method gets a data group from the device by database key.
GetDataGroupFromDeviceByKey(DataGroupKey As String, ShowWaitDlg As Boolean, FromDeviceParams As String, ToDeviceParams As String, OutError As String) As Boolean
| Parameter | Required | Description |
|---|---|---|
|
DataGroupKey |
Yes |
The database key for the data group. |
|
ShowWaitDlg |
Yes |
Indicates whether to show a status dialog box when the method is being executed (True) or not (False). |
|
FromDeviceParams |
Yes |
Parameters that may be required when getting from the device. Usually an empty string is passed. |
|
ToDeviceParams |
Yes |
Parameters that may be required when sending to the device. Usually an empty string is passed. |
|
OutError |
Yes |
Stores an error message if an error occurs. |
The GetDataGroupFromDeviceByKeyWithTxData method gets a data group from the device with transaction data.
GetDataGroupFromDeviceByKeyWithTxData(DataGroupKey As String, ShowWaitDlg As Boolean, MaxWaitTimeInMS As Integer, FromDeviceParams As String, OutDataGroupTxHdr, OutDataGroupTxData, OutError) As Boolean
| Parameter | Required | Description |
|---|---|---|
|
DataGroupKey |
Yes |
The database key for the data group. |
|
ShowWaitDlg |
Yes |
Indicates whether to show a status dialog box when the method is being executed (True) or not (False). |
|
MaxWaitTimeInMS |
Yes | |
|
FromDeviceParams |
Yes |
Parameters that may be required when getting from the device. Usually an empty string is passed. |
|
OutDataGroupTxHdr |
Yes | |
|
OutDataGroupTxData |
Yes | |
|
OutError |
Yes |
Stores an error message if an error occurs. |
The GetReferences method refreshes the list of services referenced by the connected service.
GetReferences() As Integer
Example
The following example refreshes the referenced services.
|
Sub GetReferences() 'Create and initialize the UIS Client Dim uisClient Set uisClient = CreateObject("CxUis.UisClient") uisClient.Connect("CYGDEMO.UIS")
uisClient.GetReferences() End Sub |
The ParseDataArrayRow method parses a row in the data array, returning individual values.
ParseDataArrayRow(DataInfoArray As Variant, Row As String, Facility As String, DataGroup As String, Ordinal As String, Deid As String, Udc As String, Prompt As String, RecValue As String, SendValue As String, GetFromDevice As Boolean, SendToDevice As Boolean, errorstring As String) As Boolean
| Parameter | Required | Description |
|---|---|---|
|
DataInfoArray |
Yes |
Input/Output. The array of data to be parsed. |
|
Row |
Yes |
The index of the row to be parsed (zero-based). |
|
Facility |
Yes |
Output. The facility ID. |
|
DataGroup |
Yes |
Output. The data group type. |
|
Ordinal |
Yes |
Output. The data group ordinal. |
|
Deid |
Yes |
Output. The data group element ID (DEID) to set. |
|
Udc |
Yes |
Output. The UDC to set. |
|
Prompt |
Yes |
The prompt text in the dialog box. |
|
RecValue |
Yes |
The value of the field that is received. |
|
SendValue |
Yes |
Output. The value of the field to set. |
|
GetFromDevice |
Yes |
Whether to get data from the device (True) or not (False). |
|
SendToDevice |
Yes |
Whether to send data to the device (True) or not (False). |
|
ErrorString |
Yes |
Stores an error message if an error occurs. |
This method parses a row in a two-dimensional array, usually after the array has been filled using UpdateDataArrayRow. The values of the row are saved to the variables passed for each field.
Example
See the GetAndSendData method for an example.
The PerformCmd method executes a UIS Command Task.
PerformCmd (Request As Variant, Response As Variant) As Integer
| Parameter | Required | Description |
|---|---|---|
|
Request |
Yes |
An array of parameters describing the Command Task to execute. Request parameters include: (Count as Short, CmdDescriptor (CmdType as String, CmdParameters as String, RequestingId as Integer, StatusPointId as Integer, DdsKey as Integer, CmdPriority as Integer, RequestType as String, CmdOperator as String, CmdDescriptor (DeviceParameter as String, SelectionTag as String, Comparison as String, ComparisonValue as String, SelectionTagType as String) as Array) as Array) as Array |
|
Response |
Yes |
An array including the number of times the Command Task has been executed and any errors encountered during the last run. Response parameters include: (Count as Integer, Error as Integer) as Array |
PerformCmd (Request (Count as Short, CmdDescriptor (CmdType as String, CmdParameters as String, RequestingId as Integer, StatusPointId as Integer, DdsKey as Integer, CmdPriority as Integer, RequestType as String, CmdOperator as String, CmdDescriptor (DeviceParameter as String, SelectionTag as String, Comparison as String, ComparisonValue as String, SelectionTagType as String) as Array) as Array) as Array), Response (Count as Integer, Error as Integer) as Array)
The command priority for a scripted UIS command can be assigned; by setting the UisCmdPriority=<priority> parameter where <priority> is one of the following 'Low', 'Medium', 'High', 'User', or 'Admin'.
See Prioritizing Messages in the Communication Queue for more information.
The RetrieveDeviceSummaryStatistics method retrieves current status and summary statistics for a device in the UIS as XML.
RetrieveDeviceSummaryStatistics(DeviceID As String) As String
| Parameter | Required | Description |
|---|---|---|
|
DeviceID |
Yes |
The ID of the device to retrieve. |
The RetrieveMultipleDeviceSummaryStatistics method retrieves current status and summary statistics for multiple devices in the UIS as XML.
RetrieveMultipleDeviceSummaryStatistics(DeviceIdArray) As String
| Parameter | Required | Description |
|---|---|---|
|
DeviceIdArray |
Yes |
An array of IDs of devices to retrieve. |
The RetrieveMultiQueueSnapshotXML method retrieves multiple queue snapshots as XML.
RetrieveMultiQueueSnapshotXML(QueueNameArray) As String
| Parameter | Required | Description |
|---|---|---|
|
QueueNameArray |
Yes |
An array of queue names to retrieve. |
The RetrieveQueueSnapshotXML method retrieves queue snapshot as XML.
RetrieveQueueSnapshotXML(QueueName As String) As String
| Parameter | Required | Description |
|---|---|---|
|
QueueName |
Yes |
The name or the queue to retrieve. |
The SendDataGroupToDeviceByKey method sends a data group transaction to the device by database key.
SendDataGroupToDeviceByKey(DataGroupKey As String, ShowWaitDlg As Boolean, MaxWaitTimeInMS As Integer, FromDeviceParams As String, ToDeviceParams As String, DataGroupTxData As String, OutDataGroupTxHdr, OutError) As Boolean
| Parameter | Required | Description |
|---|---|---|
|
DataGroupKey |
Yes |
The database key for the data group. |
|
ShowWaitDlg |
Yes |
Indicates whether to show a status dialog box when the method is being executed (True) or not (False). |
|
MaxWaitTimeInMS |
Yes |
|
|
FromDeviceParams |
Yes |
Parameters that may be required when getting from the device. Usually an empty string is passed. |
|
ToDeviceParams |
Yes |
Parameters that may be required when sending to the device. Usually an empty string is passed. |
|
DataGroupTxData |
Yes |
|
|
OutDataGroupTxHdr |
Yes |
|
|
OutError |
Yes |
Stores an error message if an error occurs. |
The SendSingleDEId method sends a single data group element value to a device without user interaction. It first requests the group from the device, and then sends the group with the one changed value back to the device.
SendSingleDEId(FacilityID As String, DataGroup As String, Ordinal As Integer, Deid As String, Value As String, ShowWaitDlg As Boolean, FromDeviceParams As String, ToDeviceParams As String, OutError As String) As Boolean
| Parameter | Required | Description |
|---|---|---|
|
FacilityID |
Yes |
The facility ID. |
|
DataGroup |
Yes |
The data group type. |
|
Ordinal |
Yes |
The data group ordinal. |
|
Deid |
Yes |
The data group element ID (DEID) to be set. |
|
Value |
Yes |
The value of the data group element ID. |
|
ShowWaitDlg |
Yes |
Indicates whether to show a status dialog box when the method is being executed (True) or not (False). |
|
FromDeviceParams |
Yes |
Parameters that may be required when getting from the device. Usually an empty string is passed. |
|
ToDeviceParams |
Yes |
Parameters that may be required when sending to the device. Usually an empty string is passed. |
|
OutError |
Yes |
Stores an error message if an error occurs. |
When the device parameter fields are used, both FromDeviceParams and ToDeviceParams are typically the same. The method returns True if it succeeded and False if an error occurred.
Example
The following method sets the C02 field of the GasAnal data group to a given value. During the call a wait dialog box is shown (ShowWaitDlg). If an error occurred in processing, it is displayed in a message box.
|
Sub SetC02 (val) Dim uisClient, strError, result Set uisClient = CreateObject("CxUis.UisClient") uisClient.Connect("CYGDEMO.UIS")
'Set the DEID result = uisClient.SendSingleDEId("RTU1", "GasAnal", 1, "C02", val, True,_ "", "", strError)
If (Not result) Then MsgBox "An error occurred: " & strError End If End Sub |
The SendSingleDEIdByKey method sends a single data group element ID by a data group’s DB key to a device.
SendSingleDEIdByKey(DataGroupKey As String, Deid As String, Value As String, ShowWaitDlg As Boolean, FromDeviceParams As String, ToDeviceParams As String, OutError As String) As Boolean
| Parameter | Required | Description |
|---|---|---|
|
DataGroupKey |
Yes |
The database key for the data group. |
|
Deid |
Yes |
The data group element ID (DEID) to be set. |
|
Value |
Yes |
The value of the data group element ID. |
|
ShowWaitDlg |
Yes |
Indicates whether to show a status dialog box when the method is being executed (True) or not (False). |
|
FromDeviceParams |
Yes |
Parameters that may be required when getting from the device. Usually an empty string is passed. |
|
ToDeviceParams |
Yes |
Parameters that may be required when sending to the device. Usually an empty string is passed. |
|
OutError |
Yes |
Stores an error message if an error occurs. |
This method can be used with other methods such as DdsClient.GetDataGroupInfo or DdsClient.GetDataGroupProperty that return a database key. When the device parameter fields are used, both FromDeviceParams and ToDeviceParams are typically the same. The method returns True if it succeeded and False if an error occurred.
Example
The following function serves as a wrapper for the SendSingleDEIdByKey method. It accepts a dbKey, data group element ID, and value, and performs the operation with the other fields fixed.
|
Function SetField (dbKey, deid, val) Dim uisClient, strError Set uisClient = CreateObject("CxUis.UisClient") uisClient.Connect("CYGDEMO.UIS")
'Return the success of the function SetField = uisClient.SendSingleDEIdByKey (dbKey, deid, val, False, "",_ "", strError) End Function |
The SendSingleDEIdInteractive method sends a single data group element ID to a device with user interaction.
SendSingleDEIdInteractive(FacilityID As String, DataGroup As String, Ordinal As Integer, Deid As String, Prompt As String, Title As String, FromDeviceParams As String, ToDeviceParams As String, Value As String, OutError As String) As Boolean
| Parameter | Required | Description |
|---|---|---|
|
FacilityID |
Yes |
The facility ID. |
|
DataGroup |
Yes |
The data group type. |
|
Ordinal |
Yes |
The data group ordinal. |
|
Deid |
Yes |
The data group element ID (DEID) to be set. |
|
Prompt |
Yes |
The prompt text in the dialog box. |
|
Title |
Yes |
The title of the dialog box. |
|
FromDeviceParams |
Yes |
Parameters that may be required when getting from the device. Usually an empty string is passed. |
|
ToDeviceParams |
Yes |
Parameters that may be required when sending to the device. Usually an empty string is passed. |
|
Value |
Yes |
Input/Output. The value of the data group element ID. |
|
OutError |
Yes |
Stores an error message if an error occurs. |
When Value is passed as a non-empty string, this will be the default value placed in the prompt. This field also holds the returned value that was sent to the device. When the device parameter fields are used, both FromDeviceParams and ToDeviceParams are typically the same. The method returns True if it succeeded and False if an error occurred.
Example
The following method displays a prompt to set a given field in the OpCodes data group. If an error occurs, the error message is displayed. Otherwise, the value sent to the device is displayed.
|
Sub SetOpCodePrompt (field) Dim uisClient, strVal, strError, result Set uisClient = CreateObject("CxUis.UisClient") uisClient.Connect("CYGDEMO.UIS")
'Display the DEID prompt result = uisClient.SendSingleDEIdInteractive("RTU1", "OpCodes", 1,_ field, "Enter a new value: ", "Op code",_ "", "", strVal, strError)
If (result) Then MsgBox field & " set to " & strVal Else MsgBox "An error occurred: " & strError End If End Sub |
The SendSingleUdc method sends a single Uniform Data Code (UDC) to a device without user interaction.
SendSingleUdc(FacilityID As String, DataGroup As String, Ordinal As Integer, Udc As String, Value As String, ShowWaitDlg As Boolean, FromDeviceParams As String, ToDeviceParams As String, OutError As String) As Boolean
| Parameter | Required | Description |
|---|---|---|
|
FacilityID |
Yes |
The facility ID. |
|
DataGroup |
Yes |
The data group type. |
|
Ordinal |
Yes |
The data group ordinal. |
|
Udc |
Yes |
The UDC to set. |
|
Value |
Yes |
The value of the UDC. |
|
ShowWaitDlg |
Yes |
Indicates whether to show a status dialog box when the method is being executed (True) or not (False). |
|
FromDeviceParams |
Yes |
Parameters that may be required when getting from the device. Usually an empty string is passed. |
|
ToDeviceParams |
Yes |
Parameters that may be required when sending to the device. Usually an empty string is passed. |
|
OutError |
Yes |
Stores an error message if an error occurs. |
When the device parameter fields are used, both FromDeviceParams and ToDeviceParams are typically the same. The method returns True if it succeeded and False if an error occurred.
Example
The following method sets the RPM UDC field of the ProdConfig data group to a given value. During the call a wait dialog box is shown (ShowWaitDlg). If an error occurred in processing, it is displayed in a message box.
|
Sub SetRPM (val) Dim uisClient, strError, result Set uisClient = CreateObject("CxUis.UisClient") uisClient.Connect("CYGDEMO.UIS")
'Set the UDC result = uisClient.SendSingleUdc("RTU1", "ProdConfig", 1, "RPM", val, True,_ "", "", strError)
If (Not result) Then MsgBox "An error occurred: " & strError End If End Sub |
The SendSingleUdcByKey method sends a single Uniform Data Code (UDC) by database key to a device without user interaction.
SendSingleUdcByKey(DataGroupKey As String, Udc As String, Value As String, ShowWaitDlg As Boolean, FromDeviceParams As String, ToDeviceParams As String, OutError As String) As Boolean
| Parameter | Required | Description |
|---|---|---|
|
DataGroupKey |
Yes |
The database key for the data group. |
|
Udc |
Yes |
The UDC to set. |
|
Value |
Yes |
The value of the UDC. |
|
ShowWaitDlg |
Yes |
Indicates whether to show a status dialog box when the method is being executed (True) or not (False). |
|
FromDeviceParams |
Yes |
Parameters that may be required when getting from the device. Usually an empty string is passed. |
|
ToDeviceParams |
Yes |
Parameters that may be required when sending to the device. Usually an empty string is passed. |
|
OutError |
Yes |
Stores an error message if an error occurs. |
This method can be used with other methods such as DdsClient.GetDataGroupInfo or DdsClient.GetDataGroupProperty that return a database key. When the device parameter fields are used, both FromDeviceParams and ToDeviceParams are typically the same. The method returns True if it succeeded and False if an error occurred.
Example
The following function serves as a wrapper for the SendSingleUdcByKey method. It accepts a dbKey, UDC, and value, and performs the operation with the other fields fixed.
|
Function SetField (dbKey, udc, val) Dim uisClient, strError Set uisClient = CreateObject("CxUis.UisClient") uisClient.Connect("CYGDEMO.UIS")
'Return the success of the function SetField = uisClient.SendSingleUdcByKey (dbKey, udc, val, False, "",_ "", strError) End Function |
The SendSingleUdcInteractive method sends a single UDC to a device with user interaction.
SendSingleUdcInteractive(FacilityID As String, DataGroup As String, Ordinal As Integer, Udc As String, Prompt As String, Title As String, FromDeviceParams As String, ToDeviceParams As String, Value As String, OutError As String) As Boolean
| Parameter | Required | Description |
|---|---|---|
|
FacilityID |
Yes |
The facility ID. |
|
DataGroup |
Yes |
The data group type. |
|
Ordinal |
Yes |
The data group ordinal. |
|
Udc |
Yes |
The UDC to set. |
|
Prompt |
Yes |
The prompt text in the dialog box. |
|
Title |
Yes |
The title of the dialog box. |
|
FromDeviceParams |
Yes |
Parameters that may be required when getting from the device. Usually an empty string is passed. |
|
ToDeviceParams |
Yes |
Parameters that may be required when sending to the device. Usually an empty string is passed. |
|
Value |
Yes |
Input/Output. The value of the UDC. |
|
OutError |
Yes |
Stores an error message if an error occurs. |
When Value is passed as a non-empty string, this will be the default value placed in the prompt. This field also holds the returned value that was sent to the device. When the device parameter fields are used, both FromDeviceParams and ToDeviceParams are typically the same. The method returns True if it succeeded and False if an error occurred.
Example
The following method displays a prompt to set the value of the VLVCTLPO UDC in the PumpData data group. If an error occurs, the error message is displayed. Otherwise, the value sent to the device is displayed.
|
Sub ValvePositionPrompt () Dim uisClient, strVal, strError, result Set uisClient = CreateObject("CxUis.UisClient") uisClient.Connect("CYGDEMO.UIS")
'Display the DEID prompt result = uisClient.SendSingleUdcInteractive("RTU1", "PumpData", 1,_ "VLVCTLPO", "Enter a position (0-100): ",_ "Valve Position", "", "", strVal, strError)
If (result) Then MsgBox "Valve set to " & strVal & "%." Else MsgBox "An error occurred: " & strError End If End Sub |
The SendUISCommand method sends a command to a UIS for a specified facility. Also see CanSendUisCommand and CxScript.GlobalFunctions.SendUisCommand.
SendUISCommand(FacilityId As String, Command As String, [Parameters As String], [StatusPointID As String])
| Parameter | Required | Description |
|---|---|---|
|
FacilityId |
Yes |
The ID of the facility that has the UIS command. |
|
Command |
Yes |
The name of the command. |
|
Parameters |
Yes |
Parameters that may be required for the UIS command. Use an empty string if none are specified. |
|
StatusPointID |
Yes |
The tag string of an optional status point for the command (in progress, completed, success, etc.). Use an empty string if none specified. |
This method sends a command on the UIS to which the UisClient is connected. The optional parameters are sent in semicolon delimited format ("param=value"). The status point, if used, is updated automatically. In CygNet Studio, the UIS Command Button can also be used.
The command priority for a scripted UIS command can be assigned; by setting the UisCmdPriority=<priority> parameter where <priority> is one of the following 'Low', 'Medium', 'High', 'User', or 'Admin'.
See Prioritizing Messages in the Communication Queue for more information.
Example — Get status
The following method updates the status of the METER206 device.
|
Sub GetStatus () 'Create and initialize the UIS Client Dim uisClient Set uisClient = CreateObject("CxUis.UisClient") uisClient.Connect("CYGDEMO.UIS")
'Get status (no parameters or status point) uisClient.SendUISCommand "METER206", "STATUS", "", "" End Sub |
Example — Set UIS Command Priority
The following method sets the UIS command priority.
|
Dim objUisClient : Set objUisClient = CreateObject("CxUis.UisClient") Dim strUis, strRemoteDevice, strDataGroup, arrCmdPriority, strCmdPriority
strUis = "CYGDEMO.UIS" strRemoteDevice = "FB107" strDataGroup = "RtuConfig" arrCmdPriority = Array("", "Low", "Medium", "High", "User", "Admin")
objUisClient.Connect strUis
'DG_F_DEV direct to data group For Each strCmdPriority In arrCmdPriority objUisClient.SendUISCommand strRemoteDevice, "DG_F_DEV", "DGORD=1;DGTYPE=" & strDataGroup & ";UisCmdPriority=" & strCmdPriority & ";", "" Next
'preconfigured UIS command on device For Each strCmdPriority In arrCmdPriority objUisClient.SendUISCommand strRemoteDevice, "GETTIME", "UisCmdPriority=" & strCmdPriority & ";", "" Next |
Example — Using DG_F_DEV or DG_T_DEV component types
The following examples show how to send a UIS Command that is not predefined on a device. This example allows you to specify the DG_F_DEV or DG_T_DEV component type, then the data group ordinal (DGORD) and data group type (DGTYPE) that you want to poll.
The same functionality is available with the CxScript.GlobalFunctions method SendUisCommand.
DG_T_DEV
|
Dim uisClient Set uisClient = CreateObject("CxUis.UisClient") uisClient.Connect("CYGDEMO.UIS") uisClient.SendUISCommand "WELLPILOT_KS_WELL00", "DG_T_DEV", "DGORD=0;DGTYPE=ProVlvOpCl;OpenClose=1", "" |
DG_F_DEV
|
Dim uisClient Set uisClient = CreateObject("CxUis.UisClient") uisClient.Connect("CYGDEMO.UIS") uisClient.SendUISCommand "WELLPILOT_KS_WELL00", "DG_F_DEV", "DGORD=0;DGTYPE=BasicPoll", "" |
where
Script Element Corresponds to More information UisClient.SendUisCommand
Send UIS Command CYGDEMO.UIS
CygNet Site.Service WELLPILOT_KS_WELL00
Facility DG_T_DEV (to send a data group to a field device)
DG_F_DEV (to get a data group from a field device)
Component type DGORD
Ordinal of the data group (for example, 0) DGTYPE
Data group type (for example, ProVlvOpCl – is the Production Valve Open and Close data group)
OpenClose
Parameters to send to the device (for example, Open = 1 and Close = 0) UIS Command Components
Note: You can find the Component Type, Data Group Ordinal, and Data Group Type in the properties of the Data Group. All of the information above is available in the UIS Command Properties, if you have a UIS command created already but want to use a script to run the command.
The SetActiveCommLine method sets the active communication line for a remote device.
SetActiveCommLine(RemoteDevice As String, ActiveCommLine As Variant)
| Parameter | Required | Description |
|---|---|---|
|
RemoteDevice |
Yes |
The remote device ID. |
|
ActiveCommLine |
Yes |
The ID of the communication line to use. 1 is Primary, 2 is Secondary. |
Example
The following method sets the Active Communication Line of a specific device to Secondary.
|
Sub SetCommSecondary()
'Create and initialize the UIS Client Dim uisClient Set uisClient = CreateObject("CxUis.UisClient") uisClient.Connect("CYGDEMO.UIS")
'Get Device ID Dim strDeviceId strDeviceId = edtDeviceID.Text
'Set active comm line to secondary Dim bSuccess bSuccess = ddsClient.SetActiveCommLine (strDeviceId, 2) If bSuccess = False Then MsgBox "Error in setting active comm line." Else MsgBox "Comm Line successfully set." End If End Sub |
This method is obsolete. Use DdsClient.SetCommDevProperty.
The UpdateDataArrayRow method updates a row in the data array.
UpdateDataArrayRow(DataInfoArray As Variant, Row As Integer, Facility As String, DataGroup As String, Ordinal As String, Deid As String, Udc As String, Desc As String, RecValue As String, SendValue As String, GetFromDevice As Boolean, SendToDevice As Boolean, OutError As String) As Boolean
| Parameter | Required | Description |
|---|---|---|
|
DataInfoArray |
Yes |
Input/Output. The array of data to be updated. |
|
Row |
Yes |
The index of the row to be updated (zero-based). |
|
Facility |
Yes |
The facility ID. |
|
DataGroup |
Yes |
The data group type. |
|
Ordinal |
Yes |
The data group ordinal. |
|
Deid |
Yes |
The data group element ID (DEID) to be set. (See Remarks). |
|
Udc |
Yes |
The UDC to set (see Remarks). |
|
Desc |
Yes |
The description of the data group element ID or UDC. |
|
RecValue |
Yes |
The value of the field that is received. |
|
SendValue |
Yes |
The value of the field to set. |
|
GetFromDevice |
Yes |
Whether to get data from the device (True) or not (False). |
|
SendToDevice |
Yes |
Whether to send data to the device (True) or not (False). |
|
OutError |
Yes |
Stores an error message if an error occurs. |
This method updates a row in a two-dimentional array that has been previously created using CreateDataArray. Each row can use either the Deid or Udc field. The field that is not being used can be left as an empty string.
Example
See the GetAndSendData method for an example.
|
|
|
