The mi_lock_memory() function

The mi_lock_memory() function locks and waits for a named-memory mutex specified by name and duration.

Syntax

mi_integer mi_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_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 waits until this lock has been obtained before it returns control to its calling function.

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_lock_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 for the specified duration.
MI_POTENTIAL_DEADLOCK: The acquisition of a lock on the specified named-memory block failed because it can result in deadlock.
MI_ERROR: The function was not successful.