The mi_named_get() function

The mi_named_get() function retrieves the address of a named-memory block.

Syntax

mi_integer mi_named_get (mem_name, duration, mem_ptr)
   mi_string *mem_name;
   MI_MEMORY_DURATION duration;
   void **mem_ptr;
mem_name
The null-terminated name of the named-memory block whose address the function retrieves.
duration
A value that specifies the memory duration of the named-memory block to retrieve. 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 retrieved 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_get() function obtains the address of a named-memory block based on its memory duration of duration and its name, which mem_name references. This function is useful in a UDR that needs access to a particular block of named memory. The UDR can specify the name and memory duration of the desired named-memory block to mi_named_get() and receive the address of this memory.
Important: The mi_named_get() function only retrieves the address of a block of named memory. It does not request a lock on this memory.

Return values

MI_OK
The function successfully retrieved the specified named-memory block and a pointer to this block is stored in mem_ptr.
MI_NO_SUCH_NAME
The requested named-memory block does not exist.
MI_ERROR
The function was not successful. The mem_ptr pointer is set to a NULL-valued pointer.