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.