Informix DataBlade API Programmer's Manual DataBlade API Function Descriptions

The mi_dalloc() function allocates the specified amount of memory for the specified memory duration and returns a pointer to the allocated block.

void *mi_dalloc (size, duration)

mi_integer size;

MI_MEMORY_DURATION duration;

size	is the number of bytes to allocate.
duration	is the duration of the allocated memory.

Valid in Client LIBMI Application?	Valid in User-Defined Routine?
Yes (however memory duration is ignored)	Yes

The mi_dalloc() function allocates size number of bytes of shared memory with a duration for a DataBlade API module. The mi_dalloc() function is a constructor function for user memory. It behaves exactly like mi_alloc() except that it allows you to explicitly specify the duration of the memory at allocation time.

The duration argument can be any of the following memory-duration constants:

• PER_ROUTINE (or PER_FUNCTION)

If you specify PER_ROUTINE, the database server frees the allocated memory when the UDR returns.

• PER_COMMAND

If you specify PER_COMMAND, the database server frees memory when an SQL command terminates.

• PER_STATEMENT

If you specify PER_STATEMENT, the database server frees memory when an SQL statement terminates.

In C UDRs, the database server automatically frees memory allocated with mi_dalloc() 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 the cases of return values or exceptions, where the routine would not otherwise be able to free the memory.

A UDR can use mi_free() to free memory allocated by mi_dalloc() when that memory is no longer needed.

In client LIBMI applications, mi_dalloc() works exactly like malloc(): storage is allocated on the heap of the client process. However, the database server does not automatically free this memory. Therefore, the client LIBMI application must use mi_free to free explicitly all allocations that mi_dalloc() makes.

Important: Client LIBMI applications ignore memory duration.

Within a callback routine, a call to mi_dalloc() that requests a duration of PER_COMMAND returns NULL. Therefore, a callback routine must call mi_dalloc() with a duration of PER_ROUTINE.

The mi_dalloc() function returns a pointer to the newly allocated memory. Cast this pointer to match the structure of the user-defined buffer or structure that you allocate.

The mi_dalloc() function does not throw an MI_Exception event when it encounters a runtime error. Therefore, it does not cause callbacks to be invoked.

See the descriptions of the following functions: mi_alloc(), mi_free(), mi_switch_mem_duration(), and mi_zalloc().

For more information on memory allocation and memory duration, see Managing User Memory.