Extending Informix Dynamic Server 2000 Managing a User-Defined Routine

To reload a user-defined routine explicitly, reload its shared-object file. The following methods reload a shared-object file without bringing down the database server:

• Unload and reload the shared-object module by dropping and reregistering all routines in the module.
• Replace a shared-object module with the ifx_replace_module() function.

Shared-object files are also unloaded when the database server is shut down. All memory that the database server uses, including memory for shared-object modules, is released when the database server shuts down.

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 user-defined routine. These statements remove the registration information about the user-defined routine from the system catalog tables.

The database server removes the shared-object file from the memory map after both of the following conditions occur:

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

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 user-defined routines in the database.

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 the shared object file. The surest way to unload a shared-object file is to drop all routines that the module contains.

Tip: SPL p-code is not compiled into shared-object modules. Therefore, the Routine Manager does not need to unload SPL routines.

Using the ifx_replace_module() Function

You can use the ifx_replace_module() user-defined function, which Informix provides, to replace a loaded shared-object module with a new version that has a new name. Use the following syntax for ifx_replace_module():

ifx_replace_module ("old module path", "new module path",
	"language name")

 



old module path

A character string that lists the full path of the current name of the shared-object module.


new module path

A character string that lists the full path of the new name of the shared-object module.


language name

A character string that specifies the name of the language in which the UDRs within the shared-object module are written.






For a DataBlade API shared-object library, language name must be "c".  






For a Java db-applet shared object, language name must be "dbapplet".  

For more information on the syntax of the ifx_replace_module() function, see the description of Function Expressions within the Expression segment in the Informix Guide to SQL: Syntax.

For example, to replace the circle.so shared 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.

When you execute these functions from within an ESQL/C application, you must associate the EXECUTE FUNCTION statement with a function cursor. For more information on writing ESQL/C applications, refer to the Informix ESQL/C Programmer's Manual.