The mi_alloc() function

The mi_alloc() function allocates a block of user memory of a specified size and returns a pointer to that block.

Syntax

void *mi_alloc(size)
   mi_integer size;
size
The number of bytes to allocate.
Valid in client LIBMI application? Valid in user-defined routine?
Yes Yes

Usage

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.

Server only: 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:
  • Use mi_dalloc() instead of mi_alloc() to allocate memory.

    The mi_dalloc() function works in the same way as mi_alloc() and provides the option of specifying the duration.

  • Call mi_switch_mem_duration() before you call mi_alloc().

    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.
Important: In C UDRs, use DataBlade® API memory-management functions to allocate memory. Use of a DataBlade® API memory-management function guarantees that the database server can automatically free the memory, especially in cases of return values or exceptions, where the routine would not otherwise be able to free the memory.
Client only: 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 ignore memory duration.

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.

Return values

A void pointer
A pointer to the newly allocated memory. Cast this pointer to match the user-defined buffer or structure for which the memory was allocated.
NULL
The function was unable to allocate the memory.

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.

For more information, see the discussion on how to allocate user memory in the Informix® DataBlade® API Programmer's Guide.