Using a User-Allocated MI_FPARAM Structure

The Fastpath look-up functions (in Table 65) automatically allocate an MI_FPARAM structure and save a pointer to this structure in the function descriptor that they allocate. However, there are some cases in which you might want to allocate your own MI_FPARAM structure for the UDR that Fastpath executes.

The following DataBlade API functions support use of a user-allocated MI_FPARAM structure.

Creating a User-Allocated MI_FPARAM Structure

The following DataBlade API functions create a user-allocated MI_FPARAM structure and return a pointer to this newly allocated structure:

• The mi_fparam_allocate( ) function allocates an MI_FPARAM structure and returns a pointer to this newly allocated structure.

  This user-allocated MI_FPARAM structure holds the number of arguments that you specify to mi_fparam_allocate( ).

• The mi_fparam_copy( ) function copies an existing MI_FPARAM structure to a new MI_FPARAM structure that the function allocates.

  The user-allocated MI_FPARAM structure holds the same number of arguments as the MI_FPARAM structure that mi_fparam_copy( ) copied.

Both these functions are constructor functions for an MI_FPARAM structure. They allocate the user-allocated MI_FPARAM structure in the current memory duration. By default, the current memory duration is PER_ROUTINE. For calling a UDR with Fastpath, the PER_ROUTINE memory duration refers to the duration of the calling UDR, not the UDR that you call with Fastpath.

If you have changed the current memory duration with the mi_switch_mem_duration( ) function, mi_fparam_allocate( ) or mi_fparam_copy( ) uses the current memory duration that mi_switch_mem_duration( ) has specified for the MI_FPARAM structure that it allocates.

If the current memory duration is not acceptable for your use of the MI_FPARAM structure, call mi_switch_mem_duration( ) with the desired memory duration before the call to mi_fparam_allocate( ) or mi_fparam_copy( ). Keep in mind that when you call mi_switch_mem_duration( ), you change the current memory duration for all subsequent memory allocations, including those made by mi_alloc( ).

Using a User-Allocated MI_FPARAM Structure (Server)

For C UDRs, one of the primary uses of a user-allocated MI_FPARAM structure is for data type control for generic routines. If you are calling a generic UDR, one that handles many possible data types, you can set the arguments in the MI_FPARAM structure to the specific data type. Possible uses for generic UDRs include over collection types or over type hierarchies. You can set the MI_FPARAM structure to accept the correct parameter data types for a particular invocation of the routine. For example, you could pass an employee_t data type into a UDR that was defined with the supertype person_t.

Suppose you have a type hierarchy with person_t as the supertype and employee_t as a subtype of person. The person_udr( ) UDR might be called with either the person_t or employee_t data type in the first two arguments. Suppose person_udr( ) needs to use Fastpath to execute another UDR, named person_udr2( ), to handle some additional task. The following code fragment shows how the second and third arguments from person_udr( ) are passed to person_udr2( ):

person_udr(person1, person2, data, fparam)
   pers_type *person1;
   pers_type *person2;
   mi_lvarchar *data;
   MI_FPARAM *fparam;
{
   MI_TYPEID *pers2_typeid;
   MI_FUNC_DESC *my_funcdesc;
   MI_FPARAM *my_fparam;
   mi_integer *myint_error;

   ...

   pers2_typeid = mi_fp_argtype(fparam, 1);
   my_funcdesc = mi_routine_get(conn, 0, 
      "myfunc(person_t, lvarchar)");
   my_fparam = mi_fparam_get(conn, my_funcdesc);
   mi_fp_setargtype(my_fparam, 0, pers2_typeid);
   mi_routine_exec(conn, my_funcdesc, &myint_error, person2,
      data, my_fparam);
...
}

In the preceding code fragment, the first argument of person_udr2( ) is set to have the same type as the second argument of person_udr( ), based on its MI_FPARAM structure. In this implementation, person_udr2( ) needs the actual data type of the argument, not the supertype.

Passing a User-Allocated MI_FPARAM Structure

To pass the user-allocated MI_FPARAM structure to the Fastpath interface, specify it as the last argument of the argument list that you provide to mi_routine_exec( ). The following call to mi_routine_exec( ) executes the numeric_func( ) UDR (see Figure 51) and specifies a user-allocated MI_FPARAM structure:

my_fparam = mi_fparam_allocate(2);
...
ret_val = mi_routine_exec(conn, fdesc, &error, 1, 2,
   my_fparam);

Freeing a User-Allocated MI_FPARAM

The database server automatically deallocates memory for the MI_FPARAM structures that it allocates for the function descriptor of a UDR. However, the database server does not deallocate any MI_FPARAM structure that you allocate. A user-defined MI_FPARAM structure has a memory duration of PER_COMMAND.

To conserve resources, use the mi_fparam_free( ) function to deallocate explicitly the user-defined MI_FPARAM structure once your DataBlade API module no longer needs it. The mi_fparam_free( ) function is the destructor function for a user-defined MI_FPARAM structure. It frees the MI_FPARAM structure and any resources that are associated with it.