Informix DataBlade API Programmer's Manual DataBlade API Function Descriptions

The mi_routine_exec() function executes the registered user-defined routine or cast function associated with a specified function descriptor.

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 the connection descriptor that a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect() established.
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 MI_DATUM Data Type.

The following call executes a user-defined function called a_func() that 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 */


Important: You cannot use the Fastpath interface to execute iterator functions or SPL functions with the WITH RESUME keywords in their RETURN statement. For more information on iterator functions, see Writing an Iterator Function.

See the descriptions of the following functions: mi_cast_get(), mi_fparam_get(), mi_routine_get(), mi_routine_get_by_typeid(), mi_routine_end(), and mi_td_cast_get().