void *mi_alloc(size)
mi_integer size;
The mi_alloc( ) function allocates size number of bytes of user memory for a DataBlade API module. The mi_alloc( ) function is a constructor function for user memory.
From the point of view of a C user-defined routine, this function behaves like the malloc( ) system call, except that the database server can reclaim memory that mi_alloc( ) allocates. The mi_alloc( ) function allocates the memory in the current memory duration. By default, the current memory duration is PER_ROUTINE. With the PER_ROUTINE duration, the database server frees the allocated memory after the C UDR returns.
Except in callback routines, you can change the memory duration in either of the following ways:
The mi_dalloc( ) function works in the same way as mi_alloc( ) and provides the option of specifying the duration.
The mi_switch_mem_duration( ) function changes the current memory duration for all subsequent memory allocations.
In UDR routines, the database server automatically frees memory allocated with mi_alloc( ) when an exception is raised.
In client LIBMI applications, mi_alloc( ) works exactly as malloc( ) does: it allocates storage on the heap of the client process. The database server does not perform any automatic storage retrieval. The client LIBMI application must use mi_free( ) to free explicitly all allocations that mi_alloc( ) makes.
Client LIBMI applications can use either DataBlade API memory-management functions or system memory-management functions (such as malloc( )).
The mi_alloc( ) function returns a pointer to the newly allocated user memory. Cast this pointer to match the structure of the user-defined buffer or structure that you allocate. A DataBlade API module can use mi_free( ) to free memory allocated by mi_alloc( ) when that memory is no longer needed.
The mi_alloc( ) function does not throw an MI_Exception event when it encounters a runtime error. Therefore, it does not cause callbacks to be invoked.
See also the descriptions of mi_dalloc( ), mi_free( ), mi_realloc( ), mi_switch_mem_duration( ), and mi_zalloc( ).
For more information, see the discussion on how to allocate user memory in the IBM Informix: DataBlade API Programmer's Guide.