The mi_switch_mem_duration() function

The mi_switch_mem_duration() function switches the current memory duration.

Syntax

MI_MEMORY_DURATION mi_switch_mem_duration(duration)
   MI_MEMORY_DURATION duration;
duration
A value that specifies the new current memory duration. 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 (Advanced)
For the duration of one transaction
PER_SESSION (Advanced)
For the duration of the current client session
PER_SYSTEM (Advanced)
For the duration of the database server execution
Valid in client LIBMI application? Valid in user-defined routine?
Valid, but ignored Yes

Usage

Server only:
The mi_switch_mem_duration() function switches the current memory duration to duration. The current memory duration affects the duration of all subsequent memory allocations made by any DataBlade® API constructor function that allocates its data structure in the current memory duration. For a list of these constructor functions, see the Informix® DataBlade® API Programmer's Guide. This new current memory duration remains in effect until one of the following actions occurs:
  • The user-defined routine completes.
  • You change the memory duration again with another call to mi_switch_mem_duration().
For most memory allocations in a C UDR, the duration argument must be one of the following public memory-duration constants:
  • PER_ROUTINE (or PER_FUNCTION)
  • PER_COMMAND
  • PER_STMT_EXEC
  • PER_STMT_PREP
Important: Only use a restricted memory duration in your C UDR if a public memory duration will not safely perform the task. These restricted memory durations have long duration times and can increase the possibility of memory leakage.

The mi_switch_mem_duration() function does not change the memory duration for the current allocation.

The mi_switch_mem_duration() function returns the previous memory duration. You can save the previous memory duration to switch the memory duration back after performing some allocations. For example, if the memory duration was switched from PER_ROUTINE to PER_COMMAND for a particular purpose, you can invoke mi_switch_mem_duration() to switch back to PER_ROUTINE duration once PER_COMMAND is no longer required. This action can avoid unnecessary memory consumption.

Client only: The mi_switch_mem_duration() function has no effect when it is invoked in a client LIBMI application. Client LIBMI applications ignore memory duration.

For more information about memory allocation and memory durations, see the Informix® DataBlade® API Programmer's Guide.

Return values

An MI_MEMORY_DURATION constant
A constant that indicates the previous memory duration.
MI_ERROR
The function was not successful.