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.