DataBlade API Programmer's Manual
Chapter 12: DataBlade API Function Descriptions
Home
Contents
Index
Master Index
New Book
mi_alloc()
The
mi_alloc()
function allocates a block of memory of the given size and returns a pointer to that block.
Syntax
void *mi_alloc(
size
)
mi_integer size;
size
is the number of bytes to allocate.
Valid in Client Application?
Valid in Server Routine?
Yes
Yes
Usage
In server applications, memory can be allocated with a duration of either
PER_FUNCTION
or
PER_COMMAND
. If
PER_FUNCTION
is specified, memory is freed after the server 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.
The default duration set by
mi_alloc()
is
PER_FUNCTION
. Except in callback routines, you can change the duration to
PER_COMMAND
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 adds the option of specifying the duration.
Call
mi_switch_mem_duration()
,
with a duration of
PER_COMMAND
, before you call
mi_alloc()
.
For additional information about memory allocation and duration, see the descriptions of the
mi_dalloc()
and
mi_switch_mem_duration()
functions.
All memory within server functions should be allocated with a DataBlade API allocation function such as
mi_alloc()
rather than with
malloc()
. The use of a DataBlade API allocation function guarantees that the memory automatically gets freed, especially in the cases of return values or exceptions, where the function would not otherwise be able to free the memory. In server functions, memory allocated with
mi_alloc()
is automatically freed when an exception is raised. Free memory explicitly with
mi_free()
wherever possible.
In client applications,
mi_alloc()
works exactly as
malloc()
does: storage is allocated on the heap of the client process. No automatic freeing is performed; the application must use
mi_free
to explicitly free all allocations that use
mi_alloc()
. Therefore, client applications can use either DataBlade API allocation functions or
malloc()
.
Important:
Client applications ignore duration.
This function requires the inclusion of
mitypes.h
.
Return Values
On success, returns a pointer to the newly allocated memory; if unable to allocate the memory, returns
NULL
.
Related Topics
For additional information, see the descriptions of the following functions:
mi_dalloc()
,
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.
