You can only specify BY-REFERENCE on a call to an internal procedure, user-defined function, method in an object-oriented ABL class, or external procedure in the same AVM. When you pass a ProDataSet parameter by reference, the called routine's ProDataSet definition is bound to the calling routine's ProDataSet only for the duration of the call.

To pass a ProDataSet by reference, in the calling routine, use the BY-REFERENCE keyword in the RUN statement that defines the ProDataSet parameter. There is no special syntax required in the called routine. However, since the calling routine's ProDataSet instance is substituted for the called routine's ProDataSet, only the definition of the ProDataSet is required by the called routine. In other words, the same ProDataSet is defined in both routines but only one is actually used. If the called routine's ProDataSet is not directly used to hold its own data anywhere within the routine, you can save the overhead of allocating it by including the REFERENCE-ONLY option on its definition. This keyword tells the AVM to use the definition for compiler references to the table and its fields, but not to instantiate it at run time. Any reference to the ProDataSet, except where it is passed in from another routine BY-REFERENCE, results in a run-time error.

Because of the efficiency of passing the ProDataSet with BY-REFERENCE, you should normally use this keyword in your parameter definitions in RUN statements for any case where the called procedure will always or sometimes be in the same session as the caller. Because the AVM ignores the keyword on a remote call, you get the most efficient behavior in either case.

Why then is BY-REFERENCE not the default behavior?

Passing objects by copying them is the standard for other ABL parameter types. Passing a ProDataSet by reference has certain side effects that you need to be aware of, which could make the behavior confusing if you are not conscious of what the AVM is actually doing in the background to enable your called procedure to point to the same ProDataSet instance as the caller. For this reason, you have to make a specific request to pass by reference, and you should always make sure you have considered the consequences before doing so. Since this is different from how the AVM behaves otherwise, some of the effects can seem counter-intuitive.

In general you must consider that on a call BY-REFERENCE, the AVM substitutes the ProDataSet handle in the calling procedure for the ProDataSet defined in the called procedure, and that is the cause of most of the side effects. Consider the cases described in the following sections.