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 OneDB™ 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.