IBM Agent Building Environment Developer's Toolkit

Chapter 1. Building ABE-Related Components

The following is offered to assist you in compiling and linking components or programs that use the Agent Building Environment Developer's Toolkit interfaces that are described in the sections that follow.

In some places in this section, the token ABESPOT is used as a shorthand to represent the pathname of the directory into which you installed the Agent Building Environment Developer's Toolkit. Replace this with the actual pathname that you used.

Also, to simplify the description of pathnames, this section uses the Windows and OS/2 file-system convention of a backslash (\) as the directory separator in pathnames. AIX users should substitute a forward slash (/) in place of the backslash.


Building ABE Components with C++

The first section provides some general information that applies to all of the C++ compilers that can be used to build ABE programs. The sections that follow give specific information and examples for each of the C++ environments.

General Guidelines

Using ABE Header Files

When you compile C++ code that uses ABE interfaces, you will need to #include various ABE header files that declare the classes and interfaces that your code uses. These header files are listed in the class descriptions that appear in other chapters of this document.

All of these header files are located under the ABE inc directory. You will need to add the pathname of this directory to the header-file search path used by your compiler, so that the compiler can locate the header files.

You might notice that the ABE header files are actually located in an iatk subdirectory of ABE's inc directory and be tempted to add ABESPOT\inc\iatk to your compiler's header-file search path instead of ABESPOT\inc. Resist this temptation! As the class descriptions elsewhere in this document indicate, the ABE header files are all included using a iatk prefix, such as #include <iatk/someheader.h>. The C++ compiler concatenates the prefixed header file name to the directories listed in its header-file search path to actually locate the header file.

Always Build Multithreaded Executables

Because of the multithreaded implementation of ABE, components or programs that you write to interface with the ABE adapter, agent and engine frameworks will be either implicitly or explicitly multithreaded themselves. Since most C++ environments will not build multithread-capable executables by default, you will need to use various options of your compiler to request the construction of multithread-capable executables. For some compilers, there are special options and libraries to use both at compile time and at link time. For others, nothing special has to be done at compile time, but specific multithread-capable libraries have to be used when you link your application. Details are provided below.

The preceding does not currently apply to programs that use only the ABE library framework, as the implementation of that framework does not exploit threads. This may change in the future, however, so you should still set up your build procedures to construct such executables as multithreaded ones.

Use the DLL Version of Run-time Libraries

Most C++ compilers give you a choice of building your executables with a statically-linked version of the C++ run-time library (RTL), or with a dynamically-linked (sometimes called dynamically loaded) version of the C++ RTL. In the statically-linked case, the RTL code is placed in the executable along with your application code. In the dynamically-linked version, the RTL code is packaged as a separate DLL or shared library.

All of the ABE executables provided by IBM have been built using the dynamically linked version of the corresponding RTL. Mixing statically-linked and dynamically-linked components in the same application is not always supported by the C++ compilers and can lead to unpredictable results. Thus, when you build your ABE-related components and programs, you should always build them to use the dynamically linked (a.k.a DLL) version of the C++ RTL as well.

Using ABE Libraries

When you link your ABE-related components and programs, you will need to use use some libraries provided with ABE to satisfy the references your code makes to ABE interfaces. The specific libraries to use varies across platform and compiler and are listed in the detailed sections below.

All of these ABE libraries are located in the ABE lib directory. You will need to add the pathname of this directory to the library search path used by your linker, so that it can located the necessary library files.

Using IBM VisualAge C++ on Windows 95/NT

Compiling Your Code

The VisualAge C++ compiler searches for header files in the directories listed in the INCLUDE environment variable. You should add the ABE inc directory to the list of directories you ordinarily specify in the INCLUDE list.

When you compile your code using the icc command, specify the options -Gm and -Gd. The -Gm option requests the building of multithread-capable executables and the -Gd option requests the use of the dynamically linked version of the RTL.

Linking Your Code

The VisualAge C++ linker searches for library files in the directories listed in the LIB environment variable. You should add the ABE lib directory to the list of directories you ordinarily specify in the LIB list.

ABE Import Libraries

The following table lists the import libraries that you should use to gain access to the ABE interfaces.
ABE Framework Used Import Library to Use
Agent/Adapter iagaei.lib, iagmisc.lib
Library iaglibr.lib, iagmisc.lib

A Sample Makefile

A sample makefile for building an adapter DLL using VisualAge C++ for Windows 95/NT is shown in Figure 1-1.

Figure 1-1. VisualAge C++ for Windows Makefile. This is the NMAKE style makefile for building the SampMail adapter using VisualAge C++ for Windows

# Notes:
# - This Makefile assumes that the INCLUDE environment variable has
#   been updated to include the ABE inc directory, and that the LIB
#   environment variable has been updated to include the ABE lib
#   directory.

 OFILES  = sampmail.obj
 CFLAGS  = -Q -I. -Ge- -Gm -Gd -Ft-
 LKFLAGS = -nologo
 LIBS    = iagaei.lib iagmisc.lib wsock32.lib

 sampmail.dll: $(OFILES)
         ilib -nologo $** -gi:$(@:.dll=.lib)
         ilink -dll $(LKFLAGS) $** $(@:.dll=.exp) $(LIBS)

 $(OFILES): sampmail.h

For More Information

For information about the different compile and link options, see the VisualAge C++ User's Guide manual. This book also has a description of the NMAKE utility program.

Using Microsoft Visual C++ on Windows 95/NT

Compiling Your Code

The Visual C++ compiler searches for header files in the directories listed in the INCLUDE environment variable. You should add the ABE inc directory to the list of directories you ordinarily specify in the INCLUDE list.

When you compile your code using the cl command, specify the options -MD and -GX. The -MD option requests the building of multithread-capable executables that use the dynamically-linked version of the RTL. The -GX option enables the use of exceptions.

Linking Your Code

The VisualAge C++ linker searches for library files in the directories listed in the LIB environment variable. You should add the ABE lib directory to the list of directories you ordinarly specify in the LIB list.

ABE Import Libraries

The following table lists the import libraries that you should use to gain access to the ABE interfaces.
ABE Framework Used Import Library to Use
Agent/Adapter iagaeim.lib, iagmiscm.lib
Library iaglibrm.lib, iagmiscm.lib

A Sample Makefile

A sample makefile for building an adapter DLL using Microsoft Visual C++ is shown in Figure 1-2.

Figure 1-2. Microsoft Visual C++ Makefile. This is a Visual C++ NMAKE style makefile for building an adapter DLL.

# Notes:
# - This Makefile assumes that the INCLUDE environment variable has
#   been updated to include the ABE inc directory, and that the LIB
#   environment variable has been updated to include the ABE lib
#   directory.

OFILES   = util.obj
CPPFLAGS = -nologo -I. -MD -GX
LKFLAGS  = -nologo

LIBS = iagaeim.lib iagmiscm.lib

util.dll: $(OFILES)
        lib -nologo -out:$(@:.dll=.lib) $** -def:
        link -dll $(LKFLAGS) -out:$@ -map:$(@:.dll=.map) $** $(@:.dll=.exp) $(LIBS)

$(OFILES): util.h

For More Information

If you are using Microsoft Visual C++ , the topic Dynamic Link Libraries in the following topic path:
   Key Visual C++ Topics
      Programming Topics
         Dynamic Link Libraries

in the online help will explain how to use DLLs with Microsoft Visual C++.

Using Borland C++ on Windows 95/NT

Compiling Your Code

When you compile your code using the bcc32 command, use the options:

-IABESPOT\inc
-D_RTLRTL
-tWM

The -I option adds the ABE inc directory to the list of directories the compiler searches for header files. The -D_RTLDLL option compiles your code for use with the DLL version of the Borland C++ RTL. The -tWM option requests a multithread-capable executable.

Linking Your Code

When you link your ABE-related component, use the following ilink32 options:

-LABESPOT\lib;other_lib_dirs
-Tpd

The -L option specifies the list of places the linker looks for library files; you should add the ABE lib directory to the list you ordinarily use. The -Tpd option requests the linking of a Windows 95/NT format DLL.

In addition to these options, you should specify c0d32 as the startup module, and cw32mti.lib as the RTL import library. Finally, specify the ABE related import libraries you need based on the table below.

As an EXE

If you are linking an ABE-related program as an EXE, use the following ilink32 options:

-LABESPOT\lib;other_lib_dirs
-Tpe

The -L option specifies the list of places the linker looks for library files; you should add the ABE lib directory to the list you ordinarily use. The -Tpe option requests the linking of a Windows 95/NT format EXE.

In addition to these options, you should specify c0x32 as the startup module, and cw32mti.lib as the RTL import library. Finally, specify the ABE related import libraries you need based on the table below.

ABE Import Libraries

The following table lists the import libraries that you should use to gain access to the ABE interfaces.
ABE Framework Used Import Library to Use
Agent/Adapter iagaeib.lib, iagmiscb.lib
Library iaglibrb.lib, iagmiscb.lib

A Sample Makefile

A sample makefile for building an adapter DLL using Borland C++ is shown in Figure 1-3.

Figure 1-3. Borland C++ Makefile. This is a Borland MAKE style Makefile for building an adapter DLL using Borland C++.

# Notes:
# - ABE requires that programs or DLLs that use the ABE interfaces be
#   compiled and linked using the multithreaded, DLL version of the RTL.
#   This is achieved by using -tWM and -D_RTLDLL on compiles and by
#   using cw32mti.lib as the RTL import library at link time.
#
# - This Makefile assumes that the environment variable ABESPOT is set to
#   the pathname of the directory in which ABE was installed, and that
#   BCSPOT is set to the directory in which Borland C++ was installed.
#
# - A similar Makefile can be used to build EXEs that use ABE APIs (such
#   as the agent front-end program) instead of DLLs.  Just define macro
#   EXE to be the name of the desired .exe instead of defining a DLL macro.

INCDIRS  = -I$(ABESPOT)\inc;$(BCSPOT)\include;.
LIBDIRS  = -L$(ABESPOT)\lib;$(BCSPOT)\lib
CPPFLAGS = -H- -tWM -D_RTLDLL
LKFLAGS  = -c -C -s -m
LIBS     = iagaeib.lib iagmiscb.lib iaglibrb.lib
BCLIBS   = cw32mti.lib import32.lib

DLLSTART = c0d32.obj  # Startup code for Win32 DLLs
EXESTART = c0x32.obj  # Startup code for Win32 console-mode EXEs

OFILES   = adapter.obj
HFILES   = foo.h bar.h
DLL      = adapter.dll

!ifdef DLL
$(DLL): $(OFILES)
        ilink32 -Tpd @&&%
$(LKFLAGS) $(LIBDIRS) $(DLLSTART)+
$(OFILES),$@,$(@:.dll=.map),$(LIBS) $(BCLIBS),
%
!endif

!ifdef EXE
$(EXE): $(OFILES)
        ilink32 -Tpe @&&%
$(LKFLAGS) $(LIBDIRS) $(EXESTART)+
$(OFILES),$@,$(@:.exe=.map),$(LIBS) $(BCLIBS),
%
!endif

!ifdef HFILES
$(OFILES): $(HFILES)
!endif

.cpp.obj:
        bcc32 $(CPPFLAGS) $(INCDIRS) -c $&.cpp

Using IBM VisualAge C++ on OS/2

Compiling Your Code

The VisualAge C++ compiler searches for header files in the directories listed in the INCLUDE environment variable. You should add the ABE inc directory to the list of directories you ordinarily specify in the INCLUDE list.

When you compile your code using the icc command, specify the options -Gm and -Gd. The -Gm option requests the building of multithread-capable executables and the -Gd option requests the use of the dynamically linked version of the RTL.

Linking Your Code

The VisualAge C++ linker searches for library files in the directories listed in the LIB environment variable. You should add the ABE lib directory to the list of directories you ordinarily specify in the LIB list.

ABE Import Libraries

The following table lists the import libraries that you should use to gain access to the ABE interfaces.
ABE Framework Used Import Library to Use
Agent/Adapter iagaei.lib, iagmisc.lib
Library iaglibr.lib, iagmisc.lib

A Sample Makefile

A sample makefile for building an adapter DLL using VisualAge C++ for OS/2 is shown in Figure 1-4.

Figure 1-4. VisualAge C++ for OS/2 Makefile. This is the NMAKE style makefile for building the SampMail adapter on OS/2 using VisualAge C++.

# Notes:
# - This Makefile assumes that the INCLUDE environment variable has
#   been updated to include the ABE inc directory, and that the LIB
#   environment variable has been updated to include the ABE lib
#   directory.

OFILES  = sampmail.obj
CFLAGS  = -Q -I. -Ge- -Gm -Gd -Ft-
LKFLAGS = -Q
LIBS = iagaei.lib iagmisc.lib tcp32dll.lib

sampmail.dll: $(OFILES) appldll.def
        $(CC) -Fe $@ $(LKFLAGS) $** $(LIBS)

$(OFILES): sampmail.h

For More Information

For information about the different compile and link options, see the VisualAge C++ User's Guide manual. This book also has a description of the NMAKE utility program.

Using IBM C Set++ on AIX

ABE Shared Libraries

The following table lists the shared libraries that you should use to gain access to the ABE interfaces.
ABE Framework Used Library to Use
Agent/Adapter libiagaei.a, libiagmisc.a
Library libiaglibr.a, libiagmisc.a

A Sample Makefile

A sample makefile for building an adapter module using C Set++ is shown in Figure 1-5.

Figure 1-5. C Set++ Makefile. This is the makefile for building the SampMail adapter on AIX using C Set++.

# Change the following variable to the directory
# containing the AgentBuilder inc and lib directories.

ABESPOT = /usr/local/abe

CCC = xlC_r
CCFLAGS = -I. -I$(ABESPOT)/inc -g

LDFLAGS = -L$(ABESPOT)/lib -liagaei -liagmisc -libmcls

OFILES = sampmail.o

.SUFFIXES:  .cpp
.cpp.o:
       $(CCC) -c $(CCFLAGS) $<

sampmail.so:  $(OFILES)
       /usr/lpp/xlC/bin/makeC++SharedLib_r -p0 \
       -o$@ $(OFILES) $(LDFLAGS)


Building ABE Components with Java

If your component or program is written in Java, your will need to compile your Java code using the classes that IBM supplies in the Java archive file agentbld.jar. This file is located in the ABE lib directory. To make these classes accessible to the Java compiler, add agentbld.jar to the directories and files listed in your CLASSPATH environment variable.

You will also need to include agentbld.jar in your CLASSPATH in order to run your Java-based components and programs.


[ Top of Page | Previous Page | Next Page | Table of Contents ]