Extending INFORMIX-Universal Server: User-Defined Routines

Extending INFORMIX-Universal Server: User-Defined Routines
Chapter 3: Designing a User-Defined Routine

Home Contents Index Master Index New Book

Shared Object Libraries

This section contains information about creating, loading, and replacing shared object libraries with the database server.

Creating a Shared Library

When you create external routines, you put them into a shared library that the database server can access.

Shared object files must be owned by the user ID that runs the database server. In a production installation, Universal Server runs as user informix and shared object files are owned by user informix.

To create a shared library

1. Compile the source file into an object file with the C compiler.

Include any necessary header files that the file needs, such as the library where the DataBlade API functions reside.

The following sample compile command can be used on Solaris systems:

		/compilers/bin/cc -I $INFORMIXDIR/incl -I $INFORMIXDIR/incl/esql -c abs.c

2. Create a shared object library (.so file extension on Solaris systems) and load the object file(s) for the external routine(s).

		/compilers/bin/cc -K abs.o -o abs.so

3. Put the shared library in a directory that is readable by user informix and set the permissions to 755 or 775 so that only the owner can write to the shared object files.

		chmod 755 /usr/code/abs.so

all

4. Specify the path of the shared library in the CREATE FUNCTION (or CREATE PROCEDURE) statement when you register the external routine. CREATE FUNCTION abs_eq(integer, integer)
RETURNS boolean
EXTERNAL NAME
'/usr/code/abs.so(abs_equal)'
LANGUAGE C NOT VARIANT;

Loading a Shared Library into Memory

When an application or the database server invokes one of the UDRs in a shared library, the database server performs the following tasks:

1. If the routine is overloaded, determines which UDR to execute, based upon the arguments specified in the routine invocation

For more information on routine resolution, refer to

"The Routine-Resolution Process"

2. Locates the shared library that contains the UDR from the path column in the sysprocedures system catalog table

3. Loads this shared library into memory, if the library is not already loaded

Use the onstat command-line utility with the -g dll option to view the dynamically loaded libraries in which your user-defined routines reside. Once the database server has loaded a shared library into memory, this library remains in memory until one of the following situations occurs:

All functions in the shared library are dropped with the DROP FUNCTION, DROP ROUTINE, or DROP PROCEDURE statement.

Once all user-defined routines are dropped, the database server automatically unloads the shared library from memory.

The database server is shut down.

All memory that the database server uses is released when the database server shuts down.

Replacing a Shared Object File

You can explicitly replace a shared library without bringing down the database server. You use one of the following user-defined functions that Informix provides to upgrade a shared library:

To replace a loaded shared library with a new version that has the same name and location

	ifx_reload_module

		("module path", "language name")

module path

`c'

`spl'

For example, to reload a new version of the circle.so shared library that resides in the /usr/app/opaque_types directory, you can use the EXECUTE FUNCTION statement to execute the ifx_reload_module() function as follows:

		EXECUTE FUNCTION 

		ifx_reload_module

			("/usr/apps/opaque_types/circle.so", "c")

To replace a loaded shared library with a new version that has a new name or location

		ifx_replace_module ("old module path", 

			"new module path", "language name")

For example, to replace the circle.so shared library that resides in the /usr/app/opaque_types directory with one that resides in the /usr/app/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")

ifx_replace_module

sysprocedures

These functions return one of the following integer values:

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

You can also execute these functions in a SELECT statement. For example, the following SELECT statement executes the ifx_reload_module() statement:

SELECT 

ifx_reload_module("/usr/apps/opaque_types/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.

E/C

When you execute these functions from within an INFORMIX-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.

Important: Do not overwrite a shared object file on disk while it is loaded in memory because you might cause the database server to stop functioning when the overwritten module is accessed or unloaded. Use the ifx_replace_module function to replace the shared object file.

To unload a module without restarting the database server, you must drop all routines in the module using the SQL DROP statement. After you drop all routines in the module and all instances of the routines finish executing, the database server removes the module from the memory map and records a message in the log file to indicate that the module is unloaded. After the module is unloaded, you can replace the shared object file and re-create its user-defined routines in the database.

Extending INFORMIX-Universal Server: User-Defined RoutinesChapter 3: Designing a User-Defined Routine Home Contents Index Master Index New Book

Shared Object Libraries

Creating a Shared Library

To create a shared library

Loading a Shared Library into Memory

Replacing a Shared Object File

Extending INFORMIX-Universal Server: User-Defined Routines
Chapter 3: Designing a User-Defined Routine

Home Contents Index Master Index New Book