Unloading a Shared-Object File

In an attempt to keep memory usage to a minimum, the routine manager attempts to unload a shared-object file when it finds that no one is using any of its UDRs. That is, it unloads a shared-object file when all references to the UDRs within the shared-object file are removed from the internal cache of the database server and any one of them is marked as being dropped.

The database server cleans up its cache entries when you take any of the following actions:

• Explicitly drop a UDR

  When you use the DROP FUNCTION, DROP PROCEDURE, or DROP ROUTINE to drop all UDRs in a shared-object file, the routine manager unloads the shared-object file.

• Explicitly drop a database

  The routine manager unloads all shared-object files when DROP DATABASE executes.

• Create and reference UDRs in a transaction

For example, in the following SQL fragment, the shared-object file thrashes in and out of memory because the transaction has private cache entries until committed and the management mechanism treats them as being dropped:

BEGIN WORK;
CREATE FUNCTION c_func( ) ...;
CREATE FUNCTION spl_func( ) RETURNING c_func( )...;
COMMIT WORK;

To unload a shared-object file, you can take any of the following actions:

• For each routine that references the shared object (external file), execute the following SQL statement

  ALTER ROUTINE routine-name (args, ...)
     WITH (
           MODIFY EXTERNAL NAME = 'shared-obj'
           );

  The new pathname for the shared object must be different from the existing one for the shared object to be unloaded. Instead of ROUTINE, you can specify FUNCTION for a function or PROCEDURE for a procedure.

  After the last routine is altered, nothing in the database server should refer to the old shared object, and a message appears in the online log to report that the shared object has been unloaded.

• Drop all UDRs in the shared-object file

  When you execute DROP FUNCTION, DROP PROCEDURE, or DROP ROUTINE to drop all UDRs in a shared-object file, the routine manager unloads the shared-object file. Similarly, the routine manager unloads all shared-object files when DROP DATABASE executes. Execution of one of these SQL statements is the safest way to unload a shared-object file.

• Execute the SQL procedure, ifx_unload_module( ), to request that an unused shared-object file be unloaded

  The ifx_unload_module( ) function can only unload an unused shared-object file; that is when no executing SQL statements (in any database) are using any UDRs in the specified shared-object file. If any UDR in the shared-object file is currently in use, ifx_unload_module( ) raises an error.

• Load a new module of a different name with the SQL function ifx_replace_module( )

  With the ifx_replace_module( ) function, you do not have to change all the routine definitions. This action should eventually cause the old shared-object file to unload.

For the syntax of the ifx_unload_module( ) and ifx_replace_module( ) functions, see the IBM Informix: Guide to SQL Syntax.

DataBlade modules can be shared across databases. Therefore, you might have more than one database using the same DataBlade module.

In Figure 65, the routine manager has loaded the shared-object file named source1.so. This shared-object file contains definitions for the user-defined functions func1( ), func2( ), and func3( ).

The routine manager sends an entry in the message log file when it loads and unloads a shared-object file. When the routine manager unloads the source1.so shared-object file, the message-log file would contain messages of the form:

19:14:44  Unloading Module </usr/udrs/source1.so>
19:14:44  The C Language Module </usr/udrs/source1.so> unloaded

The message-log file is a useful place to check that the shared-object file is unloaded from the virtual processors. Alternatively, you can use the onstat -g dll command to monitor the results of an shared-object-file unload.

For information about when the shared-object file is loaded, see Loading a Shared-Object File. For information on how to prevent a shared-object file from being unloaded, see Locking a Shared-Object File in Memory.