The mi_routine_exec() function

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

Syntax

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
A pointer to a connection descriptor established by a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect().

This value 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
A pointer to the function descriptor that describes the routine to execute.
error
This value 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 The return value of the executed user-defined routine is NULL.
  • MI_ERROR: mi_routine_exec() is not successful; it returns NULL.
argument_list
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

Usage

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 about MI_DATUM values, see the 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 */
Important: You cannot use the Fastpath interface to execute an iterator function or an SPL function that has WITH RESUME in its RETURN statement. For more information about iterator functions, see the Informix® DataBlade® API Programmer's Guide.

Return values

An MI_DATUM value
The return value of the executed user-defined routine.
NULL
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.