The mi_call() function

The mi_call() function checks if there is sufficient stack space for the specified user-defined routine and extends the stack size if necessary.

Syntax

mi_integer mi_call(retval, routine, nargs, argument_list)
   mi_integer *retval;
   mi_integer (*routine)();
   mi_integer nargs;
   argument_list
retval
A pointer to the location of the user-defined-function return value.
routine
A pointer to the user-defined routine.
nargs
The number of the arguments (up to a maximum of 10) in the argument list.
argument_list
A comma-separated list of from 0 to 10 arguments to pass to the user-defined routine.
Valid in client LIBMI application? Valid in user-defined routine?
No Yes

Usage

The mi_call() function allocates stack space for the user-defined routine that routine references. The function determines the amount of memory to allocate based on the following information:
  • The return value, which retval references (for user-defined functions only)
  • The number of arguments, nargs (for all user-defined routines)

The mi_call() function creates a stack only if the current stack is not large enough to hold the arguments and possible return value of the UDR. If a new stack is required, mi_call() creates it and copies onto it the number of arguments that nargs specifies. Pass the actual argument values as a comma-separated list following the nargs value.

When mi_call() copies the arguments onto this new stack, the function uses the MI_DATUM size as the size of each argument. If a routine argument is larger than an MI_DATUM structure, mi_call() does not copy all the argument bytes. You must use the correct passing mechanism for routine arguments to ensure that they fit into the size of an MI_DATUM structure.

After arguments are copied to the stack, the mi_call() function calls the specified UDR and executes it. If the UDR is a user-defined function, mi_call() puts its return value at the address that retval references.

For more information, see the discussion of control modes for query data in the Informix® DataBlade® API Programmer's Guide.

Return values

MI_NOMEM
The mi_call() function was unable to allocate virtual memory.
MI_TOOMANY
The nargs argument is greater than 10.
MI_CONTINUE
The current stack is large enough to hold the invocation of routine: no reallocation is required.
MI_DONE
The current stack was not large enough to hold the invocation of routine: mi_call() allocated a new thread stack, then called routine and put any return value in retval.