Sun Java System Message Queue 3.5 SP1 C Client Developer's Guide |
Chapter 2
Building and Running Message Queue C ClientsThis chapter provides information about building Message Queue C client applications and making sure these programs have adequate run-time support. It also lists the sample Message Queue C Client programs that are included with the Message Queue installation, and explains how you should run them
For information on how to use the API, see Chapter 3, "Using the C API". For complete reference information, please see Chapter 4, "Reference".
Getting ReadyMessage Queue provides several sample Message Queue C-client applications that illustrate how to send and receive messages. These sample applications are installed in the ...demo\C directory. 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 Programs
This section explains how you build Message Queue programs from C source files.You should already be familiar with writing and compiling C applications.
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. Note that the Message Queue C-API runtime library is a 32-bit library. For each platform, Table 2-1 lists the installed location of the header files and the supporting runtime library.
You should use the appropriate compiler for your platform, as described in the Message Queue Installation Guide.
When compiling a Message Queue C client application, you need to specify the preprocessor definition for supporting Message Queue fixed-size integer types. The preprocessor definition for each platform is shown in Table 2-2.
Table 2-2 Preprocessor Definitions for Supporting Fixed-Size Integer Types
Platform
Definition
Solaris
SOLARIS
Linux
LINUX
Windows
WIN32
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 Building Programs 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 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 are 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.
Building the Sample Programs
The following commands are meant to 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.cTo Compile and Link on Linux
g++ -DLINUX -D REENTRANT -I/opt/imq/include -o Producer \
-L/opt/imq/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
Sample C client program files are installed in the ...demo\C directory. These 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.
The sample programs expect you to specify a destination as a command-line argument. You can either create one or more physical destinations on the broker by using the administration utility imqcmd before running the sample programs, or you can use the broker’s auto-creation feature by specifying any destination name on the command line used to start the program.
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 …demo\C directory 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