The mi_dalloc() function

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

Syntax

void *mi_dalloc (size, duration)
   mi_integer size;
   MI_MEMORY_DURATION duration;
size
The number of bytes to allocate.
duration
A value that specifies the memory duration of the user memory to allocate. Valid values for duration follow:
PER_ROUTINE
For the duration of one iteration of the UDR
PER_COMMAND
For the duration of the execution of the current subquery
PER_STATEMENT (Deprecated)
For the duration of the current SQL statement
PER_STMT_EXEC
For the duration of the execution of the current SQL statement
PER_STMT_PREP
For the duration of the current prepared SQL statement
PER_TRANSACTION (Advanced)
For the duration of one transaction
PER_SESSION (Advanced)
For the duration of the current client session
PER_SYSTEM (Advanced)
For the duration of the database server execution
Valid in client LIBMI application? Valid in user-defined routine?
Yes (however, the application ignores memory duration) Yes

Usage

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

Server only:
For most memory allocations in a C UDR, the duration argument must be one of the following public 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 the execution of a subquery is complete.

  • PER_STMT_EXEC

    If you specify PER_STMT_EXEC, the database server frees memory when the execution of an SQL statement is complete.

  • PER_STMT_PREP

    If you specify PER_STMT_PREP, the database server frees memory when a prepared SQL statement terminates.

Important: Use an advanced memory duration in your C UDR only if a regular memory duration cannot safely perform the task you need done. These advanced memory durations have long duration times and can increase the possibility of memory leakage.
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 case of a return value or exception, where the routine would not be able to free the memory.

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

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

Client LIBMI applications ignore memory duration.

Within a callback function, a call to mi_dalloc() that requests a duration of PER_COMMAND returns NULL. Therefore, a callback function 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.

For more information about memory allocation and memory duration, see the Informix® DataBlade® API Programmer's Guide.

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_dalloc() function does not throw an MI_Exception event when it encounters a runtime error. Therefore, the function does not cause callbacks to be invoked.