The mi_call_on_vp() function

The mi_call_on_vp() function enables you to switch execution to a specified virtual processor (VP) to execute a specified C function.

Syntax

mi_integer mi_call_on_vp(VP_id, retval, C_func, nargs, argument_list)
   mi_integer VP_id;
   mi_integer *retval;
   mi_integer (*C_func)();
   mi_integer nargs;
   argument_list;

VP_id: The integer VP-class identifier of the VP on which to execute the specified C function. The VP that executes this C function must be a CPU VP or in a user-defined VP class. You cannot execute the C function in some other system VP class.
retval: A pointer to the integer return value of the specified C function.
C_func: A pointer to the executable C function to execute on the specified VP.
nargs: The number of arguments (up to a maximum of 10) to pass to the specified C function.
argument_list: A comma-separated list of value from 0 - 10 arguments to pass to the specified C function.

Valid in client LIBMI application?	Valid in user-defined routine?
No	Yes

Important: This advanced function can adversely affect your UDR if you use the function incorrectly. Use it only when no regular DataBlade API function can perform the task you need done.

Usage

The mi_call_on_vp() function calls the C function that C_func references on the VP that VP_id identifies. To the specified C function, mi_call_on_vp() passes the number of arguments that nargs specifies. In the mi_call_on_vp() function call, pass the actual argument values as a comma-separated list following the nargs value. When the C function completes execution, mi_call_on_vp() puts its return value in the address that retval references.

The mi_call_on_vp() function takes the following steps:

Switches the current thread to the VP of the specified VP identifier
Executes the C function that the C_func pointer indicates
Returns control to the originating VP

After a successful return, the C_func function has been executed on the specified VP.

The mi_call_on_vp() function does not switch VPs in the following cases:

If the originating VP and specified VP (VP_id) are identical
The mi_call_on_vp() function performs no switching but does not return an error.
If the specified VP (VP_id) is not a CPU VP or user-defined VP
The mi_call_on_vp() function performs no switching and returns an error (MI_ERROR). The message log provides more information about why the switch failed.

For more information about how to switch VPs, see the HCL Informix® DataBlade API Programmer's Guide.

Return values

MI_DONE: The C_func function was successfully called and its return value is referenced by retval.
MI_TOOMANY: The nargs argument is greater than 10.
MI_ERROR: The function was unable to switch VPs. The online log provides more information about why the switch failed.