Modifying a C UDR

When the database server shuts down, it releases all memory that it has reserved, including memory for shared-object modules.

To unload a shared-object module from memory without restarting the database server, you must drop all routines that the shared library contains. Use the SQL DROP ROUTINE, DROP FUNCTION, or DROP PROCEDURE statement to unregister a UDR. These statements remove the registration information about the UDR from the system catalog tables.

Removing Routines from the Shared Library

The following conditions cause the database server to remove the shared-object file from the memory map:

• You drop all routines in the module.
• All instances of the routines finish executing.
• You explicitly call ifx_unload_module.

Once these conditions are true, the database server automatically unloads the shared-object file from memory. It also puts a message in the log file to indicate that the shared object is unloaded. Once the shared object is unloaded, you can replace the shared-object file on disk and reregister its UDRs in the database.

You can use the onstat utility to verify that a module actually was unloaded:

onstat -g dll

Do not overwrite a shared-object file on disk while it is loaded in memory because you might cause the database server to generate an error when the overwritten module is accessed or unloaded. Use the ifx_replace_module() function to replace a loaded shared object file with a new version. For information on the ifx_replace_module() function, see the description of Function Expressions within the Expression segment in the IBM Informix: Guide to SQL Syntax.

For example, to replace the circle.so shared DataBlade API library that resides in the /usr/apps/opaque_types directory with one that resides in the /usr/apps/shared_libs directory, you can use the EXECUTE FUNCTION statement to execute the ifx_replace_module(), as follows:

EXECUTE FUNCTION
   ifx_replace_module("/usr/apps/opaque_types/circle.so",
      "/usr/apps/shared_libs/circle.so", "c")

The ifx_replace_module() function updates the sysprocedures system catalog with the new name or location. This functions return one of the following integer values:

• Zero indicates success.
• A negative value indicates an error message number.

You can also execute the ifx_replace_module() function in a SELECT statement, as follows:

SELECT
   ifx_replace_module("/usr/apps/opaque_types/circle.so",
      "/usr/apps/shared_libs/circle.so", "c")
   FROM customer
   WHERE customer_id = 100

If you do not want the shared library replaced multiple times with this SELECT statement, ensure that the SELECT statement returns only one row of values.