Compiling a C user-defined extension

Before you start

You must have a user-defined extension written in C. This C program can be one of the provided sample nodes described in Sample node files, the sample parser described in Sample parser files, or a node or parser that you have created yourself using the instructions in Creating a message processing or output node in C, Creating an input node in C, or Creating a parser in C. The name of the user-defined node must be in the form <nodename>.lil.

This section provides information on how to compile user-defined extensions for all supported platforms.

The filenames used in these instructions are those of the supplied samples. If you are compiling your own user-defined extensions, you must replace these filenames with your own filenames.

Prerequisites

Before you compile your user-defined extension, make sure you have an appropriate compiler that is supported by your operating system. Examples of appropriate compilers are shown below:
Windows platform Windows
Microsoft Visual C++ .NET 2003
AIX platform AIX
VisualAge® C++ for AIX Version 6.0
HP-UX platform HP-UX
HP ANSI C 03.52
Linux platform Linux (x86 platform)
Gnu g++, version 3.2 or later
Linux platform Linux (zSeries platform)
Gnu g++, version 3.2 or later
Linux platform Linux (POWER platform)
Gnu g++, version 3.3 or later
Solaris platform Solaris (SPARC platform)
Start of changeSun Studio, Forte Developer for HPC 6 update 2End of change
Solaris platform Solaris (x86-64 platform)
Sun Studio 10
z/OS platform z/OS
IBM z/OS C/C++, for z/OS version 1.5 or later

Header files

The C interfaces are defined by the following header files:
BipCni.h
Message processing nodes
BipCpi.h
Message parsers
BipCci.h
Interfaces common to both nodes and parsers
BipCos.h
Platform-specific definitions

Existing customer or third-party supplied user-defined extension libraries run on a broker with no modification or recompilation. However, you do have to create them manually in the workbench.

Compilation

Compile the source for your user-defined extension on each of the supported platforms to create the loadable implementation library (LIL) file that the broker needs to implement your user-defined extension.

Move to the directory where the user-defined extension code is located. For example:
  cd install_dir\sample\extensions\nodes\  (Windows)
 
  cd install_dir/sample/extensions/nodes  (Linux and UNIX platforms)

Compiling on Windows

Windows platform Compile the user-defined extension using the following command, ensuing that you include a space between SwitchNode.c and BipSampPluginUtil.c, and also between -link and /DLL:
  cl /VERBOSE /LD /MD /Zi /I. /I..\..\..\include\plugin SwitchNode.c 
BipSampPluginUtil.c Common.c NodeFactory.c TransformNode.c -link 
/DLL ..\..\..\lib\imbdfplg.lib /OUT:SwitchNode.lil
This example assumes that you are using the Microsoft 32-bit C/C++ Compiler, available in Microsoft Visual Studio C++ Version 7.1.

Because of the length of this command, it is shown over several lines.

Compiling on AIX

AIX platform Compile and link the user-defined extension using a supported C compiler:
xlc_r \
   -I. \
   -I /opt/IBM/mqsi/6.0/include/plugin \
   -c SwitchNode.c \
   -o SwitchNode.o

xlc_r \
   -I. \
   -I /opt/IBM/mqsi/6.0/include/plugin \
   -c BipSampPluginUtil.c \
   -o BipSampPluginUtil.o

xlc_r \
   -I. \
   -I /opt/IBM/mqsi/6.0/include/plugin \
   -c Common.c \
   -o Common.o

xlc_r \
   -I. \
   -I /opt/IBM/mqsi/6.0/include/plugin \
   -c NodeFactory.c \
   -o NodeFactory.o

xlc_r -qmkshrobj \
      -bM:SRE \
      -bexpall \
      -bnoentry \
      -o SwitchNode.lil SwitchNode.o BipSampPluginUtil.o Common.o NodeFactory.o \
      -L /opt/IBM/mqsi/6.0/lib
      -l imbdfplg

chmod a+r SwitchNode.lil

Compiling on HP-UX

HP-UX platform Compile and link the user-defined extension using a supported C compiler:
cc +z \
-I. \
   -I<install_dir>/include \
   -I<install_dir>/include/plugin \
   -c BipSampPluginUtil.c \
   -o <output_dir>/BipSampPluginUtil.o

cc +z \
-I. \
   -I<install_dir>/include \
   -I<install_dir>/include/plugin \
   -c Common.c \
   -o <output_dir>/Common.o

cc +z \
-I. \
   -I<install_dir>/include \
   -I<install_dir>/include/plugin \
   -c NodeFactory.c \
   -o <output_dir>/NodeFactory.o

cc +z \
-I. \
   -I<install_dir>/include \
   -I<install_dir>/include/plugin \
   -c SwitchNode.c \
   -o <output_dir>/SwitchNode.o

cc +z \
-I. \
   -I<install_dir>/include \
   -I<install_dir>/include/plugin \
   -c TransformNode.c \
   -o <output_dir>/TransformNode.o


ld -b \
   -o <output_dir>/SwitchNode.lil \
   <output_dir>/BipSampPluginUtil.o \
   <output_dir>/Common.o \
   <output_dir>/NodeFactory.o \
   <output_dir>/SwitchNode.o \
   <output_dir>/TransformNode.o \
   -L <install_dir>/lib \
   -L <install_dir>/xml4c/lib \
   -L <install_dir>/merant/lib \
   -L <install_dir>/jre/lib/PA_RISC2.0 \
   -L <install_dir>/jre/lib/PA_RISC2.0/server \
   -l imbdfplg

chmod a+r <output_dir>/SwitchNode.lil

Compiling on Linux

Linux platform Compile and link the user-defined extension using a supported C compiler. The lines have been split to improve readability. Enter each command as a single line of input.

/usr/bin/g++ -c -fpic -MD -trigraphs  -I. -I/opt/mqsi/include 
    -I/opt/mqsi/include/plugin -DLINUX -D__USE_GNU 
    -D_GNU_SOURCE TransformNode.c
/usr/bin/g++ -c -fpic -MD -trigraphs  -I. -I/opt/mqsi/include 
    -I/opt/mqsi/include/plugin -DLINUX -D__USE_GNU 
    -D_GNU_SOURCE SwitchNode.c /usr/bin/gcc -c -fpic -MD -trigraphs  -I. -I/opt/mqsi/include 
    -I/opt/mqsi/include/plugin -DLINUX -D__USE_GNU 
    -D_GNU_SOURCE BipSampPluginUtil.c 
/usr/bin/g++ -c -fpic -MD -trigraphs  -I. -I/opt/mqsi/include 
    -I/opt/mqsi/include/plugin -DLINUX -D__USE_GNU 
    -D_GNU_SOURCE Common.c 
/usr/bin/g++ -c -fpic -MD -trigraphs  -I. -I/opt/mqsi/include 
    -I/opt/mqsi/include/plugin -DLINUX -D__USE_GNU 
    -D_GNU_SOURCE NodeFactory.c
/usr/bin/g++ -o samples.lil 
		TransformNode.o SwitchNode.o BipSampPluginUtil.o Common.o NodeFactory.o 
	  -shared -lc -lnsl -ldl -L/opt/mqsi/lib -limbdfplg 
These commands create the file samples.lil that provide TransformNode and SwitchNode objects.
Building the C plug-in with g++ requires some changes; you must define the interface function as a C style function to the C++ compiler. In the following example, the ifdefs are needed to keep your code portable and hide the extern "C" directives from a C compiler.
 #ifdef __cplusplus                                                  
   extern "C" {                                                        
   #endif                                                              
   void LilFactoryExportPrefix * LilFactoryExportSuffix bipGetParserFactory()                                               
   {                                                                   
   ...                                                                 
   ...                                                                 
   }                                                                   
   #ifdef __cplusplus                                                  
   }                                                                   
   #endif                                                        

Compiling on Solaris

Solaris platform Compile and link the user-defined extension using a supported C compiler:
cc -mt \
   -I. \
   -I<install_dir>/include \
   -I<install_dir>/include/plugin \
   -c SwitchNode.c \
   -o <output_dir>/SwitchNode.o

cc -mt \
   -I. \
   -I<install_dir>/include \
   -I<install_dir>/include/plugin \
   -c BipSampPluginUtil.c \
   -o <output_dir>/BipSampPluginUtil.o

cc -mt \
   -I. \
   -I<install_dir>/include \
   -I<install_dir>/include/plugin \
   -c NodeFactory.c \
   -o <output_dir>/NodeFactory.o

cc -mt \
   -I. \
   -I<install_dir>/include \
   -I<install_dir>/include/plugin \
   -c Common.c \
   -o <output_dir>/Common.o

cc -G \
   -o <output_dir>/SwitchNode.lil \
      <output_dir>/SwitchNode.o \
      <output_dir>/BipSampPluginUtil.o \
      <output_dir>/NodeFactory.o \
      <output_dir>/Common.o \
   -L <install_dir>/lib /
   -l imbdfplg

chmod a+r <output_dir>/SwitchNode.lil

Compiling on z/OS

z/OS platform Force your link to use prelinker or linker by setting the _CC_STEPS variable to -1:
export _CC_STEPS=-1
Alternatively, you can add these two lines to your makefile to export it:
_CC_STEPS=-1
.EXPORT : _CC_STEPS

Compile and link the user-defined extension using a supported C compiler. If you want to create optimized builds, use -2 in place of -g in the following commands:

cc -c \
 -Wc,DLL -g -W0,long,langlvl\(extended\),EXPORTALL,TARGET\(OSV2R8\),float\(ieee\) \
 -Wc,xplink \
 -W0,LIST\(./SwitchNode.lst\) \
 -I. -I${install_dir}/include \
 -I${install_dir}/include/plugin \
 -I${install_dir}/sample/include \
 -I${install_dir}/sample/plugin \
 -o ./SwitchNode.o ./SwitchNode.c
cc -c \
 -Wc,DLL -g -W0,long,langlvl\(extended\),EXPORTALL,TARGET\(OSV2R8\),float\(ieee\) \
 -Wc,xplink \
 -W0,LIST\(./SwitchNode.lst\) \
 -I. -I${install_dir}/include \
 -I${install_dir}/include/plugin \
 -I${install_dir}/sample/include \
 -I${install_dir}/sample/plugin \
 -o ./BipSampPluginUtil.o ./BipSampPluginUtil.c
cc -c \
 -Wc,DLL -g -W0,long,langlvl\(extended\),EXPORTALL,TARGET\(OSV2R8\),float\(ieee\) \
 -Wc,xplink \
 -W0,LIST\(./SwitchNode.lst\) \
 -I. -I${install_dir}/include \
 -I${install_dir}/include/plugin \
 -I${install_dir}/sample/include \
 -I${install_dir}/sample/plugin \
 -o ./Common.o ./Common.c
cc -c \
 -Wc,DLL -g -W0,long,langlvl\(extended\),EXPORTALL,TARGET\(OSV2R8\),float\(ieee\) \
 -Wc,xplink \
 -W0,LIST\(./SwitchNode.lst\) \
 -I. -I${install_dir}/include \
 -I${install_dir}/include/plugin \
 -I${install_dir}/sample/include \
 -I${install_dir}/sample/plugin \
 -o ./NodeFactory.o ./NodeFactory.c
cc \
 -Wl,DLL -g  -Wl,p,map -Wl,LIST=ALL,MAP,XREF,REUS=RENT \
 -Wl,xplink \
 -o ./SwitchNode.lil ./SwitchNode.o ./BipSampPluginUtil.o \
 ./Common.o ./NodeFactory.o \
 ${install_dir}/lib/libimbdfplg.x

Set the file permissions of the user-defined extension to group read and run the program by issuing the following command:

chmod a+rx {output_dir}/SwitchNode.lil
Related concepts
User-defined extensions
Related reference
User-defined extensions