The mi_named_zalloc() function

The mi_named_zalloc() function allocates and initializes a named-memory block in the specified memory duration.

Syntax

mi_integer *mi_named_zalloc(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 zero-filled 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_zalloc() function allocates a named-memory block of size bytes of memory, with a memory duration of duration, and assigns it the name that mem_name references. It then initializes this named-memory block with zeros. The function saves the pointer to the allocated named-memory block in the mem_ptr argument. The mi_named_zalloc() function is a constructor function for named memory.

Important: The mi_named_zalloc() 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_free() function to free named memory when that memory is no longer needed.

Return values

MI_OK: The function was successful.
MI_NAME_ALREADY_EXISTS: A named-memory block with the mem_name name exist for the specified duration.
MI_ERROR: The function was not successful.