Managing the Reference Count

Home | Previous Page | Next Page Data Manipulation > Using Smart Large Objects > Deleting a Smart Large Object >

Managing the Reference Count

The reference count of a smart large object is the number of LO handles that refer to the smart large object in its sbspace. Each LO handle contains the location of the smart large object in an sbspace. The reference count is stored with the smart-large-object data in an sbspace. (For more information on sbspaces, see your IBM Informix: Administrator's Guide.) You can obtain the reference count with the mi_lo_stat_refcnt( ) function.

A smart large object remains allocated as long as its reference count is greater than zero (0). A reference count greater than zero indicates that at least one column contains an LO handle that references the smart large object. In this sense, the smart large object is permanent. The management that the database server performs on a reference count depends on the associated smart large object:

A smart large object whose LO handle is stored in a CLOB or BLOB column
A smart large object whose LO handle is stored in an opaque data type
A transient smart large object

Reference Counts for CLOB and BLOB Columns

For smart-large-object columns (CLOB and BLOB), the database server automatically manages the reference count, as follows:

When you store an LO handle into a CLOB or BLOB column, the smart-large-object optimizer increments by one (1) the reference count for the smart large object that the LO handle identifies.
When you delete an LO handle from a CLOB or BLOB column, the smart-large-object optimizer decrements by one (1) the reference count for the smart large object that the LO handle identifies.

At the end of the transaction, the smart-large-object optimizer automatically deletes all smart large objects stored in CLOB or BLOB columns with reference counts of zero and no open LO file descriptors.

Reference Counts for Opaque-Type Columns

The database server does not automatically manage the reference count for an opaque type that contains a smart large object (including multirepresentational opaque types). For these opaque-type columns, you must explicitly manage the reference count in special support functions of the opaque data type, as follows.

Support Function	Reference-Count Task	DataBlade API Function
assign( )	Increment the reference count by one each time a new LO handle for the smart large object is saved in the database.	mi_lo_increfcount( )
destroy( )	Decrement the reference count by one each time an LO handle that is stored in the database is removed from the database.	mi_lo_decrefcount( )
lohandles( )	If the opaque type does not have an lohandles( ) support function, you must handle the reference count in the assign( ) and destroy( ) support functions. If the opaque type has an lohandles( ) support function, you do not need to handle the reference count in the assign( ) and destroy( ) support functions. The database server handles the decrement of the reference count when it executes the lohandles( ) support function.

If you increment or decrement the reference count for a smart large object within a transaction causing it to end up with a value of zero (0), the database server automatically deletes the smart large object at the end of the transaction (as long as it has no open LO file descriptors).

Reference Counts for Transient Smart Large Objects

A transient smart large object is one that you created but have not stored its LO handle in the database. Transient 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 UDR 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:

SELECT FILETOBLOB(...) FROM table1;

However, the preceding query does not store the LO handles for these smart large objects in any database column. Therefore, each of these smart large objects is transient.

Important:

A smart large object is "temporary" in the sense that it will automatically be deleted at the end of the session (unless its LO handle is stored in the database). A transient smart large object is not a smart large object that is stored in a temporary sbspace.

You only increment the reference count to tell the database server that the LO handle for the smart large object is going to be stored in the database (and become a permanent smart large object). Therefore, the reference count of a transient smart large object is zero. The database server deletes the transient smart large object at the end of the session.

You can explicitly deallocate the LO handle for a transient smart large object with the mi_lo_release( ) function.

You can explicitly delete a transient smart large object with the mi_lo_delete_immediate( ) function.