Appendix D Creating C Components

Compile C components

This section describes how to compile and link a dynamic link library (DLL) that contains Jaguar methods. Your code must be built as a DLL in order to be installed into the Jaguar runtime environment.

When you generate source files for your component, Jaguar Manager creates an example makefile that builds the component library. You may have to edit this file to match your environment, as described in the following sections:

Build on Solaris SPARC

For servers that run on Solaris, you must build shared library (.so) files that contain your C component methods.

Follow the instructions in the sections below to build a shared library. After building the shared library, copy it to the cpplib directory of your Jaguar installation.

Build a C component library

Jaguar Manager generates a make.unix file when you generate the component skeleton. (See "Generate C component files" for instructions on generating code with Jaguar Manager.)

To build your component, run the following command:

make -f make.unix

This command builds a shared library named libComp.so, where Comp is the Jaguar Manager name of the component.

If you edit the generated make.unix file, rename the edited version so that it is not overwritten if you regenerate the skeleton files.

Build on Windows NT

For servers that run on Windows NT, you must build dynamic link library (.dll) files that contain your C component methods.

Follow the instructions in the sections below to build a DLL. After building the shared library, copy it to the cpplib directory of your Jaguar installation.

DLLs for C components

For Windows NT, you must build a DLL so that C functions use the standard C calling function.

Jaguar Manager generates a make.nt file when you generate the component skeleton. (See "Generate C component files" for instructions on generating code with Jaguar Manager.)

The generated makefile assumes that the ODBC header files and libraries can be found in one of the following locations:

The directory specified by the ODBCHOME environment variable, or
If ODBCHOME is not set, C:\msdev, which is the default installation directory for Microsoft Visual C++.

To use the generated makefile, run this command from a command window while in your component's source directory:

nmake -f make.nt

If you edit the generated make.nt file, rename the edited version so that it is not overwritten if you regenerate the skeleton files.

Example generated makefile

An example generated makefile is shown below. This makefile links the following import libraries:

libjaguar.lib - Contains import definitions for routines called by generated skeleton routines.
libjcm.lib - Contains import definitions for Connection Manager routines.
libjdispatch.lib - Contains import definitions for Jaguar C routines.

If your code calls routines defined in other import libraries, you will need to rename and edit the generated makefile to use the additional import libraries.

If you need an edited version of the generated makefile, rename the edited version so that it cannot be overwritten when you regenerate the skeleton code.

Below is an example makefile:

COMPILE_DEBUG = 1

!ifndef ODBCHOME
ODBCHOME=c:\msdev
!endif

# Compiler and Linker flags
!ifdef COMPILE_DEBUG
CFLAGS = /W3 /MD /nologo /Z7 /Od /DWIN32 /Gz
LFLAGS = /MAP /DLL /DEBUG /DEBUGTYPE:cv
!else
CFLAGS = /W3 /MD /nologo /Od /DWIN32 /Gz
LFLAGS = /MAP /DLL
!endif

#
# Where to get includes and libraries
#
SYBINCPATH =      $(JAGUAR)\include
ODBCINCPATH =     $(ODBCHOME)\include
JAGLIB =          $(JAGUAR)\lib\libjaguar.lib
JDISPLIB =          $(JAGUAR)\lib\libjdispatch.lib
CSLIB =           $(JAGUAR)\lib\libjcs.lib
CMLIB =           $(JAGUAR)\lib\libjcm.lib
ODBCLIB =         $(ODBCHOME)\lib\odbc32.lib
SYSLIBS =         kernel32.lib advapi32.lib msvcrt.lib

.c.obj:
     cl /I. /I$(SYBINCPATH) /I$(ODBCINCPATH) $(CFLAGS) \
     -Fo$@ -c $<

OBJS = Enrollment.obj Method_template.obj

Enrollment.obj: Enrollment.h
Method_template.obj: Enrollment.h

libEnrollment.dll: $(OBJS)
     link $(LFLAGS) /out:$*.dll /def:$*.def $(OBJS) $(JDISPLIB) $(CMLIB) $(ODBCLIB) $(JAGLIB) $(SYSLIBS)

clean:
     -del libEnrollment.dll

clobber:
     -del *.obj
     -del *.map
     -del *.exp
     -del *.pdb
     -del *.lib

Build with the Visual C++ IDE

If you use the Visual C++ IDE or another command line compiler to build your DLL, make sure that you specify the right options so that the compiler generates C functions using the standard C calling convention.

After building the DLL, copy it to the cpplib directory of your Jaguar installation.

A sample module definition (.def) file

The Jaguar Manager will generate a .def file for your component. Visual C++ requires a module definition file that specifies which functions are exported from a DLL and some options that control how the DLL is loaded into memory. Module definition files end with the extension .def.

For most projects, you can use the generated file as is. In some cases, you may want to edit settings other than those in the EXPORTS section. For example, your component may perform better with a smaller or larger HEAPSIZE setting.

Never edit the generated function names in the EXPORTS section of the .def file for a C component. If you do, the Jaguar dispatcher will not be able to call your methods.

Below is the example module definition file for an Enrollment component:

LIBRARY libEnrollment     INITINSTANCE
Description  'EnrollmentComponent - Jaguar Server'
HEAPSIZE      22000
PROTMODE
CODE LOADONCALL EXECUTEREAD NONCONFORMING
DATA PRELOAD READWRITE MULTIPLE NONSHARED
EXPORTS
__skl_Enrollment_v_1_0_getMajorList
__skl_Enrollment_v_1_0_getCourses
__skl_Enrollment_v_1_0_getStudentRecord
__skl_Enrollment_v_1_0_putCourseRecord
__skl_Enrollment_v_1_0_destroy
__skl_Enrollment_v_1_0_createStudentRecord
__skl_Enrollment_v_1_0_create
__skl_Enrollment_v_1_0_getMajorEnrollmentRecord
__skl_Enrollment_v_1_0_removeCourseRecord
__skl_Enrollment_v_1_0_getCourseList
__skl_Enrollment_v_1_0_getAllEnrollmentRecord

For components, the .def file must use the function names as shown in the example. Jaguar Manager changes the function names when it generates the .def file. For each method in your component, the changed name is:

__skl_Comp_v_1_0_method

where

Comp is the component name.

method is the method name.