Pass-arguments by-reference

When an argument has a value that cannot fit into an MI_DATUM structure, the routine manager passes the argument by reference. For each of these pass-by-reference arguments, you declare a parameter that is a pointer to a value of the parameter data type, in the C-function declaration.

The following code fragment shows the bigger_double() user-defined function, which compares two mi_double_precision values. Because the routine manager passes mi_double_precision values by reference, bigger_double() declares the two parameters as pointers to values of the mi_double_precision data type.

Figure 1: Passing arguments by reference

mi_double_precision *bigger_double(left, right)
   mi_double_precision *left, *right;
{
   mi_double_precision *dpp;

   dpp = mi_alloc(sizeof(mi_double_precision));
   if ( *left > *right )
      {
      *dpp = *left;
      return(dpp);
      }
   else
      {
      *dpp = *right;
      return(dpp);
      }
}

Important: Memory that the routine manager allocates to pass an argument by reference has a PER_ROUTINE memory duration. Therefore, it is guaranteed to be valid only for the duration of the UDR execution. The database server automatically frees this memory when the UDR completes.

Any C-language code that calls bigger_double() must pass the mi_double_precision values by reference, as in the following sample call:

mi_double_precision double1, double2, *result;

double1 = 13497.931669;
double2 = 235521832.00484;
result = bigger_double(&double1, &double2);

Tip: For varying-length data, the routine manager does not pass a pointer to the actual data itself. Instead, it stores the varying-length data inside a varying-length structure. Therefore, your C UDR must declare parameters that expect varying-length data as a pointer to the appropriate varying-length structure. Varying-length data includes text arguments (see Handling character arguments) and varying-length opaque data types (see Handling varying-length opaque-type arguments).

Values passed into a UDR are often also used in other places in the SQL statement. If your UDR modifies a pass-by-reference value, successive routines in the SQL statement might use the modified value. When your UDR is run within the context of an SQL statement, a routine that runs before it can see (and possibly modify) any pass-by-reference values.

Tip: Avoid the modification of a pass-by-reference argument within a C UDR. For more information, see Modify argument values.