|
| |
| Sun Java System Message Queue 3 2005Q1 Developer's Guide for C Clients | |
Chapter 1
IntroductionThis chapter summarizes the differences between the C API and the Java API to Message Queue and provides a quick start to compiling and running Message Queue C clients. It covers the following topics:
You should be familiar with the concepts presented in the Message Queue Technical Overview before you read this chapter.
Depending on your needs, after you read this chapter, you can proceed either to Chapter 3, "Client Design Issues", which describes the major issues governing C client design, or to Chapter 2, "Using the C API", which explains how you use C data types and functions to obtain the messaging behavior that interests you.
The term “C developer” is used generically throughout this book and includes the C++ developer as well.
Message Queue for the C DeveloperThe Message Queue product is an enterprise messaging system that implements the Java™ Message Specification (JMS) standard as a JMS provider. Message Queue developers can use two programming interfaces to establish a connection to the broker, and send or receive messages:
Message Queue provides a C API to its messaging services to enable legacy C applications and C++ applications to participate in JMS-based messaging. It is important to understand however that the Java Message Service specification is a standard for Java clients only; thus the C API described in this book is specific to the Message Queue provider and cannot be used with other JMS providers. A messaging application that includes a C client cannot be handled by another JMS provider.
The C interface, compared to the Java interface, does not support the following features:
- The use of administered objects
- Map, stream, or object message types
- Consumer-based flow control
- Queue browsers
- JMS application server facilities (ConnectionConsumer, distributed transactions)
- Receiving or sending SOAP messages
- Receiving or sending compressed JMS messages
- Auto-reconnect or failover, which allows the client runtime to automatically reconnect to a broker if a connection fails
- The NO_ACKNOWLEDGE mode
Like the Java interface, the C interface does support the following:
The JMS programming model is the foundation for the design of a Message Queue C client. Chapter 2, "Using the C API" explains how this model is implemented by the C data types and functions used by a Message Queue C client for delivery of messages.
The next section provides a quick introduction to building and running Message Queue clients.
Building and Running C ClientsMessage Queue provides several sample Message Queue C-client applications that illustrate how to send and receive messages. Before you run these applications, read through the next two sections to make sure that you understand the general procedure and requirements for building and running Message Queue C-Client programs.
Building C Clients
This section explains how you build Message Queue programs from C source files.You should already be familiar with writing and compiling C applications.
Header Files and Shared Libraries
The Message Queue C client includes the header files (mqcrt.h), the C client runtime shared library mqcrt, and its direct dependency libraries. When writing a Message Queue C client application, you should include the header files and link to the runtime library mqcrt.
For each platform, Table 1-1 lists the installed location of the header files and the supporting runtime library.
Pre-Processor Definitions
Use the appropriate compiler for your platform, as described in the Message Queue Release Notes.
When compiling a Message Queue C client application, you need to specify the preprocess or definition shown for each platform in Table 1-2. This definition is used to support Message Queue fixed-size integer types.
Table 1-2 Preprocessor Definitions for Supporting Fixed-Size Integer Types
Platform
Definition
Solaris
SOLARIS
Linux
LINUX
Windows
WIN32
C++ Runtime Library Support
When building a Message Queue C client application, you should be aware that the Message Queue C runtime library is a multi-threaded library and requires C++ runtime library support:
Providing Runtime Support
To run a Message Queue C-client application, you need to make sure that the application can find the mqcrt shared library. Please consult the documentation for your compiler to determine the best way to do this.
You also need to make sure that the appropriate C++ runtime support library, as described in C++ Runtime Library Support is available.
On Windows you also need to make sure that your application can find the dependent libraries NSPR and NSS that are shipped with Message Queue. These may be different from the NSPR and NSS libraries that are installed on your system to support the Netscape browser and the Sun Java System Application Server. The mqcrt shared library depends directly on the NSPR and NSS versions installed with Message Queue. If a different version of the libraries is loaded at runtime, you may get a runtime error specifying that the libraries being used are incompatible.
Working With the Sample C-Client ProgramsThis section describes the sample C-Client programs that are installed with Message Queue and explains how you should build them and run them. Table 1-3 lists the location of the sample programs on each platform.
Table 1-3 Location of C Sample Programs
Platform
Directory
Solaris
/opt/SUNWimq/demo/C
Linux
/opt/sun/mq/examples/C
Windows
IMQ_HOME\demo\C
Building the Sample Programs
The following commands illustrate the process of building and linking the sample application Producer.c on the Solaris, Linux, and Windows platforms. The commands include the preprocessor definitions needed to support fixed-size integer types. For options used to support multithreading, please consult documentation for your compiler.
To Compile and Link on Solaris
CC -compat=5 -mt -DSOLARIS -I/opt/SUNWimq/include -o Producer \
-L/opt/SUNWimq/lib -lmqcrt Producer.cFor Solaris/SPARC, if you need 64-bit support, you need to specify the following compiler options: -xarch=v9 and -L/opt/SUNWimq/lib/sparcv9. For example, to compile and link the example application, you would use the following command:
CC -compat=5 -mt -xarch=v9 -DSOLARIS -I/opt/SUNWimq/include -o Producer \
L/opt/SUNWimq/lib/sparcv9 -lmqcrt Producer.cTo Compile and Link on Linux
g++ -DLINUX -D_REENTRANT -I/opt/sun/mq/include -o Producer \
-L/opt/sun/mq/lib -lmqcrt Producer.cTo Compile on Windows
cl /c /MD -DWIN32 -I%IMQ_HOME%\include Producer.c
To Link on Windows
link Producer.obj /NODEFAULTLIB msvcrt.lib \
/LIBPATH:%IMQ_HOME%\lib mqcrt.libRunning the Sample Programs
The sample C client program files include the following:
- Producer.c and Consumer.c, which illustrate how you send a message and receive it synchronously.
- ProducerAsyncConsumer.c, which illustrates how you send a message and receive it asynchronously.
- RequestReply.c, which illustrates how you send and respond to a message that specifies a reply-to destination.
Before you run any sample programs, you should start the broker. You can display output describing the command-line options for each program by starting the program with the -help option.
The directory that contains the sample programs also includes a README file that explains how you should run these samples. For example, the following command, runs the program Producer. It specifies that the program should connect to the broker running on the host MyHost and port 8585, and that it should send a message to the destination My Topic:
C: Producer -h MyHost -p 8585 -d MyTopic
Client Application Deployment ConsiderationsWhen you are ready to deploy your client application, you should make sure the administrator knows your application’s needs. The checklist in Table 1-4 shows the basic information required. Consult with your administrator to determine the exact information needed. In some cases, it might be useful to provide a range of values rather than a specific value. Refer to the Message Queue Administration Guide for additional information about attribute names and default values.