Using Data Manipulators Via Call Method

Data manipulators are ways to change your databases by executing queries or stored procedures. They are configured in Workbench under Data Connectivity > Databases > connection type > specific database. The sample GridWorX Server database contains three data manipulators under the Northwind sample database: AddCustomer, DeleteCustomer, and UpdateCustomer.

Most data manipulators use parameters to customize the changes being made at runtime, allowing the user to perform data entry or choose a particular record to modify or delete.

This document will instruct users on how to use the Call Method command to execute a data manipulator with parameters. This method is necessary on systems licensed using the AssetWorX tag counting mode (introduced in version 10.96.2 with the GENESIS64 Basic SCADA package). AssetWorX tag counting mode interferes with traditional ways of passing parameters to the @@Execute tag.

Note: This technique also applies to Web Manipulators in the Web Services provider.

Call Method Command

This section will provide an example of how to use the Call Method command to execute a data manipulator and pass in dynamic parameter values.

Open GraphWorX64.
Add a data entry process point connected to this simulation variable: localsim::custID:String
Create a second data entry process point using this simulation variable: localsim::companyName:String

Note: As an optional step, on both process points, set DataEntryLostFocusWritesValue to True. This setting is only visible in advanced mode. This setting lets the user write the value to the point without having to use the Enter or Tab keys and provides a more natural data entry experience. This property should NOT be set on process points connected to actual equipment, as it may cause the accidental write of partial values, which may damage equipment.

Add a button.
Set the button text to Add Customer.
Configure the button's pick action to be the Call Method.
Under CommandParameters, type this into Name:

db:Northwind.AddCustomer\Execute

Note: If you are not running in AssetWorX tag counting mode, you can browse for your data manipulator's Execute method. It can be found under Data Connectivity > Databases > database type > database name > Data Manipulators > manipulator name > Execute.

If you are running in AssetWorX tag counting mode, you must type the name in manually. The format is:

db:databaseName.manipulatorName\Execute

Next to Parameters, edit the collection.
Select Add to add one member.
Set the member's Value to {{localsim::CustID:String}}.
Make sure the ValueType is String.
Add a second member.
Set the second member's Value to {{localsim::companyName:String}}.
Make sure the second member's ValueType is also String.

Note: The order of the members must match the order in which the parameters were defined in Workbench for the data manipulator.

Editing Call Method Parameters

Select OK.
Go into Runtime.
Enter values into the two data entry process points.
Select the Add Customer button.
Use SQL Server Management Studio to view the Customers table in the Northwind database and observe that your values have been added to the table.

Problem with Parameter Tags and Inline Parameters

Users familiar with using data manipulators are probably aware of parameter tags. Every data manipulator with parameters has a Parameters folder in the data browser, and in this folder are tags for each parameter.

Parameter Tags Under AddCustomer Data Manipulator

These parameter tags are designed to provide convenient data entry. To allow multiple clients to interact with the same data manipulator at once, each client essentially has its own copy of these tags. Values written by a user on Client A will not see or be able to change the values being written by Client B.

Unfortunately, this separation of clients is not possible when the parameter tags have to pass through AssetWorX. In this case, AssetWorX becomes the client, and clients of the AssetWorX asset properties will see the same value. This means that the user at Client A can see and accidentally overwrite the parameters that Client B is trying to use.

The @@Execute tag supports inline parameters, but when AssetWorX tag counting mode is enabled AssetWorX does not allow runtime parameters on the Real-time tab of an asset property, making it difficult to use parameters unless they are hard-coded.

This is why using the Call Method command is the best way to execute a data manipulator when using AssetWorX tag counting (the tag counting method used in GENESIS64 Basic SCADA).