Return a value

When a user-defined function completes, the routine manager returns its value as an MI_DATUM value. The data type of the return value determines the passing mechanism that the routine manager uses for the value, as follows:
The passing mechanism that the routine manager uses for a particular return value determines how you must declare it in the user-defined function, as follows.
Return-value data type Tasks to return the value
Data types that cannot fit into an MI_DATUM structure Return the value by reference:
  • Declare a local variable that is a pointer to the actual return value
  • Allocate the memory for the return value with the PER_ROUTINE memory duration. Use a DataBlade® API memory-management function. For more information, see Manage user memory.
  • Assign the address of this memory to a local variable
  • Store the return value in this memory
  • Return the pointer to this memory as the return value
Data types that can fit into the MI_DATUM structure Can return the value by value:
  • Declare a local variable to hold the actual return value
  • Store the return value in this local variable
  • Return the local variable as the return value
Important: A user-defined function cannot return an automatic or local variable if its data type cannot be returned by value. That is, any automatic or local variables with data types that cannot fit into an MI_DATUM structure cannot be returned by value from the UDR.
To return a value, use the automatic or local variable that you declared in the user-defined function, like you would any other C-function variable, as follows:
  • For a pass-by-reference return value, use a pointer to allocated memory.

    Most data types are passed by reference. The sample UDR bigger_double(), in Passing arguments by reference, shows how to return an mi_double_precision value by reference. It allocates PER_ROUTINE memory for the return value, which the database server frees when the user-defined function completes.

  • For a pass-by-value return value, you can return a variable directly as the value.

    For a list of data types that can be returned by value, see Types of values that fit in an MI_DATUM structure (Passed by value). The sample UDR bigger_int(), in Passing arguments by value, shows how to return an mi_integer value by value.

Tip: You can obtain information about a return value, such as its type or maximum length, from the MI_FPARAM structure. For more information, see Access return-value information.