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.