IFX_REPLACE_MODULE Function (IDS, C)

Enterprise Edition Home | Express Edition Home | Previous Page | Next Page Data Types and Expressions > Expression >

IFX_REPLACE_MODULE Function (IDS, C)

The IFX_REPLACE_MODULE function replaces a loaded shared-object file with a new version that has a different name or location. If the IFX_EXTEND_ROLE configuration parameter is set to ON, authorization to use this function is available only to the Database Server Administrator (DBSA), and to users whom the DBSA has granted the EXTEND role.

IFX_REPLACE_MODULE Function:
 
|--IFX_REPLACE_MODULE--(--old_module--,--new_module--,--"C"--)--|

Element	Description	Restrictions	Syntax
new_module	Full pathname of the new shared-object file to replace the shared-object file that old_module specifies	The shared-object file must exist with the specified pathname, which can be no more than 255 bytes long	Quoted String, p. Quoted String
old_module	Full pathname of the shared-object file to replace with the shared-object file that new_module specifies	The shared-object file must exist with the specified pathname, which can be no more than 255 bytes long	Quoted String, p. Quoted String

The IFX_REPLACE_MODULE function returns an integer value to indicate the status of the shared-object-file replacement, as follows:

Zero (0) to indicate success
A negative integer to indicate an error

Important:

Do not use the IFX_REPLACE_MODULE function to reload a module of the same name. If the full names of the old and new modules that you send to ifx_replace_module( ) are the same, then unpredictable results can occur.

After IFX_REPLACE_MODULE completes execution, the database server ages out the old_module shared-object file; that is, all statements subsequent to the IFX_REPLACE_MODULE function will use UDRs in the new_module shared-object file, and the old module will be unloaded when any statements that were using it are complete. Thus, for a brief time, both the old_module and the new_module shared-object files could be resident in memory. If this aging out behavior is undesirable, use the IFX_UNLOAD_MODULE procedure to unload the shared-object file completely.

On UNIX, for example, suppose you want to replace the circle.so shared library, which contains UDRs written in the C language. If the old version of this library resides in the /usr/apps/opaque_types directory and the new version in the /usr/apps/shared_libs directory, then the following EXECUTE FUNCTION statement executes the IFX_REPLACE_MODULE function:

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

On Windows, for another example, suppose you want to replace the circle.dll dynamic link library, which contains C UDRs. If the old version of this library resides in the C:\usr\apps\opaque_types directory and the new version in the C:\usr\apps\DLLs directory, then the following EXECUTE FUNCTION statement executes the IFX_REPLACE_MODULE function:

EXECUTE FUNCTION ifx_replace_module(
   "C:\usr\apps\opaque_types\circle.dll", 
   "C:\usr\apps\DLLs\circle.dll", "C")

To execute the IFX_REPLACE_MODULE function in an IBM Informix ESQL/C application, you must associate the function with a cursor.

For more information on how to use IFX_REPLACE_MODULE to replace a shared-object file, see the chapter on how to design a UDR in IBM Informix User-Defined Routines and Data Types Developer's Guide. For information on how to use the IFX_UNLOAD_MODULE procedure, see the section IFX_UNLOAD_MODULE Procedure (IDS, C).