Informix DataBlade API Programmer's Manual Developing a User-Defined Routine

To compile a C UDR, use a C compiler to compile the source file (.c file extension) into an object file (.o file extension) and create a shared-object file that contains the object file.

Tip: The Informix BladeSmith development tool, which is part of the DataBlade Developers Kit, automatically generates makefiles to compile the DataBlade module code that it generates. It creates a makefile for both the UNIX (with a .mak extension) and Windows (with a .dsw extension) platforms.A makefile automates compilation of C UDRs.To compile a C UDR into a shared-object file (with a .bld extension) you only have to run the appropriate makefile. For more information, see the "DataBlade Developers Kit User's Guide."

Compiling Options

Use the C compiler to compile a C UDR. Include the following compiler options:

• Specify the necessary paths for any header files that the file needs, such as an mi.h header file, which includes the declarations of the DataBlade API data structures and functions.

These paths include the following subdirectories of the main Informix installation directory (which the INFORMIXDIR environment variable specifies):

• The incl/public subdirectory contains public header files, such as mi.h.
• The incl/esql subdirectory contains Informix ESQL/C header files, such as decimal.h.

• Indicate that the DataBlade API module is a C UDR with the following compiler flag:
MI_SERVBUILD

On a Solaris system, the following sample command compiles the C UDR in the abs.c source file:

cc -KPIC -DMI_SERVBUILD -I$INFORMIXDIR/incl/public \

-I$INFORMIXDIR/incl -L$INFORMIXDIR/esql/lib -c abs.c

The following command is a sample of how to compile a C UDR called abs.c for the Windows NT platform:

cl /DNT_MI_SAPI /DMI_SERVBUILD 

-Id:\msdev\include -Id:\informix\incl\public 

-Id:\informix\incl -c abs.c

For C UDRs, you create a shared-object file to hold the compiled UDRs. This file resides in a directory on the server computer. Each UDR must have a unique name within the shared-object file.

On UNIX systems, a shared-object file is often called a shared library. On Solaris systems, shared-object files have the .so file extension.

On Windows NT systems, a shared-object file is called a dynamic link library (DLL). DLLs usually have the .dll file extension.

When the database server executes an SQL statement that contains a UDR, it loads in memory the shared-object file in which the UDR executable code resides. It determines which shared-object file to load from the externalname column of the sysprocedures system catalog table. The CREATE FUNCTION or CREATE PROCEDURE statement makes a row in this table for a particular UDR when it registers the routine.

The following steps outline how to create a shared-object file for a C UDR:

1. Create a shared-object file and put the UDR object (.o file) file for the UDR into this shared-object file.

You can put related UDRs into the same shared-object file. However, each function name must be unique within the shared-object file.

2. Put the shared-object file in a directory on which the user informix has read permission and the shared-object owner has write permission.

The shared-object file must not have permission that allows any user other than user informix to have write permission.

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

The shared-object file does not have to exist before you register its path with CREATE FUNCTION or CREATE PROCEDURE. However, at UDR runtime, the paths of the shared-object file and the registered UDR must match for the database server to locate the UDR.

Important: If a shared-object file has write permission set to all, the database server issues error -9793 and writes a message in the log file when someone tries to execute any UDR in the shared object.

For general information on how to create a shared-object file, see the chapter on how to run a user-defined routine in Extending Informix Dynamic Server 2000. For more information on how the database server loads a shared-object file, see Executing a User-Defined Routine.

The following steps show how to create a shared library called abs.so on a Solaris system.

1. The following sample command loads the abs.o object file into the abs.so shared library:
ld -G abs.o -o abs.so
2. Put the shared library in a directory on which the user informix has read permission and set the permissions to 755 or 775 so that only the owner can write to the shared libraries.
# ls -ld /usr/code
drwxr-xr-x 12 informix devel 2560 Feb 25 05:27
/usr/code
# chmod 775 /usr/code/abs.so
drwxrwxr-x 12 informix devel 2560 Feb 25 05:27
/usr/code

The following steps show how to create a DLL called abs.dll on a Windows NT system.

1. The following sample command loads the abs.o object file into the abs.so DLL:
link /DLL /OUT:abs.dll /DEF:abs.def abs.obj
d:\informix\lib\SAPI.LIB

The preceding commands assume that the Informix software is installed in the d: drive in a directory called informix.

2. Put the DLL in a directory on which the user informix has read permission and set the READONLY attribute with the attrib +r command.
attrib