Sample mi_routine_exec() calls

The following code fragment uses the mi_routine_exec() function to execute the numeric_func() routine that has INTEGER parameters.
Figure 1: Executing the numeric_func() function with INTEGER arguments
MI_CONNECTION *conn;
MI_FUNC_DESC *fdesc;
MI_DATUM ret_val;
mi_integer int_ret;
mi_integer error;
...
/* fdesc obtains from code in Obtaining a function descriptor for the numeric_func()
function */
ret_val = mi_routine_exec(conn, fdesc, &error, 1, 2);
if ( ret_val == NULL )
   {
   if ( error == MI_OK )        
      /* numeric_func() returned an SQL NULL value */
      ...
   else /* error in mi_routine_exec() */
      {
      mi_db_error_raise(NULL, MI_EXCEPTION,
         "mi_routine_exec() failed");
      return MI_ERROR;
      }
   }
else /* cast MI_DATUM in ret_val to INTEGER */
   {
   int_ret = (mi_integer) MI_DATUM;
   ...

In Executing the numeric_func() function with INTEGER arguments, the mi_routine_exec() function uses the fdesc function descriptor that the mi_routine_get() function obtained for the numeric_func() function that accepts INTEGER arguments and returns an INTEGER value (Obtaining a function descriptor for the numeric_func() function). The last two arguments to mi_routine_exec() are the integer argument values for numeric_func(). The ret_val variable is an MI_DATUM value for the mi_integer data type that the numeric_func() function returns.

Executing the numeric_func() function with INTEGER arguments also tests the return status of mi_routine_exec() to check for the return value from numeric_func(). If the return value (ret_val) is a NULL-valued pointer, the code then determines which of the following results this NULL value indicates:
  • The numeric_func() function has returned an SQL NULL value: error is MI_OK.
  • The mi_routine_exec() function failed: error is not MI_OK.

Finally, the code fragment in Executing the numeric_func() function with INTEGER arguments casts the MI_DATUM value that mi_routine_exec() has returned to an mi_integer value. The MI_DATUM structure contains the actual return value because the routine manager can pass integer values by value (they can fit into an MI_DATUM structure).

Suppose the call to mi_routine_get() had been calling the version of numeric_func() that accepted a FLOAT argument and returned a FLOAT value, as follows: 
fdesc = mi_routine_get(conn, 0, 
   "function numeric_func(float)");

The call to mi_routine_exec() to execute this version of numeric_func() would require that the argument and the return value be passed by reference, because the FLOAT data type cannot be stored directly in an MI_DATUM structure.

The following code fragment shows a sample call to mi_routine_exec() to execute the numeric_func (FLOAT) user-defined function. The argument list to mi_routine_exec() passes the FLOAT value by reference and the returned FLOAT value is returned by reference.
Figure 2: Executing the numeric_func() function with INTEGER arguments
MI_CONNECTION *conn;
MI_FUNC_DESC *fdesc;
MI_DATUM ret_val;
mi_double_precision double_arg1, double_arg2, double_ret;
mi_integer error;
...
fdesc = mi_routine_get(conn, 0, "function numeric_func(float)");
ret_val = mi_routine_exec(conn, fdesc, &error, &double_arg1,
      &double_arg2);
if ( ret_val == NULL )
   {
   if ( error == MI_OK )
      /* numeric_func() returned an SQL NULL value */
      ...
   else /* error in mi_routine_exec() */
      {
      mi_db_error_raise(NULL, MI_EXCEPTION, 
         "mi_routine_exec() failed");
      return MI_ERROR;
      }
   }
else /* cast MI_DATUM in ret_val to FLOAT */
   {
   double_ret = (mi_double_precision *)MI_DATUM;
   ...
The following call to mi_routine_exec() executes the DECIMAL-to-mytype cast function for which Obtaining a cast function for a DECIMAL-to-mytype cast obtained the function descriptor, fdesc2:
ret_val = mi_routine_exec(conn, fdesc2, &error, dec_val);
mytype_val = (mytype *)ret_val;

The dec_val argument is an mi_decimal variable that contains the DECIMAL source data type to cast to the mytype target data type with the dec_to_mt() cast function. The ret_val variable is an MI_DATUM value of the mytype data type that contains the casted DECIMAL value.