Pass a temp-table parameter by binding

You can also save the overhead of copying a temp-table's definition and data on a local call by using the BIND keyword. You use this keyword in both the calling and called routines to tell the AVM to bind both temp-table references to the same temp-table instance. In the calling routine, you add the keyword to the parameter in the RUN statement, instead of the BY-REFERENCE keyword:

RUN internal-procedure-name IN procedure-handle 
  ([ INPUT | INPUT-OUTPUT | OUTPUT ] TABLE temp-table-name BIND ).

In the called routine, you specify the keyword as part of the parameter definition:

DEFINE [ INPUT | INPUT-OUTPUT | OUTPUT ] PARAMETER TABLE FOR 
  temp-table-name BIND.

The most basic case where you would want to use the BIND keyword is when you want to use the called routine's temp-table instance instead of the calling routine's instance. For example, you may have a routine in your application that has a cache of useful data, such as all Item values for use in entering an Order, which it has retrieved from the database and stored in a temp-table. Other routines running in the same session might want access to this data, for example to display the list of Items in a selection list.

To save the overhead of copying the temp-table to all the other routines that want to share its data, you can bind the callers to the called routine's temp-table cache.

To pass a temp-table by binding from the called routine to the calling routine:

1. In the calling routine, define the temp-table as REFERENCE-ONLY. This tells the AVM not to instantiate the caller's temp-table when the routine is first run.
2. In the calling routine, specify the BIND keyword in the RUN statement that uses the temp-table parameter. This tells the AVM to bind both ends of the call to the same temp-table instance.
3. In the called routine, define the temp-table parameter with the BIND keyword. This confirms to the AVM that both ends of the call are to refer to the same instance. You must always specify BIND on both ends of the call.
4. Define the temp-table parameters in both routines as OUTPUT. This tells the AVM to use the called routine's temp-table instance and change all references within the caller to point to it.

To pass a temp-table by binding from the calling routine to the called routine:

1. In the called routine, define the temp-table as REFERENCE-ONLY.
2. In the called routine, define the temp-table parameter with the BIND keyword.
3. In the calling routine, specify the BIND keyword in the RUN statement that uses the temp-table parameter.
4. Make sure that the parameter mode matches in both routines. That is, they must both be defined as INPUT-OUTPUT or both be defined as INPUT parameters.

You can use the BIND syntax to change the scope of the temp-table that is passed from caller to called routine. When you use BY-REFERENCE in an internal procedure call, as was described earlier, the scope of the temp-table is limited to that one call. That is, the AVM changes the temp-table references (within the internal procedure you run) to refer back to the caller. When the internal procedure completes and returns to the caller, the association ends. In some exceptional cases, you might want to bind the caller's temp-table to the called routine for their mutual lifetime.

The following table describes how to decide between passing a temp-table as a parameter using the BY-REFERENCE keyword versus using BIND. This table refers only to those calls that always or sometimes occur between routines in the same session. If you know that the call will always be to routines in different sessions, you should just pass the temp-table parameter by value.