The mi_try_lock_memory() function

The mi_try_lock_memory() function requests a lock on a named-memory block specified by name and memory duration.

Syntax

mi_integer mi_try_lock_memory(mem_name, duration)
   mi_string *mem_name;
   MI_MEMORY_DURATION duration;

mem_name

The null-terminated name of the named-memory block to lock.

duration

A value that specifies the memory duration of the named-memory block to lock. 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

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_try_lock_memory() function requests a lock on the named-memory block based on its memory duration of duration and its name, which mem_name references. The function does not wait until this lock has been obtained before it returns control to its calling function. If some other process currently holds a lock on the memory, mi_try_lock_memory() returns a status of MI_LOCK_IS_BUSY. The calling code can call mi_try_lock_memory() in a loop until the function returns the MI_OK status.

Important: After you obtain a lock on a named-memory block, release it as soon as possible. You must explicitly release a named-memory lock with the mi_unlock_memory() function.

Return values

MI_OK: The function successfully locked the specified named-memory block.
MI_NO_SUCH_NAME: The requested named-memory block does not exist.
MI_LOCK_IS_BUSY: The acquisition of a lock on the specified named-memory block failed because it is locked by another process.
MI_ERROR: The function was not successful.