Passing Multiple Values
One of the questions that I see over and over again on the various technical support forums that I frequent is “What is the best way to pass multiple values from one object to another”. Let’s begin with the simplest case, where we want to call a procedure (or method) that returns a single value. Obviously can just design the procedure so that it returns the desired result and, inside a form (or other object) method, we call it as a function and capture the returned value to a local variable, like this:
*** Call the external program/procedure and catch the return
luCalcValue = MyProcedure()
This.Control.Value = luCalcValue
Use a Reference
This is fine when all that we want is a single value, but of course, there are many scenarios in which we need to return multiple values from the procedure. Probably the first thing that leaps to mind is to pass a reference to the calling object to the child procedure so that it can access the calling object’s properties and methods directly like this:
luCalcValues = MyProcedure( THISFORM ) or luCalcValues = MyProcedure( THIS )
While this looks attractive in many ways, it does break encapsulation and is, therefore, not “good OOP practice”. But if “MyProcedure” needs to call a method on a form then this is really the only way to do it. (I have seen it suggested that you explicitly name the instance of the form and then have the procedure look for an object with that name – but this only works if you are using the DO FORM command, and it only works as long as there can only ever be one instance of the form. It is not a good solution!)
However, having an external procedure or object rely on being able to call a method on another object is bad design because the procedure is therefore inextricably coupled to the calling object. It is a fundamental rule of OOP that no object should ever depend upon the internal implementation of another – because such objects cannot be used unless a another object (with the appropriate method) is also involved. If you find yourself in this scenario, then you probably should be thinking about re-designing things anyway.
For example a better approach would be to have the procedure return a flag indicating that the calling object should initiate some appropriate action. That way the decision on what to do in a given situation rests with the calling object, not the child procedure – clearly a much more flexible way of doing things.
Use Public Variables
If we aren’t going to let the procedure manipulate the object, then what about using Public Variables (or declaring Private Variables in the calling method so that they are in scope for the procedure) and having the procedure set their values. But this is really just a non-OOP variation on passing a reference and it is poor design for all of the same reasons (now the procedure is dependant upon the existence of appropriately named variables which have to be in scope). Worse, if we use Public Variables there is always the risk of “collisions” where the same variable is being changed from more than one place so that the value referred to is not necessarily the one that we were expecting.
Use a Parameter Object
So if we can’t use these methods, what can we do. Fortunately VFP allows us to create and use parameter objects and these really are the best way to go. So the first thing to decide is what should our parameter object be.
If you are using VFP Version 8.0 or later, you can use the “empty” base class (which is also the class used by SCATTER NAME) which can be instantiated and released very quickly because it has no native properties, events or methods. To add properties you have to use the ADDPROPERTY() function.
If you are using an earlier version of VFP then you can use any lightweight base class, providing that it has an AddProperty() method, either ‘relation’, which can only be defined in code, or ‘line’, if you want to define it in a visual class library, will do nicely.
Incidentally this is one of those cases where we really can use a base class directly (other commonly used base classes include SESSION and COLLECTION) – although if you use the same set of values frequently in an application it may be worth creating a standard sub class for the object to avoid the necessity of repeating the code and to handle the maintenance of the properties it uses. So, how do we do this?
Version 8.0 or later
*** Create an instance of the Empty Base class
loParams = CREATEOBJECT( 'Empty' )
*** Add and initialize a string property
llOk = ADDPROPERTY( loParams, 'cName', 'Andy Kramek' )
*** Add and initialize an Array Property
llOk = llOk AND ADDPROPERTY( loParams, 'aList[2,2]', '' )
IF llOK
** Populate the Array
WITH loParams
.aList[1,1] = 'Akron'
.aList[1,2] = 'Ohio'
.aList[2,1] = 'Phoenix'
.aList[2,2] = 'Arizona'
ENDWITH
ENDIF
Version 7.0 or earlier
*** Create an instance of a relation
loParams = CREATEOBJECT( 'Relation' )
*** Add and initialize a string property
llOk = loParams.AddProperty( 'cName', 'Andy Kramek' )
*** Add and initialize an Array Property
llOk = llOk AND loParams.AddProperty( 'aList[2,2]', '' )
IF llOK
** Populate the Array
WITH loParams
.aList[1,1] = 'Akron'
.aList[1,2] = 'Ohio'
.aList[2,1] = 'Phoenix'
.aList[2,2] = 'Arizona'
ENDWITH
ENDIF
Having got our parameter object, and populated it we can simply pass it around as if it were simply a single value. So now in our procedure, instead of returning a single value, we simply create and return the parameter object:
RETURN loParams
How do we know what we got back?
Now you may be wondering how we know what we got back in our parameter object. Well that is easy too! There are two methods, we can either use the AMEMBERS() function to get a list of all the properties on the parameter object. This is fine when using the EMPTY() base class but can get messy if you are using Relation or Line. Here is an example of this method:
*** Call the procedure that returns the parameter object
loResults = MyProcedure()
*** Use AMEMBERS() to get a list of property names
lnProps = AMEMBERS( laProps, loResults, 0 )
*** Get the Name and the value
FOR lnCnt = 1 TO lnProps
*** Get the name of the property
lcName = laProps[lnCnt]
*** And it’s value
luVal = EVAL( “loResults.” + lcName )
*** Use it however necessary…
? lcName, luVal
NEXT
Alternatively we can use PEMSTATUS() to determine if the appropriate property exists on the parameter object (this is easier when you are looking for specific, known values only):
*** Call the procedure that returns the parameter object
loResults = MyProcedure()
*** Check for the property and assign a default value if not found
lcName = IIF(PEMSTATUS( loResults, 'cName', 5 ), loResults.cName, "" )
*** Use the result however necessary…
? lcName
Remember this works both ways…
I have been talking about using a parameter object to get multiple return values, but of course there is no reason why we should not use a parameter object to PASS multiple values as well. There advantages to doing this because it gives us explicitly named parameters. In other words instead of relying on the position of a value in the list of parameters we can simply name. As a result we no longer need to count the parameters either – think of how many times you have used code like this:
IF PCOUNT() = 3
*** Passed LastName, FirstName and Initial
ELSE
IF PCOUNT() = 2
*** Assume LastName and FirstName
ELSE
IF PCOUNT() = 1
*** Assume LastName only
ELSE
*** Nothing passed
ENDIF && PCOUNT() = 1
ENDIF && PCOUNT() = 2
ENDIF && PCOUNT() = 3
That now get replaced by:
WITH loParameters
lcFirstName = IIF(PEMSTATUS( loParameters, 'FirstName', 5 ), loParameters.FirstName, "" )
lcLastName = IIF(PEMSTATUS( loParameters, 'LastName', 5 ), loParameters.LastName, "" )
lcInitials = IIF(PEMSTATUS( loParameters, 'Initials', 5 ), loParameters.Initials, "" )
ENDWITH
This is so much easier to work with and to maintain! If for no other reason than to make your own life simpler I hope you will adopt parameter objects as enthusiastically as I have.