Preface
This book provides programming and reference information for developers working with Sun Java™ System Message Queue (formerly Sun™ ONE Message Queue) 3 2005Q1, who want to use the C language binding to the Message Queue Service to send, receive, and process Message Queue messages.
This preface contains the following sections:
Who Should Use This Book
This guide is for developers who want to use the C-API in order to write C or C++ messaging programs that can interact with the Message Queue broker to send and receive JMS messages.
This book assumes that readers are experienced C or C++ programmers and that they are familiar with the Java Message Service specification.
Before You Read This Book
You must read the Message Queue Technical Overview to become familiar with Message Queue’s implementation of the Java Message Service specification, with the components of the Message Queue service, and with the basic process of developing, deploying, and administering a Message Queue application.
How This Book Is Organized
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 C-API, provides quick start instructions on compiling and building Message Queue C clients. Introduces the Message Queue C-Client sample applications that are shipped with Message Queue, and explains how you set up your environment to run these examples. Provides a deployment worksheet.
|
|
Chapter 2, "Using the C API"
|
Explains how you use the C-API to construct, to send, to receive, and to process messages. This chapter also covers error handling, memory management, and logging.
|
|
Chapter 3, "Client Design Issues"
|
Explains the major considerations that you need to keep in mind when designing a Message Queue C client.
|
|
Chapter 4, "Reference"
|
Provides complete reference information for the Message Queue C-API: data structures and functions. It also lists and describes the contents of the C-API header files.
|
|
Appendix A, "Message Queue C API Error Codes"
|
Lists the code and descriptive string returned for errors that are returned by C library functions.
|
Conventions Used in This Book
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 or function names (including all elements in the signature), package names, reserved words, and URLs.
|
|
[]
|
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 (Message Queue, 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
Message Queue 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 Message Queue Directory Variable Used by C Clients
|
Variable
|
Description
|
|
IMQ_HOME
|
This is generally used in Message Queue documentation to refer to the Message Queue base directory (root installation directory):
- On Solaris, there is no root Message Queue installation directory. Therefore, IMQ_HOME is not used in Message Queue documentation to refer to file locations on Solaris.
- On Windows, the root Message Queue installation directory is set by the Message Queue installer (by default, as C:\Program Files\Sun\MessageQueue3).
- On Linux, there is no root Message Queue installation directory. Therefore, IMQ_HOME is not used in Message Queue documentation to refer to file locations on Linux.
- For Sun Java System Application Server on Windows, Solaris, and Linux, the root Message Queue installation directory is /imq, under the Application Server base directory.
|
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 (/).
Related Documentation
In addition to this guide, Message Queue provides additional documentation resources.
The Message Queue Documentation Set
The documents that comprise the Message Queue documentation set are listed in Table 4 in the order in which you would normally use them.
Table 4 Message Queue Documentation Set
|
Document
|
Audience
|
Description
|
|
Message Queue Installation Guide
|
Developers and administrators
|
Explains how to install Message Queue software on Solaris, Linux, and Windows platforms.
|
|
Message Queue Release Notes
|
Developers and administrators
|
Includes descriptions of new features, limitations, and known bugs, as well as technical notes.
|
|
Message Queue Technical Overview
|
Developers and administrators
|
Introduces the basic concepts of JMS client design and describes Message Queue services and tools.
|
|
Message Queue Developer’s Guide for Java Clients
|
Developers
|
Provides a quick-start tutorial and programming information for developers of Java client programs using JMS and SAAJ and Message Queue software.
|
|
Message Queue Administration Guide
|
Administrators, also recommended for developers
|
Provides background and information needed to perform administration tasks using Message Queue administration tools.
|
|
Message Queue Developer’s Guide for C Clients
|
Developers
|
Provides programming and reference documentation for developers of Message Queue C and C++ client programs that use the Message Queue software.
|
Online Help
Message Queue 3 2005Q1 includes command-line utilities for performing Message Queue message service administration tasks. To access the online help for these utilities, see the Message Queue Administration Guide.
Message Queue 3 2005Q1 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
Sample applications that illustrate the C-API are listed and described in Chapter 1, "Introduction".
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.
|
|
Sun Welcomes Your Comments
Sun is interested in improving its documentation and welcomes your comments and suggestions.
To share your comments, go to http://docs.sun.com and click Send Comments. In the online form, provide the document title and part number. The part number is a seven-digit or nine-digit number that can be found on the title page of the book or at the top of the document.
