Chapter 11 Developing an EMS Client Application : Programmer Checklists

Programmer Checklists
This section provides a checklist that outlines the steps for creating an EMS application in each language:
Java Programmer’s Checklist
Install
Add the full pathnames for the following jar files to your CLASSPATH:
   jms.jar
   tibjms.jar
   tibcrypt.jar
All jar files listed in this section are located in the java subdirectory of the TIBCO Enterprise Message Service installation directory.
To use Entrust with an EMS client, you must separately purchase and install the Entrust Version 7.1 libraries. If you use the Entrust libraries, you must include them in the CLASSPATH before the JSSE JAR files. To use Entrust Version 7.1 with JDK, you must download the unlimited strength policy JAR files from Sun's website and install them in your local installation of JDK. For installation and configuration details, see Entrust Version 7.1 documentation.
See , Security Considerations for a complete discussion of what is needed for a secure deployment.
Code
Import the following packages into your EMS application:
   import javax.jms.*;
   import javax.naming.*;
Compile
Compile your EMS application with the javac compiler to generate a .class file.
For example:
   javac MyApp.java
generates a MyApp.class file.
Run
Use the java command to execute your EMS .class file.
For example:
   java MyApp
C Programmer’s Checklist
Developers of EMS C programs can use this checklist during the five phases of the development cycle.
Install
Install the EMS software release, which automatically includes the EMS client libraries, binaries, and header files in the EMS_HOME/lib subdirectory.
Code
Application programs must:
Add EMS_HOME/include to the include path. (OpenVMS environments do not require an include path; skip this item.)
Include the tibems.h header file:
    #include <tibems/tibems.h>
    #include <tibems/emsadmin.h>
Call tibems_Open() to initialize the EMS C API and tibems_Close() to deallocate the memory used by EMS when complete.
Compile and Link
See the samples/c/readme file for details.
Run
UNIX   If you use dynamic EMS libraries on a UNIX platform, the environment variable $LD_LIBARY_PATH must include the EMS_HOME/lib directory (which contains the shared library files). (On some UNIX platforms, this variable is called $SHLIB_PATH or $SYLIB_LIBRARY_PATH).
Windows   The PATH must include the ems\5.1\bin directory.
OpenVMS   The installation procedure automatically installs the shareable images required for using EMS dynamic libraries.
All Platforms   The application must be able to connect to a EMS server process (tibemsd).
Link These Library Files
EMS C programs must link the appropriate library files. The following sections describe which files to link for your operating system platform:
 
32-Bit UNIX
In 32-bit UNIX environments, both shared and static libraries are available. We recommend shared libraries to ease forward migration.
-lssl
-lcrypto
-ltibemslookup
-lldap
-lxml2
-llber
64-Bit UNIX
In 64-bit UNIX environments, both shared and static libraries are available. We recommend shared libraries to ease forward migration. In this release, 64-bit libraries are available on HP-UX, Solaris, AIX and Linux (2.4 glibc 2.3) platforms.
To use 64-bit libraries, you must include TIBCO_HOME/ems/5.1/lib/64 in your library path, and it must precede any other EMS directory in the library path.
 
-lssl
-lcrypto
-ltibemslookup64
-lldap
-lxml2
-llber
Microsoft Windows
For a list of Windows platforms that Release 5.1 supports, see the file readme.txt in the installation directory. Both DLLs and static libraries are available. We recommend DLLs to ease forward migration.
tibems.lib
ws2_32.lib
tibemslookup.lib
libxml2.lib
liboldap32.lib
olber32.lib
libldap32_d.lib
liblber32_d.lib
In addition, programs that use EMS lookup must link one of these pairs of libraries.
libtibems.lib
ws2_32.lib
ssleay32mt.lib
libeay32mt.lib
zlib.lib
liboldap32.lib
olber32.lib
libldap32_d.lib
liblber32_d.lib
In addition, programs that use EMS lookup must link one of these pairs of libraries.
OpenVMS
In OpenVMS environments, both shared and static libraries are available. We recommend shared libraries to ease forward migration.
 
When upgrading from EMS 4.3 to 4.4 or later versions, EMS client executables that were linked with the EMS 4.3 dynamic libraries (shareable images) must be relinked to the new libraries after EMS 4.4 has been installed with its associated third party libraries. The third party libraries are part of the full installation of EMS.
 
LIBCRYPTOSHR.EXE
LIBSSLSHR.EXE
LIBCRYPTO.OLB
LIBSSL.OLB
C# Programmer’s Checklist
Developers of EMS C# programs can use this checklist during the four phases of the development cycle.
Install
Code
Compile
Run
The EMS assembly must be in the global assembly cache (this location is preferred), or in the system path, or in the same directory as your program executable.
Excluded Features and Restrictions
This section summarizes features that are not available in either the .NET library, or the .NET Compact Framework library.
Note that compression, SSL, and the LDAP lookup of administered objects features are available only with Microsoft .NET Framework 2.0.
.NET Compact Framework
ConnectionConsumer, ServerSession, ServerSessionPool
Modify socket buffer sizes (see Tibems.SetSocketReceiveBufferSize and Tibems.SetSocketSendBufferSize in the HTML reference)
Daemon threads (see Tibems.SetSessionDispatcherDaemon in the HTML reference)
Character Encoding
.NET programs represent strings within messages as byte arrays. Before sending an outbound message, EMS programs translate strings to their byte representation using an encoding, which the program specifies. Conversely, when EMS programs receive inbound messages, they reconstruct strings from byte arrays using the same encoding.
When a program specifies an encoding, it applies to all strings in message bodies (names and values), and properties (names and values). It does not apply to header names nor values. The method BytesMessage.WriteUTF always uses UTF-8 as its encoding.
Outbound Messages
Programs can determine the encoding of strings in outbound messages in three ways:
Inbound Messages
An inbound message from another EMS client explicitly announces its encoding. A receiving client decodes the message using the proper encoding.
For more information about character encoding, see Character Encoding in Messages.
.NET Compact Framework (CF)
This section presents recommendations for using the EMS .NET Compact Framework API to develop applications for handheld devices.
Threads
.NET Compact Framework does not support background threads. To avoid problems with threads, we recommend that programs release all EMS resources before terminating. For example, close EMS connections when they are no longer needed (see Connection.Close in the HTML reference).
Clock Resolution
Clock resolution affects the granularity of all time-related calls and parameters—for example MessageConsumer.Receive(timeout), connect delays. On some handheld devices, clock resolution is coarser than one might expect. Check the resolution on your target device before selecting time values.