INFORMIX
DataBlade API Programmer's Manual
Chapter 12: DataBlade API Function Descriptions
Home Contents Index Master Index New Book

mi_dalloc()

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

Syntax

Usage

 The mi_dalloc() function behaves exactly like mi_alloc() except that the duration of the memory is explicitly specified at allocation time.

In client applications, mi_dalloc() works exactly like malloc(): storage is allocated on the heap of the client process. No automatic freeing is performed; the application must use mi_free to free explicitly all allocations that use mi_dalloc().

Important: Client applications ignore duration.

In server functions, memory allocated with mi_dalloc() is automatically freed when an exception is raised. A server function can use mi_free() to free memory allocated by mi_alloc(), mi_dalloc(), or mi_zalloc() if that memory is no longer needed.

Always use either mi_alloc(), mi_dalloc(), or mi_zalloc() to allocate memory for server DataBlade API applications.

Memory can be allocated with a duration of either PER_FUNCTION or PER_COMMAND. If PER_FUNCTION is specified, memory is freed when the function returns. If PER_COMMAND is specified, memory is freed by the database server when a statement or command terminates. This distinction is important because a single SQL statement might result in multiple calls to the function, for example, to return a set. In that case, memory with a duration of PER_FUNCTION would be available only for a single call to the function; memory with a duration of PER_COMMAND would be available for the entire duration of the statement, regardless of the number of function calls involved.

A callback routine must call mi_dalloc() with a duration of PER_FUNCTION. Within a callback routine, a call to mi_dalloc() that requests a duration of PER_COMMAND would return NULL.

When an application uses mi_alloc() to allocate memory, the default duration is PER_FUNCTION.

This function requires the inclusion of mitypes.h.

Return Values

On success, returns a pointer to the newly allocated memory; on failure, returns NULL.

Related Topics

For additional information, see the descriptions of the following functions: mi_alloc(), mi_free(), mi_switch_mem_duration(), and mi_zalloc().



DataBlade API Programmer's Manual, version 9.1
Copyright © 1998, Informix Software, Inc. All rights reserved.