MI_DATUM mi_routine_exec(conn, funcdesc_ptr, error, argument_list)
   MI_CONNECTION *conn;
   MI_FUNC_DESC *funcdesc_ptr;
   mi_integer *error;
   argument_list;

conn

is a pointer to a connection descriptor established by a previous call to mi_open( ), mi_server_connect( ), or mi_server_reconnect( ).

can be a pointer to a session-duration connection descriptor established by a previous call to mi_get_session_connection( ). Use of a session-duration connection descriptor is an advanced feature of the DataBlade API.

funcdesc_ptr

is a pointer to the function descriptor that describes the routine to execute.

error

is set to the status of the mi_routine_exec( ) function:

• MI_OK: mi_routine_exec( ) is successful. If mi_routine_exec( ) returns NULL, MI_OK indicates that the return value of the executed user-defined routine is NULL.
• MI_ERROR: mi_routine_exec( ) is not successful; it returns NULL.

argument_list

is a list of the routine arguments passed with the appropriate passing mechanism for their data type.

Valid in Client LIBMI Application?	Valid in User-Defined Routine?
Yes	Yes

The mi_routine_exec( ) function is one of the functions of the Fastpath interface. It performs the following tasks:

1. Copies the arguments into the function descriptor that funcdesc_ptr identifies

   To obtain a function descriptor for the user-defined routine, use the mi_routine_get( ), mi_routine_get_by_typeid( ), mi_cast_get( ), or mi_td_cast_get( ) function. The argument list specifies the arguments of the user-defined routine. If you do not specify an argument value, mi_routine_exec( ) uses the default value assigned to that argument. If the user-defined routine does not have any arguments, you can omit the argument list argument from mi_routine_exec( ).

2. Executes the routine within the routine sequence of this function descriptor

   The values within the corresponding MI_FPARAM structure for the routine are consistent between function invocations within the sequence. Use the mi_fparam_get( ) function to obtain this MI_FPARAM structure.

3. Returns an MI_DATUM value that contains the return value of the executed user-defined routine

   A NULL return value means that either the user-defined routine returned a NULL value or that the mi_routine_exec( ) function failed. The error argument holds the status of the mi_routine_exec( ) function. For more information on MI_DATUM values, see the IBM Informix: DataBlade API Programmer's Guide.

The mi_routine_exec( ) function can execute routines across databases.

The following call executes a user-defined function named a_func( ), which returns an integer value:

MI_CONNECTION *conn;
MI_FUNC_DESC *func_desc;
MI_DATUM ret_val;
mi_integer arg1, error;
...
func_desc = mi_routine_get(conn, 0, "a_func(mi_integer)");
ret_val = (mi_integer) mi_routine_exec(conn, func_desc,
   &error, arg1);
if ( ret_val == NULL ) AND ( error == MI_ERROR )
   /* generate an error */
else
   /* obtain function return value from ret_val */

An MI_DATUM value

is the return value of the executed user-defined routine.

NULL

indicates that the user-defined routine returned NULL or that the mi_routine_exec( ) function was not successful. Check the value of error to determine which of these events has occurred.

See also the descriptions of mi_cast_get( ), mi_fparam_get( ), mi_routine_end( ), mi_routine_get( ), mi_routine_get_by_typeid( ), and mi_td_cast_get( ).