Foxhound is the better* Database Monitor for SQL Anywhere.
*better: More thorough, more relevant, more effective.
...more Alerts, more All Clears, more details, more control in your hands.

Breck Carter
Last modified: July 17, 1996
mail to:

Deep Copies With AutoInstantiate

Yesterday's Tip Of The Day ended with with the following statement: "Currently there is no way to fully protect a caller's object arguments from change within a function and that would be a welcome feature."

Well, if the object arguments are Custom Class (non-visual) User Objects then that feature is available in PowerBuilder 5. When a non-visual object is marked with the new "AutoInstantiate" property it suddenly starts behaving like an structure instead of a variable as far as assignments and parameter passing is concerned.

AutoInstantiate is primarily intended to automate memory management. You don't have to create them: The objects are automatically instantiated when the reference variables (pointers) come into scope and destroyed when they fall out of scope. For example, a non-visual object declared as a window instance variable is automatically created when the window is opened and destroyed when it is closed. Local non-visual objects declared in a script live only as long as the script is executing.

In other words, AutoInstantiated objects behave just like structures, and that behaviour extends to parameters passed by value and by reference. Here's an example: n_cst_auto is created as a Custom Class User Object containing an integer instance variable ii_instance. The object is marked as AutoInstantiate by using the right mouse popup menu.

Two global functions f_by_value and f_by_ref are created. Each have a single argument of type n_cst_auto, called auo_auto, marked as "pass by value" and "pass by reference" respectively. Each function contains a single line of code:


Here's the code that exercises f_by_value and f_by_ref:

   n_cst_auto luo_auto
   integer    li_original
   integer    li_by_value
   integer    li_by_ref

   li_original = 1
   luo_auto.ii_instance = li_original
   f_by_value ( luo_auto )
   li_by_value = luo_auto.ii_instance

   li_original = 1
   luo_auto.ii_instance = li_original
   f_by_ref ( luo_auto )
   li_by_ref = luo_auto.ii_instance

   MessageBox ( "AutoInstantiate", &
       "li_original = "    + string ( li_original ) &
      + "~r~nli_by_value = " + string ( li_by_value ) &
      + "~r~nli_by_ref = " + string ( li_by_ref ) )

As you can see there is no reason to explicitly create the local variable called luo_auto; it gets created and destroyed automatically. But what we're really interested in is whether or not the calls to f_by_value and f_by_ref actually change ii_instance in the caller's copy of luo_auto. The MessageBox shows that ii_instance is indeed protected from change by the call to f_by_value:

There isn't much information about AutoInstantiate in the Help but you can find a good discussion in the new improved Online Books. Here's a roadmap:

and here's a snippet describing how AutoInstantiate causes "deep copying" of object variables:

Breck Carter can be reached by phone at (416) 763-5200 or via email at