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.