Preface
This book, the Sun™ Open Net Environment (Sun ONE) Message Queue (MQ) 3.5 C Client Developer’s Guide, provides programming and reference information for developers who want to use the C language binding to the Message Queue Service to send, receive, and process MQ messages.
This preface contains the following sections:
Audience for This Guide
This guide is meant for developers who want to use the C-API in order to write C messaging programs that can interact with the MQ broker to send and receive JMS messages.
Organization of This Guide
This guide is designed to be read from beginning to end. The following table briefly describes the contents of each chapter:
Table 1 Book Contents
|
Chapter
|
Description
|
|
Chapter 1, "Introduction"
|
Introduces the basic concepts, operations, and architecture of MQ messaging. Contains some material on programming and configuration issues to improve performance and throughput.
|
|
Chapter 2, "Building and Running MQ C Clients"
|
Explains how to compile and link MQ C clients. Introduces the MQ C-Client sample applications that are shipped with MQ and explains how you set up your environment to run these examples.
|
|
Chapter 3, "Using the C API"
|
Explains how you use the C-API to construct, to send, to receive, and to process a messages. This chapter also covers error and thread handling.
|
|
Chapter 4, "Reference"
|
Provides complete reference information for the MQ C-API: data structures and functions. It also lists and describes the contents of the C-API header files.
|
|
Appendix A, "MQ C API Error Codes"
|
Lists the code and descriptive string returned for errors that are returned by C library functions.
|
Conventions
This section provides information about the conventions used in this document.
Text Conventions
Table 2 Document Conventions
|
Format
|
Description
|
|
italics
|
Italicized text represents a placeholder. Substitute an appropriate clause or value where you see italic text. Italicized text is also used to designate a document title, for emphasis, or for a word or phrase being introduced.
|
|
monospace
|
Monospace text represents example code, commands that you enter on the command line, directory, file, or path names, error message text, class names, method names (including all elements in the signature), package names, reserved words, and URL’s.
|
|
[]
|
Square brackets to indicate optional values in a command line syntax statement.
|
|
ALL CAPS
|
Text in all capitals represents file system types (GIF, TXT, HTML and so forth), environment variables (IMQ_HOME), or acronyms (MQ, JSP).
|
|
Key+Key
|
Simultaneous keystrokes are joined with a plus sign: Ctrl+A means press both keys simultaneously.
|
|
Key-Key
|
Consecutive keystrokes are joined with a hyphen: Esc-S means press the Esc key, release it, then press the S key.
|
Directory Variable Conventions
MQ makes use of three directory variables, one of which is relevant to C clients. Table 3 describes this variable and explains how it is used on the Solaris, Windows, and Linux platforms.
Table 3 MQ Directory Variable Used by C Clients
|
Variable
|
Description
|
|
IMQ_HOME
|
This is generally used in MQ documentation to refer to the MQ base directory (root installation directory):
- On Solaris, there is no root MQ installation directory. Therefore, IMQ_HOME is not used in MQ documentation to refer to file locations on Solaris.
- On Windows, the root MQ installation directory is set by the MQ installer (by default, as C:\Program Files\Sun\MessageQueue3).
- On Linux, there is no root MQ installation directory. Therefore, IMQ_HOME is not used in MQ documentation to refer to file locations on Linux.
|
In this guide, IMQ_HOME is shown without platform-specific environment variable notation or syntax (for example, $IMQ_HOME on UNIX). Path names generally use UNIX directory separator notation (/).
Other Documentation Resources
In addition to this guide, MQ provides additional documentation resources.
The MQ Documentation Set
The documents that comprise the MQ documentation set are listed in Table 4 in the order in which you would normally use them.
Table 4 MQ Documentation Set
|
Document
|
Audience
|
Description
|
|
MQ Installation Guide
|
Developers and administrators
|
Explains how to install MQ software on Solaris, Linux, and Windows platforms.
|
|
MQ Release Notes
|
Developers and administrators
|
Includes descriptions of new features, limitations, and known bugs, as well as technical notes.
|
|
MQ Java Client Developer’s Guide
|
Developers
|
Provides a quick-start tutorial and programming information for developers of Java client programs using the MQ implementation of the JMS or SOAP/JAXM APIs.
|
|
MQ Administrator’s Guide
|
Administrators, also recommended for developers
|
Provides background and information needed to perform administration tasks using MQ administration tools.
|
|
MQ C Client Developer’s Guide
|
Developers
|
Provides programming and reference documentation for developers of MQ C client programs.
|
Online Help
MQ 3.5 includes command-line utilities for performing MQ message service administration tasks. To access the online help for these utilities, see the MQ Administrator’s Guide.
MQ 3.5 also includes a graphical user interface (GUI) administration tool, the Administration Console (imqadmin). Context sensitive online help is included in the Administration Console.
Example Client Applications
A number of example applications that provide sample client application code are included in a directory that depends upon the operating system (see the MQ Administrator’s Guide).
Sample applications that illustrate the C-API are listed and described in Chapter 2, "Building and Running MQ C Clients".
See the README file located in that directory and in each of its subdirectories for guidance on how to run the sample programs.
The Java Message Service (JMS) Specification
The JMS specification can be found at the following location:
The specification includes sample JMS Java client code.
Related Third-Party Web Site References
Third-party URLs are referenced in this document and provide additional, related information.
|
|
Note
|
Sun is not responsible for the availability of third-party Web sites mentioned in this document. Sun does not endorse and is not responsible or liable for any content, advertising, products, or other materials that are available on or through such sites or resources. Sun will not be responsible or liable for any actual or alleged damage or loss caused by or in connection with the use of or reliance on any such content, goods, or services that are available on or through such sites or resources.
|
|
