The mi_named_alloc() function
The mi_named_alloc() function allocates a named block of memory of the specified size in the specified memory duration.
Syntax
mi_integer mi_named_alloc(size, mem_name, duration, mem_ptr)
mi_integer size;
mi_string *mem_name;
MI_MEMORY_DURATION duration;
void **mem_ptr;- size
- The number of bytes to allocate to the named-memory block.
- mem_name
- The null-terminated name to assign the named-memory block.
- duration
- A value that specifies the memory duration of the named-memory
block to allocate. Valid values for duration are:
- 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
- For the duration of one transaction
- PER_SESSION
- For the duration of the current client session
- PER_SYSTEM
- For the duration of the database server execution
- mem_ptr
- The pointer to the allocated named-memory block.
| Valid in client LIBMI application? | Valid in user-defined routine? |
|---|---|
| No | Yes |
Important: This advanced function can adversely
affect your UDR if you use the function incorrectly. Use it only when
no regular DataBlade®
API function
can perform the task you need done.
Usage
The mi_named_alloc() function
allocates a named-memory block of size bytes of memory, with
a memory duration of duration, and assigns the block the name
that mem_name references. The function saves the pointer to
the allocated named-memory block in the mem_ptr argument. The mi_named_alloc() function
is a constructor function for named memory.
Important: The mi_named_alloc() function
only allocates a block of named memory. It does not request a lock
on this memory.
A DataBlade API module can use the mi_named_alloc() function to free named memory when that memory is no longer needed.
Return values
- MI_OK
- The function successfully allocated the specified named-memory block and a pointer to this block is stored in mem_ptr.
- MI_NAME_ALREADY_EXISTS
- A named-memory block with the mem_name name exists for the specified duration.
- MI_ERROR
- The function was not successful. The mem_ptr pointer is set to a NULL-valued pointer.