Copyright © TIBCO Software Inc. All Rights Reserved

> Programmer Checklists
> This section provides a checklist that outlines the steps for creating an EMS application in each language:

> • | Java Programmer’s Checklist

> • | C Programmer’s Checklist

> • | C# Programmer’s Checklist

> Java Programmer’s Checklist
> Install

> • | Install the EMS software release, which automatically includes the EMS jar files in the EMS_HOME/lib subdirectory.

> • | Add the full pathnames for the following jar files to your CLASSPATH:

> jms.jar
> tibjms.jar

> • | If SSL is used for communication, add the following file to the CLASSPATH:

> tibcrypt.jar

> | All jar files listed in this section are located in the lib subdirectory of the TIBCO Enterprise Message Service installation directory.

> To use Entrust with an EMS client, you must separately purchase and install the Entrust libraries. If you use the Entrust libraries, you must include them in the CLASSPATH before the JSSE JAR files. To use Entrust 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 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>

> • | Programs that use the C administration API must also include the emsadmin.h header file:

> #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

> • | Compile programs with an ANSI-compliant C compiler.

> • | Link with the appropriate EMS C library files; see Link These Library Files.

> 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\6.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

> • | 64-Bit UNIX

> • | Microsoft Windows

> • | OpenVMS

> 32-Bit UNIX
> In 32-bit UNIX environments, both shared and static libraries are available. We recommend shared libraries to ease forward migration.

> Table 44 Linker Flags for 32-Bit UNIX
> Linker Flag | Description
> -ltibems | All programs must link using this library flag.
> -lssl -lcrypto | Programs that use SSL must link using these library flags.
> -lz | Programs that use compression must link using this library flag.
> -ltibemslookup -lldap -lxml2 -llber | Programs that use EMS LDAP lookup must link using these library flags.
> -ltibemsadmin | Programs that use the C administration library must link using this library flag.

> 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/6.1/lib/64 in your library path, and it must precede any other EMS directory in the library path.

> Table 45 Linker Flags for 64-Bit UNIX
> Linker Flag | Description
> -ltibems64 | All programs must link using this library flag.
> -lssl -lcrypto | Programs that use SSL must link using these library flags.
> -lz | Programs that use compression must link using this library flag.
> -ltibemslookup64 -lldap -lxml2 -llber | Programs that use EMS LDAP lookup must link using these library flags.
> -ltibemsadmin64 | Programs that use the C administration library must link using this library flag.

> Microsoft Windows
> For a list of Windows platforms that Release 6.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.

> Table 46 Dynamic Library Files for Microsoft Windows
> Library File | Description
> With dynamic libraries (DLLs), use the /MT compiler option.
> tibems.lib ws2_32.lib | All programs must link these libraries.
> tibemslookup.lib libxml2.lib | Programs that use EMS LDAP lookup must link these libraries.
> 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.
> tibemsadmin.lib | Programs that use the C administration library must link using this library.

> Table 47 Static Library Files for Microsoft Windows
> Library File | Description
> With static libraries (DLLs), use the /MD compiler option.
> libtibems.lib ws2_32.lib ssleay32mt.lib libeay32mt.lib zlib.lib | All programs must link these libraries.
> libtibemslookup.lib libxml2.lib | Programs that use EMS LDAP lookup must link this library.
> 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.
> libtibemsadmin.lib | Programs that use the C administration library must link using this library.

> 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.

> Table 48 Shareable Image Library Files for OpenVMS
> Library File | Description
> LIBTIBEMSSHR.EXE | All programs must link this library.
> LIBCRYPTOSHR.EXE LIBSSLSHR.EXE | Programs that use SSL must link these libraries.
> LIBZSHR.EXE | Programs that use data compression must link this library.
> LIBTIBEMSADMINSHR.EXE | Programs that use the C administration library must link this library.

> Table 49 Static Library Files for OpenVMS
> Library File | Description
> LIBTIBEMS.OLB | All programs must link this library.
> LIBCRYPTO.OLB LIBSSL.OLB | Programs that use SSL must link these libraries.
> LIBZ.OLB | Programs that use data compression must link this library.
> LIBTIBEMSADMIN.OLB | Programs that use the C administration library must link this library.

> C# Programmer’s Checklist
> Developers of EMS C# programs can use this checklist during the four phases of the development cycle.
> Install

> • | Install the EMS software release, which automatically includes the EMS assembly DLLs in the EMS_HOME\bin subdirectory.

> Code

> • | Import the correct EMS assembly (see Table 50).

> Table 50 EMS Assembly DLL
> Version | DLL
> .NET API | TIBCO.EMS.dll
> .NET Administration API | TIBCO.EMS.ADMIN.dll
> .NET Unshared State API | TIBCO.EMS.UFO.dll
> .NET Compact Framework API | TIBCO.EMS-CF.dll

> Compile

> • | Compile with any .NET compiler.

> 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.

> • | To automatically upgrade to the latest .NET assemblies, include the appropriate policy file in the global cache. See Automatic Upgrades Between Versions for more information.

> • | The application must be able to connect to a EMS daemon process (tibemsd).

> Assembly Versioning
> TIBCO Enterprise Message Service assembly DLLs are versioned using the format 1.0.release.version, where release is the EMS release number version is an arbitrary value. For example, the assembly version number for software release 6.0.0 is similar to 1.0.600.8.

> | Applications that use a release of EMS earlier than 6.0 do not use standard .NET versioning. Prior to TIBCO Enterprise Message Service release 6.0.0, all EMS .NET assemblies showed an assembly version number 1.0.0.0, which allowed client applications to upgrade to the latest version of EMS without rebuilding. This functionality is now available through the policy DLL files.

> Automatic Upgrades Between Versions
> In order to allow for seamless upgrades between releases, the TIBCO Enterprise Message Service installation includes policy and configuration files that redirect existing applications from an older assembly to the newest assembly. There is a policy and configuration file for each EMS library:

> • | A policy.1.0.assembly file. For example, policy.1.0.TIBCO.EMS.dll. The policy file must be included in the global cache to enable automatic upgrades.

> • | An assembly.config file. For example, TIBCO.EMS.dll.config. The configuration file must be present when the related policy file is added to the global cache.

> Table 51 shows the policy and configuration files for each EMS assembly.

> Table 51 EMS Policy Files
> Version | Files
> .NET API | policy.1.0.TIBCO.EMS.dll TIBCO.EMS.dll.config
> .NET Administration API | policy.1.0.TIBCO.EMS.ADMIN.dll TIBCO.EMS.ADMIN.dll.config
> .NET Unshared State API | policy.1.0.TIBCO.EMS.UFO.dll TIBCO.EMS.UFO.dll.config

> The .NET Compact Framework API is not available for automatic upgrades.
> Enabling Updates
> To enable automatic updates for a library, add the appropriate policy file to the global cache. Note that the related configuration file must be located in the directory with the policy file in order to add the policy file to the global cache.
> Disabling Automatic Upgrades
> If you do not want your older applications to automatically move to the newer version, do not include the policy DLL in the global cache. When the policy.1.0.assembly file is absent, the client application is not upgraded.
> Running Multiple Clients from Different EMS Releases
> To deploy two or more applications that are built with different TIBCO Enterprise Message Service releases:

> 1. | Build clients using the different .NET client assemblies.

> 2. | Include all desired versions of the .NET client assemblies in the global cache.

> 3. | Do not include the policy DLL in the global cache.

> 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.

> Table 52 .NET Feature Support
> Feature | .NET | .NET Compact Framework
> XA protocols for external transaction managers | — | —
> ConnectionConsumer, ServerSession, ServerSessionPool | — | —
> Compression | Yes | —
> SSL | Yes | —
> Modify socket buffer sizes (see Tibems.SetSocketReceiveBufferSize and Tibems.SetSocketSendBufferSize in the HTML reference) | Yes | —
> Daemon threads (see Tibems.SetSessionDispatcherDaemon in the HTML reference) | Yes | —

> 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:

> • | Use the default global encoding, UTF-8.

> • | Set a non-default global encoding (for all outbound messages) using Tibems.SetEncoding.

> • | Set the encoding for an individual message using Tibems.SetMessageEncoding.

> 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 EM S .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.

Copyright © TIBCO Software Inc. All Rights Reserved