If you’ve done any Delphi or C#Builder database programming, think about the SQL statements you’ve used. Have you always known all the SQL you want to use at design time? I’m guessing the answer is no. You quite often know most of the statement, but maybe at runtime you have to substitute in some parameters for your Where clause, for example.

Well, it’s the same thing with OCL. So far we’ve been acting like we can hope to know all the OCL we ever intend to use at design time. Far more common is that you want the same ability to use Parameters in your OCL, just as you do with SQL. However, in ECO they are called Variables, rather than Parameters, but it’s the same concept. They allow us to create OCL that dynamically responds to changes at runtime.

Let me give you an example. Say we want a search screen, like this:

Here I have a grid of Person objects, and some TextBoxes above each field. As I type into one or more of the TextBoxes, the grid only displays the objects that match. How to achieve this?

Well, with static OCL, one way of achieving the end result would be with OCL like this:

Person.allInstances->select( Firstname.regExpMatch(“Ja”) and
Lastname.regExpMatch(“”) and
Country.regExpMatch(“U”))

Note that I’m using the select operator, which returns a collection of Person objects that match the Boolean expression inside the brackets. In this case, I’m doing Regular Expression matching  on each of the fields in order to return the Boolean expression expected by the select function.

Well, this will work, but really we want to be able to substitute in the values to match against at runtime. You could build up this string dynamically I guess, then shove it into the ExpressionHandle, but another way is to use Variables. Let’s look at how you do it.

Apart from the DataGrid and TextBoxes above, you’ll have a ReferenceHandle pointing at your ECOSpace, and an ExpressionHandle connected up to the ReferenceHandle. The DataGrid is connected to your ExpressionHandle. If you’ve worked your way through the tutorials, all of that should not be terribly difficult. Don’t worry about what OCL to put in the ExpressionHandle just yet.

What we need to do is to take the text entered into the TextBoxes and somehow get it into some OCL. We’ll start with just searching on the Firstname attribute, then look at what you’d do to search on all three.

Drop down a component called a VariableHandle and name it vhFirstname. The VariableHandle is responsible to holding the value of a Variable we wish to use in our OCL. A VariableHandle is a bit like a ReferenceHandle, in that needs you to give it a reference to your EcoSpace. For the ReferenceHandle, the File | New | Other | ECO Winforms App wizard did this automatically, but for the VariableHandle, you’ll have to do it yourself.

Two steps are required. Dropdown the VariableHandle’s ECOSpaceType property and select the type of the ECOSpace you are using. Then, have a look in the get_EcoSpace method of our form, and add the line in bold below. Note the Wizard has inserted the equivalent line for the ReferenceHandle (named rhRoot) just above it.

function TWinForm.get_EcoSpace: TECOSimpleSearchEcoSpace;
begin
  if not Assigned(fEcoSpace) then
  begin
    fEcoSpace := TECOSimpleSearchEcoSpace.Create;
    rhRoot.EcoSpace := fEcoSpace;
    vhFirstname.EcoSpace := fEcoSpace;  // insert this line
  end;
  result := fEcoSpace;
end;

We also need to specify the type of this Variable. In our case, it’s a string, but it could be a number, a date or time value, etc. Unlike SQL Parameters, it could be even more than this. Our variable could be a collection of strings, dates, etc, an object, or even a collection of objects! Think for awhile about the flexibility that would provide. (For those who don’t want to think about it, don’t worry, I’ll cover it in the next article)

So, to specify the type of our Variable, we use the VariableHandle’s StaticValueTypeName property. Click on the Ellipsis button for this property and you should see the Type name Selector dialog shown below, which allows you to select the simple type or class, or collection of either, that you want this VariableHandle to hold. In our case, select System.String.

OK, so we have a VariableHandle to hold the value entered into the TextBox. How do we get the value in there? Go to the TextBox component, and put the following code into its TextChanged event:

vhFirstname.Element.AsObject := txtFirstname.Text;

Now, whenever the user changes the text in the TextBox, our VariableHandle component will be updated with the new value. You can replicate this for the other attributes we want to search on (ie. Drop down two more VariableHandles, set their ECOSpaceType and StaticValueTypeName properties, add the relevant code to the get_ECOSpace method, and set up TextChanged events on the relevant TextBoxes so that the variableHandles get updated as the user changes the search text)

That’s great, but we still have no connection between the VariableHandles and the OCL in our ExpressionHandle. So, to hook them up, we need to drop down an OCLVariables component. This component is responsible for holding a collection of variables used in OCL, and the relevant VariableHandles from which their values should be retrieved. Select the OCLVariable component, and bring up the property editor for the OclVariablesCollection property. Add three members to the collection, and for each one, set the ElementHandle and VariableHandle properties. In the screenshot below, you can see how I’ve set the first one.

What this screenshot shows is I’ve created a connection between the vhFirstname VariableHandle component and a Variable called vFirstname. I’ve done the same for LastName and Country.

The last piece is to connect the ExpressionHandle that is connected to my DataGrid to my OCLVariables component, using the ExpressionHandle’s Variables property. Then, enter the following OCL into your ExpressionHandle:

Person.allInstances->select( Firstname.regExpMatch(vFirstname) and
Lastname.regExpMatch(vLastname) and
Country.regExpMatch(vCountry))

And we’re done. In concept, what happens when the OCL is evaluated, is that the OCL Parser will come across vFirstname, and now knowing what that is, will go out to the ExpressionHandle and request the value. It will, using its Variables property, look in the OCLVariables component and see that the value of vFirstname needs to come from the VariableHandle called vhFirstname. This value will be retrieved, and will either be empty or some string value that was assigned when the user typed into the TextBox. This value will be substituted into the OCL. The same happens for the other two variables and we’re away. The image below hopefully clarifies the relationships between the non-visual controls:

Now a few things to realize. In this case we’re using variables in the regExpMatch OCL function, but we can use variables in many different OCL expressions. Also, as I mentioned before, our Variable could contain more than a simple data type like a string, maybe a collection or an object (or a collection of objects), and provided that type was valid where you were placing your variable in your OCL, that’s fine. As I mentioned earlier, in the second part of this article I’ll do another example using a collection of objects as a variable, however the steps involved are basically the same, so you can porbably figure it out from here.