Load a shared-object file

When you compile a C UDR, you store its object code in a shared-object file.

(For more information, see Compile a C UDR.) For a UDR to execute, its object code must be in the memory so that a virtual processor (VP) can execute it. The database server uses virtual processors to service client-application SQL requests. A thread is a database server task that a VP schedules for processing.

Tip: For a detailed discussion of virtual processors and threads, see Virtual processors.

When the routine manager reaches the first occurrence of the UDR in the SQL statement, the routine manager determines whether its shared-object file is currently loaded into the memory space of the appropriate VP class. If the file is not yet loaded, the routine manager dynamically loads its code and data sections into the data segment for all virtual processors of the VP class. The routine manager obtains the pathname of the shared-object file from the externalname column of the row in the sysprocedures system catalog for the UDR. This loading occurs for both explicit UDR calls and implicit calls (such as operator functions and opaque-type support functions).

The following figure shows a schematic representation of what VPs look like after the routine manager loads a shared-object file.

Figure 1. Loading a shared-object file

begin figure description - This figure is described in the surrounding text. - end figure description

In the preceding figure, assume that the func1(), func2() and func3() functions are registered as user-defined functions with the CREATE FUNCTION statement and linked into the source1.so UNIX or Linux shared-object file. The client application calls the func1() user-defined function within a SELECT statement. The routine manager loads the source1.so file into memory, if this file is not yet loaded. For subsequent references to these UDRs, the routine manager can skip the shared-object load.

The routine manager sends an entry to the message log file about the status of the shared-object load, as follows:

When it successfully loads the shared-object file
When it is not able to load the shared-object file for any of the following reasons:
- The routine manager cannot find the shared-object file.
- The shared-object file does not have read permission.
- One of the symbols in the shared-object file cannot be resolved.
When it unloads a shared-object file

For example, when the routine manager loads the source1.so shared-object file, the message log file would contain messages of the form:

12:28:45 Loading Module </usr/udrs/source1.so>
12:28:45 The C Language Module </usr/udrs/source1.so> loaded

Check the message log file for these messages to ensure that the correct shared-object file is loaded into the virtual processors.

You can monitor the loaded shared-object files with the -g dll option of onstat. This option lists the shared-object files that are currently loaded into the database server.

For information about when the shared-object file is unloaded, see Unload a shared-object file. For information about how to create a shared-object file, see Creating a shared-object file. For general information about loading a shared-object file, see the HCL Informix® User-Defined Routines and Data Types Developer's Guide.