The mi_lo_release() function

The mi_lo_release() function tells the database server that the resources that are associated with a temporary smart large object can be released.

Syntax

mi_integer mi_lo_release(conn, LO_hdl)
   MI_CONNECTION *conn;
   MI_LO_HANDLE *LO_hdl;
conn
This value is one of the following connection values:

A pointer to a connection descriptor established by a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect().

A NULL-valued pointer (database server only)

LO_hdl
The LO handle for the temporary smart large object whose resources are to be deallocated.
Valid in client LIBMI application? Valid in user-defined routine?
Yes Yes

Usage

The mi_lo_release() function frees the LO handle that LO_hdl references, thereby decrementing the reference count of the smart large object by one. This function is a destructor function for the LO handle. It is useful for telling the database server that it is safe to release resources associated with a temporary smart large object. A temporary smart large object is one that has one or more LO handles, but none of these handles have been inserted into a table. Temporary smart large objects can occur in the following ways:
  • You create a smart large object (with mi_lo_create(), mi_lo_copy(), mi_lo_expand(), or mi_lo_from_file()) but do not insert its LO handle into a column of the database.
  • You invoke a user-defined routine that creates a smart large object in a query but never assigns its LO handle to a column of the database.
For example, the following query creates one smart large object for each row in the table1 table and sends each one to the client application: 
SELECT filetoblob(...) FROM table1;

The client LIBMI application can use the mi_lo_release() function to indicate to the database server when it finishes processing each of these smart large objects. Once you call this function on a temporary smart large object, the database server is free to release the resources at any time. Further use of the LO handle and any associated LO file descriptors is not guaranteed to work.

Use of this function on smart large objects that are not temporary does not cause any incorrect behavior; however, the call is expensive. You do not need to use this function for permanent smart large objects.

Server only: The mi_lo_release() function does not need a connection descriptor to execute. If your UDR does not need a valid connection for other operations, you can specify a NULL-valued pointer for the conn parameter to establish a NULL connection. For information about the advantages of a NULL connection, see the Informix® DataBlade® API Programmer's Guide.

Return values

MI_OK
The function was successful.
MI_ERROR
The function was not successful.