WebSphere Business Integration


Version 2.0.1

Message Service Client for C/C++

SC34-6984-01
 Note!
Before using this information and the product it supports, be sure to read the general information under “Notices,” on page
477.

This edition applies to IBM Message Service Client for C/C++, Version 2.0.1 and to any subsequent releases and
modifications until otherwise indicated in new editions.
This edition replaces SC34-6984-00.

Parts of the specification of the API provided by Message Service Client for C/C++ are
derived from the following sources:
The Java Message Service Specification, Version 1.1
Copyright 2002 Sun Microsystems, Inc.
901 San Antonio Road, Palo Alto, California 94303, U.S.A.
All rights reserved.
Package javax.jms (JMS 1.1 API specification)
Copyright 2002 Sun Microsystems, Inc.
901 San Antonio Road, Palo Alto, California 94303, U.S.A.
All rights reserved.

© Copyright International Business Machines Corporation 2005, 2009.

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

About this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Who this book is for . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
What skills and knowledge you need to understand this book . . . . . . . . . . . . . . . . . . xv
Terms used in this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Additional information about this book . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Summary of changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

Changes for this edition (SC34-6984-01) . . . . . . . . . . . . . . . . . . . . . . . . . . xix

Part 1. Getting started with Message Service Client for C/C++ . . . . . . . . . . 1

Chapter 1. What’s new in this release . . . . . . . . . . . . . . . . . . . . . . . 3

Chapter 2. Enhancements in V2.0 release . . . . . . . . . . . . . . . . . . . . . 5

Chapter 3. Introduction to Message Service Client for C/C++ . . . . . . . . . . . . . 9

What is Message Service Client for C/C++? . . . . . . . . . . . . . . . . . . . . . . . . . 9
Styles of messaging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
The XMS object model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Attributes and properties of objects . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Administered objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
The XMS message model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Operating environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Prerequisites for XMS applications connecting to WebSphere MQ . . . . . . . . . . . . . . . . . 14

Chapter 4. Installing Message Service Client for C/C++ . . . . . . . . . . . . . . . 15

Installing Message Service Client for C/C++ using the installation wizard . . . . . . . . . . . . . . 15
Installing from the command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Running the installer from the command line . . . . . . . . . . . . . . . . . . . . . . . 17
Installing silently . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
What is installed on AIX, Linux, and Solaris . . . . . . . . . . . . . . . . . . . . . . . . 19
What is installed on Windows (C/C++) . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Uninstalling Message Service Client for C/C++ . . . . . . . . . . . . . . . . . . . . . . . 21
Uninstalling on Message Service Client for C/C++ using Add/Remove Programs . . . . . . . . . . . 22

Chapter 5. Setting up the messaging server environment . . . . . . . . . . . . . . 25

Configuring the queue manager and broker for an application that connects to a WebSphere MQ queue manager 25
Configuring the broker for an application that uses a real-time connection to a broker . . . . . . . . . . 27
Configuring the service integration bus for an application that connects to a WebSphere service integration bus . . 28

Chapter 6. Using the XMS sample applications . . . . . . . . . . . . . . . . . . 29

The sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Running the sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Building the C or C++ sample applications . . . . . . . . . . . . . . . . . . . . . . . . . 31

Part 2. Developing XMS applications . . . . . . . . . . . . . . . . . . . . . 33

Chapter 7. Writing XMS applications . . . . . . . . . . . . . . . . . . . . . . . 35

© Copyright IBM Corp. 2005, 2009 iii

The threading model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
ConnectionFactories and Connection objects . . . . . . . . . . . . . . . . . . . . . . . . 36
Connection started and stopped mode . . . . . . . . . . . . . . . . . . . . . . . . . 36
Connection closure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Connection to a WebSphere service integration bus . . . . . . . . . . . . . . . . . . . . . 37
Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Transacted sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Message acknowledgement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Asynchronous message delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Synchronous message delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Message delivery mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Topic uniform resource identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Queue uniform resource identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Temporary destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Message producers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Message producers with no associated destination . . . . . . . . . . . . . . . . . . . . . 46
Message producers with associated destination . . . . . . . . . . . . . . . . . . . . . . 46
Message consumers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Durable subscribers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Non-durable subscribers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Synchronous message consumers . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Asynchronous message consumers . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Poison messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Queue browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Requestors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Object Deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
XMS primitive types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Implicit conversion of a property value from one data type to another . . . . . . . . . . . . . . . 52
Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Coded character set identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
XMS error and exception codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Building your own applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Network stack selection mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Chapter 8. Writing XMS applications in C . . . . . . . . . . . . . . . . . . . . . 63

Object handles in C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Object Properties in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
C functions that return a string by value . . . . . . . . . . . . . . . . . . . . . . . . . 64
C functions that return a byte array by value . . . . . . . . . . . . . . . . . . . . . . . . 65
C functions that return a string or byte array by reference . . . . . . . . . . . . . . . . . . . . 66
C functions that accept a string as input . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Error handling in C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
The error block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Message and exception listener functions in C . . . . . . . . . . . . . . . . . . . . . . . . 68
Message listener functions in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Exception listener functions in C . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Chapter 9. Writing XMS applications in C++ . . . . . . . . . . . . . . . . . . . . 71

Namespaces in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
String objects in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
C++ methods that return a byte array . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Properties in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Assignment of XMS objects to variables in C++ . . . . . . . . . . . . . . . . . . . . . . . 73
Error handling in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Message and exception listeners in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Message listeners in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Exception listeners in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

iv Message Service Client for C/C++

Use of C APIs in a C++ application . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Chapter 10. Working with administered objects . . . . . . . . . . . . . . . . . . 83

Supported types of administered object repository . . . . . . . . . . . . . . . . . . . . . . 83
Property mapping for administered objects . . . . . . . . . . . . . . . . . . . . . . . . . 84
Required properties for administered ConnectionFactory objects . . . . . . . . . . . . . . . . . . 84
Required properties for administered Destination objects . . . . . . . . . . . . . . . . . . . . 85
Creating administered objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
InitialContext objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
InitialContext properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
URI format for XMS initial contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
JNDI Lookup Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Retrieval of administered objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Chapter 11. Securing communications for XMS applications . . . . . . . . . . . . 91

Secure connections to a WebSphere MQ queue manager . . . . . . . . . . . . . . . . . . . . 91
CipherSuite and CipherSpec name mappings for connections to a WebSphere MQ queue manager . . . . . . 92
Secure connections to a WebSphere service integration bus messaging engine . . . . . . . . . . . . . 93
CipherSuite and CipherSpec name mappings for connections to a WebSphere service integration bus . . . . 94

Chapter 12. XMS messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Parts of an XMS message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Header fields in an XMS message . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Properties of an XMS message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
JMS-defined properties of a message . . . . . . . . . . . . . . . . . . . . . . . . . . 99
IBM-defined properties of a message . . . . . . . . . . . . . . . . . . . . . . . . . 100
Application-defined properties of a message . . . . . . . . . . . . . . . . . . . . . . . 101
The body of an XMS message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Data types for elements of application data . . . . . . . . . . . . . . . . . . . . . . . 102
Bytes messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Map messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Object messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Stream messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Text messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Message selectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Mapping XMS messages onto WebSphere MQ messages . . . . . . . . . . . . . . . . . . . . 107

Part 3. Troubleshooting for XMS applications . . . . . . . . . . . . . . . . 109

Chapter 13. Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Problem determination for C/C++ applications . . . . . . . . . . . . . . . . . . . . . . . 111
Error conditions that can be handled at run time . . . . . . . . . . . . . . . . . . . . . 111
Error conditions that cannot be handled at run time . . . . . . . . . . . . . . . . . . . . 112
Repeatable failures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
FFDC and trace configuration for C/C++ applications . . . . . . . . . . . . . . . . . . . . . 113
Tips for troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Part 4. XMS API reference . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Chapter 14. C classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

BytesMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
ConnectionFactory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
ConnectionMetaData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Contents v
 Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
ErrorBlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
ExceptionListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
InitialContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Iterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
MapMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
MessageConsumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
MessageListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
MessageProducer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
ObjectMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
PropertyContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
QueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Requestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
StreamMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
TextMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Chapter 15. Additional C functions . . . . . . . . . . . . . . . . . . . . . . . 271

Process CCSID functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Chapter 16. C++ classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

BytesMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
ConnectionFactory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Constructors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
ConnectionMetaData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Constructors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Exception. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

vi Message Service Client for C/C++

ExceptionListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
IllegalStateException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
InitialContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Constructors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
InvalidClientIDException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
InvalidDestinationException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
InvalidSelectorException. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Iterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
MapMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
MessageConsumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
MessageEOFException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
MessageFormatException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
MessageListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
MessageNotReadableException . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
MessageNotWritableException. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
MessageProducer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
ObjectMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Constructors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
PropertyContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
QueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Requestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Constructors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
ResourceAllocationException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
SecurityException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
StreamMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

Contents vii
 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Constructors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
TextMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
TransactionInProgressException . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
TransactionRolledBackException . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

Chapter 17. Properties of XMS objects . . . . . . . . . . . . . . . . . . . . . 403

Properties of Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Properties of ConnectionFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Properties of ConnectionMetaData . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
Properties of Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Properties of InitialContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Properties of Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Properties of MessageConsumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Properties of MessageProducer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
Properties of Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
Property definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
JMS_IBM_ArmCorrelator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
JMS_IBM_CHARACTER_SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
JMS_IBM_ENCODING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
JMS_IBM_EXCEPTIONMESSAGE . . . . . . . . . . . . . . . . . . . . . . . . . . 419
JMS_IBM_EXCEPTIONPROBLEMDESTINATION . . . . . . . . . . . . . . . . . . . . . 419
JMS_IBM_EXCEPTIONREASON . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
JMS_IBM_EXCEPTIONTIMESTAMP. . . . . . . . . . . . . . . . . . . . . . . . . . 420
JMS_IBM_FEEDBACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
JMS_IBM_FORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
JMS_IBM_LAST_MSG_IN_GROUP . . . . . . . . . . . . . . . . . . . . . . . . . . 420
JMS_IBM_MSGTYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
JMS_IBM_PUTAPPLTYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
JMS_IBM_PUTDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
JMS_IBM_PUTTIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
JMS_IBM_REPORT_COA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
JMS_IBM_REPORT_COD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
JMS_IBM_REPORT_DISCARD_MSG. . . . . . . . . . . . . . . . . . . . . . . . . . 423
JMS_IBM_REPORT_EXCEPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
JMS_IBM_REPORT_EXPIRATION . . . . . . . . . . . . . . . . . . . . . . . . . . 424
JMS_IBM_REPORT_NAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
JMS_IBM_REPORT_PAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
JMS_IBM_REPORT_PASS_CORREL_ID . . . . . . . . . . . . . . . . . . . . . . . . . 426
JMS_IBM_REPORT_PASS_MSG_ID . . . . . . . . . . . . . . . . . . . . . . . . . . 426
JMS_IBM_RETAIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
JMS_IBM_SYSTEM_MESSAGEID . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
JMS_TOG_ARM_Correlator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
JMSX_APPID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
JMSX_DELIVERY_COUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
JMSX_GROUPID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
JMSX_GROUPSEQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
JMSX_USERID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
XMSC_ASYNC_EXCEPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
XMSC_CLIENT_CCSID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
XMSC_CLIENT_ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
XMSC_CONNECTION_TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
XMSC_DELIVERY_MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
XMSC_IC_PROVIDER_URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432

viii Message Service Client for C/C++

XMSC_IC_SECURITY_AUTHENTICATION . . . . . . . . . . . . . . . . . . . . . . . 432
XMSC_IC_SECURITY_CREDENTIALS . . . . . . . . . . . . . . . . . . . . . . . . . 432
XMSC_IC_SECURITY_PRINCIPAL . . . . . . . . . . . . . . . . . . . . . . . . . . 433
XMSC_IC_SECURITY_PROTOCOL . . . . . . . . . . . . . . . . . . . . . . . . . . 433
XMSC_IC_URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
XMSC_IS_SUBSCRIPTION_MULTICAST . . . . . . . . . . . . . . . . . . . . . . . . 433
XMSC_IS_SUBSCRIPTION_RELIABLE_MULTICAST . . . . . . . . . . . . . . . . . . . . 433
XMSC_JMS_MAJOR_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
XMSC_JMS_MINOR_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
XMSC_JMS_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
XMSC_MAJOR_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
XMSC_MINOR_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
XMSC_PASSWORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
XMSC_PRIORITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
XMSC_PROVIDER_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
XMSC_RTT_CONNECTION_PROTOCOL . . . . . . . . . . . . . . . . . . . . . . . . 436
XMSC_RTT_HOST_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
XMSC_RTT_LOCAL_ADDRESS . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
XMSC_RTT_MULTICAST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
XMSC_RTT_PORT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
XMSC_TIME_TO_LIVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
XMSC_USERID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
XMSC_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
XMSC_WMQ_BROKER_CONTROLQ . . . . . . . . . . . . . . . . . . . . . . . . . 440
XMSC_WMQ_BROKER_PUBQ . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
XMSC_WMQ_BROKER_QMGR . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
XMSC_WMQ_BROKER_SUBQ . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
XMSC_WMQ_BROKER_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . 441
XMSC_WMQ_CCSID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
XMSC_WMQ_CHANNEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
XMSC_WMQ_CONNECTION_MODE . . . . . . . . . . . . . . . . . . . . . . . . . 442
XMSC_WMQ_DUR_SUBQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
XMSC_WMQ_ENCODING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
XMSC_WMQ_FAIL_IF_QUIESCE. . . . . . . . . . . . . . . . . . . . . . . . . . . 444
XMSC_WMQ_MESSAGE_BODY . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
XMSC_WMQ_MQMD_MESSAGE_CONTEXT . . . . . . . . . . . . . . . . . . . . . . 445
XMSC_WMQ_MQMD_READ_ENABLED . . . . . . . . . . . . . . . . . . . . . . . . 446
XMSC_WMQ_MQMD_WRITE_ENABLED . . . . . . . . . . . . . . . . . . . . . . . 447
XMSC_WMQ_PUT_ASYNC_ALLOWED . . . . . . . . . . . . . . . . . . . . . . . . 447
XMSC_WMQ_READ_AHEAD_ALLOWED . . . . . . . . . . . . . . . . . . . . . . . 448
XMSC_WMQ_READ_AHEAD_CLOSE_POLICY . . . . . . . . . . . . . . . . . . . . . . 449
XMSC_WMQ_HOST_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
XMSC_WMQ_LOCAL_ADDRESS . . . . . . . . . . . . . . . . . . . . . . . . . . 450
XMSC_WMQ_MESSAGE_SELECTION . . . . . . . . . . . . . . . . . . . . . . . . . 451
XMSC_WMQ_MSG_BATCH_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . 452
XMSC_WMQ_POLLING_INTERVAL . . . . . . . . . . . . . . . . . . . . . . . . . 452
XMSC_WMQ_PORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
XMSC_WMQ_PROVIDER_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . 453
XMSC_WMQ_PUB_ACK_INTERVAL . . . . . . . . . . . . . . . . . . . . . . . . . 454
XMSC_WMQ_QMGR_CCSID . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
XMSC_WMQ_QUEUE_MANAGER . . . . . . . . . . . . . . . . . . . . . . . . . . 455
XMSC_WMQ_RECEIVE_EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
XMSC_WMQ_RECEIVE_EXIT_INIT . . . . . . . . . . . . . . . . . . . . . . . . . . 455
XMSC_WMQ_SECURITY_EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
XMSC_WMQ_SECURITY_EXIT_INIT . . . . . . . . . . . . . . . . . . . . . . . . . 456
XMSC_WMQ_SEND_EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
XMSC_WMQ_SEND_EXIT_INIT . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
XMSC_WMQ_SEND_CHECK_COUNT . . . . . . . . . . . . . . . . . . . . . . . . . 457
XMSC_WMQ_SHARE_CONV_ALLOWED . . . . . . . . . . . . . . . . . . . . . . . 457
XMSC_WMQ_SSL_CERT_STORES . . . . . . . . . . . . . . . . . . . . . . . . . . 458
XMSC_WMQ_SSL_CIPHER_SPEC . . . . . . . . . . . . . . . . . . . . . . . . . . 459

Contents ix
 XMSC_WMQ_SSL_CIPHER_SUITE . . . . . . . . . . . . . . . . . . . . . . . . . . 459
XMSC_WMQ_SSL_CRYPTO_HW. . . . . . . . . . . . . . . . . . . . . . . . . . . 460
XMSC_WMQ_SSL_FIPS_REQUIRED . . . . . . . . . . . . . . . . . . . . . . . . . 461
XMSC_WMQ_SSL_KEY_REPOSITORY . . . . . . . . . . . . . . . . . . . . . . . . . 461
XMSC_WMQ_SSL_KEY_RESETCOUNT . . . . . . . . . . . . . . . . . . . . . . . . 462
XMSC_WMQ_SSL_PEER_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
XMSC_WMQ_SYNCPOINT_ALL_GETS . . . . . . . . . . . . . . . . . . . . . . . . 463
XMSC_WMQ_TARGET_CLIENT . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
XMSC_WMQ_TEMP_Q_PREFIX . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
XMSC_WMQ_TEMP_TOPIC_PREFIX . . . . . . . . . . . . . . . . . . . . . . . . . 464
XMSC_WMQ_TEMPORARY_MODEL . . . . . . . . . . . . . . . . . . . . . . . . . 464
XMSC_WMQ_WILDCARD_FORMAT . . . . . . . . . . . . . . . . . . . . . . . . . 464
XMSC_WPM_BUS_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
XMSC_WPM_CONNECTION_PROTOCOL . . . . . . . . . . . . . . . . . . . . . . . 465
XMSC_WPM_CONNECTION_PROXIMITY . . . . . . . . . . . . . . . . . . . . . . . 466
XMSC_WPM_DUR_SUB_HOME . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
XMSC_WPM_HOST_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
XMSC_WPM_LOCAL_ADDRESS. . . . . . . . . . . . . . . . . . . . . . . . . . . 467
XMSC_WPM_ME_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
XMSC_WPM_NON_PERSISTENT_MAP . . . . . . . . . . . . . . . . . . . . . . . . 468
XMSC_WPM_PERSISTENT_MAP . . . . . . . . . . . . . . . . . . . . . . . . . . 468
XMSC_WPM_PORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
XMSC_WPM_PROVIDER_ENDPOINTS . . . . . . . . . . . . . . . . . . . . . . . . 469
XMSC_WPM_SSL_CIPHER_SUITE . . . . . . . . . . . . . . . . . . . . . . . . . . 470
XMSC_WPM_SSL_KEY_REPOSITORY . . . . . . . . . . . . . . . . . . . . . . . . . 471
XMSC_WPM_SSL_KEYRING_LABEL . . . . . . . . . . . . . . . . . . . . . . . . . 471
XMSC_WPM_SSL_KEYRING_PW . . . . . . . . . . . . . . . . . . . . . . . . . . 471
XMSC_WPM_SSL_KEYRING_STASH_FILE . . . . . . . . . . . . . . . . . . . . . . . 472
XMSC_WPM_SSL_FIPS_REQUIRED . . . . . . . . . . . . . . . . . . . . . . . . . . 472
XMSC_WPM_TARGET_GROUP . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
XMSC_WPM_TARGET_SIGNIFICANCE . . . . . . . . . . . . . . . . . . . . . . . . 473
XMSC_WPM_TARGET_TRANSPORT_CHAIN . . . . . . . . . . . . . . . . . . . . . . 473
XMSC_WPM_TARGET_TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
XMSC_WPM_TEMP_Q_PREFIX . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
XMSC_WPM_TEMP_TOPIC_PREFIX . . . . . . . . . . . . . . . . . . . . . . . . . 474
XMSC_WPM_TOPIC_SPACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475

Appendix. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477

Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481

Sending your comments to IBM . . . . . . . . . . . . . . . . . . . . . . . . 489

x Message Service Client for C/C++

Figures
1. XMS objects and their relationships . . . . 11
2. Typical use of administered objects by an XMS
application . . . . . . . . . . . . . 13

© Copyright IBM Corp. 2005, 2009 xi

xii Message Service Client for C/C++
Tables
1. Message Service Client for C/C++ platforms 23. Values used for
and compilers. . . . . . . . . . . . 14 XMSC_WMQ_SSL_CIPHER_SPEC when you
2. Installed directories on AIX, Linux, and Solaris, specify SSL_RSA_WITH_DES_CBC_SHA for
and their contents . . . . . . . . . . 20 the XMSC_WMQ_SSL_CIPHER_SUITE
3. Installed directories on Windows and their property . . . . . . . . . . . . . 93
contents. . . . . . . . . . . . . . 21 24. Properties of ConnectionFactory for secure
4. XMS sample applications . . . . . . . . 29 connections to a WebSphere service integration
5. Example URIs using character level wildcard bus messaging engine . . . . . . . . . 94
scheme for WebSphere MQ V7.0 queue 25. Available CipherSuites and their equivalent
manager . . . . . . . . . . . . . 43 CipherSpecs . . . . . . . . . . . . 95
6. Example URIs using topic level wildcard 26. JMS message header fields . . . . . . . 98
scheme for WebSphere MQ V7.0 queue 27. JMS-defined properties of a message . . . . 99
manager . . . . . . . . . . . . . 43 28. IBM-defined properties of a message 100
7. Example URIs using wildcard scheme for 29. XMS data types that are compatible with Java
WebSphere service integration bus . . . . . 44 data types . . . . . . . . . . . . 103
8. Objects that are deleted automatically . . . . 51 30. Environment variable settings for C/C++
9. XMS data types and their Java equivalents 52 trace . . . . . . . . . . . . . . 113
10. Supported conversions from a property type to 31. Summary of the C classes . . . . . . . 131
other data types . . . . . . . . . . . 52 32. Summary of the C++ classes . . . . . . 273
11. Network stack selection mechanism . . . . 59 33. Exception codes and their corresponding C++
12. Data types for object handles. . . . . . . 63 exceptions . . . . . . . . . . . . 275
13. Return codes from C function calls. . . . . 67 34. Properties of Connection . . . . . . . . 403
14. The XMS classes on which the assignment 35. Properties of ConnectionFactory . . . . . 404
operator is overloaded . . . . . . . . . 74 36. Properties of ConnectionMetaData . . . . 408
15. Examples of name mapping for connection 37. Properties of Destination . . . . . . . . 409
factory and destination properties . . . . . 84 38. Properties of InitialContext . . . . . . . 410
16. Property settings for administered 39. Properties of Message . . . . . . . . . 411
ConnectionFactory objects for connections to a 40. Properties of the Message object representing
WebSphere MQ queue manager . . . . . . 84 the MQMD fields . . . . . . . . . . 413
17. Property settings for administered 41. Properties of MessageConsumer . . . . . 415
ConnectionFactory objects for real-time 42. Properties of MessageProducer. . . . . . 416
connections to a broker . . . . . . . . 85 43. Properties of Session . . . . . . . . . 416
18. Property settings for administered 44. XMS client - Ability to use WebSphere MQ v7
ConnectionFactory objects for connections to a specific features. . . . . . . . . . . 454
WebSphere service integration bus . . . . . 85 45. Table of values for MQSCO.FlipsRequired
19. Property settings for administered Destination property . . . . . . . . . . . . . 461
objects . . . . . . . . . . . . . . 85 46. CipherSuite options for connection to a
20. Properties of ConnectionFactory for WebSphere service integration bus messaging
connections to a WebSphere MQ queue engine . . . . . . . . . . . . . . 470
manager via SSL . . . . . . . . . . . 91
21. Available CipherSpecs and their JSSE
CipherSuite equivalents . . . . . . . . 92
22. Values used for
XMSC_WMQ_SSL_CIPHER_SPEC when you
specify
SSL_RSA_WITH_3DES_EDE_CBC_SHA for the
XMSC_WMQ_SSL_CIPHER_SUITE property . 93

© Copyright IBM Corp. 2005, 2009 xiii

xiv Message Service Client for C/C++
About this book
IBM® Message Service Client for C/C++ describes and documents the API
provided by Message Service Client for C/C++. This API is referred to as XMS.

This book has the following parts:

v Part 1, “Getting started with Message Service Client for C/C++,” on page 1,
which describes what Message Service Client for C/C++ is, and how to install
and use Message Service Client for C/C++
v Part 2, “Developing XMS applications,” on page 33, which describes how to
write XMS applications
v Part 3, “Troubleshooting for XMS applications,” on page 109, which documents
the XMS classes and their methods, and the properties of XMS objects
v Part 4, “XMS API reference,” on page 117, which documents the XMS classes and
their methods, and the properties of XMS objects

For the latest information about Message Service Client for C/C++, see the product
readme.txt file, which is supplied.

Who this book is for

This book is primarily for application programmers who write XMS applications.
System integrators who require non-Java applications to participate in a messaging
system, and who have XMS API application development skills. Some of the
information might also be useful to system administrators who manage systems on
which XMS applications run, or who manage WebSphere® MQ queue managers,
WebSphere Business Integration Event Broker or WebSphere Business Integration
Message Broker brokers, or WebSphere service integration buses to which XMS
applications connect.

What skills and knowledge you need to understand this book

To understand the information in this book, you need the following skills,
knowledge, and experience:
v C or C++ application programming skills. If you are not a C++ programmer, you
need some knowledge of object-oriented concepts and terminology
v A working knowledge of the operating system that you are use
v Experience in using TCP/IP as a communications protocol
v Some knowledge of the concepts and terminology associated with the messaging
servers that you intend to use
Some knowledge of the Java™ Message Service Specification, Version 1.1 and the
WebSphere MQ implementation of JMS, WebSphere MQ classes for Java Message
Service, might be beneficial, but is not absolutely necessary. You do not need to be
a Java or JMS application programmer.

Terms used in this book

The term XMS refers to the API provided by Message Service Client for C/C++.

© Copyright IBM Corp. 2005, 2009 xv

About this book

The term XMS client refers to an installed instance of Message Service Client for
C/C++ that supports an application.

The term JMS refers to Java Message Service.

The term WebSphere MQ JMS refers to WebSphere MQ classes for Java Message
Service.

WebSphere JMS is used as a general term for any of the following JMS
implementations:
v WebSphere MQ JMS
v JMS for the WebSphere default messaging provider

Messaging server is used as a general term for any of the following software
components:
v A WebSphere MQ queue manager
v A broker of WebSphere Business Integration Event Broker or WebSphere
Business Integration Message Broker
v A WebSphere service integration bus

Unless otherwise stated, or implied by the context, broker is used as a general term
for a broker of any of the following products:
v WebSphere MQ Publish/Subscribe, as supplied with WebSphere MQ
v WebSphere Business Integration Event Broker
v WebSphere Business Integration Message Broker

The phrase real-time connection to a broker refers to a connection between an

application and a broker of WebSphere Business Integration Event Broker or
WebSphere Business Integration Message Broker, where messages are transported
between the application and the broker using WebSphere MQ Real-Time Transport.
Depending on the configuration, messages might also be delivered to message
consumers using WebSphere MQ Multicast Transport.

The term Linux® means Red Hat Enterprise Linux.

Windows® is used as a general term for any of the following platforms:

v Windows 2000
v Windows Server 2003
v Windows XP

Additional information about this book

Certain sections in this book refer you to other books and information centers for
more information.

You can download the latest edition of WebSphere MQ Using Java from
http://www.ibm.com/software/integration/mqfamily/library/manualsa/ .

You can access the latest version of the information center for WebSphere Business
Integration Event Broker or WebSphere Business Integration Message Broker at
http://publib.boulder.ibm.com/infocenter/wbihelp/ .

xvi Message Service Client for C/C++

 About this book

You can access the latest version of the information center for WebSphere
Application Server at http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/
index.jsp .

About this book xvii

xviii Message Service Client for C/C++
Summary of changes
This section describes changes in this edition of Message Service Client for C/C++.
Changes since the previous edition of the book are marked by vertical lines to the
left of the changes.

Changes for this edition (SC34-6984-01)

This edition contains documentation for new features and various editorial
improvements, clarifications, and corrections.

© Copyright IBM Corp. 2005, 2009 xix

xx Message Service Client for C/C++
Part 1. Getting started with Message Service Client for C/C++
Chapter 1. What’s new in this release . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Chapter 2. Enhancements in V2.0 release . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 3. Introduction to Message Service Client for C/C++ . . . . . . . . . . . . . . . . . . 9

What is Message Service Client for C/C++? . . . . . . . . . . . . . . . . . . . . . . . . . 9
Styles of messaging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
The XMS object model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Attributes and properties of objects . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Administered objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
The XMS message model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Operating environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Prerequisites for XMS applications connecting to WebSphere MQ . . . . . . . . . . . . . . . . . 14

Chapter 4. Installing Message Service Client for C/C++. . . . . . . . . . . . . . . . . . . . 15

Installing Message Service Client for C/C++ using the installation wizard . . . . . . . . . . . . . . 15
Installing from the command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Running the installer from the command line . . . . . . . . . . . . . . . . . . . . . . . 17
Installing silently . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
What is installed on AIX, Linux, and Solaris . . . . . . . . . . . . . . . . . . . . . . . . 19
What is installed on Windows (C/C++) . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Uninstalling Message Service Client for C/C++ . . . . . . . . . . . . . . . . . . . . . . . 21
Uninstalling on Message Service Client for C/C++ using Add/Remove Programs . . . . . . . . . . . 22

Chapter 5. Setting up the messaging server environment . . . . . . . . . . . . . . . . . . . 25

Configuring the queue manager and broker for an application that connects to a WebSphere MQ queue manager 25
Configuring the broker for an application that uses a real-time connection to a broker . . . . . . . . . . 27
Configuring the service integration bus for an application that connects to a WebSphere service integration bus . . 28

Chapter 6. Using the XMS sample applications . . . . . . . . . . . . . . . . . . . . . . 29

The sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Running the sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Building the C or C++ sample applications . . . . . . . . . . . . . . . . . . . . . . . . . 31

© Copyright IBM Corp. 2005, 2009 1

2 Message Service Client for C/C++
Chapter 1. What’s new in this release
This topic summarizes what is new in this release of Message Service Client for
C/C++ .

The following sections summarize the key enhancements.

IPv6 Support

This release of IBM Message Service Client for C/C++ enables XMS applications
developed using C or C++ programming language to connect to Messaging
Servers, such as WebSphere MQ, WebSphere SIB, and WebSphere Message Broker
running on an Internet Protocol version 6 (IPv6) enabled network.

The XMS applications, however, will continue to run on IPv4 networks. Users who
have only IPv4 stack and no IPv6 stack configured, may continue to use IPv4. See
“Network stack selection mechanism” on page 58 for details.

Addition of JMS_IBM_ArmCorrelator and JMS_TOG_ARM_Correlator

With the release of version 2.0.1, XMS adds two new properties for the Message
object. These properties are JMS_IBM_ArmCorrelator and
JMS_TOG_ARM_Correlator. These properties enable associating a unique
enterprise-wide Id for data being exchanged between disparate applications
running in complex, heterogenous environment of large enterprises.

These two properties are synonyms. Thus, applications can set the property with
one name and retrieve the same with the other property name. The use of
JMS_TOG_ARM_Correlator is however preferred over the use of
JMS_IBM_ArmCorrelator.

Performance enhancements

XMS 2.0.1 introduces several performance enhancements.

© Copyright IBM Corp. 2005, 2009 3

4 Message Service Client for C/C++
Chapter 2. Enhancements in V2.0 release
This topic summarizes the enhancements in the V2.0 release of Message Service
Client for C/C++.

Some of these enhancements are as a result of changes to the implementation of

Message Service Clients for C/C++, and some are as a result of exploiting changes
to the underlying WebSphere MQ functionality.

The following sections summarize the key enhancements.

Publish/subscribe messaging

WebSphere MQ V7.0 contains embedded publish/subscribe function. This function

replaces WebSphere MQ Publish/Subscribe, which was supplied with WebSphere
MQ V6.0.

Message Service Clients for C/C++ applications can use the embedded
publish/subscribe function, and can use it instead of using WebSphere Event
Broker or WebSphere Message Broker for publish/subscribe messaging with
WebSphere MQ as the transport. Configuring Message Service Clients for C/C++
to use the new function is simpler than configuring Message Service Clients for
C/C++ to use WebSphere MQ Publish/Subscribe, WebSphere Event Broker, or
WebSphere Message Broker. Administrators and application developers no longer
need to manage publication queues, subscriber queues, subscription stores, and
subscriber cleanup.

The embedded publish/subscribe function also provides some additional features

such as retained publications and a choice of two wildcard schemes for specifying
a range of topics to which an application wishes to subscribe.

An application can still use a real-time connection to a broker of WebSphere Event

Broker or WebSphere Message Broker for publish/subscribe messaging. This
support is unchanged.

Applications using WebSphere MQ Publish/Subscribe can use the embedded

publish/subscribe function without change when the queue manager to which
they are connected is upgraded. Properties that are set by an application, but are
not required by the embedded publish/subscribe function, are ignored.

WebSphere MQ messaging provider

The WebSphere MQ messaging provider has two modes of operation:

v WebSphere MQ messaging provider normal mode
v WebSphere MQ messaging provider migration mode

The WebSphere MQ messaging provider normal mode uses all the features of the
WebSphere MQ Version 7.0 queue managers to implement JMS. This mode is used
only to connect to a WebSphere MQ queue manager and can connect to WebSphere
MQ Version 7.0 queue managers in either client or bindings mode. This mode is
optimized to use the new WebSphere MQ Version 7.0 function. The WebSphere
MQ messaging provider migration mode is based on WebSphere MQ Version 6.0

© Copyright IBM Corp. 2005, 2009 5

 function and uses only features that were available in the WebSphere MQ Version
6.0 queue manager to implement JMS. You can connect to a WebSphere MQ
Version 7.0 queue manager using WebSphere MQ messaging provider migration
mode but you cannot use any of the Version 7.0 optimizations. This mode allows
connections to either of the following queue manager versions:
1. WebSphere MQ Version 7.0 queue manager in bindings or client mode, but this
mode uses only those features that were available to a WebSphere MQ Version
6.0 queue manager.
2. WebSphere MQ Version 6.0 or earlier queue manager in client mode.

If you want to connect to WebSphere Event Broker or WebSphere Message Broker

using either WebSphere MQ Enterprise Transport, use the WebSphere MQ
messaging provider migration mode. If you use WebSphere MQ Real-Time
Transport, the WebSphere MQ messaging provider migration mode is
automatically selected, because you have explicitly selected properties in the
connection factory object. Connection to WebSphere Event Broker or WebSphere
Message Broker using the WebSphere MQ Enterprise Transport follows the general
rules for mode selection described in Rules for selecting the WebSphere MQ
messaging provider mode .

Asynchronous message consumption

WebSphere MQ V7.0 supports asynchronous message consumption. An application

can register a callback function for a destination. When a suitable message is sent
to the destination, WebSphere MQ calls the function and passes the message as a
parameter. The function then processes the message asynchronously. In previous
releases of WebSphere MQ, this feature was available only when using WebSphere
MQ classes for JMS and Message Service Clients for C/C++.

Message Service Clients for C/C++ has been changed to exploit this new feature in
WebSphere MQ V7.0. The implementation of XMS message listeners is now a more
natural fit with WebSphere MQ, and Message Service Clients for C/C++ no longer
has to poll a destination to check whether a suitable message has been sent to the
destination. The performance of XMS message listeners is improved as a result,
particularly when an application uses multiple message listeners in a session to
monitor multiple destinations. Message throughput is increased, and the time
taken to deliver a message to a message listener after it has arrived at a destination
is reduced.

Message selection

With the exception of selecting messages by message identifier or correlation

identifier, all message selection in previous releases of WebSphere MQ was done
by Message Service Clients for C/C++. In WebSphere MQ V7.0, all message
selection is done by the queue manager on all platforms except z/OS®. For an
application connected to a z/OS queue manager, message selection is done by the
queue manager in the publish/subscribe domain, but is still done by Message
Service Clients for C/C++ in the point-to-point domain.

As a result, message throughput is increased for applications that consume

messages using message selection, where the message selection is done by the
queue manager. The performance improvement is greater for an application that
connects in client mode because only those messages that satisfy the selection
criteria are transported over the network, and Message Service Clients for C/C++
sees only those messages that it delivers to the application.

6 Message Service Client for C/C++

Sharing a communications connection

In previous releases of WebSphere MQ, if a WebSphere MQ client application

connected to a queue manager more than once using the same MQI channel, each
instance of the MQI channel required a separate TCP connection. In WebSphere
MQ V7.0, each connection to the queue manager using the same MQI channel can
share a single TCP connection. This arrangement means that fewer network
resources are required and the total time taken to create multiple connections to
the queue manager is reduced, particularly when using SSL because the SSL
handshake takes place only once at the start of the TCP connection.

Message Service Clients for C/C++ exploits this enhancement. For an application
that connects to a queue manager in client mode, Message Service Clients for
C/C++ might create more than one connection to a queue manager using the MQI
channel whose name is specified as a property of the ConnectionFactory object.
Each of these connections to the queue manager can now share a single TCP
connection.

Read ahead on client connections

Using read ahead can improve performance when browsing messages or

consuming non persistent messages from a client application. This performance
improvement is available to both MQI and XMS applications. Client applications
using MQGET or asynchronous consume will benefit from the performance
improvements when browsing messages or consuming non-persistent messages.

If an application uses a client connection to consume nonpersistent messages from

a destination, the destination can be configured so that Message Service Clients for
C/C++ uses a buffer to store the messages of interest before delivering them to the
application. This optimization is called read ahead and can be used by applications
that consume messages synchronously by calling receive() method, and by message
listeners which consume messages asynchronously.

Read ahead is particularly effective for destinations with a large number of

messages that need to be consumed rapidly. Read ahead does not apply to
persistent messages because, if persistent messages were read into a buffer, the
queue manager would no longer be able to recover the messages following a
failure. However, an application that consumes messages from a destination with a
mixture of persistent and nonpersistent messages can still use read ahead. The
order of the messages is preserved, but the runtime benefits of read ahead apply
only to the nonpersistent messages.

When deciding whether to use read ahead, consider the following points:
v If an application is consuming messages from a destination that is configured for
read ahead, and the application ends for any reason, any nonpersistent messages
that are currently stored in the buffer are discarded.
v If all the following conditions are true, messages sent to a queue in a session
might not be received in the order in which they were sent:
– An application uses two message consumers in the same session to consume
the messages from the queue.
– Each message consumer uses a different Destination object for the queue.
– Any or both of the Destination objects are configured for read ahead

Asynchronous message send

Chapter 2. Enhancements in V2.0 release 7

 When an application sends messages to a destination, the destination can be
configured so that, when the application calls send(),Message Service Clients for
C/C++ forwards the message to the queue manager and returns control back to
the application without determining whether the queue manager has received the
message safely. Message Service Clients for C/C++ can work in this way only for
nonpersistent messages and for persistent messages sent in a transacted session.

This optimization is of most benefit to an application that connects to a queue

manager in client mode and needs to send a sequence of messages in rapid
succession, but does not require immediate feedback from the queue manager for
each message sent.

Reading and writing the message descriptor from a Message Service Clients for
C/C++ application

You can now access the message descriptor (MQMD) of a WebSphere MQ message.
This feature is available only when connecting to a WebSphere MQ queue manager
version 6 and above and is controlled by destination properties described later.

All MQMD fields are exposed except StrucId and Version; BackoutCount can be
read but not written to.

Message Service Clients for C/C++ provides message attributes that allow XMS
applications to set MQMD fields and so enable XMS applications to drive
WebSphere MQ applications.

Some restrictions apply when using Publish/Subscribe type of messaging. MQMD

fields like MsgID, CorrelId, if set are ignored.

Accessing WebSphere MQ Message data from a Message Service Clients for

C/C++ application

You can access the complete WebSphere® MQ message data including the
MQRFH2 header (if present) and any other WebSphere MQ headers (if present)
within a Message Service Clients for C/C++ application as the body of a
JMSBytesMessage.

The function described in this topic is available only when connecting to a

WebSphere MQ queue manager at Version 6.0 or later and the WebSphere MQ
messaging provider is in normal mode.

Destination object properties determine how the XMS application accesses the
whole of a WebSphere MQ message (including the MQRFH2 header, if present) as
the body of a JMSBytesMessage..

8 Message Service Client for C/C++

Chapter 3. Introduction to Message Service Client for C/C++
This chapter introduces Message Service Client for C/C++.

The chapter contains the following sections:

v “What is Message Service Client for C/C++?”
v “Styles of messaging” on page 10
v “The XMS object model” on page 10
v “The XMS message model” on page 13
v “Operating environments” on page 13

What is Message Service Client for C/C++?

Message Service Client for C/C++ provides an API called XMS that has the same
set of interfaces as the Java Message Service (JMS) API. Message Service Client for
C/C++ contains two implementations of XMS, one for use by C applications and
another for use by C++ applications.

XMS supports both the point-to-point and the publish/subscribe styles of

messaging, and supports both synchronous and asynchronous message delivery.

An XMS application can connect to, and use the resources of, any of the following
messaging servers:
v A WebSphere MQ queue manager.
The application can connect in either bindings or client mode.
v A WebSphere service integration bus.
The application can use a direct TCP/IP connection, or it can use HTTP over
TCP/IP.
v A broker of WebSphere Event Broker or WebSphere Message Broker.
Messages are transported between the application and the broker using
WebSphere MQ Real-Time Transport and, depending on the configuration,
messages can be delivered to the application using WebSphere MQ Multicast
Transport.

By connecting to a WebSphere MQ queue manager, an XMS application can use

WebSphere MQ Enterprise Transport to communicate with a broker of WebSphere
Event Broker or WebSphere Message Broker. Alternatively, an XMS application can
use a WebSphere MQ Publish/Subscribe broker.

An XMS application can exchange messages with any of the following types of
application:
v An XMS application
v A WebSphere MQ JMS application
v A native WebSphere MQ application
v A JMS application that is using the WebSphere default messaging provider

© IBM Corporation 2005 9

Styles of messaging
XMS supports the point-to-point and publish/subscribe styles of messaging.

Styles of messaging are also called messaging domains.

Point-to-point messaging
A common form of point-to-point messaging uses queuing. In the simplest
case, an application sends a message to another application by identifying,
implicitly or explicitly, a destination queue. The underlying messaging and
queuing system receives the message from the sending application and
routes the message to its destination queue. The receiving application can
then retrieve the message from the queue.
If the underlying messaging and queuing system contains a message
broker, the broker might replicate a message and route copies of the
message to different queues so that more than one application can receive
the message. The broker might also transform a message and add data to
it.
A key characteristic of point-to-point messaging is that an application
identifies a destination queue when it sends a message. The configuration
of the underlying messaging and queuing system then determines
precisely which queue the message is put on so that it can be retrieved by
the receiving application.
Publish/subscribe messaging
In publish/subscribe messaging, there are two types of application:
publisher and subscriber.
A publisher supplies information in the form of messages. When a publisher
publishes a message, it specifies a topic, which identifies the subject of the
information inside the message.
A subscriber is a consumer of the information that is published. A
subscriber specifies the topics it is interested in by sending subscription
requests to a publish/subscribe broker. The broker receives published
messages from publishers and subscription requests from subscribers, and
it routes published messages to subscribers. A subscriber receives messages
on only those topics, to which it has subscribed.
A key characteristic of publish/subscribe messaging is that a publisher
identifies a topic when it publishes a message, and a subscriber receives
the message only if has subscribed to the topic. If a message is published
on a topic for which there are no subscribers, no application receives the
message.
An application can be both a publisher and a subscriber.

The XMS object model

The XMS API is an object-oriented interface. The XMS object model is based on the
JMS 1.1 object model.

The following list summarizes the main XMS classes, or types of object:
ConnectionFactory
A ConnectionFactory object encapsulates a set of configuration parameters
for a connection. An application uses a ConnectionFactory to create a
connection. An application can create a ConnectionFactory object at run

10 Message Service Client for C/C++

 time, or it can create a ConnectionFactory object from an object definition
that is retrieved from a repository of administered objects.
Connection
A Connection object encapsulates an application’s active connection to a
messaging server. An application uses a connection to create sessions.
Destination
The source from where an application sends messages or receives
messages. In the publish/subscribe domain, a Destination object
encapsulates a topic and, in the point-to-point domain, a Destination object
encapsulates a queue. An application can create a Destination object at run
time, or it can create a Destination object from an object definition that is
retrieved from a repository of administered objects.
Session
A session is a single threaded context for sending and receiving messages.
An application uses a session to create messages, message producers, and
message consumers.
Message
A Message object encapsulates a message that an application sends
(MessageProducer) or receives (MessageConsumer).
MessageProducer
An object used by an application to send messages to a destination.
MessageConsumer
An object used by an application to receive messages sent to a destination.

Figure 1 shows these objects and their relationships.

ConnectionFactory

Creates

Connection

Creates

Creates Creates
MessageProducer Session MessageConsumer

Sends to Creates Receives from

Destination Message Destination

Figure 1. XMS objects and their relationships

XMS applications written in C++ use these classes and their methods. XMS
applications written in C use the same object model even though C is not an object
oriented language. When a C application calls a function to create an object, XMS

Chapter 3. Introduction to Message Service Client for C/C++ 11

 stores the object internally and returns a handle for the object to the application.
The application can then use the handle subsequently to access the object. For
example, if a C application creates a ConnectionFactory, XMS returns a handle for
the ConnectionFactory to the application. In general, for each C++ method in the
C++ interface, there is an equivalent C function in the C interface.

The XMS object model is based on the domain independent interfaces that are
described in Java Message Service Specification, Version 1.1. Domain specific classes,
such as Topic, TopicPublisher, and TopicSubscriber, are not provided.

Attributes and properties of objects

An XMS object can have attributes and properties, which are characteristics of the
object, that are implemented in different ways.
Attributes
An object characteristic that is always present and occupies storage, even if
the attribute does not have a value. In this respect, an attribute is similar to
a field in a fixed length data structure. A distinguishing feature of
attributes is that each attribute has its own methods for setting and getting
its value.
Properties
A property of an object is present and occupies storage only after its value
is set. However, a property cannot be deleted (nor can the storage be
recovered) after its value has been set, although you can change its value.
XMS provides a set of generic methods for setting and getting property
values.

Administered objects
Using administered objects, you can administer the connection settings used by
client applications to be administered from a central repository. An application
retrieves object definitions from the central repository and uses them to create
ConnectionFactory and Destination objects. This allows applications to be
de-coupled from the resources that they use at runtime.

For example, XMS applications can be written and tested with administered objects
that reference a set of connections and destinations in a test environment. When
the applications are deployed, the administered objects can be changed to point the
applications to a production environment.

XMS supports two types of administered object:

v A ConnectionFactory object, which is used by applications to make the initial
connection to the server
v A Destination object, which is used by applications to specify the destination for
messages that are being sent, and the source of messages that are being received.
A destination is either a topic or a queue on the server to which an application
connects.

The WebSphere MQ JMS administration tool (JMSAdmin) available with

WebSphere MQ can be used to create and manage administered objects for
WebSphere MQ, WebSphere Message Broker, or WebSphere Event Broker in a
central repository of administered objects.

The administered objects in the repository can be used by WebSphere MQ JMS

applications, and also by XMS applications for ConnectionFactories and

12 Message Service Client for C/C++

 Destinations for WebSphere MQ queue manager, or for a realtime connection to a
broker. An administrator can change the object definitions held in the repository
without affecting application code.

The following diagram shows how an XMS application typically uses administered
objects.

Administration console XMS application

Produces/consumes
Administers Looks up
messages

Destination

Administered Messaging server

objects repository

ConnectionFactory

Figure 2. Typical use of administered objects by an XMS application

The XMS message model

The XMS message model is the same as the WebSphere JMS message model.

In particular, XMS implements the same message header fields and message
properties that WebSphere JMS implements:
v JMS header fields. These are fields whose names commence with the prefix JMS.
v JMS defined properties. These are properties whose names commence with the
prefix JMSX.
v IBM defined properties. These are the properties whose names commence with
the prefix JMS_IBM_.

As a result, XMS applications can exchange messages with WebSphere JMS

applications. For each message sent by an XMS or WebSphere JMS application,
some of the header fields and properties are set by the application, others are set
by XMS or WebSphere JMS when the message is sent, and the remainder are set by
XMS or WebSphere JMS when the message is received. Where appropriate, these
header fields and properties are propagated with a message through a messaging
server and are made available to any application that receives the message.

Operating environments
An XMS client is supplied for each of the tested operating systems.

Chapter 3. Introduction to Message Service Client for C/C++ 13

 Table 1 lists the compiler for each client platform.
Table 1. Message Service Client for C/C++ platforms and compilers
Operating system Compiler
®
Microsoft Windows XP with Service Pack 1, Microsoft Visual C++ .NET 2005, service
Windows 2000, Windows Advanced Server Pack 1
2003 (Intel® 32 bit)
Microsoft Windows 2003 Server x64 edition Microsoft Visual C++ .NET 2005, service
Pack 1
Red Hat Enterprise Linux 3.0 or 4.0 (Intel 32 gcc 3.3.3
bit), SUSE Linux ES 9 (Intel 32 bit)
Red Hat Enterprise Linux 4.0 with update 4 gcc 4.1
(x86_64)
Sun Solaris version 9 (on SPARC) C compiler: Forte Developer 6 Update 2

C++ compiler: Forte Developer 6 Update 2

®
AIX 5.3 with ML4 IBM XL C/C++ Compiler version 7.0

Note: XMS on Sun Solaris has been built and tested using both the Forte
Developer 6 Update 2 C and C++ compilers. The version of the C compiler
and the C++ compiler itself are both version 5.3.

The XMS C libraries are readily usable with objects built with earlier or later
versions of the Sun Studio C compilers.

The XMS C++ libraries are readily usable with later 5.x versions of the Sun
Studio C compilers. Note that the XMS C++ libraries are likely to be
unusable with objects built by a C++ compiler with version earlier than 5.x,
or with 5.x compilers operating in version 4 compatibility mode. Therefore,
if an object has been compiled by a version 5.x compiler specifying the
-compat option, it is likely to be unusable, either at link time or run time,
with the XMS C++ libraries.

Prerequisites for XMS applications connecting to WebSphere MQ

Some prerequisites apply if your XMS application connects to WebSphere MQ.

For applications that connect to a WebSphere MQ queue manager, you must install
the appropriate WebSphere MQ client libraries on the machine you use to run the
XMS application. These libraries are pre-installed on machines with a local queue
manager.

For XMS client for C/C++, use the WebSphere MQ Version 7.0.0.1 client libraries.
These enable client mode connections to WebSphere MQ Version 7.0, and
WebSphere MQ Version 6.0, and WebSphere MQ Version 5.3 queue managers and
bindings mode connections to WebSphere MQ Version 7.0 local queue managers.

XMS client for C/C++ can still work with WebSphere MQ Version 7.0.0.0 client
libraries but will not be able to use WebSphere MQ Version 7.0 features.

14 Message Service Client for C/C++

Chapter 4. Installing Message Service Client for C/C++
This chapter describes how to install Message Service Client for C/C++ (XMS).

About this task

Message Service Client for C/C++ is installed using an InstallAnywhere installer.

You can either use the installer in the form of a wizard with a graphical user
interface, or you can invoke the installer from a command prompt. For general
information about InstallAnywhere, see the InstallAnywhere Web site at
http://www.acresso.com/products/ia/installanywhere-overview.htm.

The installer also installs GSKit.

Note: When you are installing on Windows using the installation wizard, you can
choose the location in which GSKit is installed.

This chapter contains the following sections:

v “Installing Message Service Client for C/C++ using the installation wizard”
v “Installing from the command line” on page 17
v “What is installed on AIX, Linux, and Solaris” on page 19
v “What is installed on Windows (C/C++)” on page 20
v “Uninstalling Message Service Client for C/C++” on page 21

Installing Message Service Client for C/C++ using the installation

wizard
The installation for Message Service Client for C/C++ uses an InstallAnywhere
installer. Two setup options are available, so that you can choose either a complete
or a custom installation.

Before you begin

The installed client requires 150 MB of disk space on AIX, Linux, Solaris, and
Windows.

About this task

To install Message Service Client for C/C++ on AIX, Linux, Solaris, or Windows,
follow this procedure. You can click Cancel at any time during the install setup
process to stop the installation process from continuing, but note that the Cancel
option is not available while the product is actually being installed.
1. If you are installing from a SupportPac, complete the following steps,
otherwise proceed directly to step 2 on page 16;
a. On AIX, Linux, or Solaris, log in as root. On Windows, log on as an
administrator.
b. Create a temporary directory and extract the contents of the zipped file
supplied with Message Service Client for C/C++ into the directory.
A subdirectory of the temporary directory is created. The subdirectory is
called gxixms_install and contains the files needed for the installation.

© IBM Corporation 2005 15

 c. Run the setup file:
v On AIX, run the file called setup.bin that is in the gxixms_install
directory.
v On Linux, run the file called setup.bin that is in the gxixms_install
directory.
v On Solaris, run the file called setup.bin that is in the gxixms_install
directory.
v On Windows, run the file setup.exe that is in the gxixms_install
directory.
Messages informing you that the installer is preparing to install are
displayed. Message Service Client for C/C++ provides a JVM for the
installer; you do not need to provide one.
2. When the installation wizard opens, select the appropriate language to be
used in the wizard and click OK.
3. In the Introduction panel, text notifying that the installation wizard will install
IBM Message Service Client for C/C++ on your computer is displayed. Click
Next.
4. If the wizard asks you to read the license agreement, and you accept the terms
of the license agreement, click I accept the terms in the license agreement,
and then click Next. On Windows only, the installer asks you where you want
to install GSKit.
5. If you are installing on Windows and you want to install GSKit in the
directory suggested, click Next ; otherwise, choose another directory. The
installation wizard asks you where you want to install Message Service Client
for C/C++.
6. To install Message Service Client for C/C++ in the directory suggested, click
Next; otherwise choose another directory. If you choose to install Message
Service Client for C/C++ in a directory that does not currently exist, the
installation wizard creates the directory for you.
The installation wizard asks you to choose the setup type that best suits your
needs.
7. Select the type of setup that you require:
v To install all program features, click the Complete icon.
v To choose which features you want to install, click the Custom icon.
8. Click Next.
If you select the complete install option, the installation wizard displays
details of the installation options that you have selected, and you can proceed
as described in step 10 on page 17. If you select the custom install option, the
installation wizard asks you which features you want to install, and you must
complete step 9 before moving on to step 10 on page 17.
9. For a custom install only, select the Message Service Client for C/C++ features
that you want to be installed and then click Next.
If you want to develop XMS applications, ensure that you select the
Development Tools and Samples feature. This feature provides the sample
applications, and the libraries and header files needed to compile C and C++
applications. If you do not select this feature, only the files needed to run
XMS applications are installed.
The installation wizard displays details of the installation options that you
have selected.

16 Message Service Client for C/C++

 10. When you are satisfied with your selected installation options, click Install to
start the installation. Note that Cancel becomes unavailable when the
installation has started.
The installation wizard displays a bar showing the progress of the installation.
Wait for the progress bar to complete. When the installation completes
successfully, the wizard displays a message confirming that the
InstallAnywhere wizard has successfully installed IBM Message Service Client
for C/C++ on your computer.
11. Click Next. If you want to view the readme file for Message Service Client for
C/C++, select View Readme and then click Done.
12. If you selected View Readme option in the previous step, the readme is
displayed in the installation wizard. Click Done to close the installation
wizard.

Results

You have now successfully installed Message Service Client for C/C++, which is
ready to use.

What to do next

Before running any XMS applications, including the sample applications provided
with XMS, you must set up the messaging server environment as described in
Chapter 5, “Setting up the messaging server environment,” on page 25.

Installing from the command line

As an alternative to using the installation wizard, you can run the installation from
the command line.

About this task

Running the installer from a command prompt allows you to finely control the
installation. The following options are available:
v Perform a console-based, text-based installation.
v Record a response file using the runtime command line option -r.
v Perform an unattended, or silent installation, which requires no interaction with
the wizard by invoking the installer from a command prompt using the runtime
command line option silent. The silent install uses the response file that you
specify when you type in the command.

To use any of these options, type the appropriate command as described in the
sub-topics.

This section contains the following subsections:

v “Running the installer from the command line”
v “Installing silently” on page 18

Running the installer from the command line

You can run the installation from the command line to perform a console-based,
text-based installation.

Chapter 4. Installing Message Service Client for C/C++ 17

 About this task

Running the installer from a command prompt using the option console allows
you to perform a console-based, text-based installation.
v On AIX, type the following command:
setup.bin -i console
v On Linux, type the following command:
setup.bin -i console
v On Solaris, type the following command:
setup.bin -i console
v On Windows, type the following command:
setup.exe -i console

Installing silently
If you invoke the installer from a command prompt using the runtime command
line option silent, you can perform an unattended, or silent installation.

About this task

Running the installer in silent mode requires no interaction with the wizard. You
can invoke a silent install using all the default setup options, or provide a response
file for a non-standard installation.

To use any of these options, type the appropriate command from the following list.
v To run a silent install using all the default setup options, type one of the
following commands:
– On AIX, type:
setup.bin -i silent -DLICENSE_ACCEPTED=TRUE
– On Linux, type:
setup.bin -i silent -DLICENSE_ACCEPTED=TRUE
– On Solaris, type:
setup.bin -i silent -DLICENSE_ACCEPTED=TRUE
– On Windows, type:
setup.exe -i silent -DLICENSE_ACCEPTED=TRUE
In this way, you explicitly accept the license agreement and the install can
proceed using the default options.
v To record a response file using the wizard, type one of the following commands:
– On AIX, type:
setup.bin -r responsefilename.txt
– On Linux, type:
setup.bin -r responsefilename.txt
– On Solaris, type:
setup.bin -r responsefilename.txt
– On Windows, type:
setup.exe -r responsefilename.txt
You can use the console option in conjunction with the above command to
record the response file in a text-based manner. For example
– On Windows, type:
setup.exe -i console -r responsefilename.txt

18 Message Service Client for C/C++

 v To invoke a silent install using a response file, type one of the following
commands:
– On AIX, type:
setup.bin -i silent -f [responsefilename.txt]
– On Linux, type:
setup.bin -i silent -f [responsefilename.txt]
– On Solaris, type:
setup.bin -i silent -f [responsefilename.txt]
– On Windows, type:
setup.exe -i silent -f [responsefilename.txt]
v You can use the silent option for uninstalling by adding it as an argument to the
uninstaller command. For example:
– On Windows, type:
uninstaller.exe -u silent
v You can use the console option instead to perform a text-based uninstallation.
For example:
– On Windows, type:
uninstaller.exe -u console

What is installed on AIX, Linux, and Solaris

On AIX, Linux, and Solaris, Message Service Client for C/C++ is installed in the
/opt/IBM/XMS directory unless you choose to install it in a different directory.

Table 2 on page 20 lists the installed directories, relative to the installation

directory, and describes their contents.

Chapter 4. Installing Message Service Client for C/C++ 19

 Table 2. Installed directories on AIX, Linux, and Solaris, and their contents
Installed feature Installed directory Contents
Runtime The readme.txt file for the product and the
license agreement
_jvm The Java Virtual Machine (JVM) required by
the uninstaller
_uninst The files required to uninstall Message
Service Client for C/C++
bin Programs, for example, gxitrcfmt and gxisc
lib The shared object libraries required to
compile and run XMS applications, and a
symbolic link to the shared object library in
the lib/3.3 directory
lib64 The shared object libraries required to
compile and run XMS applications on 64 bit
platforms
Note: This directory will only appear on
currently supported 64 bit platforms.
lib/3.3 On Linux only, the shared object library
required to compile XMS applications written
in C++ using the gcc 3.3 compiler, and to run
the applications
lib/4.1 and lib64/4.1 On RHEL4.0 x86_64 only, the shared object
library required to compile XMS applications
written in C++ using the gcc 4.1 compiler,
and to run the applications
Development tools/c/include The XMS header files for C
Tools
tools/cpp/include The XMS header files for C++
Documentation doc This documentation as a PDF file
and Samples
tools/samples The readme.txt file for the sample
applications
tools/samples/bin The compiled sample applications and the
command file to run them
tools/samples/ The source and makefile for the C message
SampleConsumerC consumer sample application
tools/samples/ The source and makefile for the C message
SampleProducerC producer sample application
tools/samples/ The source and makefile for the C++ message
SampleConsumerCPP consumer sample application
tools/samples/ The source and makefile for the C++ message
SampleProducerCPP producer sample application
tools/samples/ The sampleconfig tool
SampleConfigC

What is installed on Windows (C/C++)

On Windows x86, XMS is installed in the C:\Program Files\IBM\XMS directory
and on Windows x64, XMS is installed in the C:\Program Files (x86) \IBM\XMS
directory unless you choose to install it in a different directory.

20 Message Service Client for C/C++

 Table 3 lists the installed directories, relative to the installation directory, and
describes their contents.
Table 3. Installed directories on Windows and their contents
Installed feature Installed directory Contents
Runtime The license agreement for the product and the
readme.txt file
_jvm The Java Virtual Machine (JVM) required by
the uninstaller
_uninst The files required to uninstall Message Service
Client for C/C++
bin The *.dll and *.pdb files required to run XMS
applications. Programs, for example, gxitrcfmt
and gxisc
bin64 The *.dlls required to run 64bit XMS
aplications
licenses The licenses for Message Service Client for
C/C++.
Development tools\c\include The XMS header files for C
Tools
tools\cpp\include The XMS header files for C++
tools\lib The XMS link libraries for C and C++
tools\lib64 On x64 only, 64bit XMS link libraries for C and
C++
Documentation doc This documentation as a PDF file
and Samples
tools\samples\bin The compiled sample applications and the
command file to run them
tools\samples\ The source and makefile for the C message
SampleConsumerC consumer sample application
tools\samples\ The source and makefile for the C message
SampleProducerC producer sample application
tools\samples\ The source and makefile for the C++ message
SampleConsumerCPP consumer sample application
tools\samples\ The source and makefile for the C++ message
SampleProducerCPP producer sample application
tools\samples\c\ The sampleconfig tool
sampleconfig
tools\samples\ The readme.txt file for the sample applications
readme.txt

Note: On Windows, redistributable Microsoft runtime libraries for Microsoft Visual

C++ .NET 2005 Service Pack1 is installed by XMS in the
WINDOWS\WinSxS directory. For more details on these Microsoft
redistributed files, and any implications of their use, see the Microsoft
website.

Uninstalling Message Service Client for C/C++

An uninstaller is provided to remove Message Service Client for C/C++ from your
system.

Chapter 4. Installing Message Service Client for C/C++ 21

 About this task

To remove Message Service Client for C/C++ from your AIX, Linux, Solaris, or
Windows system, follow this procedure. The Uninstaller also removes GSKit from
your system.
1. On AIX, Linux or Solaris, log in as root. On Windows, log on as an
administrator.
2. Run the uninstaller:
v On AIX, run the file called uninstaller that is in the directory
install_dir/_uninst.
v On Linux, run the file called uninstaller that is in the directory
install_dir/_uninst.
v On Solaris, run the file called uninstaller that is in the directory
install_dir/_uninst.
v On Windows, run the file uninstaller.exe that is in the directory
install_dir\_uninst.
install_dir is the directory where you have installed Message Service Client for
C/C++.
The Uninstaller window opens and displays the following message:
The wizard will uninstall Message Service Client for C/C++ from your computer.
3. Click Uninstall.
The Uninstaller window displays details of what is about to be uninstalled and
begins the uninstallation process. After all the items have been uninstalled, the
following message is displayed:
All items were successfully uninstalled.
4. Click Done to close the Uninstaller window.

Results

You have now successfully removed the Message Service Client for C/C++ from
your system.

Uninstalling on Message Service Client for C/C++ using

Add/Remove Programs
As an alternative to launching the uninstaller manually, you can remove Message
Service Client for C/C++ from your Windows system using Add/Remove
Programs.

About this task

To remove Message Service Client for C/C++ using Add/Remove Programs,
follow this procedure. The Uninstaller also removes GSKit from your system.

The Add/Remove Programs window shows only one instance of Message Service
Client for C/C++. If you have problems uninstalling Message Service Client for
C/C++, or you have more than one instance of Message Service Client for C/C++,
you might want to uninstall Message Service Client for C/C++ using the
procedure described in “Uninstalling Message Service Client for C/C++” on page
21.
1. Log on to Windows as an administrator.
2. From the Windows task bar, click Start —> Settings —> Control Panel. The
Control Panel window opens.
22 Message Service Client for C/C++
3. Double-click Add/Remove Programs. The Add/Remove Programs window
opens.
4. Click IBM Message Service Client for C/C++ to select it.
5. Click Change/Remove. The Uninstaller window opens and displays the
following message:
The wizard will uninstall Message Service Client for C/C++ from your computer.
6. Click Uninstall. The Uninstaller window displays details of what is about to be
uninstalled and begins the uninstallation process. After all the items have been
uninstalled, the following message is displayed:
All items were successfully uninstalled.
7. Click Done to close the Uninstaller window.

Results

You have now successfully removed Message Service Client for C/C++ from your
system.

Chapter 4. Installing Message Service Client for C/C++ 23

24 Message Service Client for C/C++
Chapter 5. Setting up the messaging server environment
This chapter describes how to set up the messaging server environment to allow
XMS applications to connect to a server.

Before you begin

The following prerequisite applies to setting up the messaging server environment:

v For applications that connect to a WebSphere MQ queue manager, the
WebSphere MQ client (or queue manager for bindings mode) is required.

There are currently no prerequisites for applications that use a real-time connection
to a broker.

For additional information about prerequisites, refer to the readme.txt file for
Message Service Client for C/C++.

About this task

You must set up the messaging server environment before running any XMS
applications, including the sample applications provided with XMS.

This chapter contains the following sections:

v “Configuring the queue manager and broker for an application that connects to
a WebSphere MQ queue manager”
v “Configuring the broker for an application that uses a real-time connection to a
broker” on page 27
v “Configuring the service integration bus for an application that connects to a
WebSphere service integration bus” on page 28

Configuring the queue manager and broker for an application that

connects to a WebSphere MQ queue manager
This section assumes that you are using WebSphere MQ version 7.0. Before you
can run an application that connects to a WebSphere MQ queue manager, you
must configure the queue manager. For a publish/subscribe application, some
additional configuration is required if you are using Queued Publish/Subscribe
interface.

Before you begin

Before starting this task, you must do the following:

v Make sure that your application has access to a queue manager that is running.
v If your application is a publish/subscribe application and uses Queued
Publish/Subscribe interface, make sure that “PSMODE” attribute is set to
“ENABLED” on the queue manager.
v Make sure that your application uses a connection factory whose properties are
set appropriately to connect to the queue manager. If your application is a
publish/subscribe application, make sure that the appropriate connection factory

© IBM Corporation 2005 25

 properties are set for using the broker. For more information about the
properties of a connection factory, “Properties of ConnectionFactory” on page
404.

About this task

You configure the queue manager and broker to run XMS applications in the same
way that you configure the queue manager and queued publish/subscribe
interface to run WebSphere MQ JMS applications. The following steps summarize
what you need to do:
1. On the queue manager, create the queues that your application needs.
For information about how to do this, see the WebSphere MQ System
Administration Guide.
If your application is a publish/subscribe application and uses Queued
Publish/Subscribe interface that needs access to WebSphere MQ JMS system
queues, wait until Step 4a before creating the queues.
2. Grant the user ID associated with your application the authority to connect to
the queue manager and the appropriate authorities to access the queues.
For information about how to do this, see the WebSphere MQ System
Administration Guide. If your application connects to the queue manager in
client mode, see also WebSphere MQ Clients or WebSphere MQ Security.
3. If your application connects to the queue manager in client mode, make sure
that a server connection channel is defined at the queue manager and that a
listener has been started.
For information about how to do this, see WebSphere MQ Clients.
You do not need to perform this step for each application that connects to the
queue manager. One server connection channel definition and one listener can
support all the applications that connect in client mode.
4. If your application is a publish/subscribe application, and uses Queued
Publish/Subscribe interface, perform the following steps.
a. On the queue manager, create the WebSphere MQ JMS system queues by
running the script of MQSC commands supplied with WebSphere MQ.
Make sure that the user ID associated with the broker has the authorities it
needs to access the queues.
For information about where to find the script and how to run it, see
WebSphere MQ Using Java.
You need to perform this step only once for the queue manager. The same
set of WebSphere MQ JMS system queues can support all XMS and
WebSphere MQ JMS applications that connect to the queue manager.
b. Grant the user ID associated with your application the authorities it needs
to access the WebSphere MQ JMS system queues.
For information about what authorities the user ID needs, see WebSphere
MQ Using Java.
c. For a broker of WebSphere Event Broker or WebSphere Message Broker,
create and deploy a message flow to service the queue where applications
send messages that they publish.
The basic message flow comprises an MQInput message processing node to
read the published messages and a Publication message processing node to
publish the messages.
For information about how to create and deploy a message flow, see the
WebSphere Event Broker or WebSphere Message Broker Information Center.

26 Message Service Client for C/C++

 You do not need to perform this step if a suitable message flow is already
deployed at the broker.

Results

You can now start your application.

Configuring the broker for an application that uses a real-time

connection to a broker
Before you can run an application that uses a real-time connection to a broker, you
must configure the broker.

Before you begin

Before starting this task, you must do the following:

v Make sure that your application has access to a broker that is running.
v Make sure that your application uses a connection factory whose properties are
set appropriately for a real-time connection to the broker. For more information
about the properties of a connection factory, see “Properties of
ConnectionFactory” on page 404.

About this task

You configure the broker to run XMS applications in the same way that you
configure the broker to run WebSphere MQ JMS applications. The following steps
summarize what you need to do but, for more details, see the WebSphere Event
Broker or WebSphere Message Broker Information Center:
1. Create and deploy a message flow to read messages from the TCP/IP port on
which the broker is listening and publish the messages.
You can do this in either of the following ways:
v Create a message flow that contains a Real-timeOptimizedFlow message
processing node.
v Create a message flow that contains a Real-timeInput message processing
node and a Publication message processing node.
You must configure the Real-timeOptimizedFlow or Real-timeInput node to
listen on the port used for real-time connections. In XMS, the default port
number for real-time connections is 1506.
You do not need to perform this step if a suitable message flow is already
deployed at the broker.
2. If you require messages to be delivered to your application using WebSphere
MQ Multicast Transport, configure the broker to enable multicast. Configure the
topics that need to be multicast enabled, specifying a reliable quality of service
for those topics that need to be configured for reliable multicast.
3. If your application supplies a user ID and a password when it connects to the
broker, and you want the broker to authenticate your application using this
information, configure the user name server and the broker for simple
telnet-like password authentication.

Results

You can now start your application.

Chapter 5. Setting up the messaging server environment 27

Configuring the service integration bus for an application that
connects to a WebSphere service integration bus
Before you can run an application that connects to a WebSphere service integration
bus, you must configure the service integration bus in the same way that you
configure the service integration bus to run JMS applications that use the default
messaging provider.

Before you begin

Before starting this task, you must do the following:

v Make sure that a messaging bus has been created and that your server has been
added to the bus as a bus member.
v Make sure that your application has access to a service integration bus that
contains at least one messaging engine that is running.
v If HTTP operation, is required then an HTTP messaging engine inbound
transport channel must be defined. By default, channels for SSL and TCP will
already have been predefined during the server installation.
v Make sure that your application uses a connection factory whose properties are
set appropriately to connect to the service integration bus using a bootstrap
server. The minimum information that you need to specify is:
– The provider endpoint, which describes the location and protocol to use
when negotiating a connection to the messaging server (that is, via the
bootstrap server). In its simplest form, for a server installed with default
settings, this can be set to the hostname of the server.
– The name of the bus through which messages should be sent.
For more information about the properties of a connection factory, see
“Properties of ConnectionFactory” on page 404.

About this task

Any queue or topic spaces that you require must be defined. By default a topic
space called Default.Topic.Space will already have been predefined during the
server installation but, if you require further topic spaces, you must create these
yourself. You do not need to predefine individual topics within a topic space, since
the server instantiates these dynamically as required.

The following steps summarize what you need to do but, for more details, see the
WebSphere Application Server Information Center.
1. Create the queues that your application needs for point-to-point messaging.
2. Create any additional topic spaces that your application needs for
publish/subscribe messaging.

Results

You can now start your application.

28 Message Service Client for C/C++

Chapter 6. Using the XMS sample applications
This chapter provides information about how to use the sample applications
provided with XMS.

About this task

This chapter contains the following sections:

v “The sample applications”
v “Running the sample applications” on page 30
v “Building the C or C++ sample applications” on page 31

The sample applications

The sample applications provide an overview of the common features of each API.
You can use them to verify your installation and messaging server setup and your
own applications.

These samples do not cover the whole of the API, but rather provide an overview
of how to use some of the most common features. They are subject to change in
future releases of XMS.

If you require guidance on how to create your own applications, use the sample
applications as a starting point. Look through the sample source code and identify
the key steps to create each required object for your application
(ConnectionFactory, Connection, Session, Destination, and a Producer, or a
Consumer, or both), and to set any specific properties that are needed to specify
how you want your application to work. For additional information, see Chapter 7,
“Writing XMS applications,” on page 35.

Table 4 shows the three sets of sample applications (one for each API) that are
supplied with XMS.
Table 4. XMS sample applications
Name of sample Description
SampleConsumerC A message consumer application that consumes messages from
a queue or topic.
SampleConsumerCPP
SampleProducerC A message producer application that produces messages to a
queue or on a topic.
SampleProducerCPP
SampleConfigC A configuration application that you can use to create a
file-based administered object repository containing a connection
factory and destination for your particular connection settings.
This administered object repository can then be used with each
of the sample consumer and producer applications.

The samples that support the same functionality in the various APIs have
syntactical differences.
v The sample message consumer and producer applications both support the
following:

© IBM Corporation 2005 29

 – Connections to WebSphere MQ, WebSphere Event Broker, WebSphere
Message Broker (using a real-time connection to a broker), and a WebSphere
service integration bus
– Administered object repository lookups via the initial context interface
– Connections to queues (WebSphere MQ and WebSphere service integration
bus) and topics (WebSphere MQ, real-time connection to a broker, and
WebSphere service integration bus)
– Base, bytes, map, object, stream, and text messages.
v The sample message consumer application supports synchronous and
asynchronous receive modes, and SQL Selector statements.
v The sample message producer application supports persistent and non-persistent
delivery modes.

Both the source and a compiled version are provided for each application.

Operating modes

The samples can operate in one of two modes:

v Simple mode - you can run the samples with the minimum user input.
v Advanced mode - you can customize more finely the way in which the samples
operate.

All the samples are compatible and can therefore operate across languages.

Where to find the samples

To find out where sample applications for Message Service Client for C/C++ are
installed:
v For AIX, Linux, and Solaris see Table 2 on page 20.
v For Windows, see Table 3 on page 21.

Running the sample applications

You can run the C and C++ sample applications interactively in either simple or
advanced mode, or noninteractively using auto-generated or custom response files.

Before you begin

Before running any of the supplied sample applications, you must first set up the
messaging server environment so that the applications can connect to a server as
described in Chapter 5, “Setting up the messaging server environment,” on page
25.

For C or C++ sample applications, you must have set up one of the following
environment variables:
v On AIX, the <install_dir>/lib directory on your LIBPATH
v On Linux and Solaris, the <install_dir>/lib directory on your
LD_LIBRARY_PATH
v On Windows, the <install_dir>\bin directory on your PATH

About this task

The operation of the C and C++ sample applications is identical for all platforms.

30 Message Service Client for C/C++

 Tip: When you are running a sample application, type ? at any time for help on
what to do next.

The following steps summarize what you need to do to run the C and C++ sample
applications.
1. Select the mode in which you want to run the sample application. Type either
Advanced or Simple.
2. Answer the questions. To select the default value, which is shown in the square
brackets at the end of the question, press Enter. To select a different value, type
the appropriate value, and press Enter.
Here is an example question:
Enter connection type [wpm]:
In this case, the default value is wpm (connection to a WebSphere service
integration bus).

Results

When you run the sample applications, response files are generated automatically
in the current working directory. Response file names are in the format
<connectiontype>-<sampletype>.rsp; (for example, wpm-producer.rsp). If required,
you can use a generated response file to rerun the sample application with the
same options, without re-entering these options manually.

Building the C or C++ sample applications

When you build a sample C or C++ application, an executable version is created.

Before you begin

To build the C or C++ samples, you must have the appropriate compiler installed
as described in “Operating environments” on page 13.

About this task

This section provides the information that you need to build the C and C++
applications.
1. Open a command prompt window.
2. Change to the directory that contains the source and makefile for the sample
application you want to build.
3. Type one of the following commands:
a. If you are using AIX, Linux, or Solaris type make.
b. If you are using Windows, type nmake.
The command builds an executable version of the application in the current
directory. This application has the same name as the folder; for example, if you
are building the C version of the sample message producer application,
SampleProducerC.exe is created in the SampleProducerC folder.
4. Before running the samples, make sure that the directory where you have
installed XMS is specified by the appropriate environment variable:
a. On AIX, the <install_dir>/lib directory must be in the path specified by the
LIBPATH environment variable.
b. On Linux and Solaris, the <install_dir>/lib directory must be in the path
specified by the LD_LIBRARY_PATH environment variable.

Chapter 6. Using the XMS sample applications 31

 c. On Windows, the <install_dir>\bin directory must be in the path specified
by the PATH environment variable.
Note: If the application is built in 64bit mode then on Windows
<install_dir>/bin64 should be added to the PATH environment variable, in
place of <install_dir>/bin and on all other platforms <install_dir>/lib64 should
be added to the appropriate environment variable, in place of <install_dir>/lib.

32 Message Service Client for C/C++

Part 2. Developing XMS applications
Chapter 7. Writing XMS applications . . . . . . . . . . . . . . . . . . . . . . . . . . 35
The threading model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
ConnectionFactories and Connection objects . . . . . . . . . . . . . . . . . . . . . . . . 36
Connection started and stopped mode . . . . . . . . . . . . . . . . . . . . . . . . . 36
Connection closure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Connection to a WebSphere service integration bus . . . . . . . . . . . . . . . . . . . . . 37
Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Transacted sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Message acknowledgement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Asynchronous message delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Synchronous message delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Message delivery mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Topic uniform resource identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Queue uniform resource identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Temporary destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Message producers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Message producers with no associated destination . . . . . . . . . . . . . . . . . . . . . 46
Message producers with associated destination . . . . . . . . . . . . . . . . . . . . . . 46
Message consumers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Durable subscribers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Non-durable subscribers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Synchronous message consumers . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Asynchronous message consumers . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Poison messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Handling poison messages in ASF . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Queue browsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Requestors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Object Deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
XMS primitive types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Implicit conversion of a property value from one data type to another . . . . . . . . . . . . . . . 52
Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Coded character set identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
XMS error and exception codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Building your own applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Network stack selection mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Chapter 8. Writing XMS applications in C . . . . . . . . . . . . . . . . . . . . . . . . 63

Object handles in C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Object Properties in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
C functions that return a string by value . . . . . . . . . . . . . . . . . . . . . . . . . 64
C functions that return a byte array by value . . . . . . . . . . . . . . . . . . . . . . . . 65
C functions that return a string or byte array by reference . . . . . . . . . . . . . . . . . . . . 66
C functions that accept a string as input . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Error handling in C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
The error block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Message and exception listener functions in C . . . . . . . . . . . . . . . . . . . . . . . . 68
Message listener functions in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Exception listener functions in C . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Chapter 9. Writing XMS applications in C++ . . . . . . . . . . . . . . . . . . . . . . . 71

Namespaces in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
String objects in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
C++ methods that return a byte array . . . . . . . . . . . . . . . . . . . . . . . . . . 72

© Copyright IBM Corp. 2005, 2009 33

Properties in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Assignment of XMS objects to variables in C++ . . . . . . . . . . . . . . . . . . . . . . . 73
Error handling in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Message and exception listeners in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Message listeners in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Exception listeners in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Use of C APIs in a C++ application . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Chapter 10. Working with administered objects . . . . . . . . . . . . . . . . . . . . . . 83

Supported types of administered object repository . . . . . . . . . . . . . . . . . . . . . . 83
Property mapping for administered objects . . . . . . . . . . . . . . . . . . . . . . . . . 84
Required properties for administered ConnectionFactory objects . . . . . . . . . . . . . . . . . . 84
Required properties for administered Destination objects . . . . . . . . . . . . . . . . . . . . 85
Creating administered objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
InitialContext objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
InitialContext properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
URI format for XMS initial contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
JNDI Lookup Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Retrieval of administered objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Chapter 11. Securing communications for XMS applications . . . . . . . . . . . . . . . . . . 91

Secure connections to a WebSphere MQ queue manager . . . . . . . . . . . . . . . . . . . . 91
CipherSuite and CipherSpec name mappings for connections to a WebSphere MQ queue manager . . . . . . 92
Secure connections to a WebSphere service integration bus messaging engine . . . . . . . . . . . . . 93
CipherSuite and CipherSpec name mappings for connections to a WebSphere service integration bus . . . . 94

Chapter 12. XMS messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Parts of an XMS message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Header fields in an XMS message . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Properties of an XMS message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
JMS-defined properties of a message . . . . . . . . . . . . . . . . . . . . . . . . . . 99
IBM-defined properties of a message . . . . . . . . . . . . . . . . . . . . . . . . . 100
Application-defined properties of a message . . . . . . . . . . . . . . . . . . . . . . . 101
The body of an XMS message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Data types for elements of application data . . . . . . . . . . . . . . . . . . . . . . . 102
Bytes messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Map messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Object messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Stream messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Text messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Message selectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Mapping XMS messages onto WebSphere MQ messages . . . . . . . . . . . . . . . . . . . . 107

34 Message Service Client for C/C++

Chapter 7. Writing XMS applications
This chapter provides information to help you when writing XMS applications.

About this task

The information in this chapter applies to C and C++ applications.

If you are writing applications in C, see also Chapter 8, “Writing XMS applications
in C,” on page 63. If you are writing applications in C++, see also Chapter 9,
“Writing XMS applications in C++,” on page 71.

This chapter contains the following sections:

v “The threading model”
v “ConnectionFactories and Connection objects” on page 36
v “Sessions” on page 38
v “Destinations” on page 42
v “Message producers” on page 46
v “Message consumers” on page 46
v “Queue browsers” on page 50
v “Requestors” on page 51
v “Object Deletion” on page 51
v “XMS primitive types” on page 52
v “Implicit conversion of a property value from one data type to another” on page
52
v “Iterators” on page 54
v “Coded character set identifiers” on page 56
v “XMS error and exception codes” on page 58
v “Building your own applications” on page 58
v “Network stack selection mechanism” on page 58

The threading model

General rules govern how a multithreaded application can use XMS objects.
v Only objects of the following types can be used concurrently on different
threads:
– ConnectionFactory
– Connection
– ConnectionMetaData
– Destination
v A Session object can be used on only a single thread at any one time.

Exceptions to these rules are indicated by entries labelled “Thread context” in the
interface definitions of the methods in the API reference chapters.

© IBM Corporation 2005 35

ConnectionFactories and Connection objects
A ConnectionFactory object provides a template that an application uses to create a
Connection object. The application uses the Connection object to create a Session
object.

For C and C++ applications a single type of ConnectionFactory has a property that
enables you to select which type of protocol you want to use for a connection.

An XMS application can create multiple connections, and a multithreaded

application can use a single Connection object concurrently on multiple threads. A
Connection object encapsulates a communications connection between an
application and a messaging server.

A connection serves several purposes:

v When an application creates a connection, the application can be authenticated.
v An application can associate a unique client identifier with a connection. The
client identifier is used to support durable subscriptions in the
publish/subscribe domain. The client identifier can be set in two ways:
The preferred way of assigning a connection’s client identifier is to configure in
a client-specific ConnectionFactory object using properties and transparently
assign it to the connection it creates.
An alternative way of assigning a client identifier is to use a provider-specific
value that is set on the Connection object. This value does not override the
identifier that has been administratively configured. It is provided for the case
where no administratively specified identifier exists. If an administratively
specified identifier does exist, an attempt to override it with a provider-specific
value causes an exception to be thrown. If an application explicitly sets an
identifier, it must do this immediately after creating the connection and before
any other action on the connection is taken; otherwise, an exception is thrown.
v A C application can register an exception listener function and context data with
a connection. A C++ application can register an exception listener with a
connection.

An XMS application typically creates a connection, one or more sessions, and a

number of message producers and message consumers.

Creating a connection is relatively expensive in terms of system resources because

it involves establishing a communications connection, and it might also involve
authenticating the application.

Connection started and stopped mode

A connection can operate in either started or stopped mode.

When an application creates a connection, the connection is in stopped mode.

When the connection is in stopped mode, the application can initialize sessions,
and it can send messages but cannot receive them, either synchronously or
asynchronously.

An application can start a connection by calling the Start Connection method.

When the connection is in started mode, the application can send and receive
messages. The application can then stop and restart the connection by calling the
Stop Connection and Start Connection methods.

36 Message Service Client for C/C++

Connection closure
An application closes a connection by calling the Close Connection method.

When an application closes a connection, XMS performs the following actions:

v It closes all the sessions associated with the connection and deletes certain
objects associated with these sessions. For more information about which objects
are deleted, see “Object Deletion” on page 51. At the same time, XMS rolls back
any transactions currently in progress within the sessions.
v It ends the communications connection with the messaging server.
v It releases the memory and other internal resources used by the connection.

XMS does not acknowledge the receipt of any messages that it has failed to
acknowledge during a session, prior to closing the connection. For more
information about acknowledging the receipt of messages, see “Message
acknowledgement” on page 39.

Exception Handling
If a C application registers an exception listener function and context data with a
connection, or if a C++ application registers an exception listener with a
connection, XMS notifies the application asynchronously when a serious problem
occurs with the connection.

XMS notifies a C application by calling the exception listener function, passing a

pointer to the context data as one parameter and the handle for the error block as
the other parameter. XMS notifies a C++ application by calling the onException()
method of the exception listener, passing a pointer to the exception as a parameter.

If an application uses a connection only to consume messages asynchronously it

learns about a problem with the connection only by using an exception listener.

For more information about using exception listener functions in a C application,

see “Exception listener functions in C” on page 69. If you are using C++, see
“Exception listeners in C++” on page 80.

Connection to a WebSphere service integration bus

An XMS application can connect to a WebSphere service integration bus either by
using a direct TCP/IP connection or by using HTTP over TCP/IP.

The HTTP protocol can be used in situations where a direct TCP/IP connection is
not possible. One common situation is when communicating through a firewall,
such as when two enterprises exchange messages. Using HTTP to communicate
through a firewall is often referred to as HTTP tunnelling. HTTP tunnelling,
however, is inherently slower than using a direct TCP/IP connection because
HTTP headers add significantly to the amount of data that is transferred, and
because the HTTP protocol requires more communication flows than TCP/IP.

To create a TCP/IP connection, an application can use a connection factory whose

XMSC_WPM_TARGET_TRANSPORT_CHAIN property is set to
XMSC_WPM_TARGET_TRANSPORT_CHAIN_BASIC. This is the default value of
the property. If the connection is created successfully, the
XMSC_WPM_CONNECTION_PROTOCOL property of the connection is set to
XMSC_WPM_CP_TCP.

Chapter 7. Writing XMS applications 37

 To create a connection that uses HTTP, an application must use a connection
factory whose XMSC_WPM_TARGET_TRANSPORT_CHAIN property is set to the
name of an inbound transport chain that is configured to use an HTTP transport
channel. If the connection is created successfully, the
XMSC_WPM_CONNECTION_PROTOCOL property of the connection is set to
XMSC_WPM_CP_HTTP. For information about how to configure transport chains,
see the WebSphere Application Server Version 6.0x Information Center.

An application has a similar choice of communication protocols when connecting

to a bootstrap server. The XMSC_WPM_PROVIDER_ENDPOINTS property of a
connection factory is a sequence of one or more endpoint addresses of bootstrap
servers. The bootstrap transport chain component of each endpoint address can be
either XMSC_WPM_BOOTSTRAP_TCP, for a TCP/IP connection to a bootstrap
server or XMSC_WPM_BOOTSTRAP_HTTP, for a connection that uses HTTP.

Sessions
A session is a single threaded context for sending and receiving messages.

An application can use a session to create messages, message producers, message

consumers, queue browsers, and temporary destinations. An application can also
use a session to run local transactions.

An application can create multiple sessions, where each session produces and
consumes messages independently of the other sessions. If two message consumers
in separate sessions (or even in the same session) subscribe to the same topic, each
receives a copy of any message published on that topic.

Unlike a Connection object, a Session object cannot be used concurrently on

different threads. Only the Close Session method of a Session object can be called
from a thread other than the one that the Session object is using at the time. The
Close Session method ends a session and releases any system resources allocated to
the session.

If an application must process messages concurrently on more than one thread, the
application must first create the additional threads, and then use a different session
on each thread.

Transacted sessions
XMS applications can run local transactions. A local transaction is a transaction that
involves changes only to the resources of the queue manager or service integration
bus to which the application is connected.

The information in this section is relevant only if an application connects to a

WebSphere MQ queue manager or a WebSphere service integration bus. The
information is not relevant for a real-time connection to a broker.

To run local transactions, an application must first create a transacted session by

calling the Create Session method of a Connection object, specifying as a parameter
that the session is transacted. Subsequently, all messages sent and received within
the session are grouped into a sequence of transactions. A transaction ends when
the application commits or rolls back the messages it has sent and received since
the transaction began.

38 Message Service Client for C/C++

 To commit a transaction, an application calls the Commit method of the Session
object. When a transaction is committed, all messages sent within the transaction
become available for delivery to other applications, and all messages received
within the transaction are acknowledged so that the messaging server does not
attempt to deliver them to the application again. In the point-to-point domain, the
messaging server also removes the received messages from their queues.

To roll back a transaction, an application calls the Rollback method of the Session
object. When a transaction is rolled back, all messages sent within the transaction
are discarded by the messaging server, and all messages received within the
transaction become available for delivery again. In the point-to-point domain, the
messages that were received are put back on their queues and become visible to
other applications again.

A new transaction starts automatically when an application creates a transacted

session or calls the Commit or Rollback method. Therefore, a transacted session
always has an active transaction.

When an application closes a transacted session, an implicit rollback occurs. When

an application closes a connection, an implicit rollback occurs for all the
connection’s transacted sessions.

A transaction is wholly contained within a transacted session. A transaction cannot

span sessions. This means that it is not possible for an application to send and
receive messages in two or more transacted sessions and then commit or roll back
all these actions as a single transaction.

Message acknowledgement
Every session that is not transacted has an acknowledgement mode that
determines how messages received by the application are acknowledged. Three
acknowledgement modes are available, and the choice of acknowledgement mode
affects the design of the application.

The information in this section is relevant only if an application connects to a

WebSphere MQ queue manager or a WebSphere service integration bus. The
information is not relevant for a real-time connection to a broker.

XMS uses the same mechanism for acknowledging the receipt of messages that
JMS uses.

If a session is not transacted, the way that messages received by the application are
acknowledged is determined by the acknowledgement mode of the session. The
three acknowledgement modes are described in the following paragraphs:
XMSC_AUTO_ACKNOWLEDGE
The session automatically acknowledges each message received by the
application.
If messages are delivered synchronously to the application, the session
acknowledges receipt of a message every time a Receive call completes
successfully. If messages are delivered asynchronously to a C application,
the session acknowledges receipt of a message every time a call to a
message listener function completes successfully. For a C++ application, the
session acknowledges receipt of a message every time a call to the
onMessage() method of a message listener completes successfully.

Chapter 7. Writing XMS applications 39

 If the application receives a message successfully, but a failure prevents
acknowledgement from occurring, the message becomes available for
delivery again. The application must therefore be able to handle a message
that is re-delivered.
XMSC_DUPS_OK_ACKNOWLEDGE
The session acknowledges the messages received by the application at
times it selects.
Using this acknowledgement mode reduces the amount of work the
session must do, but a failure that prevents message acknowledgement
might result in more than one message becoming available for delivery
again. The application must therefore be able to handle messages that are
re-delivered.

Restriction: In AUTO_ACKNOWLEDGE and

DUPS_OK_ACKNOWLEDGE modes, XMS C/C++ does not
support an application throwing an unhandled exception in a
message listener. This means that messages are always
acknowledged when the message listener returns, regardless
of whether it was processed successfully (provided any
failures are non-fatal and do not prevent the application from
continuing). If you require finer control of message
acknowledgement, use the CLIENT_ACKNOWLEDGE or
transacted modes, which give the application full control of
the acknowledgement functions.
XMSC_CLIENT_ACKNOWLEDGE
The application acknowledges the messages it receives by calling the
Acknowledge method of the Message class.
The application can acknowledge the receipt of each message individually,
or it can receive a batch of messages and call the Acknowledge method
only for the last message it receives. When the Acknowledge method is
called all messages received since the last time the method was called are
acknowledged.

In conjunction with any of these acknowledgement modes, an application can stop

and restart the delivery of messages in a session by calling the Recover method of
the Session class. Messages whose receipt was previously unacknowledged are
re-delivered. However, they might not be delivered in the same sequence in which
they were previously delivered. In the meantime, higher priority messages might
have arrived, and some of the original messages might have expired. In the
point-to-point domain, some of the original messages might have been consumed
by another application.

An application can determine whether a message is being re-delivered by

examining the contents of the JMSRedelivered header field of the message. The
application does this by calling the Get JMSRedelivered method of the Message
class.

Asynchronous message delivery

If a C application registers a message listener function and context data with a
message consumer, or if a C++ application registers a message listener with a
message consumer, the application can receive messages asynchronously.

40 Message Service Client for C/C++

 When a message arrives for a message consumer, XMS delivers the message to a C
application by calling the message listener function, passing a pointer to the
context data as one parameter and the handle for the message as the other
parameter.XMS delivers the message to a C++ application by calling the
onMessage() method of the message listener, passing a pointer to the message as a
parameter.

XMS uses one thread to handle all asynchronous message delivery for a session.
This means that only one message listener function or one onMessage() method
can run at a time. If more than one message consumer in a session is receiving
messages asynchronously, and a message listener function or onMessage() method
is currently delivering a message to one message consumer, then any other
message consumers that are waiting for the same message must continue to wait.
Other messages that are waiting to be delivered to the session must also continue
to wait.

If an application requires concurrent delivery of messages, it must create more than

one session, so that XMS uses more than one thread to handle asynchronous
message delivery. In this way, more than one message listener function or
onMessage() method can run concurrently.

If an application requires concurrent delivery of messages, it must create more than

one session, so that XMS uses more than one thread to handle asynchronous
message delivery. In this way, more than one message listener function or
onMessage() method can run concurrently

For more information about using message listener functions in a C application,

see “Message listener functions in C” on page 68. If you are using C++, see
“Message listeners in C++” on page 78.

Synchronous message delivery

Messages are delivered synchronously to an application if the application uses the
Receive methods of MessageConsumer objects.

Using the Receive methods, an application can wait a specified period of time for a
message, or it can wait indefinitely. Alternatively, if an application does not want
to wait for a message, it can use the Receive with No Wait method.

Message delivery mode

XMS supports two modes of message delivery.
v Persistent messages are delivered once and once only. A messaging server takes
special precautions, such as logging the messages, to ensure that persistent
messages are not lost in transit, even in the event of a failure.
v Nonpersistent messages are delivered no more than once. Nonpersistent messages
are less reliable than persistent messages because they can be lost in transit in
the event of a failure.

The choice of delivery mode is a trade-off between reliability and performance.

Nonpersistent messages are typically transported more quickly than persistent
messages.

Chapter 7. Writing XMS applications 41

Destinations
An XMS application uses a Destination object to specify the destination of
messages that are being sent, and the source of messages that are being received.

An XMS application can either create a Destination object at run time, or obtain a
predefined destination from the repository of administered objects.

As with a ConnectionFactory, the most flexible way for an XMS application to

specify a destination is to define it as an administered object. Using this approach,
applications written in C and C++ languages, as well as Java, can share the same
definition of the destination. The properties of administered Destination objects can
be changed without changing any code.

You can create a destination for a C or C++ application in either of the following
ways:
v By specifying a uniform resource identifier (URI), which is a string that identifies a
destination, you have the option to specify one or more properties of the
destination
v By specifying whether you require a queue or topic and providing a destination
name

For further information, see “Destination” on page 152 for C or “Destination” on

page 293 for C++.

For further information about creating a URI, see “Topic uniform resource
identifiers” and “Queue uniform resource identifiers” on page 44.

Topic uniform resource identifiers

The topic uniform resource identifier (URI) specifies the name of the topic; it can
also specify one or more properties for it.

The URI for a topic begins with the sequence topic://, followed by the name of
the topic and (optional) a list of name-value pairs that set the remaining topic
properties. A topic name cannot be empty.

Here is an example in a fragment of C++ code:

topic = session.createTopic("topic://Sport/Football/Results?multicast=7");

For more information about the properties of a topic, including the name and valid
values that you can use in a URI, see “Properties of Destination” on page 409.

When specifying a topic URI for use in a subscription, wildcards can be used. The
syntax for these wildcards depends on the connection type and broker version; the
following options are available:
v WebSphere MQ V7.0 queue manager with Character level wildcard format
v WebSphere MQ V7.0 queue manager with Topic level wild card format
v WebSphere MQ V6.0 queue manager with broker V1 (WebSphere MQ V6.0
Publish/Subscribe)
v WebSphere MQ V6.0 with, or real-time connection to, broker V2 (WebSphere
Event Broker or WebSphere Message Broker)
v WebSphere service integration bus

42 Message Service Client for C/C++

 WebSphere MQ V7.0 queue manager with Character level
wildcard format

WebSphere MQ V7.0 queue manager with Character level wildcard format uses the
following wild card characters:
* for 0 or more characters
? for 1 character
% for an escape character

Table 5 gives some examples of how to use this wildcard scheme.

Table 5. Example URIs using character level wildcard scheme for WebSphere MQ V7.0 queue manager
Uniform Resource Identifier Matches Examples
″topic://Sport*Results″ All topics starting with ″Sport″ ″topic://SportsResults″ and ″topic://Sport/
and ending in ″Results″ Hockey/National/Div3/Results″
″topic://Sport?Results″ All topics starting with ″Sport″ ″topic://SportsResults″ and ″topic://
followed by a single character, SportXResults″
followed by ″Results″
″topic://Sport/*ball*/Div?/ Topics ″topic://Sport/Football/Div1/Results/2002/Nov″
Results/*/???″ and ″topic://Sport/Netball/National/Div3/
Results/02/Jan″

WebSphere MQ V7.0 queue manager with Topic level wild card

format

WebSphere MQ V7.0 queue manager with Topic level wild card format uses the
following wildcard characters:
# to match multiple levels
+ to match a single level
Table 6 gives some examples of how to use this wildcard scheme.
Table 6. Example URIs using topic level wildcard scheme for WebSphere MQ V7.0 queue manager
Uniform Resource
Identifier Matches Examples
″topic://Sport/+/Results″ All topics with a single hierarchical level ″topic://Sport/Football/Results″ and
name between Sport and Results ″topic://Sport/Ju-Jitsu/Results″
″topic://Sport/#/Results″ All topics starting with ″Sport/″ and ″topic://Sport/Football/Results″ and
ending in ″/Results″ ″topic://Sport/Hockey/National/Div3/
Results″
″topic://Sport/Football/#″ All topics starting with ″Sport/Football/″ ″topic://Sport/Football/Results″ and
″topic://Sport/Football/TeamNews/
Signings/Managerial″

WebSphere MQ V6.0 queue manager with broker V1

WebSphere MQ V6.0 queue manager with broker V1 uses the following wildcard
characters:
* for 0 or more characters
? for 1 character
% for an escape character

Chapter 7. Writing XMS applications 43

 Table 5 on page 43 gives some examples of how to use this wildcard scheme.

WebSphere MQ V6.0 with, or real-time connection to, a broker V2

WebSphere MQ V6.0 with, or real-time connection to, a broker V2 uses the

following wildcard characters:
# to match multiple levels
+ to match a single level

Table 6 on page 43 gives some examples of how to use this wildcard scheme.

WebSphere service integration bus

WebSphere MQ with, or real-time connection to, a broker V2 uses the following

wildcard characters:
* to match any characters at one level in the hierarchy
// to match 0 or more levels
//. to match 0 or more levels (at the end of a Topic expression)

Table 7 gives some examples of how to use this wildcard scheme.

Table 7. Example URIs using wildcard scheme for WebSphere service integration bus
Uniform Resource
Identifier Matches Examples
″topic://Sport/*ball/ All topics with a single hierarchical level ″topic://Sport/Football/Results″ and
Results″ name ending in ″ball″ between Sport and ″topic://Sport/Netball/Results″
Results
″topic://Sport// All topics starting with ″Sport/″ and ″topic://Sport/Football/Results″ and
Results″ ending in ″/Results″ ″topic://Sport/Hockey/National/Div3/
Results″
″topic://Sport/ All topics starting with ″Sport/Football/″ ″topic://Sport/Football/Results″ and
Football//.″ ″topic://Sport/Football/TeamNews/
Signings/Managerial″
″topic://Sport/*ball// Topics ″topic://Sport/Football/Results″ and
Results//.″ ″topic://Sport/Netball/National/Div3/
Results/2002/November″

Queue uniform resource identifiers

The URI for a queue specifies the name of the queue; it can also specify one or
more properties of the queue.

The URI for a queue begins with the sequence queue://, followed by the name of
the queue; it might also include a list of name-value pairs that set the remaining
queue properties.

For WebSphere MQ queues (but not for WebSphere Application Server default
messaging provider queues), the queue manager on which the queue resides may
be specified before the queue, with a / separating the queue manager name from
the queue name.

If a queue manager is specified, then it must be the one to which XMS is directly
connected for the connection using this queue, or it must be accessible from this
queue. Remote queue managers are only supported for retrieving messages from

44 Message Service Client for C/C++

 queues, not for putting messages onto queues. For full details, refer to the
WebSphere MQ queue manager documentation.

If no queue manager is specified, then the extra / separator is optional, and its
presence or absence makes no difference to the definition of the queue.

The following queue definitions are all equivalent for a WebSphere MQ queue
called QB on a queue manager called QM_A, to which XMS is directly connected:
queue://QB
queue:///QB
queue://QM_A/QB

The following is an example of queue definitions for C++:

ioQueue = session.createQueue("queue:///SYSTEM.DEFAULT.LOCAL.QUEUE");

The name of the queue manager is omitted. This is interpreted as the queue
manager to which the owning connection is connected at the time when the Queue
object is used.

The following example of C code connects to queue Q1 on queue manager

HOST1.QM1, and causes all messages to be sent as nonpersistent and priority 5
messages:
rc = xmsDestCreate(
"queue://HOST1.QM1/Q1?persistence=1&priority=5",
&ioQueue);

Temporary destinations
XMS applications can create and use temporary destinations.

An application typically uses a temporary destination to receive replies to request

messages. To specify the destination where a reply to a request message is to be
sent, an application calls the Set JMSReplyTo method of the Message object
representing the request message. The destination specified on the call can be a
temporary destination.

To create a temporary destination, a C application calls the

xmsDestCreateTemporaryByType() function. As parameters on the call, the
application specifies the handle for the session in which the temporary destination
is being created and the type of temporary destination, which is either a queue or
a topic.

A C++ application creates a temporary queue by calling the

createTemporaryQueue() method of a Session object, and it creates a temporary
topic by calling the createTemporaryTopic() method of a Session object.

Although a session is used to create a temporary destination, the scope of a

temporary destination is actually the connection that was used to create the
session. Any of the connection’s sessions can create message producers and
message consumers for the temporary destination. The temporary destination
remains until it is explicitly deleted, or the connection ends, whichever happens
first.

When an application creates a temporary queue, a queue is created in the

messaging server to which the application is connected. If the application is
connected to a queue manager, a dynamic queue is created from the model queue
whose name is specified by the XMSC_WMQ_TEMPORARY_MODEL property,

Chapter 7. Writing XMS applications 45

 and the prefix that is used to form the name of the dynamic queue is specified by
the XMSC_WMQ_TEMP_Q_PREFIX property. If the application is connected to a
service integration bus, a temporary queue is created in the bus, and the prefix that
is used to form the name of the temporary queue is specified by the
XMSC_WPM_TEMP_Q_PREFIX property.

When an application that is connected to a service integration bus creates a

temporary topic, the prefix that is used to form the name of the temporary topic is
specified by the XMSC_WPM_TEMP_TOPIC_PREFIX property.

Message producers
In XMS, a message producer can be created either with a valid destination or with
no associated destination. When creating a message producer with a null
destination, a valid destination needs to be specified when sending a message.

Message producers with no associated destination

In the C and C++ API, a message producer can be created with a null destination.

In the C API, NULL can be passed into the xmsSessCreateProducer() function, to

create a message producer with no associated destination. In this case, the
destination must be specified when the message is sent. For further details about
creating a message producer in a C API, see “Session” on page 243.

To create a message producer with no associated destination when using the C++
API, a default xms::Destination object created using the default constructor must be
passed into the Session::createProducer() method. For further details about creating
a message producer in a C++ API, see “Session” on page 373.

Message producers with associated destination

In this scenario, the message producer is created using a valid destination. During
the send operation, the destination need not be specified.

Message consumers
Message consumers can be classified as durable and non-durable subscribers and
synchronous and asynchronous message consumers.

Durable subscribers
A durable subscriber is a message consumer that receives all messages published
on a topic, including those published while the subscriber is inactive.

The information in this section is relevant only if an application connects to a

WebSphere MQ queue manager or a WebSphere service integration bus. The
information is not relevant for a real-time connection to a broker.

To create a durable subscriber for a topic, an application calls the Create Durable
Subscriber method of a Session object, specifying as parameters a name that
identifies the durable subscription and a Destination object representing the topic.
The application can create a durable subscriber with or without a message selector,
and it can specify whether the durable subscriber is to receive messages published
by its own connection.

46 Message Service Client for C/C++

The session used to create a durable subscriber must have an associated client
identifier. The client identifier is the same as that associated with the connection
that is used to create the session; it is specified as described in
“ConnectionFactories and Connection objects” on page 36.

The name that identifies the durable subscription must be unique within the client
identifier, and therefore the client identifier forms part of the full, unique identifier
of the durable subscription. The messaging server maintains a record of the
durable subscription and ensures that all messages published on the topic are
retained until they are acknowledged by the durable subscriber or they expire.

The messaging server continues to maintain the record of the durable subscription
even after the durable subscriber closes. To reuse a durable subscription that was
created previously, an application must create a durable subscriber specifying the
same subscription name, and using a session with the same client identifier, as
those associated with the durable subscription. Only one session at a time can have
a durable subscriber for a particular durable subscription.

The scope of a durable subscription is the messaging server that is maintaining a

record of the subscription. If two applications connected to different messaging
servers each create a durable subscriber using the same subscription name and
client identifier, two completely independent durable subscriptions are created.

To delete a durable subscription, an application calls the Unsubscribe method of a

Session object, specifying as a parameter the name that identifies the durable
subscription. The client identifier associated with the session must be the same as
that associated with the durable subscription. The messaging server deletes the
record of the durable subscription that it is maintaining and does not send any
more messages to the durable subscriber.

To change an existing subscription, an application can create a durable subscriber

using the same subscription name and client identifier, but specifying a different
topic, or message selector (or both). Changing a durable subscription is equivalent
to deleting the subscription and creating a new one.

For an application that connects to WebSphere MQ v7.0 queue manager, XMS

manages the subscriber queues. Hence the application is not required to specify a
subscriber queue. XMS will ignore the subscriber queue if specified.

However for an application that connects to WebSphere MQ v6.0 queue manager,

each durable subscriber must have a designated subscriber queue. To specify the
name of the subscriber queue for a topic, set the XMSC_WMQ_DUR_SUBQ
property of the Destination object representing the topic. The default subscriber
queue is SYSTEM.JMS.D.SUBSCRIBER.QUEUE.

Durable subscribers connecting to WebSphere MQ v6.0 queue managers can share

a single subscriber queue, or each durable subscriber can retrieve its messages
from its own exclusive subscriber queue. For a discussion about which approach to
adopt for your application, see WebSphere MQ Using Java.

Note that you cannot change the subscriber queue for a durable subscription. The
only way to change the subscriber queue is to delete the subscription and create a
new one.

For an application that connects to a service integration bus, each durable

subscriber must have a designated durable subscription home. To specify the

Chapter 7. Writing XMS applications 47

 durable subscription home for all durable subscribers that use the same
connection, set the XMSC_WPM_DUR_SUB_HOME property of the
ConnectionFactory object that is used to create the connection. To specify the
durable subscription home for an individual topic, set the
XMSC_WPM_DUR_SUB_HOME property of the Destination object representing
the topic. A durable subscription home must be specified for a connection before
an application can create a durable subscriber that uses the connection. Any value
specified for a destination overrides the value specified for the connection.

Non-durable subscribers
A non-durable subscriber is a message consumer that only receives messages that
are published while the subscriber is active. Messages delivered while the
subscriber is inactive are lost.

The information in this section is relevant only when you are using
publish/subscribe messaging over WebSphere MQ v6.0 queue manager.

If consumer objects are not deleted before or during the closing of the connection,
messages can be left on the broker queues for subscribers that are no longer active.

In this situation, the queues can be cleared of these messages using the Cleanup
utility provided with WebSphere MQ Classes for JMS. Details of how to use this
utility are provided in WebSphere MQ Using Java. You may also need to increase the
queue depth of the subscriber queue if there are large numbers of messages left on
this queue.

Synchronous message consumers

The synchronous message consumer receives the messages from a queue
synchronously.

A synchronous message consumer receives one message at a time. When the

Receive(with a wait interval) method is used; the call waits only a specified period
of time in milliseconds for a message, or until the message consumer is closed.

If the Receive with No Wait method is used, the synchronous message consumer
receives messages without any delay; if the next message is available, it is received
immediately, otherwise a pointer to a null Message object is returned.

Asynchronous message consumers

The asynchronous message consumer receives message from a queue
asynchronously. The message listener registered by the application is invoked
whenever a new message is available on the queue.

Poison messages
A poison message is one which cannot be processed by a receiving MDB
application. If a poison message is encountered, the XMS MessageConsumer object
can requeue it according to two queue properties, BOQUEUE, and BOTHRESH.

In some circumstances, a message delivered to an MDB might be rolled back onto

a WebSphere MQ queue. This can happen, for example, if a message is delivered
within a unit of work that is subsequently rolled back. A message that is rolled
back is generally delivered again, but a badly formatted message might repeatedly
cause an MDB to fail and therefore cannot be delivered. Such a message is called a
poison message. You can configure WebSphere MQ so that the poison message is

48 Message Service Client for C/C++

automatically transferred to another queue for further investigation or is discarded.
For information about how to configure WebSphere MQ in this way, see Handling
poison messages in ASF.

Sometimes, a badly-formatted message arrives on a queue. In this context,

badly-formatted means that the receiving application cannot process the message
correctly. Such a message can cause the receiving application to fail and to back
out this badly-formatted message. The message can then be repeatedly delivered to
the input queue and repeatedly backed out by the application. These messages are
known as poison messages. The XMS MessageConsumer object detects poison
messages and reroutes them to an alternative destination.

The WebSphere MQ queue manager keeps a record of the number of times that
each message has been backed out. When this number reaches a configurable
threshold value, the message consumer requeues the message to a named backout
queue. If this re-queuing fails for any reason, the message is removed from the
input queue and either requeued to the dead-letter queue, or discarded.

XMS ConnectionConsumer objects handle poison messages in the same way and
using the same queue properties. If multiple connection consumers are monitoring
the same queue, it is possible that the poison message may be delivered to an
application more times than the threshold value before the requeue occurs. This
behavior is due to the way individual connection consumers monitor queues and
requeue poison messages.

The threshold value and the name of the back out queue are attributes of a
WebSphere MQ queue. The names of the attributes are BackoutThreshold and
BackoutRequeueQName. The queue they apply to is as follows:
v For point-to-point messaging, this is the underlying local queue. This is
important when message consumers and connection consumers use queue
aliases.
v For publish/subscribe messaging in WebSphere MQ messaging provider normal
mode, it is the model queue from which the Topic’s managed queue is created.
v For publish/subscribe messaging in WebSphere MQ messaging provider
migration mode, it is the CCSUB queue defined on the TopicConnectionFactory
object, or the CCDSUB queue defined on the Topic object.

To set the BackoutThreshold and BackoutRequeueQName attributes, issue the

following MQSC command:
ALTER QLOCAL(your.queue.name) BOTHRESH(threshold value)
BOQUEUE(your.backout.queue.name)

For publish/subscribe messaging, if your system creates a dynamic queue for each
subscription, these attribute values are obtained from the WebSphere MQ classes
for JMS model queue, SYSTEM.JMS.MODEL.QUEUE. To alter these settings, use:
ALTER QMODEL(SYSTEM.JMS.MODEL.QUEUE) BOTHRESH(threshold value)
BOQUEUE(your.backout.queue.name)

If the backout threshold value is zero, poison message handling is disabled, and
poison messages remain on the input queue. Otherwise, when the backout count
reaches the threshold value, the message is sent to the named backout queue. If the
backout count reaches the threshold value, but the message cannot go to the
backout queue, the message is sent to the dead-letter queue or it is discarded. This
situation occurs if the backout queue is not defined, or if the MessageConsumer
object cannot send the message to the backout queue.

Chapter 7. Writing XMS applications 49

 Handling poison messages in ASF
When you use Application Server Facilities (ASF), the ConnectionConsumer, rather
than the MessageConsumer, processes poison messages. The ConnectionConsumer
requeues messages according to the BackoutThreshold and
BackoutRequeueQName properties of the queue.

When an application uses ConnectionConsumers, the circumstances in which a

message is backed out depend on the session that the application server provides:
v When the session is non-transacted, with AUTO_ACKNOWLEDGE or
DUPS_OK_ACKNOWLEDGE, a message is backed out only after a system error,
or if the application terminates unexpectedly.
v When the session is non-transacted with CLIENT_ACKNOWLEDGE,
unacknowledged messages can be backed out by the application server calling
Session.recover().
Typically, the client implementation of MessageListener or the application server
calls Message.acknowledge(). Message.acknowledge() acknowledges all messages
delivered on the session so far.
v When the session is transacted, unacknowledged messages can be backed out by
the application server calling Session.rollback().

Queue browsers
An application uses a queue browser to browse messages on a queue without
removing them.

To create a queue browser, an application calls the Create Queue Browser method
of a Session object, specifying as a parameter a Destination object that identifies the
queue to be browsed. The application can create a queue browser with or without
a message selector.

After creating a queue browser, the application can call the Get Messages method
of the QueueBrowser object to get a list of the messages on the queue. The list of
messages is returned as an iterator that encapsulates a list of Message objects. The
order of the Message objects in the list is the same as the order in which the
messages would be retrieved from the queue. The application can then use the
iterator to browse each message in turn.

The iterator is updated dynamically as messages are put on the queue and
removed from the queue. Each time the application uses the iterator to browse the
next message on the queue, the message returned reflects the current contents of
the queue. When the iterator indicates that there are no more messages on the
queue, it stops returning messages, even if further messages arrive on the queue.
However, by calling the Reset Iterator method of the Iterator object, the application
can continue to use the same iterator to browse messages, starting from the
beginning of the queue.

An application can call the Get Messages method more than once for a given
queue browser. Each call returns a new iterator. The application can therefore use
more than one iterator to browse the messages on a queue and maintain multiple
positions within the queue.

An application can use a queue browser to search for a suitable message to remove
from a queue, and then use a message consumer with a message selector to
remove the message. The message selector can select the message according to the

50 Message Service Client for C/C++

 value of the JMSMessageID header field. For information about this and other JMS
message header fields, see “Header fields in an XMS message” on page 97.

Requestors
An application uses a requestor to send a request message and then to wait for
and to receive the reply.

Many messaging applications are based on algorithms that send a request message
and then wait for a reply. XMS provides a class called Requestor to help with the
development of this style of application.

To create a requestor, an application calls the Create Requestor constructor of the

Requestor class, specifying as parameters a Session object and a Destination object
that identifies where request messages are to be sent. The session must not be
transacted nor have an acknowledgement mode of
XMSC_CLIENT_ACKNOWLEDGE. The constructor automatically creates a
temporary queue or topic where reply messages are to be sent.

After creating a requestor, the application can call the Request method of the
Requestor object to send a request message and then wait for, and receive, a reply
from the application that receives the request message. The call waits until the
reply is received or until the session ends, whichever occurs first. Only one reply is
required by the requestor for each request message.

When the application closes the requestor, the temporary queue or topic is deleted.
The associated session, however, does not close.

Object Deletion
When an application deletes an XMS object that it has created, XMS releases the
internal resources that have been allocated to the object.

When an application creates an XMS object, XMS allocates memory and other
internal resources to the object. XMS retains these internal resources until the
application explicitly deletes the object by calling the object’s close or delete
method, at which point XMS releases the internal resources. In a C++ application,
an object is also deleted when it goes out of scope. If an application tries to delete
an object that is already deleted, the call is ignored.

When an application deletes a Connection or Session object, XMS deletes certain

associated objects automatically and releases their internal resources. These are
objects that were created by the Connection or Session object and have no function
independent from the object. These objects are shown in Table 8. Note that, if an
application closes a connection with dependent sessions, all objects dependent on
those sessions are also deleted. Only a Connection or Session object can have
dependent objects.
Table 8. Objects that are deleted automatically
Deleted object Method Dependent objects that are deleted automatically
Connection Close Connection ConnectionMetaData and Session objects
Session Close Session MessageConsumer, MessageProducer,
QueueBrowser, and Requestor objects

Chapter 7. Writing XMS applications 51

XMS primitive types
XMS provides equivalents of the eight Java primitive types (byte, short, int, long,
float, double, char and boolean). This allows the interchange of messages between
XMS and JMS without data becoming lost or corrupted.

Table 9 lists the Java equivalent data type, size, and minimum and maximum value
of each XMS primitive type.
Table 9. XMS data types and their Java equivalents
Compatible
Java data
XMS data type type Size Minimum value Maximum value
xmsBOOL boolean 32 bits xmsFALSE xmsTRUE
7
xmsSBYTE byte 8 bits -2 (-128 ) 27-1 (127)
xmsCHAR byte 8 bits -27 (-128 ) 27-1 (127)
xmsCHAR16 char 16 bits 0 (\u0000) 216-1 (\uFFFF)
xmsSHORT short 16 bits -215 (-32768) 215-1 (32767)
xmsINT int 32 bits -231 (-2147483648) 231-1 (2147483647)
xmsLONG long 64 bits -263 (-9223372036854775808) 263-1 (9223372036854775807)
xmsFLOAT float 32 bits -3.402823E-38 (to 7 digits 3.402823E+38 (to 7 digits
precision) precision)
xmsDOUBLE double 64 bits -1.79769313486231E-308 (to 15 1.79769313486231E+308 (to 15
digits precision) digits precision)

Implicit conversion of a property value from one data type to another

When an application gets the value of a property, the value can be converted by
XMS into another data type. Many rules govern which conversions are supported
and how XMS performs the conversions.

A property of an object has a name and a value; the value has an associated data
type, where the value of a property is also referred to as the property type.

An application uses the methods of the PropertyContext class to get and set the
properties of objects. In order to get the value of a property, an application calls
the method that is appropriate for the property type. For example, to get the value
of an integer property, an application typically calls the Get Integer Property
method.

However, when an application gets the value of a property, the value can be
converted by XMS into another data type. For example, to get the value of an
integer property, an application can call the Get String Property method, which
returns the value of the property as a string. The conversions supported by XMS
are shown in Table 10.
Table 10. Supported conversions from a property type to other data types
Property type Supported target data types
String xmsBOOL, xmsDOUBLE, xmsFLOAT, xmsINT, xmsLONG,
xmsSBYTE, xmsSHORT
xmsBOOL String, xmsSBYTE, xmsINT, xmsLONG, xmsSHORT

52 Message Service Client for C/C++

Table 10. Supported conversions from a property type to other data types (continued)
Property type Supported target data types
xmsCHAR String
xmsDOUBLE String
xmsFLOAT String, xmsDOUBLE
xmsINT String, xmsLONG
xmsLONG String
xmsSBYTE String, xmsINT, xmsLONG, xmsSHORT
xmsSBYTE array String
xmsSHORT String, xmsINT, xmsLONG

The following general rules govern the supported conversions:

v Numeric property values can be converted from one data type to another
provided no data is lost during the conversion. For example, the value of a
property with data type xmsINT can be converted into a value with data type
xmsLONG, but it cannot be converted into a value with data type xmsSHORT.
v A property value of any data type can be converted into a string.
v A string property value can be converted to any other data type provided the
string is formatted correctly for the conversion. If an application attempts to
convert a string property value that is not formatted correctly, XMS may return
errors.
v If an application attempts a conversion that is not supported, XMS may return
an error.

The following rules apply when a property value is converted from one data type
to another:
v When converting a boolean property value to a string, the value xmsTRUE is
converted to the string “true”, and the value false is converted to the string
“false”.
v When converting a boolean property value to a numeric data type, including
xmsSBYTE, the value xmsTRUE is converted to 1, and the value xmsFALSE is
converted to 0.
v When converting a string property value to a boolean value, the string “true”
(not case sensitive) or “1” is converted to xmsTRUE, and the string “false” (not
case sensitive) or “0” is converted to xmsFALSE. All other strings cannot be
converted.
v When converting a string property value to a value with data type xmsINT,
xmsLONG, xmsSBYTE, or xmsSHORT, the string must have the following
format:
[blanks][sign]digits
The string components are defined as follows:
blanks Optional leading blank characters.
sign An optional plus sign (+) or minus sign (-) character.
digits A contiguous sequence of digit characters (0-9). At least one digit
character must be present.

Chapter 7. Writing XMS applications 53

 After the sequence of digit characters, the string can contain other characters
that are not digit characters, but the conversion stops as soon as the first of these
characters is reached. The string is assumed to represent a decimal integer.
XMS may return an error if the string is not formatted correctly.
v When converting a string property value to a value with data type xmsDOUBLE
or xmsFLOAT, the string must have the following format:
[blanks][sign][digits][point[d_digits]][e_char[e_sign]e_digits]
The string components are defined as follows:
blanks (Optional) Leading blank characters.
sign (Optional) Plus sign (+) or minus sign (-) character.
digits A contiguous sequence of digit characters (0-9). At least one digit
character must be present in either digits or d_digits.
point (Optional) Decimal point (.).
d_digits
A contiguous sequence of digit characters (0-9). At least one digit
character must be present in either digits or d_digits.
e_char An exponent character, which is either E or e.
e_sign (Optional) Plus sign (+) or minus sign (-) character for the exponent.
e_digits
A contiguous sequence of digit characters (0-9) for the exponent. At least
one digit character must be present if the string contains an exponent
character.
After the sequence of digit characters, or the optional characters representing an
exponent, the string can contain other characters that are not digit characters,
but the conversion stops as soon as the first of these characters is reached. The
string is assumed to represent a decimal floating point number with an exponent
that is a power of 10.
XMS may return an error if the string is not formatted correctly.
v When converting a numeric property value to a string, including a property
value with data type xmsSBYTE, the value is converted to the string
representation of the value as a decimal number, not the string containing the
ASCII character for that value. For example, the integer 65 is converted to the
string “65”, not the string “A”.
v When converting a byte array property value to a string, each byte is converted
to the 2 hexadecimal characters that represent the byte. For example, the byte
array {0xF1, 0x12, 0x00, 0xFF} is converted to the string “F11200FF”.

Conversions from a property type to other data types are supported by the
methods of both the Property and the PropertyContext classes. However, the C
functions xmsPropertyGetStringByRef() and xmsGetStringPropertyByRef() make no
attempt to convert a property value that is not a string. If an application calls
either of these functions to get a pointer to a property value that is not a string,
XMS may return an error.

Iterators
An iterator encapsulates a list of objects and a cursor that maintains the current
position in the list. A C or C++ application uses an iterator to retrieve each object
in the list in turn.

54 Message Service Client for C/C++

When an iterator is created, the position of the cursor is before the first object. An
application uses an iterator to retrieve each object in turn. To retrieve the objects,
the application uses the following three methods of the Iterator class:
v Check for More Objects
v Get Next Object
v Reset Iterator

The Iterator class is equivalent to the Enumerator class in Java.

An application can use an iterator to perform the following tasks:

v To get the properties of a message
v To get the name-value pairs in the body of a map message
v To browse the messages on a queue
v To get the names of the JMS defined message properties supported by a
connection

The following code fragment shows how a C application can use an iterator to
print out all properties of a message:
/********************************************************/
/* XMS Sample using an iterator to browse properties */
/********************************************************/
rc = xmsMsgGetProperties(hMsg, &it, xmsError);
if (rc == XMS_OK)
{
rc = xmsIteratorHasNext(it, &more, xmsError);
while (more)
{
rc = xmsIteratorGetNext(it, (xmsHObj)&p, xmsError);
if (rc == XMS_OK)
{
xmsPropertyGetName(p, name, 100, &len, xmsError);
printf("Property name=\"%s\"\n", name);
xmsPropertyGetTypeId(p, &type, xmsError);
switch (type)
{
case XMS_PROPERTY_TYPE_INT:
{
xmsINT value=0;
xmsPropertyGetInt(p, &value, xmsError);
printf("Property value=%d\n", value);
break;
}
case XMS_PROPERTY_TYPE_STRING:
{
xmsINT len=0;
char value[100];
xmsPropertyGetString(p, value, 100, &len, xmsError);
printf("Property value=\"%s\"\n", value);
break;
}
default:
{
printf("Unhandled property type (%d)\n", (int)type);
}
}
xmsPropertyDispose(&p, xmsError);
}
rc = xmsIteratorHasNext(it, &more, xmsError);
}
printf("Finished iterator....\n");

Chapter 7. Writing XMS applications 55

 xmsIteratorDispose(&it, xmsError);
}
/********************************************************/

Coded character set identifiers

For C or C++ strings of character set identifiers (CCSIDs) that an object passes to,
or receives from, XMS might require conversion. The XMSC_CLIENT_CCSID
property of the object tells XMS which code page the object is using.

When an object in a C or C++ application passes a string of character data to XMS

across the API XMS converts (if necessary) the character data in the string from the
code page used by the object into the code page required by XMS for the data.
Similarly, when an object receives a string of character data from XMS across the
API XMS converts (if necessary) the character data in the string from the code
page that the data is currently in into the code page used by the object. Therefore,
in order to convert the character data in a string, XMS must identify which code
page an object is using.

The XMSC_CLIENT_CCSID property of a ConnectionFactory, Connection, Session,

MessageProducer, or MessageConsumer object specifies which code page the object
is using. The value of the XMSC_CLIENT_CCSID propertyis a CCSID which
identifies a code page. XMS sets the property when an application creates one of
these objects, but the application can change its value subsequently.

When an application starts, XMS derives an appropriate CCSID for the application
from the environment in which the application is running. This CCSID is called the
process CCSID. At any time, the application can change the process CCSID by
calling xmsSetClientCCSID(). This is a C function that does not belong to any class,
but C++ applications can use the function as well.

When an application creates a connection factory, XMS sets the

XMSC_CLIENT_CCSID property of the object. If the connection factory is created
from an object definition retrieved from a repository of administered objects, and
the object definition specifies a value for the XMSC_CLIENT_CCSID property, XMS
uses this value to set the property. Otherwise, XMS sets the property to the special
value XMSC_CCSID_PROCESS, which means that the connection factory is using
the code page identified by the process CCSID.

When an application uses a connection factory to create a connection, XMS copies

the XMSC_CLIENT_CCSID property of the ConnectionFactory object to the newly
created Connection object. XMS copies the property only at the time the
application creates the connection. If the application subsequently changes the
value of the XMSC_CLIENT_CCSID property of the ConnectionFactory object,
XMS does not propagate the change to the XMSC_CLIENT_CCSID property of the
Connection object.

In the same way, when an application uses a connection to create a session, XMS
copies the XMSC_CLIENT_CCSID property of the Connection object to the newly
created Session object. When an application uses a session to create a message
producer or message consumer, XMS copies the XMSC_CLIENT_CCSID property
of the Session object to the newly created MessageProducer or MessageConsumer
object. In each case, XMS copies the property only at the time the application
creates the object.

56 Message Service Client for C/C++

At any time, an application can change the value of the XMSC_CLIENT_CCSID
property of an object by calling the Set Integer Property method of the
PropertyContext class. The application can set the property to one of the following
values:
A coded character set identifier (CCSID)
The object is using the code page identified by the specified CCSID. If the
application specifies either a CCSID that is not valid or a CCSID for which
the platform does not support code page conversion, the call fails and XMS
returns an error.
XMSC_CCSID_UTF8
The object is using the UTF-8 representation of Unicode data.
XMSC_CCSID_UTF16
The object is using the UTF-16 representation of Unicode data.
XMSC_CCSID_UTF32
The object is using the UTF-32 representation of Unicode data.
XMSC_CCSID_PROCESS
The object is using the code page identified by the process CCSID. XMS
queries the process CCSID whenever it needs to determine which code
page the object is using. If the application changes the process CCSID by
calling xmsSetClientCCSID(), XMS detects the change the next time it
determines which code page the object is using.
This is a special value of the property and is not an actual CCSID.
XMSC_CCSID_HOST
The object is using the code page identified by the CCSID that is derived
from the environment in which the application is running. This CCSID is
the same as the process CCSID unless the application has changed the
process CCSID by calling xmsSetClientCCSID().
This is a special value of the property and is not an actual CCSID.
XMSC_CCSID_NO_CONVERSION
Strings of character data received by the object are not converted.
This is a special value of the property and is not an actual CCSID.

The strings of character data that an application passes to, and receives from, XMS
include (but are not exclusively confined to) the strings in messages. The strings
that require conversion might be in any of the following parts of a message:
v Header fields (see “Header fields in an XMS message” on page 97)
v Properties (see “Properties of an XMS message” on page 98)
v The body (see “The body of an XMS message” on page 101)

When XMS converts the strings in an outgoing message, it uses the code page
associated with the session that created the message. When XMS converts the
strings in an incoming message, it uses the code page associated with the message
consumer that receives the message. XMS determines the code page from the value
of the XMSC_CLIENT_CCSID property of the relevant Session or
MessageConsumer object.

Converting strings in messages might have an impact on performance depending

on the amount of data to be converted the frequency with which conversion
occurs. If you are designing applications to maximize the throughput of messages,

Chapter 7. Writing XMS applications 57

 you might want to consider ways of reducing the amount of data conversion that
is required. The following examples illustrate how this can be done:
v For example, you might know that the strings in incoming messages are in a
certain code page (the UTF-8 representation of Unicode data). You might
determine this information from a knowledge of the application that sends the
messages or the message server environment through which the messages pass.
If you can arrange for the application that receives the messages to use the same
code page, no data conversion of the strings is required.
v If you can arrange for both the sending and receiving applications to use the
same code page, you might consider using bytes messages and reading and
writing strings as byte arrays. No data conversion is performed in these
circumstances.

Note: The XMSC_CLIENT_CCSID property is not required for .NET applications.

In .NET, all strings are passed using the native .NET string class. Because
this class has a fixed encoding, no further information is required to
interpret it.

XMS error and exception codes

XMS uses a range of error codes to indicate failures. These error codes are not
explicitly listed in this documentation because they may vary from release to
release. Only XMS exception codes (in the format XMS_X_...) are documented
because they remain the same across releases of XMS.

Building your own applications

You build your own applications like you build the sample applications.

About this task

This section lists the prerequisites you need to build your own C or C++
applications. For additional guidance on how to build your own applications, use
the makefiles provided for each sample application.

Tip: To assist with problem diagnosis in the event of a failure, you might find it
helpful to compile applications with symbols included.

On Windows, if you are building a C or C++ application, make sure that your
compilation settings are correct. All of the XMS libraries are compiled using the
multithreaded runtime libraries. Therefore, when you are a building C or C++
application using the XMS libraries, make sure that your project or makefile
compiler flag settings are set to select multi-threaded runtime libraries (/MD or,
for debug, /MDd), and not single-threaded runtime libraries (/ML or, for debug,
/MLd).

Build your C or C++ application, as described in “Building the C or C++ sample

applications” on page 31

Network stack selection mechanism

This section describes the network stack selection mechanism when both IPv4 and
IPv6 network stacks are enabled on a machine.

58 Message Service Client for C/C++

When both IPv4 and IPv6 network stacks are enabled on a machine, the connection
binds to either of the two network stacks based on the host name and local
address properties.

The host name is specified by any of these properties,

XMSC_WMQ_HOST_NAME, XMSC_RTT_HOST_NAME, and
XMSC_WPM_PROVIDER_ENDPOINTS, while the local address may be
determined by XMSC_WMQ_LOCAL_ADDRESS, XMSC_RTT_LOCAL_ADDRESS,
or XMSC_WPM_LOCAL_ADDRESS.

The following table lists the outcome for the possible combinations of network
stacks in use for the host name and local address.
Table 11. Network stack selection mechanism
Stack Host Name Local Address Connection result
IPv4 only stack IPv4 address None Connection binds to
IPv4 stack
IPv6 address None Connection fails to
resolve host name
Host name resolves None Connection binds to
to both IPv4 and IPv6 IPv4 stack
addresses
IPv4 address IPv4 address Connection binds to
IPv4 stack
IPv6 address IPv4 address Connection fails to
resolve host name
Remote host name IPv4 address Connection binds to
resolves to both IPv4 IPv4 stack
and IPv6 addresses
Any address IPv6 address Connection fails to
resolve local address
IPv4 address Local address Connection binds to
resolves to both IPv4 IPv4 stack
and IPv6 addresses
IPv6 address Local address Connection fails to
resolves to both IPv4 resolve host name
and IPv6 addresses
Remote host name Local address Connection binds to
resolves to both IPv4 resolves to both IPv4 IPv4 stack
and IPv6 addresses and IPv6 addresses

Chapter 7. Writing XMS applications 59

 Table 11. Network stack selection mechanism (continued)
Stack Host Name Local Address Connection result
Dual (IPv4 and IPv6) IPv4 address None Connection binds to
stack IPv4 stack
IPv6 address None Connection binds to
IPv6 stack
Remote host name None For WPM and RTT,
resolves to both IPv4 connection binds to
and IPv6 addresses IPv6 stack.

For WebSphere MQ,

channel binds to
stack determined by
the value of the
MQIPADDRV
environment
variable.
IPv4 address IPv4 address Connection binds to
IPv4 stack
IPv6 address IPv4 address Connection fails to
resolve host name
Remote host name IPv4 address Connection binds to
resolves to both IPv4 IPv4 stack
and IPv6 addresses
IPv4 address IPv6 address Maps an IPv4 host
name to an IPv4
mapped IPv6
address. IPv6
implementations that
do not support IPv4
mapped IPv6
addressing fail to
resolve host name.
IPv6 address IPv6 address Connection binds to
IPv6 stack
Remote host name IPv6 address Connection binds to
resolves to both IPv4 IPv6 stack
and IPv6 addresses
IPv4 address Local address Connection binds to
resolves to both IPv4 IPv4 stack
and IPv6 addresses
IPv6 address Local address Connection binds to
resolves to both IPv4 IPv6 stack
and IPv6 addresses
Remote host name Local address For WPM and RTT,
resolves to both IPv4 resolves to both IPv4 connection binds to
and IPv6 addresses and IPv6 addresses IPv6 stack.

For WebSphere MQ,

channel binds to
stack determined by
the value of the
MQIPADDRV
environment
variable.

60 Message Service Client for C/C++

Table 11. Network stack selection mechanism (continued)
Stack Host Name Local Address Connection result
IPv6 only stack IPv4 address None Maps an IPv4 host
name to an IPv4
mapped IPv6
address. IPv6
implementations that
do not support IPv4
mapped IPv6
addressing fail to
resolve host name
IPv6 address None Connection binds to
IPv6 stack
Remote host name None Connection binds to
resolves to both IPv4 IPv6 stack
and IPv6 addresses
Any address IPv4 address Connection fails to
resolve local address
IPv4 address IPv6 address Maps an IPv4 host
name to an IPv4
mapped IPv6
address. IPv6
implementations that
do not support IPv4
mapped IPv6
addressing fail to
resolve host name
IPv6 address IPv6 address Connection binds to
IPv6 stack
Remote host name IPv6 address Connection binds to
resolves to both IPv4 IPv6 stack
and IPv6 addresses
IPv4 address Local address Maps an IPv4 host
resolves to both IPv4 name to an IPv4
and IPv6 addresses mapped IPv6
address. IPv6
implementations that
do not support IPv4
mapped IPv6
addressing fail to
resolve host name
IPv6 address Local address Connection binds to
resolves to both IPv4 IPv6 stack
and IPv6 addresses
Remote host name Local address Connection binds to
resolves to both IPv4 resolves to both IPv4 IPv6 stack
and IPv6 addresses and IPv6 addresses

Chapter 7. Writing XMS applications 61

62 Message Service Client for C/C++
Chapter 8. Writing XMS applications in C
This chapter provides information help you write XMS applications in C.

About this task

The chapter contains the following sections:

v “Object handles in C”
v “Object Properties in C” on page 64
v “C functions that return a string by value” on page 64
v “C functions that return a byte array by value” on page 65
v “C functions that return a string or byte array by reference” on page 66
v “C functions that accept a string as input” on page 67
v “Error handling in C” on page 67
v “Message and exception listener functions in C” on page 68

Object handles in C
A C application uses an object handle to access an object. There are two kinds of
object handles; one has a data type that is related to the type of the object, and the
other is a generic object handle whose data type is not related to the type of the
object.

When a C application calls a function to create an object, XMS stores the object
internally and returns a handle for the object to the application. The application
can then use the handle to access the object.

Every object handle has a data type, which is related to the object type. Table 12
shows the object handle data type for each type of object. Note that BytesMessage,
MapMessage, ObjectMessage, StreamMessage, TextMessage, and Message objects
all have handles with the same data type, xmsHMsg. For more information about
how to use handles for messages, see “The body of an XMS message” on page 101.
Table 12. Data types for object handles
Type of object Object handle data type
Connection xmsHConn
ConnectionFactory xmsHConnFact
ConnectionMetaData xmsHConnMetaData
Destination xmsHDest
ErrorBlock xmsHErrorBlock
InitialContext xmsHInitialContext
Iterator xmsHIterator
Message, BytesMessage, MapMessage, ObjectMessage, xmsHMsg
StreamMessage, and TextMessage
MessageConsumer xmsHMsgConsumer
MessageProducer xmsHMsgProducer
Property xmsHProperty

© Copyright IBM Corp. 2005, 2009 63

 Table 12. Data types for object handles (continued)
Type of object Object handle data type
QueueBrowser xmsHQueueBrowser
Requestor xmsHRequestor
Session xmsHSess

Certain functions return a generic object handle, which is not related to the type of
object that they create. A generic object handle has data type xmsHObj.

If an application receives a generic object handle from one of these functions, the
application can call the xmsGetHandleTypeId() function in the PropertyContext
class to determine the related data type object handle for that object. The
application can then call any function to perform an operation on the object by
casting, if necessary, the generic object handle to the data type required by the
function.

Object Properties in C
A C application uses the functions in the PropertyContext class to get and set the
properties of objects.

For each XMS data type, the PropertyContext class contains a function to get the
value of a property with that data type and a function to set its value. For
example, a C application can call the function xmsGetIntProperty() to get the value
of an integer property and the function xmsSetIntProperty() to set its value.

Functions in the PropertyContext class can operate on any object that can have
properties. Each individual class does not contain its own functions to get and set
the properties of objects of that class. As a result, functions in the PropertyContext
class accept only generic object handles as input. If an application is currently
accessing an object using a handle with a data type that is related to the type of
the object, the application must cast the handle to the generic object handle data
type, xmsHObj, in order to get or set the properties of the object. For more
information about generic object handles, see “Object handles in C” on page 63.

All objects except ErrorBlock, Iterator, and Property objects can have properties.

If an application sets the value of a property, the new value replaces any previous
value the property had.

C functions that return a string by value

This section describes the interface used by C functions that return a string by
value.

In the C API, certain functions return a string as a parameter. Each of these

functions uses the same interface for retrieving a string. The following example C
code illustrates the function, xmsGetStringProperty() in the PropertyContext class:
xmsRC xmsGetStringProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsCHAR *propertyValue,
xmsINT length,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);

64 Message Service Client for C/C++

 Three parameters control the retrieval of a string:
propertyValue
This parameter is a pointer to a buffer provided by the application into
which XMS copies the characters in the string. If data conversion is
required, XMS converts the characters into the code page used by the
application before copying them into the buffer.
length This parameter is the length of the buffer in bytes. This is an input
parameter that must be set by the application before the call. If you specify
XMSC_QUERY_SIZE instead, the string is not returned, but its length is
returned in the actualLength parameter.
actualLength
This output parameter is the length of the string that XMS copies into the
buffer. If data conversion is required, this is the length after conversion.
The length is measured in bytes. XMS always returns a null terminated
string, and the length reported to the application includes the terminating
null character. If you specify a null pointer for this parameter on input, the
length of the string is not returned.

If the buffer is not large enough to store the whole string, including the
terminating null character, XMS returns the string truncated to the length of the
buffer, sets the actualLength parameter to the length of the whole string, and
returns error code XMS_E_DATA_TRUNCATED.

If an XMS application receives a message sent by a JMS application, strings in the

header fields, properties, and body of the message might contain embedded null
characters. Strings containing embedded nulls cannot be manipulated using the
standard C string manipulator because they read the first null character to be the
end of the string.

C functions that return a byte array by value

This section describes the interface used by C functions that return a byte array by
value.

In the C API, certain functions return a byte array as a parameter. Each of these
functions uses the same interface for retrieving a byte array. The following example
written in C code illustrates the function, xmsGetByteArrayProperty() in the
PropertyContext class:
xmsRC xmsGetByteArrayProperty(xmsHObj object
xmsCHAR *propertyName,
xmsSBYTE *propertyValue,
xmsINT length,
xmsINT *actualLength
xmsHErrorBlock errorBlock) const;

Three parameters control the retrieval of a byte array:

propertyValue
This parameter is a pointer to a buffer provided by the application into
which XMS copies the bytes in the array.
length This parameter is the length of the buffer in bytes. This is an input
parameter that must be set by the application before the call. If you specify
XMSC_QUERY_SIZE instead, the byte array is not returned, but its length is
returned in the actualLength parameter.

Chapter 8. Writing XMS applications in C 65

 actualLength
This output parameter is the number of bytes in the array that XMS copies
into buffer. If you specify a null pointer for this parameter on input, the
length of the array is not returned.

If the buffer is not large enough to store the whole array, XMS returns the array
truncated to the length of the buffer, sets the actualLength parameter to the length
of the whole array, and returns an error.

Two functions, xmsBytesMsgReadBytes() and xmsStreamMsgReadBytes(), have a

slightly different interface. Using one of these functions, an application can retrieve
a byte array in stages by successive calls to the function. Each call reads bytes into
the buffer provided by the application starting from the current position of an
internal cursor, and an output parameter, returnedLength, to determine how many
bytes have been read into the buffer. Neither function has the equivalent of the
actualLength parameter in its interface, but an application can specify
XMSC_QUERY_SIZE to determine the number of bytes remaining in an array starting
from the current position of the cursor.

C functions that return a string or byte array by reference

This section describes the interface used by C functions that return a string or byte
array by reference.

When a C application calls one of the functions described in “C functions that

return a string by value” on page 64 or “C functions that return a byte array by
value” on page 65, XMS must copy the string or byte array into the buffer
provided by the application. If an application is processing a large volume of
messages, and the strings or byte arrays in the messages are very large, then the
time taken to copy them might affect performance.

The C API has functions to deliver better performance. When an application calls
one of these functions, one parameter returns a pointer to a string or byte array
that is stored in memory owned by XMS, and another parameter returns the length
of the string or byte array. Examples of these functions are
xmsBytesMsgReadBytesByRef() and xmsGetStringPropertyByRef().

If data conversion is required for a string, XMS converts the characters into the
code page of the application and returns a pointer to the converted string. The
length returned to the application is the length of the converted string.

If data conversion is required, the first time an application retrieves a string by

reference might take as long as retrieving the string by value. However, XMS
caches the converted string and so subsequent calls to retrieve the same string do
not take as long.

Note: These functions return a pointer to memory owned by XMS. You must not
attempt to free or modify the contents of this memory as doing so will cause
unpredictable results.

The pointer returned to the application remains valid until the next time that the
application adds a new piece of data to the bytes message.

66 Message Service Client for C/C++

C functions that accept a string as input
This section describes the interface used by C functions that accept a string as an
input parameter.

In the C API, certain functions accept a string as an input parameter. Each of these
functions uses the same interface for passing a string to XMS. The following
example of C code illustrates the function, xmsSetStringProperty() in the
PropertyContext class:
xmsRC xmsSetStringProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsCHAR *propertyValue,
xmsINT length,
xmsHErrorBlock errorBlock);

Two input parameters control passing a string to XMS:

propertyValue
A pointer to a character array that contains the string to be passed to XMS.
length The length of the string in bytes. If the string is null terminated with no
embedded null characters, you can specify XMSC_CALCULATE_STRING_SIZE
instead and XMS calculates its length.

Error handling in C
Most functions in the C API return a value that is a return code, and have an
optional input parameter that is a handle for an error block. This section describes
the roles of the return code and the error block.

Return codes
The return code from a C function call indicates whether the call was successful.
The return code has data type xmsRC. Table 13 lists the possible return codes and
gives their meaning.
Table 13. Return codes from C function calls
Return code Meaning
XMS_OK The call completed successfully.
Any other value The call failed. The error block contains more details about why the call
failed. The return code is the same as the exception code that is
returned in the error block.

The error block

When an application calls a C function, the application can include a handle for an
error block as an input parameter on the call. If the call fails, XMS stores
information in the error block about why the call failed. The application can then
retrieve this information.

An error block contains the following information:

Exception code
An integer representing the exception. The exception code provides a
high-level indication of why the call failed, but it does not indicate
precisely which error has occurred. The header file xmsc.h defines a named
constant for each exception code.

Chapter 8. Writing XMS applications in C 67

 The exception code matches the JMS exception that is thrown by a JMS
method in the same circumstances.
Error code
An integer representing the error. The error code provides a more precise
indication of which error has occurred. The header file xmsc.h defines a
named constant for each error code.
Error string
A null terminated string of characters that describes the error. The
characters in the string are the same as those in the named constant that
represents the error code.
Error data
A null terminated string of characters that provides additional information
about the error. The information is free format.
Linked error
The handle for an linked error block. To report more information about a
call that has failed, XMS can create one or more additional error blocks and
chain them from the error block provided by the application.

XMS provides a set of helper functions to create an error block and extract
information from it. An application must use a helper function to create an error
block and obtain a handle for it before calling the first function that can accept the
handle as an input parameter. If the function call fails, the application can then use
other helper functions to extract information about the error that XMS has stored
in the error block. For details of these helper functions, see “ErrorBlock” on page
157.

Message and exception listener functions in C

A C application uses a message listener function to receive messages
asynchronously, and an exception listener function to be notified asynchronously of
a problem with a connection.

Message listener functions in C

To receive messages asynchronously, a C application must register a message
listener function and context data with one or more message consumers. The
application does this by calling the xmsMsgConsumerSetMessageListener()
function for each message consumer, passing pointers to the message listener
function and context data as parameters.

A message listener function is a callback function written by the user. When a

message arrives for a message consumer, XMS calls the message listener function
to deliver the message, passing a pointer to the context data as one parameter and
the handle for the message as the other parameter.

The format and content of the context data is defined by the application, and the
data itself occupies memory owned by the application. For example, the context
data might be a structure allocated on the heap. The context data contains all the
information that the message listener function needs to refer to when processing a
message. XMS does not make a copy of the context data, and so the application
must ensure that the context data is still available when XMS calls the message
listener function.

68 Message Service Client for C/C++

 Note: The application must release the resources used by a message that is
received asynchronously. XMS does not release these resources.

To stop the asynchronous delivery of messages to a message consumer, the

application can call the xmsMsgConsumerSetMessageListener() function again, by
passing a null pointer as a parameter instead of a pointer to a message listener
function.

A new message listener function and context data can be registered with a message
consumer without cancelling the registration of an existing message listener
function. If an existing message listener function is running when a new message
listener function is registered, the active message listener function completes as
usual, and any subsequent messages are processed by calls to the new message
listener function. If a transaction is in progress when a message listener function is
changed, the transaction is completed by calls to the new message listener
function.

For more information about the message listener function, including its signature,
see “MessageListener” on page 198.

Exception listener functions in C

Using an exception listener function is similar in principle to using a message
listener function.

A C application must register an exception listener function with a connection by

calling the xmsConnSetExceptionListener() function, passing pointers to the
exception listener function and context data as parameters. An exception listener
function is a callback function written by the user. If XMS detects a problem with
the connection, XMS calls the exception listener function, passing a pointer to the
context data as one parameter and the handle for an error block as the other
parameter.

The context data contains all the information that the exception listener function
requires when processing an error block. In all other respects, the context data is
used with an exception listener function in the same way as it is used with a
message listener function.

For more information about the exception listener function, including its signature,
see “MessageListener” on page 333.

Note: The application is required to release the resources used by an error block
received in this way. XMS does not release these resources.

To stop the asynchronous reporting of problems with a connection, the application

can call the xmsConnSetExceptionListener() function again, by passing a null
pointer as a parameter instead of a pointer to an exception listener function.

Chapter 8. Writing XMS applications in C 69

70 Message Service Client for C/C++
Chapter 9. Writing XMS applications in C++
This chapter provides information to help you when writing XMS applications in
C++.

About this task

The chapter contains the following sections:

v “Namespaces in C++”
v “String objects in C++” on page 72
v “C++ methods that return a byte array” on page 72
v “Properties in C++” on page 73
v “Assignment of XMS objects to variables in C++” on page 73
v “Error handling in C++” on page 76
v “Message and exception listeners in C++” on page 78
v “Use of C APIs in a C++ application” on page 80

Namespaces in C++
All the C++ classes supplied with XMS are declared in a namespace called xms.

A C++ application can therefore adopt one of the following approaches when
referring to the names of XMS classes:
v The application can qualify the names of XMS classes with the name of the
namespace, xms, as show in the following C++ code fragment:
#include <xms.hpp>

using namespace std;

int main(int argc, char *argv[])

{
xms::ConnectionFactory connFact;
xms::Connection conn;

connFact.setIntProperty(XMSC_CONNECTION_TYPE, XMSC_CT_RTT);
connFact.setIntProperty(XMSC_RTT_CONNECTION_PROTOCOL, XMSC_RTT_CP_TCP);
connFact.setStringProperty(XMSC_RTT_HOST_NAME, "localhost");
connFact.setIntProperty(XMSC_RTT_PORT, 1506);

conn = connFact.createConnection();

// Other code here

cout << "Exiting..." << endl;

return(0);
}
v The application can use a using directive to make the names of XMS classes
available without having to qualify them. For example:
#include <xms.hpp>

using namespace std;

using namespace xms;

© IBM Corporation 2005 71

 int main(int argc, char *argv[])
{
ConnectionFactory connFact;
Connection conn;

connFact.setIntProperty(XMSC_CONNECTION_TYPE, XMSC_CT_RTT);
connFact.setIntProperty(XMSC_RTT_CONNECTION_PROTOCOL, XMSC_RTT_CP_TCP);
connFact.setStringProperty(XMSC_RTT_HOST_NAME, "localhost");
connFact.setIntProperty(XMSC_RTT_PORT, 1506);

conn = connFact.createConnection();

// Other code here

cout << "Exiting..." << endl;

return(0);
}

String objects in C++

In the C++ API, a String object encapsulates a string. When called, certain methods
accept a String object as a parameter or return a String object.

A String object can encapsulate a null terminated character array. Alternatively, a

String object can encapsulate a byte array with embedded null characters, where
the byte array might or might not be, null terminated. Therefore, when an
application creates a String object from a byte array, the application must specify
the length of the array. The following code fragment creates both types of String
object:
#include <xms.hpp>

using namespace std;

int main(int argc, char *argv[])

{
xms::String strA("Normal character string");
xms::String strB("This\0string\0contains\0nulls", 26);

// The overloaded assignment operator can be used to create

// a String object from a null terminated character array.

xms::String strC = "Another character string";

// Other code here

return(0);
}

To make it easier to create and manipulate String objects, certain operators and
constructors are overloaded on the String class. If an application calls a method
that requires a String object as an input parameter, it is not necessary to create the
String object first. The application can pass a null terminated character array to the
method as a parameter, and XMS automatically creates a String object on the stack.

In addition, the String class encapsulates methods to create and manipulate String
objects. For the definitions of these methods, see “String” on page 395.

C++ methods that return a byte array

This section describes the interface used by C++ methods that return a byte array.

72 Message Service Client for C/C++

 In the C++ API, certain methods return a byte array as a parameter. Each of these
methods uses the same interface for retrieving a byte array. The following example
illustrates one of these methods, PropertyContext.getBytesProperty():
xmsINT getBytesProperty(const String & propertyName,
xmsSBYTE *propertyValue,
const xmsINT length,
xmsINT *actualLength) const;

The parameters propertyValue, length, and actualLength control the retrieval of the
byte array in the same way as described in “C functions that return a byte array
by value” on page 65.

Other examples of these methods are MapMessage.getBytes(),

MapMessage.getObject(), Property.getByteArray(), and String.get().

Properties in C++
A C++ application uses the methods in the PropertyContext class to get and set the
properties of objects.

The PropertyContext class is an abstract superclass that encapsulates methods that

get and set properties. These methods are inherited, directly or indirectly, by the
following classes:
v BytesMessage
v Connection
v ConnectionFactory
v ConnectionMetaData
v Destination
v InitialContext
v MapMessage
v Message
v MessageConsumer
v MessageProducer
v ObjectMessage
v QueueBrowser
v Requestor
v Session
v StreamMessage
v TextMessage

If an application sets the value of a property, the new value replaces any previous
value the property had.

Assignment of XMS objects to variables in C++

This section describes how XMS objects are assigned to variables in C++.

The assignment operator is overloaded on each of the XMS classes listed in

Table 14 on page 74. If an object is already assigned to one variable, and an
application assigns the value of that variable to another variable of the same type,
the precise action of the overloaded assignment operator depends on the type of
the object being assigned:

Chapter 9. Writing XMS applications in C++ 73

 v For some types of objects, a copy of the object is assigned to the second variable.
This is called a deep copy. When a deep copy is made, the original object and its
copy become two completely separate objects, which can be used independently
of each other.
v For the other types of objects, only a reference to the object is copied and
assigned to the second variable. This is called a shallow copy. When a shallow
copy is made, the two variables reference the same object. If an application
makes changes to the object by accessing the object through one variable, the
application can see those changes if it accesses the object through the other
variable.
Table 14 indicates, for each type of object, whether the overloaded assignment
operator makes a shallow or a deep copy of an object.
Table 14. The XMS classes on which the assignment operator is overloaded
Class Shallow copy Deep copy
BytesMessage U
Connection U
ConnectionFactory U
ConnectionMetaData U
Destination U
Exception U
IllegalStateException U
InitialContext U
InvalidClientIDException U
InvalidDestinationException U
InvalidSelectorException U
Iterator U
MapMessage U
Message U
MessageConsumer U
MessageEOFException U
MessageFormatException U
MessageNotReadableException U
MessageNotWritableException U
MessageProducer U
ObjectMessage U
Property U
QueueBrowser U
Requestor U
ResourceAllocationException U
SecurityException U
Session U
StreamMessage U
String U
TextMessage U

74 Message Service Client for C/C++

Table 14. The XMS classes on which the assignment operator is overloaded (continued)
Class Shallow copy Deep copy
TransactionInProgressException U
TransactionRolledBackException U

When a shallow copy of an object is made, the object is deleted only when all the
variables that reference the object go out of scope. If the application closes or
deletes the object before the variables that reference the object go out of scope, the
application can no longer access the object through any of the variables.

The following code fragment illustrates these concepts:

#include <xms.hpp>

using namespace std;

int main(int argc, char *argv[])

{
xms::ConnectionFactory cf;
xms::Connection conn;
xms::Session sess;
xms::Session sess2;

cf.setIntProperty(XMSC_CONNECTION_TYPE, XMSC_CT_RTT);
cf.setIntProperty(XMSC_RTT_CONNECTION_PROTOCOL, XMSC_RTT_CP_TCP);
cf.setStringProperty(XMSC_RTT_HOST_NAME, "localhost");
cf.setIntProperty(XMSC_RTT_PORT, 1506);

conn = cf.createConnection();
sess = conn.createSession();

// Make a shallow copy of the Session object.

sess2 = sess;

// Set a property in the Session object using the sess2 variable.

sess2.setStringProperty("property", "test");

// Make another shallow copy of the Session object.

if (sess2.isNull() != xmsTRUE)
{
xms::Session sess3 = sess2;

// Set another property in the Session object, this time using

// the sess3 variable.

sess3.setStringProperty("another property", "test");

}

// The sess3 variable is now out of scope, but the second property
// is still set in the Session object.

// Close the Session object.

sess.close();

// The Session object is now closed and can no longer be accessed

// through the sess2 variable. As a result, the following statement
// causes "invalid session" to be written to the standard output
// stream.

Chapter 9. Writing XMS applications in C++ 75

 if (sess2.isNull() == xmsTRUE)
{
cout << "invalid session" << endl;
}

return(0);
}

Error handling in C++

XMS throws an exception when it detects an error while processing a call to a
method.

An XMS exception is an object of one of the following types:

v Exception
v IllegalStateException
v InvalidClientIDException
v InvalidDestinationException
v InvalidSelectorException
v MessageEOFException
v MessageFormatException
v MessageNotReadableException
v MessageNotWritableException
v ResourceAllocationException
v SecurityException
v TransactionInProgressException
v TransactionRolledBackException

The Exception class is a superclass of each of the remaining classes in this list. As a
result, an application can include the calls to XMS methods in a try block and, to
catch all types of XMS exception, the application can specify the Exception class in
the exception declaration of the catch construct. The following code fragment
illustrates this technique:
#include <xms.hpp>

using namespace std;

int main(int argc, char *argv[])

{
int nRC = 0;

try
{
xms::ConnectionFactory connFact;
xms::Connection conn;

connFact.setIntProperty(XMSC_CONNECTION_TYPE, XMSC_CT_RTT);
connFact.setIntProperty(XMSC_RTT_CONNECTION_PROTOCOL, XMSC_RTT_CP_TCP);
connFact.setStringProperty(XMSC_RTT_HOST_NAME, "localhost");
connFact.setIntProperty(XMSC_RTT_PORT, 1506);

conn = connFact.createConnection();

// Other code here

}
catch(xms::Exception & ex)
{
// Error handling code here

76 Message Service Client for C/C++

 nRC = -1;
}

return(nRC);
}

If an application uses this technique to catch XMS exceptions, it must catch an

exception by reference, and not by value. This ensures that an exception is not
sliced and that valuable data about the error is not lost.

The Exception class itself is a subclass of the std::exception class. Therefore, to

catch all exceptions, including those thrown by the C++ runtime environment, an
application can specify the std::exception class in the exception declaration of the
catch construct. The following code fragment illustrates this concept:
#include <xms.hpp>

using namespace std;

int main(int argc, char *argv[])

{
int nRC = 0;

try
{
xms::ConnectionFactory connFact;

connFact.setIntProperty(XMSC_CONNECTION_TYPE, XMSC_CT_RTT);
connFact.setIntProperty(XMSC_RTT_CONNECTION_PROTOCOL, XMSC_RTT_CP_TCP);
connFact.setStringProperty(XMSC_RTT_HOST_NAME, "localhost");
connFact.setIntProperty(XMSC_RTT_PORT, 1506);

// Additional code here

}
catch(exception & ex)
{
// Error handling code here

nRC = -1;
}

return(nRC);
}

After an application catches an XMS exception, it can use the methods of the
Exception class to find out information about the error. For the definitions of these
methods, see “Exception” on page 297. The information encapsulated by an XMS
exception is essentially the same as the information provided to a C application in
an error block. For details of this information, see “The error block” on page 67.

XMS can create an exception for each error it detects during a call and link the
exceptions to form a chain. After an application has caught the first exception, it
can call the getLinkedException() method to get a pointer to the next exception in
the chain. The application can continue to call the getLinkedException() method on
each exception in the chain until a null pointer is returned, indicating that there are
no more exceptions in the chain.

Because the getLinkedException() method returns a pointer to a linked exception,

the application must release the object using the C++ delete operator.

Chapter 9. Writing XMS applications in C++ 77

 The Exception class provides the dump() method, which an application can use to
dump an exception, as formatted text, to a specified C++ output stream. The
operator << is overloaded on the Exception class and can be used for the same
purpose.

Message and exception listeners in C++

A C++ application uses a message listener to receive messages asynchronously, and
it uses an exception listener to be notified asynchronously of a problem with a
connection.

Message listeners in C++

To receive messages asynchronously, a C++ application must define a message
listener class that is based on the abstract class MessageListener. The message
listener class must provide an implementation of the onMessage() method. The
application can then instantiate the class to create a message listener and register
the message listener with one or more message consumers by calling the
setMessageListener() method for each message consumer. Subsequently, when a
message arrives for a message consumer, XMS calls the onMessage() method to
deliver the message. XMS does not make a copy of the message listener, and the
application must ensure that the message listener is still available when XMS calls
the onMessage() method.

If more than one message consumer in a session has a registered message listener,
only one onMessage() method can run at a time. For more information about this
situation, and what to do if your application requires concurrent delivery of
messages, see “Asynchronous message delivery” on page 40.

To stop the asynchronous delivery of messages to a message consumer, the

application can call the setMessageListener() method again, by passing a null
pointer as the parameter instead of a pointer to a message listener. Unless the
registration of a message listener is cancelled in this way, the message listener
must exist for as long as the message consumer exists.

A new message listener can be registered with a message consumer without

cancelling the registration of an existing message listener. If the onMessage()
method of an existing message listener is running when a new message listener is
registered, the active method completes normally, and any subsequent messages
are processed by calls to the onMessage() method of the new message listener. If a
transaction is in progress when a message listener is changed, the transaction is
completed by calls to the onMessage() method of the new message listener.

The following code fragment provides an example of a message listener class

implementation with an onMessage() method:
#include <xms.hpp>

using namespace std;

class MyMsgListener : public xms::MessageListener

{
public:

xmsVOID onMessage(const xms::Message * pMsg);

};

-------–--------------------------------------------

78 Message Service Client for C/C++

xmsVOID MyMsgListener::onMessage(const xms::Message * pMsg)
{
if (pMsg != NULL)
{
cout << pMsg->getJMSCorrelationID() << endl;
cout << pMsg->getJMSMessageID() << endl;

if (pMsg->getType() == XMS_MESSAGE_TYPE_BYTES)
{
xms::BytesMessage * pBytes = (xms::BytesMessage *) pMsg;

cout << pBytes->readUTF() << endl;

}

delete pMsg;
}
}

Because XMS delivers a pointer to a message when it calls the onMessage()

method, the application must release the message using the delete operator.

The following code fragment now shows how an application can use this message
listener class to implement the asynchronous delivery of messages to a message
consumer:
#include <xms.hpp>

using namespace std;

int main(int argc, char *argv[])

{
int nRC = 0;
xms::ConnectionFactory cf;
xms::Connection conn;
xms::Session sess;
xms::Destination dest;
xms::MessageConsumer msgConn;
MyMsgListener msgLst;

try
{
cf.setIntProperty(XMSC_CONNECTION_TYPE, XMSC_CT_RTT);
cf.setIntProperty(XMSC_RTT_CONNECTION_PROTOCOL, XMSC_RTT_CP_TCP);
cf.setStringProperty(XMSC_RTT_HOST_NAME, "localhost");
cf.setIntProperty(XMSC_RTT_PORT, 1506);

conn = cf.createConnection();
sess = conn.createSession();
dest = xms::Destination(XMS_DESTINATION_TYPE_TOPIC, "test");
msgConn = sess.createConsumer(dest);

msgConn.setMessageListener(&msgLst);

conn.start();

while(xmsTRUE)
{
Sleep(1000);
cout << "Waiting..." << endl;
}
}
catch(exception & ex)
{
nRC = -1;

Chapter 9. Writing XMS applications in C++ 79

 }

return(nRC);
}

Exception listeners in C++

Using an exception listener is similar in principle to using a message listener.

A C++ application must define an exception listener class that is based on the
abstract class ExceptionListener. The exception listener class must provide an
implementation of the onException() method. The application can then instantiate
the class to create an exception listener, and register the exception listener with a
connection by calling the setExceptionListener() method. Subsequently, if XMS
detects a problem with the connection, XMS calls the onException() method to pass
an exception to the application. XMS does not make a copy of the exception
listener, and so the application must ensure that the exception listener is still
available when XMS calls the onException() method.

To stop the asynchronous reporting of problems with a connection, the application

can call the setExceptionListener() method again, by passing a null pointer as the
parameter instead of a pointer to an exception listener. Unless the registration of an
exception listener is cancelled in this way, the exception listener must exist for as
long as the connection exists.

Because XMS passes a pointer to an exception when it calls the onException()

method, the application must release the exception by using the C++ delete
operator.

Use of C APIs in a C++ application

Most C++ classes supplied with XMS provide a getHandle() method. A C++
application can call the getHandle() method of an object to retrieve the handle that
a C application would use to access the object. The C++ application can then use
the handle to access the object by calling functions in the C API.

The following code fragment illustrates how this is done:

#include <xms.hpp>

using namespace std;

int main(int argc, char *argv[])

{
xms::ConnectionFactory cf;
xms::Connection conn;
xmsHConn hConn;

cf.setIntProperty(XMSC_CONNECTION_TYPE, XMSC_CT_RTT);
cf.setIntProperty(XMSC_RTT_CONNECTION_PROTOCOL, XMSC_RTT_CP_TCP);
cf.setStringProperty(XMSC_RTT_HOST_NAME, "localhost");
cf.setIntProperty(XMSC_RTT_PORT, 1506);

conn = cf.createConnection();

// Retrieve the handle for the connection.

hConn = conn.getHandle();

// Using the retrieved handle, call a C API function.

xmsConnStart(hConn, NULL);

80 Message Service Client for C/C++

 // Other code here

return(0);
}

Using the handle for an object, a C++ application can close or delete the object by
calling the appropriate C API function. However, if a C++ application does that it
can no longer use the object using the C++ API.

Being able to use the C API is useful because some functions are available only in
the C API. An example of such a function is described in “C functions that return a
string or byte array by reference” on page 66.

Chapter 9. Writing XMS applications in C++ 81

82 Message Service Client for C/C++
Chapter 10. Working with administered objects
This chapter provides information about administered objects. XMS applications
can retrieve object definitions from a central administered objects repository, and
use them to create connection factories and destinations.

About this task

The chapter contains the following sections:

v “Supported types of administered object repository”
v “Property mapping for administered objects” on page 84
v “Required properties for administered ConnectionFactory objects” on page 84
v “Required properties for administered Destination objects” on page 85
v “Creating administered objects” on page 85
v “InitialContext objects” on page 86
v “InitialContext properties” on page 86
v “URI format for XMS initial contexts” on page 87
v “JNDI Lookup Web service” on page 88
v “Retrieval of administered objects” on page 89

Supported types of administered object repository

XMS supports three types of administered object directory: File System,
Lightweight Directory Access Protocol (LDAP), and COS naming.

File System object directories take the form of serialized Java and Naming
Directory Interface (JNDI) objects. LDAP object directories are directories that
contain JNDI objects. File System and LDAP object directories can both be
administered using the JMSAdmin tool available with WebSphere MQ. Both these
object directories can be used to administer client connections by centralizing
WebSphere MQ connection factories and destinations. This allows the network
administrator to deploy multiple applications that all refer to the same central
repository, and that are automatically updated to reflect changes to connection
settings made in the central repository.

A COS naming directory contains WebSphere service integration bus connection

factories and destinations and can be administered using the WebSphere
Application Server administrative console. In order for an XMS application to be
able to retrieve objects from the COS naming directory, a JNDI lookup Web service
must be deployed. This Web service is not available on all WebSphere service
integration technologies. Refer to the product documentation for details.

Note: It is necessary to restart application connections for changes to the object

directory to take effect.

© Copyright IBM Corp. 2005, 2009 83

Property mapping for administered objects
To enable applications to use WebSphere MQ JMS and WebSphere Application
Server connection factory and destination object definitions, the properties
retrieved from these definitions must be mapped on to the corresponding XMS
properties that can be set on XMS connection factories and destinations.

In order to create, for example, an XMS connection factory with properties

retrieved from a WebSphere MQ JMS connection factory, the properties must be
mapped between the two.

All property mappings are performed automatically.

The following table demonstrates the mappings between some of the most
common properties of connection factories and destinations. The properties shown
in this table are just a small set of examples, and not all properties shown are
relevant to all connection types and servers.
Table 15. Examples of name mapping for connection factory and destination properties
WebSphere service
WebSphere MQ JMS integration bus property
property name XMS property name name
PERSISTENCE (PER) XMSC_DELIVERY_MODE
EXPIRY (EXP) XMSC_TIME_TO_LIVE
PRIORITY (PRI) XMSC_PRIORITY
XMSC_WPM_HOST_NAME serverName
XMSC_WPM_BUS_NAME busName
XMSC_WPM_TOPIC_SPACE topicName

Required properties for administered ConnectionFactory objects

When an application creates a connection factory, a number of properties must be
defined to create a connection to a messaging server.

The properties listed in the following tables are the minimum required for an
application to set to create a connection to a messaging server. If you want to
customize the way that a connection is created, then your application can set any
additional properties of the ConnectionFactory object as necessary. For further
information, and a complete list of available properties, see “Properties of
ConnectionFactory” on page 404.

Connection to a WebSphere MQ queue manager

Table 16. Property settings for administered ConnectionFactory objects for connections to a
WebSphere MQ queue manager
Required XMS Equivalent WebSphere MQ JMS property required
XMSC_CONNECTION_TYPE XMS works this out from the connection factory class
name and TRANSPORT (TRAN) property.
XMSC_WMQ_HOST_NAME HOSTNAME (HOST)
XMSC_WMQ_PORT PORT

84 Message Service Client for C/C++

 Real-time connection to a broker
Table 17. Property settings for administered ConnectionFactory objects for real-time
connections to a broker
Required XMS Equivalent WebSphere MQ JMS property required
XMSC_CONNECTION_TYPE XMS works this out from the connection factory class
name and TRANSPORT (TRAN) property.
XMSC_RTT_HOST_NAME HOSTNAME (HOST)
XMSC_RTT_PORT PORT

Connection to a WebSphere service integration bus

Table 18. Property settings for administered ConnectionFactory objects for connections to a
WebSphere service integration bus
XMS property Description
XMSC_CONNECTION_TYPE The type of messaging server to which an application
connects. This is determined from the connection
factory class name.
XMSC_WPM_BUS_NAME For a connection factory, the name of the service
integration bus that the application connects to or, for
a destination, the name of the service integration bus
in which the destination exists.

Required properties for administered Destination objects

An application that creates a Destination object must set several properties as
compared to an application using an administered Destination object.
Table 19. Property settings for administered Destination objects
Type of connection Property Description
WebSphere MQ queue QUEUE (QU) The queue that you wish to connect to
manager
TOPIC (TOP) The topic that the application uses as a
destination
Real-time connection to a TOPIC (TOP) The topic that the application uses as a
broker destination
WebSphere service topicName If your application is connecting to a topic
integration bus
queueName If your application is connecting to a queue

Creating administered objects

The ConnectionFactory and Destination object definitions that XMS applications
require to make a connection to a messaging server must be created using the
appropriate administrative tools.

Before you begin

For further details about the different types of administered object repository that
XMS supports, see “Supported types of administered object repository” on page 83.

Chapter 10. Working with administered objects 85

 About this task

To create the administered objects for WebSphere MQ, use the WebSphere MQ
Explorer or WebSphere MQ JMS administration (JMSAdmin) tool.

To create the administered objects for WebSphere MQ, WebSphere Event Broker, or
WebSphere Message Broker, use the WebSphere MQ JMS administration
(JMSAdmin) tool.

To create administered objects for WebSphere service integration bus, use the
WebSphere Application Server administrative console.

The following steps summarize what you do to create administered objects.

1. Create a connection factory and define the properties needed to create a
connection from your application to your chosen server. The minimum
properties that XMS requires to make a connection are defined in “Required
properties for administered ConnectionFactory objects” on page 84.
2. Create the required destination on the messaging server to which your
application will connect:
v For a connection to a WebSphere MQ queue manager, create a queue or
topic.
v For a real-time connection to a broker, create a topic.
v For a connection to a WebSphere service integration bus, create a queue or a
topic.
The minimum properties that XMS requires to make a connection are defined
in “Required properties for administered Destination objects” on page 85.

InitialContext objects
An application must create an initial context to be used to make a connection to
the administered objects repository to retrieve the required administered objects.

About this task

An InitialContext object encapsulates a connection to the repository. The XMS API

provides methods to perform the following tasks:
v Create an InitialContext object.
v Delete the InitialContext object when it is no longer required.
v Lookup an administered object in the administered object repository.

For further details about creating an InitialContext object, see “InitialContext” on

page 161 for C, “InitialContext” on page 301 for C++, and “Properties of
InitialContext” on page 410.

InitialContext properties
The parameters of the InitialContext constructor include the location of the
repository of administered objects, given as a uniform resource indicator (URI). In
order for an application to establish a connection to the repository, it may be
necessary to provide more information than the information contained in the URI.

In JNDI, the additional information is provided in an environment Hashtable to

the constructor.

86 Message Service Client for C/C++

 In the C and C++ implementations of XMS, the information is provided by setting
properties on the InitialContext object after it has been constructed. For C and C++,
therefore, the creation of the InitialContext object and the connection to the
directory (for the lookup) are done separately so that the properties can be set on
the InitialContext object before an application connects to the directory to retrieve
administered objects.

The location of the administered object repository is defined in the XMSC_IC_URL

property. This property is typically passed on the Create call, but can be modified
to connect to a different naming directory before the lookup. For FileSystem or
LDAP contexts, this property defines the address of the directory. For COS naming,
this is the address of the Web service that uses these properties to connect to the
JNDI directory.

The following properties are passed unmodified to the Web service which will use
them to use to connect to the JNDI directory.
v XMSC_IC_PROVIDER_URL
v XMSC_IC_SECURITY_CREDENTIALS
v XMSC_IC_SECURITY_AUTHENTICATION
v XMSC_IC_SECURITY_PRINCIPAL
v XMSC_IC_SECURITY_PROTOCOL

URI format for XMS initial contexts

The location of the repository of administered objects is provided as a uniform
resource indicator (URI). The format of the URI depends on the context type.

FileSystem context

For the FileSystem context, the URL gives the location of the file system based
directory. The structure of the URL is as defined by RFC 1738, Uniform Resource
Locators (URL): the URL has the prefix file://, and the syntax following this prefix
is a valid definition of a file that can be opened on the system on which XMS is
running.

This syntax can be platform-specific, and can use either ’/ separators or ’\’
separators. If you use ’\’, then each separator needs to be escaped by using an
additional ’\’. This prevents the C runtime from trying to interpret the separator as
an escape character for what follows. Furthermore, if the URI is coded as literal C
strings in source code, the compiler also requires each ’\’ character to be escaped.

These examples illustrate this syntax:

file://myBindings
file:///admin/.bindings
file://\\admin\\.bindings
file://c:/admin/.bindings
file://c:\\admin\\.bindings
file://\\\\madison\\shared\\admin\\.bindings
file:///usr/admin/.bindings

The following examples show the syntax written as literal C strings within source
code:
"file://c:\\\\admin\\\\.bindings"
"file://\\\\\\\\madison\\\\shared\\\\admin\\\\.bindings"

Chapter 10. Working with administered objects 87

 LDAP context

For the LDAP context, the basic structure of the URL is as defined by RFC 2255,
The LDAP URL Format, with the case-insensitive prefix ldap://

The precise syntax is illustrated in the following example:

LDAP://[Hostname][:Port][“/”[DistinguishedName]]

This syntax is as defined in the RFC but without support for any attributes, scope,
filters, or extensions.

Examples of this syntax include:

ldap://madison:389/cn=JMSData,dc=IBM,dc=UK
ldap://madison/cn=JMSData,dc=IBM,dc=UK
LDAP:///cn=JMSData,dc=IBM,dc=UK

WSS context

For the WSS context, the URL is in the form of a Web services endpoint, with the
prefix http://.

Alternatively, you can use the prefix cosnaming:// or wsvc://.

These two prefixes are interpreted as meaning that you are using a WSS context
with the URL accessed over http, which enables the initial context type to be
derived easily directly from the URL.

Examples of this syntax include the following:

http://madison.ibm.com:9080/xmsjndi/services/JndiLookup
cosnaming://madison/jndilookup

JNDI Lookup Web service

To access a COS naming directory from XMS, a JNDI Lookup Web service must be
deployed on a WebSphere service integration bus server. This Web service
translates the Java information from the COS naming service into a form that XMS
applications can read.

The Web service is provided in the enterprise archive file SIBXJndiLookupEAR.ear,

located within the install directory. This can be installed within a WebSphere
service integration bus server by using either the administrative console or the
wsaadmin scripting tool. Refer to the product documentation for further
information on deploying Web service applications.

To define the Web service within XMS applications, you simply need to set the
XMSC_IC_URL property of the InitialContext object to the Web service endpoint
URL. For example, if the Web service is deployed on a server host called MyServer,
an example of a Web service endpoint URL:
wsvc://MyHost:9080/SIBXJndiLookup/services/JndiLookup

Setting the XMSC_IC_URL property allows InitialContext Lookup calls to invoke

the Web service at the defined endpoint, which in turn looks up the required
administered object from the COS naming service.

C and C++ applications can use the Web service.

88 Message Service Client for C/C++

Retrieval of administered objects
XMS retrieves an administered object from the repository using the address
provided when the InitialContext object is created, or in the InitialContext
properties.

Objects to be retrieved can have the following types of names:

v A simple name describing the Destination object, for example, a queue
destination called SalesOrders
v A composite name, which can be made up of SubContexts, separated by ’/’, and
it must end with the object name. An example of a composite name is
″Warehouse/PickLists/DispatchQueue2″ where Warehouse and Picklists are
SubContexts in the naming directory, and DispatchQueue2 is the name of a
Destination object.

Chapter 10. Working with administered objects 89

90 Message Service Client for C/C++
Chapter 11. Securing communications for XMS applications
This chapter provides information about setting up secure communications to
enable XMS applications to connect via Secure Sockets Layer (SSL) to a WebSphere
service integration bus messaging engine or WebSphere MQ queue manager.

About this task

The chapter contains the following sections:

v “Secure connections to a WebSphere MQ queue manager”
v “CipherSuite and CipherSpec name mappings for connections to a WebSphere
MQ queue manager” on page 92
v “Secure connections to a WebSphere service integration bus messaging engine”
on page 93
v “CipherSuite and CipherSpec name mappings for connections to a WebSphere
service integration bus” on page 94

Secure connections to a WebSphere MQ queue manager

To enable an XMS C or C++ application to make secure connections to a
WebSphere MQ queue manager, the relevant properties must be defined in the
ConnectionFactory object.

The protocol used in the encryption negotiation can be either Secure Sockets Layer
(SSL) or Transport Layer Security (TLS), depending on which CipherSuite you
specify in the ConnectionFactory object.

If you use the WebSphere MQ Version 7.0.0.1 and above client libraries and
connect to a WebSphere MQ Version 7 queue manager, then you can create
multiple connections to same queue manager in XMS application. However
connection to different queue manager is not permitted. If you attempt you get the
MQRC_SSL_ALREADY_INITIALIZED error.

If you use the WebSphere MQ Version 6 and above client libraries, then you can
create a new SSL connection only if you close any previous SSL connection first.
Multiple concurrent SSL connections from the same process to the same or
different queue managers are not permitted. If you attempt more than one request,
you get the warning MQRC_SSL_ALREADY_INITIALIZED, which might mean that some
requested parameters for the SSL connection were ignored.

ConnectionFactory properties for connections via SSL to a WebSphere MQ

manager, with a brief description, are shown in the following table:
Table 20. Properties of ConnectionFactory for connections to a WebSphere MQ queue manager via SSL
Name of property Description
XMSC_WMQ_SSL_CERT_STORES The locations of the servers that hold the certificate revocation
lists (CRLs) to be used on an SSL connection to a queue
manager.
XMSC_WMQ_SSL_CIPHER_SPEC The name of the cipher spec to be used on a secure
connection to a queue manager.

© Copyright IBM Corp. 2005, 2009 91

Table 20. Properties of ConnectionFactory for connections to a WebSphere MQ queue manager via SSL (continued)
Name of property Description
XMSC_WMQ_SSL_CIPHER_SUITE The name of the CipherSuite to be used on an SSL or TLS
connection to a queue manager. The protocol used in
negotiating the secure connection depends on the specified
CipherSuite.
XMSC_WMQ_SSL_CRYPTO_HW Configuration details for the cryptographic hardware
connected to the client system.
XMSC_WMQ_SSL_FIPS_REQUIRED The value of this property determines whether an application
can or cannot use non-FIPS compliant cipher suites. If this
property is set to true, only FIPS algorithms are used for the
client-server connection.
XMSC_WMQ_SSL_KEY_REPOSITORY The location of the key database file in which keys and
certificates are stored.
XMSC_WMQ_SSL_KEY_RESETCOUNT The KeyResetCount represents the total number of
unencrypted bytes sent and received within an SSL
conversation before the secret key is renegotiated.
XMSC_WMQ_SSL_PEER_NAME The peer name to be used on an SSL connection to a queue
manager.

CipherSuite and CipherSpec name mappings for connections to a

WebSphere MQ queue manager
The InitialContext translates between the JMSAdmin Connection Factory property
SSLCIPHERSUITE and the XMS near-equivalent
XMSC_WMQ_SSL_CIPHER_SPEC. A similar translation is necessary if you specify
a value for XMSC_WMQ_SSL_CIPHER_SUITE but omit value for
XMSC_WMQ_SSL_CIPHER_SPEC.

Table 21 lists the available CipherSpecs and their JSSE CipherSuite equivalents.
Table 21. Available CipherSpecs and their JSSE CipherSuite equivalents
CipherSpec Equivalent JSSE CipherSuite
DES_SHA_EXPORT SSL_RSA_WITH_DES_CBC_SHA
DES_SHA_EXPORT1024 SSL_RSA_EXPORT1024_WITH_DES_CBC_SHA
FIPS_WITH_3DES_EDE_CBC_SHA SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA
FIPS_WITH_DES_CBC_SHA SSL_RSA_FIPS_WITH_DES_CBC_SHA
NULL_MD5 SSL_RSA_WITH_NULL_MD5
NULL_SHA SSL_RSA_WITH_NULL_SHA
RC2_MD5_EXPORT SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5
RC4_56_SHA_EXPORT1024 SSL_RSA_EXPORT1024_WITH_RC4_56_SHA
RC4_MD5_EXPORT SSL_RSA_EXPORT_WITH_RC4_40_MD5
RC4_MD5_US SSL_RSA_WITH_RC4_128_MD5
RC4_SHA_US SSL_RSA_WITH_RC4_128_SHA
TLS_RSA_WITH_3DES_EDE_CBC_SHA SSL_RSA_WITH_3DES_EDE_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA SSL_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA SSL_RSA_WITH_AES_256_CBC_SHA
TLS_RSA_WITH_DES_CBC_SHA SSL_RSA_WITH_DES_CBC_SHA

92 Message Service Client for C/C++

Table 21. Available CipherSpecs and their JSSE CipherSuite equivalents (continued)
CipherSpec Equivalent JSSE CipherSuite
TRIPLE_DES_SHA_US SSL_RSA_WITH_3DES_EDE_CBC_SHA

Note: A one-to-one mapping for the CipherSuite name

SSL_RSA_WITH_3DES_EDE_CBC_SHA or SSL_RSA_WITH_DES_CBC_SHA
must account for the setting of the property
XMSC_WMQ_SSL_FIPSREQUIRED and apply an heuristic.

If you specify SSL_RSA_WITH_3DES_EDE_CBC_SHA or

SSL_RSA_WITH_DES_CBC_SHA for the property
XMSC_WMQ_SSL_CIPHER_SUITE, and there is no value for
XMSC_WMQ_SSL_CIPHER_SPEC, a value for XMSC_WMQ_SSL_CIPHER_SPEC is
chosen according to the following tables.

The values used for XMSC_WMQ_SSL_CIPHER_SPEC when you specify

SSL_RSA_WITH_3DES_EDE_CBC_SHA for the XMSC_WMQ_SSL_CIPHER_SUITE
property are shown in the following table:
Table 22. Values used for XMSC_WMQ_SSL_CIPHER_SPEC when you specify
SSL_RSA_WITH_3DES_EDE_CBC_SHA for the XMSC_WMQ_SSL_CIPHER_SUITE property
Input: XMSC_WMQ_SSL_FIPSREQUIRED value Output: XMSC_WMQ_SSL_CIPHER_SPEC chosen
xmsFALSE (that is, MQSSL_FIPS_NO) TRIPLE_DES_SHA_US
xmsTRUE (that is, MQSSL_FIPS_YES) TLS_RSA_WITH_3DES_EDE_CBC_SHA

The values used for XMSC_WMQ_SSL_CIPHER_SPEC when you specify

SSL_RSA_WITH_DES_CBC_SHA for the XMSC_WMQ_SSL_CIPHER_SUITE
property are shown in the following table:
Table 23. Values used for XMSC_WMQ_SSL_CIPHER_SPEC when you specify SSL_RSA_WITH_DES_CBC_SHA
for the XMSC_WMQ_SSL_CIPHER_SUITE property
Input: XMSC_WMQ_SSL_FIPSREQUIRED value Output: XMSC_WMQ_SSL_CIPHER_SPEC chosen
xmsFALSE (that is, MQSSL_FIPS_NO) DES_SHA_EXPORT
xmsTRUE (that is, MQSSL_FIPS_YES) TLS_RSA_WITH_DES_CBC_SHA

Secure connections to a WebSphere service integration bus

messaging engine
To enable an XMS C/C++ application to make secure connections to a WebSphere
service integration bus messaging engine, the relevant properties must be defined
in the ConnectionFactory object.

XMS provides SSL and HTTPS support for connections to a WebSphere service
integration bus. SSL and HTTPS provide secure connections for authentication and
confidentiality.

Like WebSphere security, XMS security is configured with respect to JSSE security
standards and naming conventions, which include the use of CipherSuites to
specify the algorithms that are used when negotiating a secure connection. The
protocol used in the encryption negotiation can be either SSL or TLS, depending on
which CipherSuite you specify in the ConnectionFactory object.

Chapter 11. Securing communications for XMS applications 93

 The security capabilities for XMS C/C++ application are provided by IBM’s
standard security enablement component, Global Security Kit (GSKit). XMS
configures the relevant GSKit options by means of properties set on the XMS
ConnectionFactory object. These properties must be specified regardless of whether
the ConnectionFactory object is an administered object.

Table 24 lists the properties that must be defined in the ConnectionFactory object.
Table 24. Properties of ConnectionFactory for secure connections to a WebSphere service integration bus messaging
engine
Name of property Description
XMSC_WPM_SSL_CIPHER_SUITE The name of the CipherSuite to be used on an SSL or TLS
connection to a WebSphere service integration bus messaging
engine. The protocol used in negotiating the secure
connection depends on the specified CipherSuite.
XMSC_WPM_SSL_KEY_REPOSITORY A path to the file that is the keyring file containing the public
or private keys to be used in the secure connection.
XMSC_WPM_SSL_KEYRING_LABEL The certificate to be used when authenticating with the server.
XMSC_WPM_SSL_KEYRING_PW The password for the keyring file.
XMSC_WPM_SSL_KEYRING_STASH_FILE The name of a binary file containing the password of the key
repository file.
XMSC_WPM_SSL_FIPS_REQUIRED The value of this property determines whether an application
can or cannot use non-FIPS compliant cipher suites. If this
property is set to true, only FIPS algorithms are used for the
client-server connection.

The following is an example of ConnectionFactory properties for secure

connections to a WebSphere integration messaging engine:
cf.setStringProperty(XMSC_WPM_PROVIDER_ENDPOINTS, host_name:port_number:chain_name);
cf.setStringProperty(XMSC_WPM_SSL_KEY_REPOSITORY, key_repository_pathname);
cf.setStringProperty(XMSC_WPM_TARGET_TRANSPORT_CHAIN, transport_chain);
cf.setStringProperty(XMSC_WPM_SSL_CIPHER_SUITE, cipher_suite);
cf.setStringProperty(XMSC_WPM_SSL_KEYRING_STASH_FILE, stash_file_pathname);

Where chain_name should be set to either BootstrapTunneledSecureMessaging or

BootstrapSecureMessaging, and port_number is the number of the port on which
the bootstrap server listens for incoming requests.

The following is an example of ConnectionFactory properties for secure

connections to a WebSphere integration messaging engine with sample values
inserted:
/* CF properties needed for an SSL connection */
cf.setStringProperty(XMSC_WPM_PROVIDER_ENDPOINTS,"localhost:7286:BootstrapSecureMessaging");
cf.setStringProperty(XMSC_WPM_TARGET_TRANSPORT_CHAIN,"InboundSecureMessaging");
cf.setStringProperty(XMSC_WPM_SSL_KEY_REPOSITORY,"C:\\Program Files\\IBM\\gsk7\\bin\\XMSkey.kdb");
cf.setStringProperty(XMSC_WPM_SSL_KEYRING_STASH_FILE,"C:\\Program Files\\IBM\\gsk7\\bin\\XMSkey.sth");
cf.setStringProperty(XMSC_WPM_SSL_CIPHER_SUITE,"SSL_RSA_EXPORT_WITH_RC4_40_MD5");

CipherSuite and CipherSpec name mappings for connections

to a WebSphere service integration bus
Because GSKit uses CipherSpecs rather than CipherSuites, the JSSE-style
CipherSuite names specified in the XMSC_WPM_SSL_CIPHER_SUITE property
must be mapped to the GSKit-style CipherSpec names.

94 Message Service Client for C/C++

 Table 25 lists the equivalent CipherSpec for each recognized CipherSuite.
Table 25. Available CipherSuites and their equivalent CipherSpecs
CipherSuite CipherSpec equivalent
SSL_RSA_WITH_NULL_MD5 NULL_MD5
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 RC2_MD5_EXPORT
SSL_RSA_EXPORT_WITH_RC4_40_MD5 RC4_MD5_EXPORT
SSL_RSA_WITH_RC4_128_MD5 RC4_MD5_US
SSL_RSA_WITH_NULL_SHA NULL_SHA
SSL_RSA_EXPORT1024_WITH_RC4_56_SHA RC4_56_SHA_EXPORT1024
SSL_RSA_WITH_RC4_128_SHA RC4_SHA_US
SSL_RSA_WITH_DES_CBC_SHA DES_SHA_EXPORT
SSL_RSA_EXPORT1024_WITH_DES_CBC_SHA DES_SHA_EXPORT1024
SSL_RSA_FIPS_WITH_DES_CBC_SHA FIPS_WITH_DES_CBC_SHA
SSL_RSA_WITH_3DES_EDE_CBC_SHA TRIPLE_DES_SHA_US
SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA FIPS_WITH_3DES_EDE_CBC_SHA
TLS_RSA_WITH_DES_CBC_SHA TLS_RSA_WITH_DES_CBC_SHA
TLS_RSA_WITH_3DES_EDE_CBC_SHA TLS_RSA_WITH_3DES_EDE_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA

Chapter 11. Securing communications for XMS applications 95

96 Message Service Client for C/C++
Chapter 12. XMS messages
This chapter describes the structure and content of XMS messages and explains
how applications process XMS messages.

This chapter contains the following sections:

v “Parts of an XMS message”
v “Header fields in an XMS message”
v “Properties of an XMS message” on page 98
v “The body of an XMS message” on page 101
v “Message selectors” on page 106
v “Mapping XMS messages onto WebSphere MQ messages” on page 107

Parts of an XMS message

An XMS message consists of a header, a set of properties, and a body.
Header
The header of a message contains fields, and all messages contain the same
set of header fields. XMS and applications use the values of the header
fields to identify and route messages. For more information about header
fields, see “Header fields in an XMS message.”
Set of properties
The properties of a message specify additional information about the
message. Although all messages have the same set of header fields, every
message can have a different set of properties. For more information, see
“Properties of an XMS message” on page 98.
Body The body of a message contains application data. For more information,
see “The body of an XMS message” on page 101.

An application can select which messages it wants to receive. It does this by using
message selectors, which specify the selection criteria. The criteria can be based on
the values of certain header fields and the values of any of the properties of a
message. For more information about message selectors, see “Message selectors”
on page 106.

Header fields in an XMS message

To allow an XMS application to exchange messages with a WebSphere JMS
application, the header of an XMS message contains the JMS message header
fields.

The names of these header fields commence with the prefix JMS. For a description
of the JMS message header fields, see the Java Message Service Specification, Version
1.1.

XMS implements the JMS message header fields as attributes of a Message object.
Each header field has its own methods for setting and getting its value. For a
description of these methods, see “Message” on page 179 for C, or “Message” on
page 317 for C++. A header field is always readable and writable.

© IBM Corporation 2005 97

 Table 26 lists the JMS message header fields and indicates how the value of each
field is set for a transmitted message. Some of the fields are set automatically by
XMS when an application sends a message or, in the case of JMSRedelivered, when
an application receives a message.
Table 26. JMS message header fields
Name of the JMS message How the value is set for a transmitted message (in the
header field format method [class])
JMSCorrelationID Set JMSCorrelationID [Message]
JMSDeliveryMode Send [MessageProducer]
JMSDestination Send [MessageProducer]
JMSExpiration Send [MessageProducer]
JMSMessageID Send [MessageProducer]
JMSPriority Send [MessageProducer]
JMSRedelivered Receive [MessageConsumer]
JMSReplyTo Set JMSReplyTo [Message]
JMSTimestamp Send [MessageProducer]
JMSType Set JMSType [Message]

Properties of an XMS message

XMS supports three kinds of message property: JMS defined properties, IBM
defined properties, and application-defined properties.

An XMS application can exchange messages with a WebSphere JMS application

because XMS supports the following predefined properties of a Message object:
v The same JMS-defined properties that WebSphere JMS supports. The names of
these properties begin with the prefix JMSX.
v The same IBM-defined properties that WebSphere JMS supports. The names of
these properties begin with the prefix JMS_IBM_.

Each predefined property has two names:

v A JMS name, for a JMS-defined property, or a WebSphere JMS name, for an
IBM-defined property.
This is the name by which the property is known in JMS or WebSphere JMS, and
it is also the name that is transmitted with a message that has this property. An
XMS application uses this name to identify the property in a message selector
expression.
v An XMS name to identify the property in all situations except in a message
selector expression. Each XMS name is defined as a named constant in one of
the header files, xmsc.h, xmsc_rtt.h, xmsc_wmq.h, or xmsc_wpm.h. The value of the
named constant is the corresponding JMS or WebSphere JMS name

In addition to the predefined properties, an XMS application can create and use its
own set of message properties. These properties are called application defined
properties.

For information about getting and setting the properties of messages, see “Object
Properties in C” on page 64 or “Properties in C++” on page 73.

98 Message Service Client for C/C++

 After an application creates a message, the properties of the message are readable
and writable. The properties remain readable and writable after the application
sends the message. When an application receives a message, the properties of the
message are read-only. If an application calls the Clear Properties method of the
Message class when the properties of a message are read-only, the properties
become readable and writable. The method also clears the properties.

The received message, when forwarded after clearing up the message properties,
will behave in a manner consistent with the behavior of forwarding a standard
WMQ XMS for C/C++ BytesMessage with message properties cleared up.

This is, however, not recommended since the following properties will be lost:
v JMS_IBM_Encoding property value, implying that the message data cannot be
decoded meaningfully.
v JMS_IBM_Format property value, implying that the header chaining between the
(MQMD or the new MQRFH2) message header and existing headers would be
broken.

To determine the values of all the properties of a message, an application can call
the Get Properties method of the Message class. The method creates an iterator
that encapsulates a list of Property objects, where each Property object represents a
property of the message. The application can then use the methods of the Iterator
class to retrieve each Property object in turn, and it can use the methods of the
Property class to retrieve the name, data type, and value of each property. For a
sample fragment of C code that performs a similar function, see “Iterators” on
page 54.

JMS-defined properties of a message

Several JMS-defined properties of a message are supported by both XMS and
WebSphere JMS.

Table 27 lists the JMS-defined properties of a message that are supported by both
XMS and WebSphere JMS. For a description of the JMS-defined properties, see Java
Message Service Specification, Version 1.1. The JMS-defined properties are not valid
for a real-time connection to a broker.

The table specifies the data type of each property and indicates how the value of
the property is set for a transmitted message. Some of the properties are set
automatically by XMS when an application sends a message or, in the case of
JMSXDeliveryCount, when an application receives a message.
Table 27. JMS-defined properties of a message
XMS name of the JMS How the value is set for a transmitted
defined property JMS name Data type message (in the format method [class])
JMSX_APPID JMSXAppID String Send [MessageProducer]
JMSX_DELIVERY_COUNT JMSXDeliveryCount xmsINT Receive [MessageConsumer]
JMSX_GROUPID JMSXGroupID String Set String Property [PropertyContext]
JMSX_GROUPSEQ JMSXGroupSeq xmsINT Set Integer Property [PropertyContext]
JMSX_USERID JMSXUserID String Send [MessageProducer]

Chapter 12. XMS messages 99

 IBM-defined properties of a message
Several IBM-defined properties of a message are supported by XMS and
WebSphere JMS.

Table 28 lists the IBM defined properties of a message that are supported by both
XMS and WebSphere JMS. For more information about the IBM-defined properties,
see WebSphere MQ Using Java or the WebSphere Application Server Information
Center.

The table specifies the data type of each property and indicates how the value of
the property is set for a transmitted message. Some of the properties are set
automatically by XMS when an application sends a message.
Table 28. IBM-defined properties of a message
How the value is set
for a transmitted
XMS name of the IBM defined message (in the
property WebSphere JMS name Data type format method [class])
JMS_IBM_CHARACTER_SET JMS_IBM_Character_Set xmsINT Set Integer Property
[PropertyContext]
JMS_IBM_ENCODING JMS_IBM_Encoding xmsINT Set Integer Property
[PropertyContext]
JMS_IBM_EXCEPTIONMESSAGE JMS_IBM_ExceptionMessage String Receive
[MessageConsumer]
JMS_IBM_EXCEPTIONREASON JMS_IBM_ExceptionReason xmsINT Receive
[MessageConsumer]
JMS_IBM_EXCEPTIONTIMESTAMP JMS_IBM_ExceptionTimestamp xmsLONG Receive
[MessageConsumer]
JMS_IBM_EXCEPTIONPROBLEM JMS_IBM_ExceptionProblemDestination String Receive
DESTINATION [MessageConsumer]
JMS_IBM_FEEDBACK JMS_IBM_Feedback xmsINT Set Integer Property
[PropertyContext]
JMS_IBM_FORMAT JMS_IBM_Format String Set String Property
[PropertyContext]
JMS_IBM_LAST_MSG_IN_GROUP JMS_IBM_Last_Msg_In_Group xmsBOOL Set Integer Property
[PropertyContext]
JMS_IBM_MSGTYPE JMS_IBM_MsgType xmsINT Set Integer Property
[PropertyContext]
JMS_IBM_PUTAPPLTYPE JMS_IBM_PutApplType xmsINT Send
[MessageProducer]
JMS_IBM_PUTDATE JMS_IBM_PutDate String Send
[MessageProducer]
JMS_IBM_PUTTIME JMS_IBM_PutTime String Send
[MessageProducer]
JMS_IBM_REPORT_COA JMS_IBM_Report_COA xmsINT Set Integer Property
[PropertyContext]
JMS_IBM_REPORT_COD JMS_IBM_Report_COD xmsINT Set Integer Property
[PropertyContext]
JMS_IBM_REPORT_DISCARD_MSG JMS_IBM_Report_Discard_Msg xmsINT Set Integer Property
[PropertyContext]

100 Message Service Client for C/C++

Table 28. IBM-defined properties of a message (continued)
How the value is set
for a transmitted
XMS name of the IBM defined message (in the
property WebSphere JMS name Data type format method [class])
JMS_IBM_REPORT_EXCEPTION JMS_IBM_Report_Exception xmsINT Set Integer Property
[PropertyContext]
JMS_IBM_REPORT_EXPIRATION JMS_IBM_Report_Expiration xmsINT Set Integer Property
[PropertyContext]
JMS_IBM_REPORT_NAN JMS_IBM_Report_NAN xmsINT Set Integer Property
[PropertyContext]
JMS_IBM_REPORT_PAN JMS_IBM_Report_PAN xmsINT Set Integer Property
[PropertyContext]
JMS_IBM_REPORT_PASS_CORREL_ JMS_IBM_Report_Pass_Correl_ID xmsINT Set Integer Property
ID [PropertyContext]
JMS_IBM_REPORT_PASS_MSG_ID JMS_IBM_Report_Pass_Msg_ID xmsINT Set Integer Property
[PropertyContext]
JMS_IBM_SYSTEM_MESSAGEID JMS_IBM_System_MessageID String Send
[MessageProducer]

Application-defined properties of a message

An XMS application can create and use its own set of message properties. When
an application sends a message, these properties are also transmitted with the
message. A receiving application, using message selectors, can then select which
messages it wants to receive based on the values of these properties.

To allow a WebSphere JMS application to select and process messages sent by an

XMS application, the name of an application-defined property must conform to the
rules for forming identifiers in message selector expressions, as documented in
WebSphere MQ Using Java. The value of an application-defined property must have
one of the following data types: xmsBOOL, xmsSBYTE, xmsSHORT, xmsINT,
xmsLONG, xmsFLOAT, xmsDOUBLE, or String (or character array, if you are
using the C interface).

The body of an XMS message

The body of a message contains application data. However, a message can have no
body, and comprise only the header fields and properties.

XMS supports five types of message body:

Bytes The body contains a stream of bytes. A message with this type of body is
called a bytes message. The BytesMessage class for C or C++ contains the
methods to process the body of a bytes message. For more information, see
“Bytes messages” on page 103.
Map The body contains a set of name-value pairs, where each value has an
associated data type. A message with this type of body is called a map
message. The MapMessage class for C or C++ contains the methods to
process the body of a map message. For more information, see “Map
messages” on page 104.
Object
The body contains a serialized Java or .NET object. A message with this

Chapter 12. XMS messages 101

 type of body is called an object message. The ObjectMessage class for C or
C++ contains the methods to process the body of an object message. For
more information, see “Object messages” on page 104.
Stream
The body contains a stream of values, where each value has an associated
data type. A message with this type of body is called a stream message. The
StreamMessage class for C or C++contains the methods to process the
body of a stream message. For more information, see “Stream messages”
on page 105.
Text The body contains a string. A message with this type of body is called a
text message. The TextMessage class for C or C++contains the methods to
process the body of a text message. For more information, see “Text
messages” on page 105.

In the C interface, XMS returns a message handle to an application when the

application creates a message. The application can use this handle to call any of
the methods of the Message class and any of the methods of the BytesMessage,
MapMessage, ObjectMessage, StreamMessage, or TextMessage class, whichever is
appropriate for the type of message body. However, if an application tries to call a
method that is inappropriate for the type of message body, the call fails and XMS
returns an error.

A C application can call the xmsMsgGetTypeId() function to determine the body

type of a message. The function returns one of the following values:
XMS_MESSAGE_TYPE_BASE
If the message has no body
XMS_MESSAGE_TYPE_BYTES
If the message is a bytes message
XMS_MESSAGE_TYPE_MAP
If the message is a map message
XMS_MESSAGE_TYPE_OBJECT
If the message is an object message
XMS_MESSAGE_TYPE_STREAM
If the message is a stream message
XMS_MESSAGE_TYPE_TEXT
If the message is a text message

In the C++ interface, BytesMessage, MapMessage, ObjectMessage, StreamMessage,

and TextMessage are subclasses of the Message class.

For information about the size and maximum and minimum values of each of
these data types, see Table 9 on page 52.

Data types for elements of application data

To ensure that an XMS application can exchange messages with a WebSphere MQ
JMS application, both the applications must be able to interpret the application
data in the body of a message in the same way.

For this reason, each element of application data written in the body of a message
by an XMS application must have one of the data types listed in Table 29 on page
103. For each XMS data type, the table shows the compatible Java data type. XMS

102 Message Service Client for C/C++

 provides the methods to write elements of application data only with these data
types.
Table 29. XMS data types that are compatible with Java data types
Compatible Java
XMS data type Represents data type
xmsBOOL The boolean value xmsTRUE or xmsFALSE boolean
xmsCHAR16 Double byte character char
xmsSBYTE Signed 8-bit integer byte
xmsSHORT Signed 16-bit integer short
xmsINT Signed 32-bit integer int
xmsLONG Signed 64-bit integer long
xmsFLOAT Signed floating point number float
xmsDOUBLE Signed double precision floating point number double
String String of characters String

For information about the size, maximum value and minimum value of each of
these data types, see “XMS primitive types” on page 52.

Bytes messages
The body of a bytes message contains a stream of bytes. The body contains only
the actual data, and it is the responsibility of the sending and receiving
applications to interpret this data.

Bytes messages are particularly useful if an XMS application needs to exchange

messages with applications that are not using the XMS or JMS application
programming interface.

After an application creates a bytes message, the body of the message is write-only.
The application assembles the application data into the body by calling the
appropriate write methods of the BytesMessage class. Each time the application
writes a value to the bytes message stream, the value is assembled immediately
after the previous value written by the application. XMS maintains an internal
cursor to remember the position of the last byte that was assembled.

When the application sends the message, the body of the message becomes
read-only. In this mode, the application can send the message repeatedly.

When an application receives a bytes message, the body of the message is

read-only. The application can use the appropriate read methods of the
BytesMessage class to read the contents of the bytes message stream. The
application reads the bytes in sequence, and XMS maintains an internal cursor to
remember the position of the last byte that was read.

In the case of C only, an application can skip over bytes without reading them by
calling a read function with a null pointer for the value parameter or by calling
xmsBytesMsgReadBytes(). For information about how to skip over a string, see
“xmsBytesMsgReadUTF – Read UTF String” on page 139.

If an application calls the Reset method of the BytesMessage class when the body
of a bytes message is write-only, the body becomes read-only. The method also
repositions the cursor at the beginning of the bytes message stream.

Chapter 12. XMS messages 103

 If an application calls the Clear Body method of the Message class for C or C++
when the body of a bytes message is read-only, the body becomes write-only. The
method also clears the body.

Map messages
The body of a map message contains a set of name-value pairs, where each value
has an associated data type.

In each name-value pair, the name is a string that identifies the value, and the
value is an element of application data that has one of the XMS data types listed in
Table 29 on page 103. The order of the name-value pairs is not defined. The
MapMessage class contains the methods to set and get name-value pairs.

An application can access a name-value pair randomly by specifying its name.

Alternatively, a C or C++ application can access the name-value pairs sequentially
using an iterator. The application can call the Get Name-Value Pairs method of the
MapMessage class to create an iterator that encapsulates a list of Property objects,
where each Property object encapsulates a name-value pair. The application can
then use the methods of the Iterator class to retrieve each Property object in turn,
and it can use the methods of the Property class to retrieve the name, data type,
and value of each name-value pair. Although a name-value pair is not a property,
the methods of the Property class treat a name-value pair like a property.
CONFIRM THAT WHOLE OF THIS APPLIES TO C/C++

When an application gets the value of a name-value pair, the value can be
converted by XMS into another data type. For example, to get an integer from the
body of a map message, an application can call the Get String method of the
MapMessage class, which returns the integer as a string. The supported
conversions are the same as those that are supported when XMS converts a
property value from one data type to another. For more information about the
supported conversions, see “Implicit conversion of a property value from one data
type to another” on page 52.

After an application creates a map message, the body of the message is readable
and writable. The body remains readable and writable after the application sends
the message. When an application receives a map message, the body of the
message is read-only. If an application calls the Clear Body method of the Message
class when the body of a map message is read-only, the body becomes readable
and writable. The method also clears the body.

Object messages
The body of an object message contains a serialized Java or .NET object.

An XMS application can receive an object message, change its header fields and
properties, and then send it to another destination. An application can also copy
the body of an object message and use it to form another object message. XMS
treats the body of an object message as an array of bytes.

After an application creates an object message, the body of the message is readable
and writable. The body remains readable and writable after the application sends
the message. When an application receives an object message, the body of the
message is read-only. If an application calls the Clear Body method of the Message
class for C or C++ when the body of an object message is read-only, the body
becomes readable and writable. The method also clears the body.

104 Message Service Client for C/C++

Stream messages
The body of a stream message contains a stream of values, where each value has
an associated data type.

The data type of a value is one of the XMS data types listed in Table 29 on page
103.

After an application creates a stream message, the body of the message is

write-only. The application assembles the application data into the body by calling
the appropriate write methods of the StreamMessage class for C or C++. Each time
the application writes a value to the message stream, the value and its data type
are assembled immediately after the previous value written by the application.
XMS maintains an internal cursor to remember the position of the last value that
was assembled.

When the application sends the message, the body of the message becomes
read-only. In this mode, the application can send the message multiple times.

When an application receives a stream message, the body of the message is

read-only. The application can use the appropriate read methods of the
StreamMessage class for C or C++ to read the contents of the message stream. The
application reads the values in sequence, and XMS maintains an internal cursor to
remember the position of the last value that was read.

Using the C interface only, an application can skip over a value without reading it
by calling a read function with a null pointer for the value parameter or by calling
xmsStreamMsgReadBytes() or xmsStreamMsgReadObject() for the buffer parameter.
For information about how to skip over a value that is a string, see
“xmsStreamMsgReadString – Read String” on page 262.

When an application reads a value from the message stream, the value can be
converted by XMS into another data type. For example, to read an integer from the
message stream, an application can call the Read String method, which returns the
integer as a string. The supported conversions are the same as those that are
supported when XMS converts a property value from one data type to another. For
more information about the supported conversions, see “Implicit conversion of a
property value from one data type to another” on page 52.

If an error occurs while an application is attempting to read a value from the

message stream, the cursor is not advanced. The application can recover from the
error by attempting to read the value as another data type.

If an application calls the Reset method of the StreamMessage class for C or C++
when the body of a stream message is write-only, the body becomes read-only. The
method also repositions the cursor at the beginning of the message stream.

If an application calls the Clear Body method of the Message class for C or C++
when the body of a stream message is read-only, the body becomes write-only. The
method also clears the body.

Text messages
The body of a text message contains a string.

After an application creates a text message, the body of the message is readable
and writable. The body remains readable and writable after the application sends

Chapter 12. XMS messages 105

 the message. When an application receives a text message, the body of the message
is read-only. If an application calls the Clear Body method of the Message class for
C or C++ when the body of a text message is read-only, the body becomes
readable and writable. The method also clears the body.

Message selectors
An XMS application uses messages selectors to select the messages it wants to
receives.

When an application creates a message consumer, it can associate a message

selector expression with the consumer. The message selector expression specifies
the selection criteria.

When an application is connecting to WebSphere MQ V7.0 queue manager the

message selection is done at the queue manager side. XMS does not do any
selection and simply delivers the message it received from the queue manager thus
providing better performance.

However when an application is connecting to WebSphere MQ V6.0 and below,

WebSphere Event Broker, or WebSphere Message Broker, WebSphere Service
Integration Bus XMS determines whether each incoming message satisfies the
selection criteria. If a message satisfies the selection criteria, XMS delivers the
message to the message consumer. If a message does not meet the selection
criteria, XMS does not deliver the message and, in the point-to-point domain, the
message remains on the queue.

An application can create more than one message consumer, each with its own
message selector expression. If an incoming message meets the selection criteria of
more than one message consumer, XMS delivers the message to each of these
consumers.

A message selector expression can reference the following properties of a message:

v JMS-defined properties
v IBM-defined properties
v Application-defined properties
It can also reference the following message header fields:
v JMSCorrelationID
v JMSDeliveryMode
v JMSMessageID
v JMSPriority
v JMSTimestamp
v JMSType
A message selector expression, however, cannot reference data in the body of a
message.

Here is an example of a message selector expression:

JMSPriority > 3 AND manufacturer = 'Jaguar' AND model in ('xj6','xj12')

XMS delivers a message to a message consumer with this message selector

expression only if the message has a priority greater than 3; an application-defined

106 Message Service Client for C/C++

 property, manufacturer, with a value of Jaguar; and another application
defined-property, model, with a value of xj6 or xj12.

The syntax rules for forming a message selector expression in XMS are the same as
those in WebSphere MQ JMS. For information about how to construct a message
selector expression, see WebSphere MQ Using Java. Note that, in a message selector
expression, the names of JMS-defined properties must be the JMS names, and the
names of IBM-defined properties must be the WebSphere MQ JMS names. You
cannot use the XMS names in a message selector expression.

Mapping XMS messages onto WebSphere MQ messages

The JMS header fields and properties of an XMS message are mapped onto fields
in the header structures of a WebSphere MQ message.

When an XMS application is connected to a WebSphere MQ queue manager,

messages sent to the queue manager are mapped onto WebSphere MQ messages in
the same way that WebSphere MQ JMS messages are mapped onto WebSphere MQ
messages in similar circumstances.

If the XMSC_WMQ_TARGET_CLIENT property of a Destination object is set to

XMSC_WMQ_TARGET_DEST_JMS, the JMS header fields and properties of a
message sent to the destination are mapped onto fields in the MQMD and
MQRFH2 header structures of the WebSphere MQ message. Setting the
XMSC_WMQ_TARGET_CLIENT property in this way assumes that the application
that receives the message can handle an MQRFH2 header. The receiving
application might therefore be another XMS application, a WebSphere MQ JMS
application, or a native WebSphere MQ application that has been designed to
handle an MQRFH2 header.

If the XMSC_WMQ_TARGET_CLIENT property of a Destination object is set to

XMSC_WMQ_TARGET_DEST_MQ instead, the JMS header fields and properties of
a message sent to the destination are mapped onto fields in the MQMD header
structure of the WebSphere MQ message. The message does not contain an
MQRFH2 header, and any JMS header fields and properties that cannot be mapped
onto fields in the MQMD header structure are ignored. The application that
receives the message can therefore be a native WebSphere MQ that has not been
designed to handle an MQRFH2 header.

WebSphere MQ messages received from a queue manager are mapped onto XMS
messages in the same way that WebSphere MQ messages are mapped onto
WebSphere MQ JMS messages in similar circumstances.

If an incoming WebSphere MQ message has an MQRFH2 header, the resulting

XMS message has a body whose type is determined by the value of the Msd
property contained in the mcd folder of the MQRFH2 header. If the Msd property
is not present in the MQRFH2 header, or if the WebSphere MQ message has no
MQRFH2 header, the resulting XMS message has a body whose type is determined
by the value of the Format field in the MQMD header. If the Format field is set to
MQFMT_STRING, the XMS message is a text message. Otherwise, the XMS
message is a bytes message. If the WebSphere MQ message has no MQRFH2
header, only those JMS header fields and properties that can be derived from fields
in the MQMD header are set.

For more information about mapping WebSphere MQ JMS messages onto

WebSphere MQ messages, see WebSphere MQ Using Java.

Chapter 12. XMS messages 107

108 Message Service Client for C/C++
Part 3. Troubleshooting for XMS applications
Chapter 13. Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Problem determination for C/C++ applications . . . . . . . . . . . . . . . . . . . . . . . 111
Error conditions that can be handled at run time . . . . . . . . . . . . . . . . . . . . . 111
Error conditions that cannot be handled at run time . . . . . . . . . . . . . . . . . . . . 112
Repeatable failures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
FFDC and trace configuration for C/C++ applications . . . . . . . . . . . . . . . . . . . . . 113
Tips for troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

© Copyright IBM Corp. 2005, 2009 109

110 Message Service Client for C/C++
Chapter 13. Troubleshooting
This chapter provides information to help you to detect and deal with problems.

About this task

This chapter contains the following sections:

v “Problem determination for C/C++ applications”
v “FFDC and trace configuration for C/C++ applications” on page 113
v “Tips for troubleshooting” on page 114

Problem determination for C/C++ applications

This section provides information to help you to detect and deal with problems in
XMS C/C++ applications.

This section contains the following subsections:

v “Error conditions that can be handled at run time”
v “Error conditions that cannot be handled at run time” on page 112
v “Repeatable failures” on page 112

Error conditions that can be handled at run time

Return codes from API calls are error conditions that can be handled at run time.
The way in which you deal with this type of error depends on whether you are
using the C or C++ API.

How to detect errors at run time

If an application calls a C API function and the call fails, a response with a return
code other than XMS_OK is returned with an XMS error block containing more
information about the reason for the failure. For further details, see “Return codes”
on page 67 and “ErrorBlock” on page 157.

The C++ API throws an exception when a method is used.

An application uses an exception listener to be notified asynchronously of a

problem with a connection. The exception listener is supplied to, and is initialized
using, the XMS C or C++ API. For further information, see “Message and
exception listener functions in C” on page 68 and “Message and exception listeners
in C++” on page 78.

How to handle errors at run time

Some error conditions are an indication that some resource is unavailable, and the
action that an application can take depends on the XMS function that the
application is calling. For example, if a connection fails to connect to the server,
then the application may wish to retry periodically until a connection is made. An
XMS error block or exception might not contain enough information to determine
what action to take, and, in these situations, there is often a linked error block or
exception that contains more specific diagnostic information.

© IBM Corporation 2005 111

 In the C API, always test for a response with a return code other than XMS_OK,
and always pass an error block on the API call. The action taken usually depends
on which API function is the application using. For further details, see “Error
handling in C” on page 67.

In the C++ API, always include calls to methods in a try block and, to catch all
types of XMS exception, specify the Exception class in the catch construct. For
further details, see “Error handling in C++” on page 76.

The exception listener is an asynchronous error condition path that can be started
at any time. When the exception listener function is started, on its own thread, it is
usually an indication of a more severe failure than a normal XMS API error
condition. Any appropriate action may be taken, but you must be careful to follow
the rules for the XMS threading model as described in “The threading model” on
page 35.

Error conditions that cannot be handled at run time

First Failure Data Capture (FFDC) records can be written in the current working
directory if the XMS library code finds a condition that it cannot handle. If an
FFDC record is written, this often indicates a serious condition, and it is likely that
XMS functions incorrectly because of the same unhandleable condition.

The type of FFDC record that XMS generates depends on the type of failure that
has occurred. There are two distinct types of FFDC record:
v The first type of FFDC record is sometimes, but not always, generated as a result
of a user’s own application causing a failure, and usually results in the
application being terminated. This type of failure is often characterized in the
FFDC record as ’Unhandled Exception detected’ or ’SIGNAL xx received’. The
FFDC record contains detailed information describing the cause of the failure
and also contains a function stack back-trace which shows the failing function
stack.
v The second type of FFDC record is generated by XMS itself in cases where it has
detected an unexpected condition. Generally, the application continues to run
but, depending upon the reason for which the FFDC record was generated, XMS
API function calls may return negative responses.

Repeatable failures
If you are dealing with a repeatable failure, it might be necessary for you to
capture product trace over an extended period of time to allow the problem to be
diagnosed.

If you need to provide a product trace, either enable trace as advised by the IBM
Support Center representative or as described in “FFDC and trace configuration for
C/C++ applications” on page 113.

It is important that the size of the trace file is large enough to capture the trace
while the repeatable problem occurs. To set the size of the trace file, either use
environment variable XMS_TRACE_FILE_SIZE or use the gxisc executable
command as follows:
alter trace(enabled) tracesize(xxxx)

Refer to Table 30 on page 113 for the descriptions of various environment variable
settings for C/C++ trace.

112 Message Service Client for C/C++

 After the failure that you are tracing has occurred, you must either copy the trace
files or disable the trace using the following command:
gxisc trace(disabled)

This is because trace wraps, which means that leaving trace on would eventually
cause the trace at the point of failure to be lost.

XMS product trace is written in compressed form to gain a performance

advantage. You can format the trace files using the gxitrcfmt tool.

If you are experiencing problems where you do not have access to the information
provided in the error block, you may want to enable the
XMS_FFDC_EXCEPTIONS environment variable. This produces an FFDC record
whenever the XMS API returns an error from a function. The FFDC record contains
full details of the XMS error block to assist in debugging failures.

Refer to “FFDC and trace configuration for C/C++ applications” for more
information on the gxisc and gxitrcfmt commands.

FFDC and trace configuration for C/C++ applications

First Failure Data Capture (FFDC) records are stored in human readable text files
with names that start with the prefix xmsffdc. Trace files are binary and can be
formatted. Trace file names start with the prefix xms.

XMS creates FFDC records and trace files in the current working directory, unless
you specify an alternative location by configuring an XMS environment variable as
described below.

Trace configuration using XMS environment variables

To configure trace for an XMS C or C++ application, set the following XMS
environment variables before running the application:
Table 30. Environment variable settings for C/C++ trace
Environment variables Default Settings Meaning
XMS_TRACE_ON Not applicable normal Selected components are traced.
full All components are traced.
partial A comma separated list of component identifiers to
trace. For example, ″partial,osa,cal″ only traces XMS
components gxiosa and gxical. Use full trace to show
the components that can be traced.
XMS_TRACE_FILE_PATH Current /dirpath/ The directory path that trace and FFDC records are
working written to.
directory
XMS creates FFDC and trace files in the current
working directory, unless you specify an alternative
location by setting the environment variable
XMS_TRACE_FILE_PATH to the fully qualified path
name of the directory where you want XMS to create
the FFDC and trace files. You must set this environment
variable before you start the application that you want
to trace, and you must make sure that the user identifier
under which the application runs has the authority to
write to the directory where XMS creates the FFDC and
trace files.

Chapter 13. Troubleshooting 113

Table 30. Environment variable settings for C/C++ trace (continued)
Environment variables Default Settings Meaning
XMS_TRACE_FILE_SIZE 200000 integer The maximum size that XMS product trace can grow to
(in kilobytes), that is, 10 represents 10,000 bytes.
XMS_TRACE_FILE_NUMBER 4 integer The number of files that can be used to store trace
records. (200000 / 4 = 50000 bytes per file.)

Dynamic trace configuration

To configure trace dynamically, use the executable gxisc. You can use gxisc to
enable and disable trace in a running XMS C or C++ application, and to modify
the trace size. You must run gxisc on the same machine as the XMS application.

To invoke gxisc, use the process id of the XMS application for which you want to
alter the trace configuration, as shown in the example below.
gxisc 1234 <enter>
display all <enter>
alter trace(enabled) tracesize(100) <enter>
help <enter>
alter trace(disabled) <enter>
alter <enter>
end

gxisc <enter>
alter pid(1234) trace(enabled) <enter>
end

cat a.file <enter>

alter pid(1234) trace(enabled)

end

cat a.file | gxisc <enter>

cat b.file <enter>

alter trace(disabled) tracesize(1000)

end

cat b.file | gxisc 1234 <enter>

Note: Trace settings are not retained after the XMS C or C++ application
terminates.

Trace file formatting

To minimize processing and disk overheads at runtime, XMS outputs trace in a

binary format into one or more trace files with the extension .trc. You can format
trace files by using the executable gxitrcfmt, as shown in the following example:
gxitrcfmt xms01234.trc

A formatted file has the suffix txt, for example:

cat xms01234.trc.txt

Tips for troubleshooting

Use these tips to help you troubleshoot problems with using XMS.

114 Message Service Client for C/C++

An XMS application cannot connect to a queue manager (not
authorized)

The XMS C/C++ client may have different behavior from that of theWebSphere
MQ JMS client. Therefore, you may find that your XMS application cannot connect
to your queue manager, although your JMS application can.
v A simple solution to this problem is to try using a userid that is no more than 12
characters long and is authorized completely in the queue manager’s authority
list. If this solution is not ideal, a different but more complex approach would be
to use security exits. If you need further help on this issue, contact IBM Support
for assistance.
v If you set the XMSC_USERID property of the connection factory, it must match
the userid and password of the logged on user. If you do not set this property,
the queue manager will use the userid of the logged on user by default.

Chapter 13. Troubleshooting 115

116 Message Service Client for C/C++
Part 4. XMS API reference
Chapter 14. C classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
BytesMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
xmsBytesMsgGetBodyLength – Get Body Length . . . . . . . . . . . . . . . . . . . . 132
xmsBytesMsgReadBoolean – Read Boolean Value . . . . . . . . . . . . . . . . . . . . 133
xmsBytesMsgReadByte – Read Byte . . . . . . . . . . . . . . . . . . . . . . . . . 133
xmsBytesMsgReadBytes – Read Bytes . . . . . . . . . . . . . . . . . . . . . . . . 133
xmsBytesMsgReadBytesByRef – Read Bytes by Reference. . . . . . . . . . . . . . . . . . 134
xmsBytesMsgReadChar – Read Character . . . . . . . . . . . . . . . . . . . . . . . 135
xmsBytesMsgReadDouble – Read Double Precision Floating Point Number . . . . . . . . . . . 135
xmsBytesMsgReadFloat – Read Floating Point Number . . . . . . . . . . . . . . . . . . 136
xmsBytesMsgReadInt – Read Integer . . . . . . . . . . . . . . . . . . . . . . . . 136
xmsBytesMsgReadLong – Read Long Integer . . . . . . . . . . . . . . . . . . . . . . 137
xmsBytesMsgReadShort – Read Short Integer. . . . . . . . . . . . . . . . . . . . . . 137
xmsBytesMsgReadUnsignedByte – Read Unsigned Byte . . . . . . . . . . . . . . . . . . 138
xmsBytesMsgReadUnsignedShort – Read Unsigned Short Integer . . . . . . . . . . . . . . . 138
xmsBytesMsgReadUTF – Read UTF String. . . . . . . . . . . . . . . . . . . . . . . 139
xmsBytesMsgReset – Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
xmsBytesMsgWriteBoolean – Write Boolean Value . . . . . . . . . . . . . . . . . . . . 140
xmsBytesMsgWriteByte – Write Byte . . . . . . . . . . . . . . . . . . . . . . . . 140
xmsBytesMsgWriteBytes – Write Bytes . . . . . . . . . . . . . . . . . . . . . . . . 141
xmsBytesMsgWriteChar – Write Character. . . . . . . . . . . . . . . . . . . . . . . 141
xmsBytesMsgWriteDouble – Write Double Precision Floating Point Number . . . . . . . . . . . 142
xmsBytesMsgWriteFloat – Write Floating Point Number . . . . . . . . . . . . . . . . . . 142
xmsBytesMsgWriteInt – Write Integer . . . . . . . . . . . . . . . . . . . . . . . . 143
xmsBytesMsgWriteLong – Write Long Integer . . . . . . . . . . . . . . . . . . . . . 143
xmsBytesMsgWriteShort – Write Short Integer . . . . . . . . . . . . . . . . . . . . . 143
xmsBytesMsgWriteUTF – Write UTF String . . . . . . . . . . . . . . . . . . . . . . 144
Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
xmsConnClose – Close Connection . . . . . . . . . . . . . . . . . . . . . . . . . 144
xmsConnCreateSession – Create Session . . . . . . . . . . . . . . . . . . . . . . . 145
xmsConnGetClientID – Get Client ID . . . . . . . . . . . . . . . . . . . . . . . . 146
xmsConnGetExceptionListener – Get Exception Listener . . . . . . . . . . . . . . . . . . 146
xmsConnGetMetaData – Get Metadata . . . . . . . . . . . . . . . . . . . . . . . . 147
xmsConnSetClientID – Set Client ID . . . . . . . . . . . . . . . . . . . . . . . . . 147
xmsConnSetExceptionListener – Set Exception Listener . . . . . . . . . . . . . . . . . . 148
xmsConnStart – Start Connection . . . . . . . . . . . . . . . . . . . . . . . . . . 149
xmsConnStop – Stop Connection . . . . . . . . . . . . . . . . . . . . . . . . . . 149
ConnectionFactory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
xmsConnFactCreate – Create Connection Factory . . . . . . . . . . . . . . . . . . . . 149
xmsConnFactCreateConnection – Create Connection (using the default user identity) . . . . . . . . 150
xmsConnFactCreateConnectionForUser – Create Connection (using a specified user identity) . . . . . . 150
xmsConnFactDispose – Delete Connection Factory . . . . . . . . . . . . . . . . . . . . 151
ConnectionMetaData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
xmsConnMetaDataGetJMSXProperties – Get JMS Defined Message Properties . . . . . . . . . . . 152
Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
xmsDestCreate – Create Destination (using a URI) . . . . . . . . . . . . . . . . . . . . 153
xmsDestCreateByType – Create Destination (specifying a type and name) . . . . . . . . . . . . 153
xmsDestCreateTemporaryByType – Create Temporary Destination . . . . . . . . . . . . . . . 154
xmsDestDispose – Delete Destination . . . . . . . . . . . . . . . . . . . . . . . . 155
xmsDestGetName – Get Destination Name . . . . . . . . . . . . . . . . . . . . . . 155
xmsDestGetTypeId – Get Destination Type . . . . . . . . . . . . . . . . . . . . . . 156

© Copyright IBM Corp. 2005, 2009 117

 xmsDestToString – Get Destination Name as URI . . . . . . . . . . . . . . . . . . . . 156
ErrorBlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
xmsErrorClear – Clear Error Block . . . . . . . . . . . . . . . . . . . . . . . . . 157
xmsErrorCreate – Create Error Block . . . . . . . . . . . . . . . . . . . . . . . . 157
xmsErrorDispose – Delete Error Block . . . . . . . . . . . . . . . . . . . . . . . . 158
xmsErrorGetErrorCode – Get Error Code . . . . . . . . . . . . . . . . . . . . . . . 158
xmsErrorGetErrorData – Get Error Data . . . . . . . . . . . . . . . . . . . . . . . 159
xmsErrorGetErrorString – Get Error String . . . . . . . . . . . . . . . . . . . . . . 159
xmsErrorGetJMSException – Get Exception Code . . . . . . . . . . . . . . . . . . . . 160
xmsErrorGetLinkedError – Get Linked Error . . . . . . . . . . . . . . . . . . . . . . 160
ExceptionListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
onException – On Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
InitialContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
xmsInitialContextCreate – Create Initial Context . . . . . . . . . . . . . . . . . . . . . 161
xmsInitialContextDispose – Delete Initial Context . . . . . . . . . . . . . . . . . . . . 162
xmsInitialContextLookup – Look Up Object in Initial Context . . . . . . . . . . . . . . . . 162
Iterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
xmsIteratorDispose – Delete Iterator . . . . . . . . . . . . . . . . . . . . . . . . . 163
xmsIteratorGetNext – Get Next Object . . . . . . . . . . . . . . . . . . . . . . . . 163
xmsIteratorHasNext – Check for More Objects . . . . . . . . . . . . . . . . . . . . . 164
xmsIteratorReset – Reset Iterator . . . . . . . . . . . . . . . . . . . . . . . . . . 164
MapMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
xmsMapMsgGetBoolean – Get Boolean Value. . . . . . . . . . . . . . . . . . . . . . 165
xmsMapMsgGetByte – Get Byte . . . . . . . . . . . . . . . . . . . . . . . . . . 165
xmsMapMsgGetBytes – Get Bytes . . . . . . . . . . . . . . . . . . . . . . . . . 166
xmsMapMsgGetBytesByRef – Get Bytes by Reference . . . . . . . . . . . . . . . . . . . 167
xmsMapMsgGetChar – Get Character . . . . . . . . . . . . . . . . . . . . . . . . 167
xmsMapMsgGetDouble – Get Double Precision Floating Point Number . . . . . . . . . . . . . 168
xmsMapMsgGetFloat – Get Floating Point Number. . . . . . . . . . . . . . . . . . . . 168
xmsMapMsgGetInt – Get Integer . . . . . . . . . . . . . . . . . . . . . . . . . . 169
xmsMapMsgGetLong – Get Long Integer . . . . . . . . . . . . . . . . . . . . . . . 169
xmsMapMsgGetMap – Get Name-Value Pairs . . . . . . . . . . . . . . . . . . . . . 170
xmsMapMsgGetObject – Get Object . . . . . . . . . . . . . . . . . . . . . . . . . 170
xmsMapMsgGetShort – Get Short Integer . . . . . . . . . . . . . . . . . . . . . . . 171
xmsMapMsgGetString – Get String . . . . . . . . . . . . . . . . . . . . . . . . . 172
xmsMapMsgGetStringByRef – Get String by Reference . . . . . . . . . . . . . . . . . . 172
xmsMapMsgItemExists – Check Name-Value Pair Exists . . . . . . . . . . . . . . . . . . 173
xmsMapMsgSetBoolean – Set Boolean Value . . . . . . . . . . . . . . . . . . . . . . 174
xmsMapMsgSetByte – Set Byte . . . . . . . . . . . . . . . . . . . . . . . . . . 174
xmsMapMsgSetBytes – Set Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . 175
xmsMapMsgSetChar – Set Character . . . . . . . . . . . . . . . . . . . . . . . . 175
xmsMapMsgSetDouble – Set Double Precision Floating Point Number . . . . . . . . . . . . . 176
xmsMapMsgSetFloat – Set Floating Point Number . . . . . . . . . . . . . . . . . . . . 176
xmsMapMsgSetInt – Set Integer . . . . . . . . . . . . . . . . . . . . . . . . . . 177
xmsMapMsgSetLong – Set Long Integer . . . . . . . . . . . . . . . . . . . . . . . 177
xmsMapMsgSetObject – Set Object . . . . . . . . . . . . . . . . . . . . . . . . . 177
xmsMapMsgSetShort – Set Short Integer . . . . . . . . . . . . . . . . . . . . . . . 178
xmsMapMsgSetString – Set String . . . . . . . . . . . . . . . . . . . . . . . . . 179
Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
xmsMsgAcknowledge – Acknowledge . . . . . . . . . . . . . . . . . . . . . . . . 180
xmsMsgClearBody – Clear Body . . . . . . . . . . . . . . . . . . . . . . . . . . 180
xmsMsgClearProperties – Clear Properties. . . . . . . . . . . . . . . . . . . . . . . 181
xmsMsgDispose – Delete Message . . . . . . . . . . . . . . . . . . . . . . . . . 181
xmsMsgGetJMSCorrelationID – Get JMSCorrelationID . . . . . . . . . . . . . . . . . . . 181
xmsMsgGetJMSDeliveryMode – Get JMSDeliveryMode . . . . . . . . . . . . . . . . . . 182

118 Message Service Client for C/C++

 xmsMsgGetJMSDestination – Get JMSDestination . . . . . . . . . . . . . . . . . . . . 183
xmsMsgGetJMSExpiration – Get JMSExpiration . . . . . . . . . . . . . . . . . . . . . 183
xmsMsgGetJMSMessageID – Get JMSMessageID . . . . . . . . . . . . . . . . . . . . 184
xmsMsgGetJMSPriority – Get JMSPriority . . . . . . . . . . . . . . . . . . . . . . . 185
xmsMsgGetJMSRedelivered – Get JMSRedelivered . . . . . . . . . . . . . . . . . . . . 185
xmsMsgGetJMSReplyTo – Get JMSReplyTo . . . . . . . . . . . . . . . . . . . . . . 186
xmsMsgGetJMSTimestamp – Get JMSTimestamp . . . . . . . . . . . . . . . . . . . . 186
xmsMsgGetJMSType – Get JMSType . . . . . . . . . . . . . . . . . . . . . . . . . 187
xmsMsgGetProperties – Get Properties . . . . . . . . . . . . . . . . . . . . . . . . 188
xmsMsgGetTypeId – Get Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
xmsMsgPropertyExists – Check Property Exists . . . . . . . . . . . . . . . . . . . . . 189
xmsMsgSetJMSCorrelationID – Set JMSCorrelationID . . . . . . . . . . . . . . . . . . . 189
xmsMsgSetJMSDeliveryMode – Set JMSDeliveryMode. . . . . . . . . . . . . . . . . . . 190
xmsMsgSetJMSDestination – Set JMSDestination. . . . . . . . . . . . . . . . . . . . . 190
xmsMsgSetJMSExpiration – Set JMSExpiration . . . . . . . . . . . . . . . . . . . . . 191
xmsMsgSetJMSMessageID – Set JMSMessageID . . . . . . . . . . . . . . . . . . . . . 191
xmsMsgSetJMSPriority – Set JMSPriority . . . . . . . . . . . . . . . . . . . . . . . 192
xmsMsgSetJMSRedelivered – Set JMSRedelivered . . . . . . . . . . . . . . . . . . . . 192
xmsMsgSetJMSReplyTo – Set JMSReplyTo . . . . . . . . . . . . . . . . . . . . . . . 193
xmsMsgSetJMSTimestamp – Set JMSTimestamp . . . . . . . . . . . . . . . . . . . . . 193
xmsMsgSetJMSType – Set JMSType . . . . . . . . . . . . . . . . . . . . . . . . . 194
MessageConsumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
xmsMsgConsumerClose – Close Message Consumer . . . . . . . . . . . . . . . . . . . 194
xmsMsgConsumerGetMessageListener – Get Message Listener . . . . . . . . . . . . . . . . 195
xmsMsgConsumerGetMessageSelector – Get Message Selector . . . . . . . . . . . . . . . . 195
xmsMsgConsumerReceive – Receive. . . . . . . . . . . . . . . . . . . . . . . . . 196
xmsMsgConsumerReceiveNoWait – Receive with No Wait . . . . . . . . . . . . . . . . . 196
xmsMsgConsumerReceiveWithWait – Receive (with a wait interval) . . . . . . . . . . . . . . 197
xmsMsgConsumerSetMessageListener – Set Message Listener . . . . . . . . . . . . . . . . 197
MessageListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
onMessage – On Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
MessageProducer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
xmsMsgProducerClose – Close Message Producer . . . . . . . . . . . . . . . . . . . . 199
xmsMsgProducerGetDeliveryMode – Get Default Delivery Mode . . . . . . . . . . . . . . . 199
xmsMsgProducerGetDestination – Get Destination . . . . . . . . . . . . . . . . . . . . 200
xmsMsgProducerGetDisableMsgID – Get Disable Message ID Flag . . . . . . . . . . . . . . 200
xmsMsgProducerGetDisableMsgTS – Get Disable Time Stamp Flag . . . . . . . . . . . . . . 200
xmsMsgProducerGetPriority – Get Default Priority . . . . . . . . . . . . . . . . . . . . 201
xmsMsgProducerGetTimeToLive – Get Default Time to Live. . . . . . . . . . . . . . . . . 201
xmsMsgProducerSend – Send . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
xmsMsgProducerSendDest – Send (to a specified destination) . . . . . . . . . . . . . . . . 202
xmsMsgProducerSendDestWithAttr – Send (to a specified destination, specifying a delivery mode, priority,
and time to live) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
xmsMsgProducerSendWithAttr – Send (specifying a delivery mode, priority, and time to live) . . . . . 204
xmsMsgProducerSetDeliveryMode – Set Default Delivery Mode . . . . . . . . . . . . . . . 205
xmsMsgProducerSetDisableMsgID – Set Disable Message ID Flag . . . . . . . . . . . . . . . 205
xmsMsgProducerSetDisableMsgTS – Set Disable Time Stamp Flag . . . . . . . . . . . . . . . 206
xmsMsgProducerSetPriority – Set Default Priority . . . . . . . . . . . . . . . . . . . . 206
xmsMsgProducerSetTimeToLive – Set Default Time to Live . . . . . . . . . . . . . . . . . 207
ObjectMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
xmsObjectMsgGetObjectAsBytes – Get Object as Bytes . . . . . . . . . . . . . . . . . . 207
xmsObjectMsgSetObjectAsBytes – Set Object as Bytes . . . . . . . . . . . . . . . . . . . 208
Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
xmsPropertyCreate – Create Property (with no property value or property type) . . . . . . . . . . 209
xmsPropertyDispose – Delete Property . . . . . . . . . . . . . . . . . . . . . . . . 209
xmsPropertyDuplicate – Copy Property . . . . . . . . . . . . . . . . . . . . . . . 210

Part 4. XMS API reference 119

 xmsPropertyGetBoolean – Get Boolean Property Value . . . . . . . . . . . . . . . . . . 210
xmsPropertyGetByte – Get Byte Property Value . . . . . . . . . . . . . . . . . . . . . 211
xmsPropertyGetByteArray – Get Byte Array Property Value . . . . . . . . . . . . . . . . . 211
xmsPropertyGetByteArrayByRef – Get Byte Array Property Value by Reference . . . . . . . . . . 212
xmsPropertyGetChar – Get Character Property Value . . . . . . . . . . . . . . . . . . . 212
xmsPropertyGetDouble – Get Double Precision Floating Point Property Value . . . . . . . . . . . 213
xmsPropertyGetFloat – Get Floating Point Property Value . . . . . . . . . . . . . . . . . 213
xmsPropertyGetInt – Get Integer Property Value . . . . . . . . . . . . . . . . . . . . 214
xmsPropertyGetLong – Get Long Integer Property Value . . . . . . . . . . . . . . . . . . 214
xmsPropertyGetName – Get Property Name . . . . . . . . . . . . . . . . . . . . . . 215
xmsPropertyGetShort – Get Short Integer Property Value . . . . . . . . . . . . . . . . . . 215
xmsPropertyGetString – Get String Property Value . . . . . . . . . . . . . . . . . . . . 216
xmsPropertyGetStringByRef – Get String Property Value by Reference . . . . . . . . . . . . . 216
xmsPropertyGetTypeId – Get Property Type . . . . . . . . . . . . . . . . . . . . . . 217
xmsPropertyIsTypeId – Check Property Type . . . . . . . . . . . . . . . . . . . . . . 218
xmsPropertySetBoolean – Set Boolean Property Value . . . . . . . . . . . . . . . . . . . 219
xmsPropertySetByte – Set Byte Property Value . . . . . . . . . . . . . . . . . . . . . 219
xmsPropertySetByteArray – Set Byte Array Property Value . . . . . . . . . . . . . . . . . 219
xmsPropertySetChar – Set Character Property Value . . . . . . . . . . . . . . . . . . . 220
xmsPropertySetDouble – Set Double Precision Floating Point Property Value . . . . . . . . . . . 220
xmsPropertySetFloat – Set Floating Point Property Value . . . . . . . . . . . . . . . . . . 221
xmsPropertySetInt – Set Integer Property Value . . . . . . . . . . . . . . . . . . . . . 221
xmsPropertySetLong – Set Long Integer Property Value . . . . . . . . . . . . . . . . . . 222
xmsPropertySetShort – Set Short Integer Property Value . . . . . . . . . . . . . . . . . . 222
xmsPropertySetString – Set String Property Value . . . . . . . . . . . . . . . . . . . . 223
PropertyContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
xmsGetBooleanProperty – Get Boolean Property. . . . . . . . . . . . . . . . . . . . . 223
xmsGetByteArrayProperty – Get Byte Array Property . . . . . . . . . . . . . . . . . . . 224
xmsGetByteArrayPropertyByRef – Get Byte Array Property by Reference . . . . . . . . . . . . 225
xmsGetByteProperty – Get Byte Property . . . . . . . . . . . . . . . . . . . . . . . 225
xmsGetCharProperty – Get Character Property . . . . . . . . . . . . . . . . . . . . . 226
xmsGetDoubleProperty – Get Double Precision Floating Point Property . . . . . . . . . . . . . 226
xmsGetFloatProperty – Get Floating Point Property . . . . . . . . . . . . . . . . . . . 227
xmsGetHandleTypeId – Get Handle Type . . . . . . . . . . . . . . . . . . . . . . . 227
xmsGetIntProperty – Get Integer Property . . . . . . . . . . . . . . . . . . . . . . . 228
xmsGetLongProperty – Get Long Integer Property . . . . . . . . . . . . . . . . . . . . 228
xmsGetObjectProperty – Get Object Property . . . . . . . . . . . . . . . . . . . . . . 229
xmsGetProperty – Get Property . . . . . . . . . . . . . . . . . . . . . . . . . . 230
xmsGetShortProperty – Get Short Integer Property . . . . . . . . . . . . . . . . . . . . 230
xmsGetStringProperty – Get String Property . . . . . . . . . . . . . . . . . . . . . . 231
xmsGetStringPropertyByRef – Get String Property by Reference . . . . . . . . . . . . . . . 232
xmsSetBooleanProperty – Set Boolean Property . . . . . . . . . . . . . . . . . . . . . 232
xmsSetByteProperty – Set Byte Property . . . . . . . . . . . . . . . . . . . . . . . 233
xmsSetByteArrayProperty – Set Byte Array Property . . . . . . . . . . . . . . . . . . . 234
xmsSetCharProperty – Set Character Property . . . . . . . . . . . . . . . . . . . . . 234
xmsSetDoubleProperty – Set Double Precision Floating Point Property . . . . . . . . . . . . . 235
xmsSetFloatProperty – Set Floating Point Property . . . . . . . . . . . . . . . . . . . . 235
xmsSetIntProperty – Set Integer Property . . . . . . . . . . . . . . . . . . . . . . . 236
xmsSetLongProperty – Set Long Integer Property . . . . . . . . . . . . . . . . . . . . 236
xmsSetObjectProperty – Set Object Property . . . . . . . . . . . . . . . . . . . . . . 237
xmsSetProperty – Set Property. . . . . . . . . . . . . . . . . . . . . . . . . . . 238
xmsSetShortProperty – Set Short Integer Property . . . . . . . . . . . . . . . . . . . . 238
xmsSetStringProperty – Set String Property . . . . . . . . . . . . . . . . . . . . . . 239
QueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
xmsQueueBrowserClose – Close Queue Browser . . . . . . . . . . . . . . . . . . . . 239
xmsQueueBrowserGetEnumeration – Get Messages . . . . . . . . . . . . . . . . . . . 240
xmsQueueBrowserGetMessageSelector – Get Message Selector . . . . . . . . . . . . . . . . 240
xmsQueueBrowserGetQueue – Get Queue . . . . . . . . . . . . . . . . . . . . . . . 241
Requestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

120 Message Service Client for C/C++

 Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
xmsRequestorClose – Close Requestor . . . . . . . . . . . . . . . . . . . . . . . . 242
xmsRequestorCreate – Create Requestor . . . . . . . . . . . . . . . . . . . . . . . 242
xmsRequestorRequest – Request . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
xmsSessClose – Close Session . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
xmsSessCommit – Commit . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
xmsSessCreateBrowser – Create Queue Browser . . . . . . . . . . . . . . . . . . . . . 244
xmsSessCreateBrowserSelector – Create Queue Browser (with message selector) . . . . . . . . . . 245
xmsSessCreateBytesMessage – Create Bytes Message . . . . . . . . . . . . . . . . . . . 245
xmsSessCreateConsumer – Create Consumer . . . . . . . . . . . . . . . . . . . . . . 246
xmsSessCreateConsumerSelector – Create Consumer (with message selector) . . . . . . . . . . . 246
xmsSessCreateConsumerSelectorLocal – Create Consumer (with message selector and local message flag) 247
xmsSessCreateDurableSubscriber – Create Durable Subscriber . . . . . . . . . . . . . . . . 248
xmsSessCreateDurableSubscriberSelector – Create Durable Subscriber (with message selector and local
message flag) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
xmsSessCreateMapMessage – Create Map Message . . . . . . . . . . . . . . . . . . . . 250
xmsSessCreateMessage – Create Message . . . . . . . . . . . . . . . . . . . . . . . 250
xmsSessCreateObjectMessage – Create Object Message . . . . . . . . . . . . . . . . . . 251
xmsSessCreateProducer – Create Producer. . . . . . . . . . . . . . . . . . . . . . . 251
xmsSessCreateStreamMessage – Create Stream Message . . . . . . . . . . . . . . . . . . 252
xmsSessCreateTextMessage – Create Text Message . . . . . . . . . . . . . . . . . . . . 252
xmsSessCreateTextMessageInit – Create Text Message (initialized) . . . . . . . . . . . . . . . 252
xmsSessGetAcknowledgeMode – Get Acknowledgement Mode. . . . . . . . . . . . . . . . 253
xmsSessGetTransacted – Determine Whether Transacted . . . . . . . . . . . . . . . . . . 254
xmsSessRecover – Recover . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
xmsSessRollback – Rollback . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
xmsSessUnsubscribe – Unsubscribe . . . . . . . . . . . . . . . . . . . . . . . . . 255
StreamMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
xmsStreamMsgReadBoolean – Read Boolean Value . . . . . . . . . . . . . . . . . . . . 256
xmsStreamMsgReadByte – Read Byte . . . . . . . . . . . . . . . . . . . . . . . . 256
xmsStreamMsgReadBytes – Read Bytes . . . . . . . . . . . . . . . . . . . . . . . . 257
xmsStreamMsgReadBytesByRef – Read Bytes by Reference . . . . . . . . . . . . . . . . . 258
xmsStreamMsgReadChar – Read Character . . . . . . . . . . . . . . . . . . . . . . 258
xmsStreamMsgReadDouble – Read Double Precision Floating Point Number . . . . . . . . . . . 259
xmsStreamMsgReadFloat – Read Floating Point Number . . . . . . . . . . . . . . . . . . 259
xmsStreamMsgReadInt – Read Integer . . . . . . . . . . . . . . . . . . . . . . . . 259
xmsStreamMsgReadLong – Read Long Integer . . . . . . . . . . . . . . . . . . . . . 260
xmsStreamMsgReadObject – Read Object . . . . . . . . . . . . . . . . . . . . . . . 260
xmsStreamMsgReadShort – Read Short Integer . . . . . . . . . . . . . . . . . . . . . 261
xmsStreamMsgReadString – Read String . . . . . . . . . . . . . . . . . . . . . . . 262
xmsStreamMsgReset – Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
xmsStreamMsgWriteBoolean – Write Boolean Value . . . . . . . . . . . . . . . . . . . 263
xmsStreamMsgWriteByte – Write Byte . . . . . . . . . . . . . . . . . . . . . . . . 264
xmsStreamMsgWriteBytes – Write Bytes . . . . . . . . . . . . . . . . . . . . . . . 264
xmsStreamMsgWriteChar – Write Character . . . . . . . . . . . . . . . . . . . . . . 264
xmsStreamMsgWriteDouble – Write Double Precision Floating Point Number . . . . . . . . . . . 265
xmsStreamMsgWriteFloat – Write Floating Point Number . . . . . . . . . . . . . . . . . 265
xmsStreamMsgWriteInt – Write Integer . . . . . . . . . . . . . . . . . . . . . . . . 266
xmsStreamMsgWriteLong – Write Long Integer . . . . . . . . . . . . . . . . . . . . . 266
xmsStreamMsgWriteObject – Write Object . . . . . . . . . . . . . . . . . . . . . . . 267
xmsStreamMsgWriteShort – Write Short Integer . . . . . . . . . . . . . . . . . . . . . 267
xmsStreamMsgWriteString – Write String . . . . . . . . . . . . . . . . . . . . . . . 268
TextMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
xmsTextMsgGetText – Get Text . . . . . . . . . . . . . . . . . . . . . . . . . . 268
xmsTextMsgSetText – Set Text . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

Chapter 15. Additional C functions . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Part 4. XMS API reference 121

Process CCSID functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
xmsGetClientCCSID – Get Process CCSID . . . . . . . . . . . . . . . . . . . . . . . 271
xmsSetClientCCSID – Set Process CCSID . . . . . . . . . . . . . . . . . . . . . . . 271

Chapter 16. C++ classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

BytesMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
getBodyLength – Get Body Length . . . . . . . . . . . . . . . . . . . . . . . . . 275
readBoolean – Read Boolean Value . . . . . . . . . . . . . . . . . . . . . . . . . 276
readByte – Read Byte. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
readBytes – Read Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
readChar – Read Character . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
readDouble – Read Double Precision Floating Point Number . . . . . . . . . . . . . . . . 277
readFloat – Read Floating Point Number . . . . . . . . . . . . . . . . . . . . . . . 278
readInt – Read Integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
readLong – Read Long Integer . . . . . . . . . . . . . . . . . . . . . . . . . . 278
readShort – Read Short Integer . . . . . . . . . . . . . . . . . . . . . . . . . . 279
readUnsignedByte – Read Unsigned Byte . . . . . . . . . . . . . . . . . . . . . . . 279
readUnsignedShort – Read Unsigned Short Integer . . . . . . . . . . . . . . . . . . . . 279
readUTF – Read UTF String . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
reset – Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
writeBoolean – Write Boolean Value . . . . . . . . . . . . . . . . . . . . . . . . . 280
writeByte – Write Byte . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
writeBytes – Write Bytes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
writeChar – Write Character . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
writeDouble – Write Double Precision Floating Point Number . . . . . . . . . . . . . . . . 282
writeFloat – Write Floating Point Number . . . . . . . . . . . . . . . . . . . . . . . 282
writeInt – Write Integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
writeLong – Write Long Integer . . . . . . . . . . . . . . . . . . . . . . . . . . 283
writeShort – Write Short Integer . . . . . . . . . . . . . . . . . . . . . . . . . . 283
writeUTF – Write UTF String . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
close – Close Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
createSession – Create Session . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
getClientID – Get Client ID. . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
getExceptionListener – Get Exception Listener . . . . . . . . . . . . . . . . . . . . . 286
getHandle – Get Handle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
getMetaData – Get Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
isNull – Check Whether Null . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
setClientID – Set Client ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
setExceptionListener – Set Exception Listener. . . . . . . . . . . . . . . . . . . . . . 288
start – Start Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
stop – Stop Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
ConnectionFactory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Constructors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
ConnectionFactory – Create Connection Factory . . . . . . . . . . . . . . . . . . . . . 289
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
~ConnectionFactory – Delete Connection Factory . . . . . . . . . . . . . . . . . . . . 289
createConnection – Create Connection (using the default user identity) . . . . . . . . . . . . . 290
createConnection – Create Connection (using a specified user identity) . . . . . . . . . . . . . 290
getHandle – Get Handle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
isNull – Check Whether Null . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
ConnectionMetaData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
getHandle – Get Handle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
getJMSXProperties – Get JMS Defined Message Properties . . . . . . . . . . . . . . . . . 292

122 Message Service Client for C/C++

 isNull – Check Whether Null . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Constructors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Destination – Create Destination (specifying a type and name) . . . . . . . . . . . . . . . . 293
Destination – Create Destination (using a URI) . . . . . . . . . . . . . . . . . . . . . 294
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
~Destination – Delete Destination . . . . . . . . . . . . . . . . . . . . . . . . . 294
getHandle – Get Handle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
getName – Get Destination Name . . . . . . . . . . . . . . . . . . . . . . . . . 295
getTypeId – Get Destination Type . . . . . . . . . . . . . . . . . . . . . . . . . 295
isNull – Check Whether Null . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
toString – Get Destination Name as URI . . . . . . . . . . . . . . . . . . . . . . . 296
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Exception. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
~Exception – Delete Exception. . . . . . . . . . . . . . . . . . . . . . . . . . . 297
dump – Dump Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
getErrorCode – Get Error Code . . . . . . . . . . . . . . . . . . . . . . . . . . 298
getErrorData – Get Error Data . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
getErrorString – Get Error String . . . . . . . . . . . . . . . . . . . . . . . . . . 298
getHandle – Get Handle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
getJMSException – Get Exception Code. . . . . . . . . . . . . . . . . . . . . . . . 299
getLinkedException – Get Linked Exception . . . . . . . . . . . . . . . . . . . . . . 299
isNull – Check Whether Null . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
ExceptionListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
onException – On Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
IllegalStateException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
InitialContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Constructors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
InitialContext – Create Initial Context . . . . . . . . . . . . . . . . . . . . . . . . 301
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
~InitialContext – Delete Initial Context . . . . . . . . . . . . . . . . . . . . . . . . 302
getHandle – Get Handle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
isNull – Check Whether Null . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
lookup – Look Up Object in Initial Context . . . . . . . . . . . . . . . . . . . . . . 303
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
InvalidClientIDException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
InvalidDestinationException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
InvalidSelectorException. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Iterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
~Iterator – Delete Iterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
getHandle – Get Handle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
getNext – Get Next Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
hasNext – Check for More Objects . . . . . . . . . . . . . . . . . . . . . . . . . 305
isNull – Check Whether Null . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
reset – Reset Iterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
MapMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
getBoolean – Get Boolean Value . . . . . . . . . . . . . . . . . . . . . . . . . . 307
getByte – Get Byte. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
getBytes – Get Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
getChar – Get Character . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
getDouble – Get Double Precision Floating Point Number . . . . . . . . . . . . . . . . . 308
getFloat – Get Floating Point Number . . . . . . . . . . . . . . . . . . . . . . . . 309

Part 4. XMS API reference 123

 getInt – Get Integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
getLong – Get Long Integer . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
getMap – Get Name-Value Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . 310
getObject – Get Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
getShort – Get Short Integer . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
getString – Get String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
itemExists – Check Name-Value Pair Exists . . . . . . . . . . . . . . . . . . . . . . 312
setBoolean – Set Boolean Value . . . . . . . . . . . . . . . . . . . . . . . . . . 312
setByte – Set Byte . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
setBytes – Set Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
setChar – Set Character . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
setDouble – Set Double Precision Floating Point Number . . . . . . . . . . . . . . . . . . 314
setFloat – Set Floating Point Number . . . . . . . . . . . . . . . . . . . . . . . . 314
setInt – Set Integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
setLong – Set Long Integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
setObject – Set Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
setShort – Set Short Integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
setString – Set String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
~Message – Delete Message . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
acknowledge – Acknowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
clearBody – Clear Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
clearProperties – Clear Properties. . . . . . . . . . . . . . . . . . . . . . . . . . 319
getHandle – Get Handle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
getJMSCorrelationID – Get JMSCorrelationID. . . . . . . . . . . . . . . . . . . . . . 320
getJMSDeliveryMode – Get JMSDeliveryMode . . . . . . . . . . . . . . . . . . . . . 320
getJMSDestination – Get JMSDestination . . . . . . . . . . . . . . . . . . . . . . . 320
getJMSExpiration – Get JMSExpiration . . . . . . . . . . . . . . . . . . . . . . . . 321
getJMSMessageID – Get JMSMessageID . . . . . . . . . . . . . . . . . . . . . . . 321
getJMSPriority – Get JMSPriority . . . . . . . . . . . . . . . . . . . . . . . . . . 322
getJMSRedelivered – Get JMSRedelivered . . . . . . . . . . . . . . . . . . . . . . . 322
getJMSReplyTo – Get JMSReplyTo . . . . . . . . . . . . . . . . . . . . . . . . . 323
getJMSTimestamp – Get JMSTimestamp . . . . . . . . . . . . . . . . . . . . . . . 323
getJMSType – Get JMSType. . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
getProperties – Get Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
isNull – Check Whether Null . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
propertyExists – Check Property Exists . . . . . . . . . . . . . . . . . . . . . . . . 325
setJMSCorrelationID – Set JMSCorrelationID . . . . . . . . . . . . . . . . . . . . . . 325
setJMSDeliveryMode – Set JMSDeliveryMode . . . . . . . . . . . . . . . . . . . . . 325
setJMSDestination – Set JMSDestination . . . . . . . . . . . . . . . . . . . . . . . 326
setJMSExpiration – Set JMSExpiration . . . . . . . . . . . . . . . . . . . . . . . . 326
setJMSMessageID – Set JMSMessageID . . . . . . . . . . . . . . . . . . . . . . . . 327
setJMSPriority – Set JMSPriority . . . . . . . . . . . . . . . . . . . . . . . . . . 327
setJMSRedelivered – Set JMSRedelivered . . . . . . . . . . . . . . . . . . . . . . . 327
setJMSReplyTo – Set JMSReplyTo. . . . . . . . . . . . . . . . . . . . . . . . . . 328
setJMSTimestamp – Set JMSTimestamp . . . . . . . . . . . . . . . . . . . . . . . . 328
setJMSType – Set JMSType . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
MessageConsumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
close – Close Message Consumer . . . . . . . . . . . . . . . . . . . . . . . . . . 329
getHandle – Get Handle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
getMessageListener – Get Message Listener . . . . . . . . . . . . . . . . . . . . . . 330
getMessageSelector – Get Message Selector . . . . . . . . . . . . . . . . . . . . . . 330
isNull – Check Whether Null . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
receive – Receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
receive – Receive (with a wait interval) . . . . . . . . . . . . . . . . . . . . . . . . 331
receiveNoWait – Receive with No Wait . . . . . . . . . . . . . . . . . . . . . . . . 332
setMessageListener – Set Message Listener . . . . . . . . . . . . . . . . . . . . . . 332

124 Message Service Client for C/C++

 Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
MessageEOFException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
MessageFormatException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
MessageListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
onMessage – On Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
MessageNotReadableException . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
MessageNotWritableException. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
MessageProducer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
close – Close Message Producer . . . . . . . . . . . . . . . . . . . . . . . . . . 335
getDeliveryMode – Get Default Delivery Mode . . . . . . . . . . . . . . . . . . . . . 335
getDestination – Get Destination . . . . . . . . . . . . . . . . . . . . . . . . . . 336
getDisableMsgID – Get Disable Message ID Flag . . . . . . . . . . . . . . . . . . . . 336
getDisableMsgTS – Get Disable Time Stamp Flag . . . . . . . . . . . . . . . . . . . . 336
getHandle – Get Handle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
getPriority – Get Default Priority . . . . . . . . . . . . . . . . . . . . . . . . . . 337
getTimeToLive – Get Default Time to Live . . . . . . . . . . . . . . . . . . . . . . . 337
isNull – Check Whether Null . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
send – Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
send – Send (specifying a delivery mode, priority, and time to live) . . . . . . . . . . . . . . 338
send – Send (to a specified destination). . . . . . . . . . . . . . . . . . . . . . . . 339
send – Send (to a specified destination, specifying a delivery mode, priority, and time to live) . . . . . 340
setDeliveryMode – Set Default Delivery Mode . . . . . . . . . . . . . . . . . . . . . 341
setDisableMsgID – Set Disable Message ID Flag . . . . . . . . . . . . . . . . . . . . . 341
setDisableMsgTS – Set Disable Time Stamp Flag. . . . . . . . . . . . . . . . . . . . . 342
setPriority – Set Default Priority . . . . . . . . . . . . . . . . . . . . . . . . . . 342
setTimeToLive – Set Default Time to Live . . . . . . . . . . . . . . . . . . . . . . . 342
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
ObjectMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
getObject – Get Object as Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . 343
setObject – Set Object as Bytes. . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Constructors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Property – Copy Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Property – Create Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Property – Create Property (with no property value or property type) . . . . . . . . . . . . . 346
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
~Property – Delete Property . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
getBoolean – Get Boolean Property Value . . . . . . . . . . . . . . . . . . . . . . . 347
getByte – Get Byte Property Value . . . . . . . . . . . . . . . . . . . . . . . . . 347
getByteArray – Get Byte Array Property Value . . . . . . . . . . . . . . . . . . . . . 348
getChar – Get Character Property Value . . . . . . . . . . . . . . . . . . . . . . . 348
getDouble – Get Double Precision Floating Point Property Value . . . . . . . . . . . . . . . 349
getFloat – Get Floating Point Property Value . . . . . . . . . . . . . . . . . . . . . . 349
getHandle – Get Handle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
getInt – Get Integer Property Value . . . . . . . . . . . . . . . . . . . . . . . . . 350
getLong – Get Long Integer Property Value . . . . . . . . . . . . . . . . . . . . . . 350
getShort – Get Short Integer Property Value . . . . . . . . . . . . . . . . . . . . . . 350
getString – Get String Property Value . . . . . . . . . . . . . . . . . . . . . . . . 351
getTypeId – Get Property Type . . . . . . . . . . . . . . . . . . . . . . . . . . 351
isNull – Check Whether Null . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
isTypeId – Check Property Type . . . . . . . . . . . . . . . . . . . . . . . . . . 352
name – Get Property Name . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
setBoolean – Set Boolean Property Value . . . . . . . . . . . . . . . . . . . . . . . 353

Part 4. XMS API reference 125

 setByte – Set Byte Property Value. . . . . . . . . . . . . . . . . . . . . . . . . . 353
setByteArray – Set Byte Array Property Value . . . . . . . . . . . . . . . . . . . . . 354
setChar – Set Character Property Value . . . . . . . . . . . . . . . . . . . . . . . . 354
setDouble – Set Double Precision Floating Point Property Value . . . . . . . . . . . . . . . 354
setFloat – Set Floating Point Property Value . . . . . . . . . . . . . . . . . . . . . . 355
setInt – Set Integer Property Value . . . . . . . . . . . . . . . . . . . . . . . . . 355
setLong – Set Long Integer Property Value . . . . . . . . . . . . . . . . . . . . . . 355
setShort – Set Short Integer Property Value . . . . . . . . . . . . . . . . . . . . . . 356
setString – Set String Property Value . . . . . . . . . . . . . . . . . . . . . . . . 356
PropertyContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
getBooleanProperty – Get Boolean Property . . . . . . . . . . . . . . . . . . . . . . 357
getByteProperty – Get Byte Property . . . . . . . . . . . . . . . . . . . . . . . . 357
getBytesProperty – Get Byte Array Property . . . . . . . . . . . . . . . . . . . . . . 357
getCharProperty – Get Character Property. . . . . . . . . . . . . . . . . . . . . . . 358
getDoubleProperty – Get Double Precision Floating Point Property . . . . . . . . . . . . . . 358
getFloatProperty – Get Floating Point Property . . . . . . . . . . . . . . . . . . . . . 359
getIntProperty – Get Integer Property . . . . . . . . . . . . . . . . . . . . . . . . 359
getLongProperty – Get Long Integer Property . . . . . . . . . . . . . . . . . . . . . 360
getObjectProperty – Get Object Property . . . . . . . . . . . . . . . . . . . . . . . 360
getProperty – Get Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
getShortProperty – Get Short Integer Property . . . . . . . . . . . . . . . . . . . . . 361
getStringProperty – Get String Property . . . . . . . . . . . . . . . . . . . . . . . 362
setBooleanProperty – Set Boolean Property . . . . . . . . . . . . . . . . . . . . . . 362
setByteProperty – Set Byte Property . . . . . . . . . . . . . . . . . . . . . . . . . 362
setBytesProperty – Set Byte Array Property . . . . . . . . . . . . . . . . . . . . . . 363
setCharProperty – Set Character Property . . . . . . . . . . . . . . . . . . . . . . . 363
setDoubleProperty – Set Double Precision Floating Point Property. . . . . . . . . . . . . . . 364
setFloatProperty – Set Floating Point Property . . . . . . . . . . . . . . . . . . . . . 364
setIntProperty – Set Integer Property . . . . . . . . . . . . . . . . . . . . . . . . 365
setLongProperty – Set Long Integer Property . . . . . . . . . . . . . . . . . . . . . . 365
setObjectProperty – Set Object Property . . . . . . . . . . . . . . . . . . . . . . . 366
setProperty – Set Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
setShortProperty – Set Short Integer Property. . . . . . . . . . . . . . . . . . . . . . 367
setStringProperty – Set String Property . . . . . . . . . . . . . . . . . . . . . . . . 367
QueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
close – Close Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
getEnumeration – Get Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 368
getHandle – Get Handle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
getMessageSelector – Get Message Selector . . . . . . . . . . . . . . . . . . . . . . 369
getQueue – Get Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
isNull – Check Whether Null . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Requestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Constructors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Requestor – Create Requestor . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
close – Close Requestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
getHandle – Get Handle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
isNull – Check Whether Null . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
request – Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
ResourceAllocationException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
SecurityException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
close – Close Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
commit – Commit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

126 Message Service Client for C/C++

 createBrowser – Create Queue Browser . . . . . . . . . . . . . . . . . . . . . . . . 374
createBrowser – Create Queue Browser (with message selector). . . . . . . . . . . . . . . . 375
createBytesMessage – Create Bytes Message . . . . . . . . . . . . . . . . . . . . . . 375
createConsumer – Create Consumer . . . . . . . . . . . . . . . . . . . . . . . . . 375
createConsumer – Create Consumer (with message selector). . . . . . . . . . . . . . . . . 376
createConsumer – Create Consumer (with message selector and local message flag) . . . . . . . . . 376
createDurableSubscriber – Create Durable Subscriber . . . . . . . . . . . . . . . . . . . 377
createDurableSubscriber – Create Durable Subscriber (with message selector and local message flag) . . . 377
createMapMessage – Create Map Message. . . . . . . . . . . . . . . . . . . . . . . 378
createMessage – Create Message . . . . . . . . . . . . . . . . . . . . . . . . . . 379
createObjectMessage – Create Object Message . . . . . . . . . . . . . . . . . . . . . 379
createProducer – Create Producer . . . . . . . . . . . . . . . . . . . . . . . . . 379
createQueue – Create Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
createStreamMessage – Create Stream Message . . . . . . . . . . . . . . . . . . . . . 380
createTemporaryQueue – Create Temporary Queue . . . . . . . . . . . . . . . . . . . . 380
createTemporaryTopic – Create Temporary Topic . . . . . . . . . . . . . . . . . . . . 381
createTextMessage – Create Text Message . . . . . . . . . . . . . . . . . . . . . . . 381
createTextMessage – Create Text Message (initialized) . . . . . . . . . . . . . . . . . . . 382
createTopic – Create Topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
getAcknowledgeMode – Get Acknowledgement Mode . . . . . . . . . . . . . . . . . . 382
getHandle – Get Handle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
getTransacted – Determine Whether Transacted . . . . . . . . . . . . . . . . . . . . . 383
isNull – Check Whether Null . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
recover – Recover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
rollback – Rollback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
unsubscribe – Unsubscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
StreamMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
readBoolean – Read Boolean Value . . . . . . . . . . . . . . . . . . . . . . . . . 386
readByte – Read Byte. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
readBytes – Read Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
readChar – Read Character . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
readDouble – Read Double Precision Floating Point Number . . . . . . . . . . . . . . . . 388
readFloat – Read Floating Point Number . . . . . . . . . . . . . . . . . . . . . . . 388
readInt – Read Integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
readLong – Read Long Integer . . . . . . . . . . . . . . . . . . . . . . . . . . 389
readObject – Read Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
readShort – Read Short Integer . . . . . . . . . . . . . . . . . . . . . . . . . . 390
readString – Read String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
reset – Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
writeBoolean – Write Boolean Value . . . . . . . . . . . . . . . . . . . . . . . . . 391
writeByte – Write Byte . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
writeBytes – Write Bytes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
writeChar – Write Character . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
writeDouble – Write Double Precision Floating Point Number . . . . . . . . . . . . . . . . 392
writeFloat – Write Floating Point Number . . . . . . . . . . . . . . . . . . . . . . . 393
writeInt – Write Integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
writeLong – Write Long Integer . . . . . . . . . . . . . . . . . . . . . . . . . . 393
writeObject – Write Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
writeShort – Write Short Integer . . . . . . . . . . . . . . . . . . . . . . . . . . 394
writeString – Write String . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Constructors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
String – Create String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
String – Create String (from a byte array) . . . . . . . . . . . . . . . . . . . . . . . 396
String – Create String (from a character array) . . . . . . . . . . . . . . . . . . . . . 396
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
~String – Delete String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
c_str – Get Pointer to String . . . . . . . . . . . . . . . . . . . . . . . . . . . 397

Part 4. XMS API reference 127

 concatenate – Concatenate Strings . . . . . . . . . . . . . . . . . . . . . . . . . 397
equalTo – Compare Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
get – Get String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
isNull – Check Whether Null . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
TextMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
getText – get Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
setText – Set Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
TransactionInProgressException . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
TransactionRolledBackException . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

Chapter 17. Properties of XMS objects . . . . . . . . . . . . . . . . . . . . . . . . . 403

Properties of Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Properties of ConnectionFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Properties of ConnectionMetaData . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
Properties of Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Properties of InitialContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Properties of Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Properties of MessageConsumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Properties of MessageProducer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
Properties of Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
Property definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
JMS_IBM_ArmCorrelator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
JMS_IBM_CHARACTER_SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
JMS_IBM_ENCODING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
JMS_IBM_EXCEPTIONMESSAGE . . . . . . . . . . . . . . . . . . . . . . . . . . 419
JMS_IBM_EXCEPTIONPROBLEMDESTINATION . . . . . . . . . . . . . . . . . . . . . 419
JMS_IBM_EXCEPTIONREASON . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
JMS_IBM_EXCEPTIONTIMESTAMP. . . . . . . . . . . . . . . . . . . . . . . . . . 420
JMS_IBM_FEEDBACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
JMS_IBM_FORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
JMS_IBM_LAST_MSG_IN_GROUP . . . . . . . . . . . . . . . . . . . . . . . . . . 420
JMS_IBM_MSGTYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
JMS_IBM_PUTAPPLTYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
JMS_IBM_PUTDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
JMS_IBM_PUTTIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
JMS_IBM_REPORT_COA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
JMS_IBM_REPORT_COD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
JMS_IBM_REPORT_DISCARD_MSG. . . . . . . . . . . . . . . . . . . . . . . . . . 423
JMS_IBM_REPORT_EXCEPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
JMS_IBM_REPORT_EXPIRATION . . . . . . . . . . . . . . . . . . . . . . . . . . 424
JMS_IBM_REPORT_NAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
JMS_IBM_REPORT_PAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
JMS_IBM_REPORT_PASS_CORREL_ID . . . . . . . . . . . . . . . . . . . . . . . . . 426
JMS_IBM_REPORT_PASS_MSG_ID . . . . . . . . . . . . . . . . . . . . . . . . . . 426
JMS_IBM_RETAIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
JMS_IBM_SYSTEM_MESSAGEID . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
JMS_TOG_ARM_Correlator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
JMSX_APPID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
JMSX_DELIVERY_COUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
JMSX_GROUPID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
JMSX_GROUPSEQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
JMSX_USERID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
XMSC_ASYNC_EXCEPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
XMSC_CLIENT_CCSID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
XMSC_CLIENT_ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
XMSC_CONNECTION_TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
XMSC_DELIVERY_MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

128 Message Service Client for C/C++

XMSC_IC_PROVIDER_URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
XMSC_IC_SECURITY_AUTHENTICATION . . . . . . . . . . . . . . . . . . . . . . . 432
XMSC_IC_SECURITY_CREDENTIALS . . . . . . . . . . . . . . . . . . . . . . . . . 432
XMSC_IC_SECURITY_PRINCIPAL . . . . . . . . . . . . . . . . . . . . . . . . . . 433
XMSC_IC_SECURITY_PROTOCOL . . . . . . . . . . . . . . . . . . . . . . . . . . 433
XMSC_IC_URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
XMSC_IS_SUBSCRIPTION_MULTICAST . . . . . . . . . . . . . . . . . . . . . . . . 433
XMSC_IS_SUBSCRIPTION_RELIABLE_MULTICAST . . . . . . . . . . . . . . . . . . . . 433
XMSC_JMS_MAJOR_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
XMSC_JMS_MINOR_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
XMSC_JMS_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
XMSC_MAJOR_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
XMSC_MINOR_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
XMSC_PASSWORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
XMSC_PRIORITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
XMSC_PROVIDER_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
XMSC_RTT_CONNECTION_PROTOCOL . . . . . . . . . . . . . . . . . . . . . . . . 436
XMSC_RTT_HOST_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
XMSC_RTT_LOCAL_ADDRESS . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
XMSC_RTT_MULTICAST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
XMSC_RTT_PORT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
XMSC_TIME_TO_LIVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
XMSC_USERID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
XMSC_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
XMSC_WMQ_BROKER_CONTROLQ . . . . . . . . . . . . . . . . . . . . . . . . . 440
XMSC_WMQ_BROKER_PUBQ . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
XMSC_WMQ_BROKER_QMGR . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
XMSC_WMQ_BROKER_SUBQ . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
XMSC_WMQ_BROKER_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . 441
XMSC_WMQ_CCSID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
XMSC_WMQ_CHANNEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
XMSC_WMQ_CONNECTION_MODE . . . . . . . . . . . . . . . . . . . . . . . . . 442
XMSC_WMQ_DUR_SUBQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
XMSC_WMQ_ENCODING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
XMSC_WMQ_FAIL_IF_QUIESCE. . . . . . . . . . . . . . . . . . . . . . . . . . . 444
XMSC_WMQ_MESSAGE_BODY . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
XMSC_WMQ_MQMD_MESSAGE_CONTEXT . . . . . . . . . . . . . . . . . . . . . . 445
XMSC_WMQ_MQMD_READ_ENABLED . . . . . . . . . . . . . . . . . . . . . . . . 446
XMSC_WMQ_MQMD_WRITE_ENABLED . . . . . . . . . . . . . . . . . . . . . . . 447
XMSC_WMQ_PUT_ASYNC_ALLOWED . . . . . . . . . . . . . . . . . . . . . . . . 447
XMSC_WMQ_READ_AHEAD_ALLOWED . . . . . . . . . . . . . . . . . . . . . . . 448
XMSC_WMQ_READ_AHEAD_CLOSE_POLICY . . . . . . . . . . . . . . . . . . . . . . 449
XMSC_WMQ_HOST_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
XMSC_WMQ_LOCAL_ADDRESS . . . . . . . . . . . . . . . . . . . . . . . . . . 450
XMSC_WMQ_MESSAGE_SELECTION . . . . . . . . . . . . . . . . . . . . . . . . . 451
XMSC_WMQ_MSG_BATCH_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . 452
XMSC_WMQ_POLLING_INTERVAL . . . . . . . . . . . . . . . . . . . . . . . . . 452
XMSC_WMQ_PORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
XMSC_WMQ_PROVIDER_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . 453
XMSC_WMQ_PUB_ACK_INTERVAL . . . . . . . . . . . . . . . . . . . . . . . . . 454
XMSC_WMQ_QMGR_CCSID . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
XMSC_WMQ_QUEUE_MANAGER . . . . . . . . . . . . . . . . . . . . . . . . . . 455
XMSC_WMQ_RECEIVE_EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
XMSC_WMQ_RECEIVE_EXIT_INIT . . . . . . . . . . . . . . . . . . . . . . . . . . 455
XMSC_WMQ_SECURITY_EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
XMSC_WMQ_SECURITY_EXIT_INIT . . . . . . . . . . . . . . . . . . . . . . . . . 456
XMSC_WMQ_SEND_EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
XMSC_WMQ_SEND_EXIT_INIT . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
XMSC_WMQ_SEND_CHECK_COUNT . . . . . . . . . . . . . . . . . . . . . . . . . 457
XMSC_WMQ_SHARE_CONV_ALLOWED . . . . . . . . . . . . . . . . . . . . . . . 457
XMSC_WMQ_SSL_CERT_STORES . . . . . . . . . . . . . . . . . . . . . . . . . . 458

Part 4. XMS API reference 129

 XMSC_WMQ_SSL_CIPHER_SPEC . . . . . . . . . . . . . . . . . . . . . . . . . . 459
XMSC_WMQ_SSL_CIPHER_SUITE . . . . . . . . . . . . . . . . . . . . . . . . . . 459
XMSC_WMQ_SSL_CRYPTO_HW. . . . . . . . . . . . . . . . . . . . . . . . . . . 460
XMSC_WMQ_SSL_FIPS_REQUIRED . . . . . . . . . . . . . . . . . . . . . . . . . 461
XMSC_WMQ_SSL_KEY_REPOSITORY . . . . . . . . . . . . . . . . . . . . . . . . . 461
XMSC_WMQ_SSL_KEY_RESETCOUNT . . . . . . . . . . . . . . . . . . . . . . . . 462
XMSC_WMQ_SSL_PEER_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
XMSC_WMQ_SYNCPOINT_ALL_GETS . . . . . . . . . . . . . . . . . . . . . . . . 463
XMSC_WMQ_TARGET_CLIENT . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
XMSC_WMQ_TEMP_Q_PREFIX . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
XMSC_WMQ_TEMP_TOPIC_PREFIX . . . . . . . . . . . . . . . . . . . . . . . . . 464
XMSC_WMQ_TEMPORARY_MODEL . . . . . . . . . . . . . . . . . . . . . . . . . 464
XMSC_WMQ_WILDCARD_FORMAT . . . . . . . . . . . . . . . . . . . . . . . . . 464
XMSC_WPM_BUS_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
XMSC_WPM_CONNECTION_PROTOCOL . . . . . . . . . . . . . . . . . . . . . . . 465
XMSC_WPM_CONNECTION_PROXIMITY . . . . . . . . . . . . . . . . . . . . . . . 466
XMSC_WPM_DUR_SUB_HOME . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
XMSC_WPM_HOST_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
XMSC_WPM_LOCAL_ADDRESS. . . . . . . . . . . . . . . . . . . . . . . . . . . 467
XMSC_WPM_ME_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
XMSC_WPM_NON_PERSISTENT_MAP . . . . . . . . . . . . . . . . . . . . . . . . 468
XMSC_WPM_PERSISTENT_MAP . . . . . . . . . . . . . . . . . . . . . . . . . . 468
XMSC_WPM_PORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
XMSC_WPM_PROVIDER_ENDPOINTS . . . . . . . . . . . . . . . . . . . . . . . . 469
XMSC_WPM_SSL_CIPHER_SUITE . . . . . . . . . . . . . . . . . . . . . . . . . . 470
XMSC_WPM_SSL_KEY_REPOSITORY . . . . . . . . . . . . . . . . . . . . . . . . . 471
XMSC_WPM_SSL_KEYRING_LABEL . . . . . . . . . . . . . . . . . . . . . . . . . 471
XMSC_WPM_SSL_KEYRING_PW . . . . . . . . . . . . . . . . . . . . . . . . . . 471
XMSC_WPM_SSL_KEYRING_STASH_FILE . . . . . . . . . . . . . . . . . . . . . . . 472
XMSC_WPM_SSL_FIPS_REQUIRED . . . . . . . . . . . . . . . . . . . . . . . . . . 472
XMSC_WPM_TARGET_GROUP . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
XMSC_WPM_TARGET_SIGNIFICANCE . . . . . . . . . . . . . . . . . . . . . . . . 473
XMSC_WPM_TARGET_TRANSPORT_CHAIN . . . . . . . . . . . . . . . . . . . . . . 473
XMSC_WPM_TARGET_TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
XMSC_WPM_TEMP_Q_PREFIX . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
XMSC_WPM_TEMP_TOPIC_PREFIX . . . . . . . . . . . . . . . . . . . . . . . . . 474
XMSC_WPM_TOPIC_SPACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475

130 Message Service Client for C/C++

Chapter 14. C classes
This section documents the C classes and their functions.

The following table summarizes all the classes.

Table 31. Summary of the C classes
Class Description
“BytesMessage” on page 132 A bytes message is a message whose body
comprises a stream of bytes.
“Connection” on page 144 A Connection object represents an
application’s active connection to a broker.
“ConnectionFactory” on page 149 An application uses a connection factory to
create a connection.
“ConnectionMetaData” on page 152 A ConnectionMetaData object provides
information about a connection.
“Destination” on page 152 A destination is where an application sends
messages, or it is a source from which an
application receives messages, or both.
“ErrorBlock” on page 157 If a C function call fails, XMS can store
information about why the call failed in an
error block.
“ExceptionListener” on page 161 An application uses an exception listener to
be notified asynchronously of a problem
with a connection.
“InitialContext” on page 161 An application uses an InitialContext object
to create objects from object definitions that
are retrieved from a repository of
administered objects.
“Iterator” on page 163 An iterator encapsulates a list of objects. An
application uses an iterator to access each
object in turn.
“MapMessage” on page 165 A map message is a message whose body
comprises a set of name-value pairs, where
each value has an associated data type.
“Message” on page 179 A Message object represents a message that
an application sends or receives.
“MessageConsumer” on page 194 An application uses a message consumer to
receive messages sent to a destination.
“MessageListener” on page 198 An application uses a message listener to
receive messages asynchronously.
“MessageProducer” on page 198 An application uses a message producer to
send messages to a destination.
“ObjectMessage” on page 207 An object message is a message whose body
comprises a serialized Java or .NET object.
“Property” on page 209 A Property object represents a property of
an object.

© Copyright IBM Corp. 2005, 2009 131

 Table 31. Summary of the C classes (continued)
Class Description
“PropertyContext” on page 223 The PropertyContext class contains functions
that get and set properties. These functions
can operate on any object that can have
properties.
“QueueBrowser” on page 239 An application uses a queue browser to
browse messages on a queue without
removing them.
“Requestor” on page 241 An application uses a requestor to send a
request message and then wait for, and
receive, the reply.
“Session” on page 243 A session is a single threaded context for
sending and receiving messages.
“StreamMessage” on page 256 A stream message is a message whose body
comprises a stream of values, where each
value has an associated data type.
“TextMessage” on page 268 A text message is a message whose body
comprises a string.

The definition of each function lists the exception codes that XMS might return if it
detects an error while processing a call to the function. Each exception code is
represented by its named constant.

BytesMessage
A bytes message is a message whose body comprises a stream of bytes.

Functions
xmsBytesMsgGetBodyLength – Get Body Length
Interface:
xmsRC xmsBytesMsgGetBodyLength(xmsHMsg message,
xmsLONG *bodyLength,
xmsHErrorBlock errorBlock);

Get the length of the body of the message when the body of the message is
read-only.
Parameters:
message (input)
The handle for the message.
bodyLength (output)
The length of the body of the message in bytes. The function
returns the length of the whole body regardless of where the
cursor for reading the message is currently positioned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION

132 Message Service Client for C/C++

xmsBytesMsgReadBoolean – Read Boolean Value
Interface:
xmsRC xmsBytesMsgReadBoolean(xmsHMsg message,
xmsBOOL *value,
xmsHErrorBlock errorBlock);

Read a boolean value from the bytes message stream.

Parameters:
message (input)
The handle for the message.
value (output)
The boolean value that is read. If you specify a null pointer on
input, the function skips over the boolean value without reading it.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadByte – Read Byte

Interface:
xmsRC xmsBytesMsgReadByte(xmsHMsg message,
xmsSBYTE *value,
xmsHErrorBlock errorBlock);

Read the next byte from the bytes message stream as a signed 8-bit integer.
Parameters:
message (input)
The handle for the message.
value (output)
The byte that is read. If you specify a null pointer on input, the
function skips over the byte without reading it.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadBytes – Read Bytes

Interface:

Chapter 14. C classes 133

 xmsRC xmsBytesMsgReadBytes(xmsHMsg message,
xmsSBYTE *buffer,
xmsINT bufferLength,
xmsINT *returnedLength,
xmsHErrorBlock errorBlock);

Read an array of bytes from the bytes message stream starting from the current
position of the cursor.
Parameters:
message (input)
The handle for the message.
buffer (output)
The buffer to contain the array of bytes that is read. If the number
of bytes remaining to be read from the stream before the call is
greater than or equal to the length of the buffer, the buffer is filled.
Otherwise, the buffer is partially filled with all the remaining
bytes.
If you specify a null pointer on input, the function skips over the
bytes without reading them. If the number of bytes remaining to
be read from the stream before the call is greater than or equal to
the length of the buffer, the number of bytes skipped is equal to
the length of the buffer. Otherwise, all the remaining bytes are
skipped.
bufferLength (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, no bytes are read into the buffer, but the number of bytes
remaining in the stream, starting from the current position of the
cursor, is returned in the returnedLength parameter, and the cursor
is not advanced.
returnedLength (output)
The number of bytes that are read into the buffer. If the buffer is
partially filled, the value is less than the length of the buffer,
indicating that there are no more bytes remaining to be read. If
there are no bytes remaining to be read from the stream before the
call, the value is XMSC_END_OF_STREAM.
If you specify a null pointer on input, the function returns no
value.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION

xmsBytesMsgReadBytesByRef – Read Bytes by Reference

Interface:
xmsRC xmsBytesMsgReadBytesByRef(xmsHMsg message,
xmsSBYTE **stream,
xmsINT *length,
xmsHErrorBlock errorBlock);

134 Message Service Client for C/C++

Get a pointer to the start of the bytes message stream and get the length of the
stream.

For more information about how to use this function, see “C functions that return
a string or byte array by reference” on page 66.
Parameters:
message (input)
The handle for the message.
stream (output)
A pointer to the start of the bytes message stream.
length (output)
The number of bytes in the bytes message stream.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION

xmsBytesMsgReadChar – Read Character

Interface:
xmsRC xmsBytesMsgReadChar(xmsHMsg message,
xmsCHAR16 *value,
xmsHErrorBlock errorBlock);

Read the next 2 bytes from the bytes message stream as a character.
Parameters:
message (input)
The handle for the message.
value (output)
The character that is read. If you specify a null pointer on input,
the function skips over the bytes without reading them.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadDouble – Read Double Precision Floating

Point Number
Interface:
xmsRC xmsBytesMsgReadDouble(xmsHMsg message,
xmsDOUBLE *value,
xmsHErrorBlock errorBlock);

Chapter 14. C classes 135

 Read the next 8 bytes from the bytes message stream as a double precision floating
point number.
Parameters:
message (input)
The handle for the message.
value (output)
The double precision floating point number that is read. If you
specify a null pointer on input, the function skips over the bytes
without reading them.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadFloat – Read Floating Point Number

Interface:
xmsRC xmsBytesMsgReadFloat(xmsHMsg message,
xmsFLOAT *value,
xmsHErrorBlock errorBlock);

Read the next 4 bytes from the bytes message stream as a floating point number.
Parameters:
message (input)
The handle for the message.
value (output)
The floating point number that is read. If you specify a null pointer
on input, the function skips over the bytes without reading them.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadInt – Read Integer

Interface:
xmsRC xmsBytesMsgReadInt(xmsHMsg message,
xmsINT *value,
xmsHErrorBlock errorBlock);

Read the next 4 bytes from the bytes message stream as a signed 32-bit integer.
Parameters:

136 Message Service Client for C/C++

 message (input)
The handle for the message.
value (output)
The integer that is read. If you specify a null pointer on input, the
function skips over the bytes without reading them.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadLong – Read Long Integer

Interface:
xmsRC xmsBytesMsgReadLong(xmsHMsg message,
xmsLONG *value,
xmsHErrorBlock errorBlock);

Read the next 8 bytes from the bytes message stream as a signed 64-bit integer.
Parameters:
message (input)
The handle for the message.
value (output)
The long integer that is read. If you specify a null pointer on input,
the function skips over the bytes without reading them.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadShort – Read Short Integer

Interface:
xmsRC xmsBytesMsgReadShort(xmsHMsg message,
xmsSHORT *value,
xmsHErrorBlock errorBlock);

Read the next 2 bytes from the bytes message stream as a signed 16-bit integer.
Parameters:
message (input)
The handle for the message.
value (output)
The short integer that is read. If you specify a null pointer on
input, the function skips over the bytes without reading them.

Chapter 14. C classes 137

 errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadUnsignedByte – Read Unsigned Byte

Interface:
xmsRC xmsBytesMsgReadUnsignedByte(xmsHMsg message,
xmsBYTE *value,
xmsHErrorBlock errorBlock);

Read the next byte from the bytes message stream as an unsigned 8-bit integer.
Parameters:
message (input)
The handle for the message.
value (output)
The byte that is read. If you specify a null pointer on input, the
function skips over the byte without reading it.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadUnsignedShort – Read Unsigned Short Integer

Interface:
xmsRC xmsBytesMsgReadUnsignedShort(xmsHMsg message,
xmsUSHORT *value,
xmsHErrorBlock errorBlock);

Read the next 2 bytes from the bytes message stream as an unsigned 16-bit integer.
Parameters:
message (input)
The handle for the message.
value (output)
The unsigned short integer that is read. If you specify a null
pointer on input, the function skips over the bytes without reading
them.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
138 Message Service Client for C/C++
 v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

xmsBytesMsgReadUTF – Read UTF String

Interface:
xmsRC xmsBytesMsgReadUTF(xmsHMsg message,
xmsCHAR *buffer,
xmsINT bufferLength,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);

Read a string, encoded in UTF-8, from the bytes message stream. If required, XMS
converts the characters in the string from UTF-8 into the local code page.

For more information about how to use this function, see “C functions that return
a string by value” on page 64.
Parameters:
message (input)
The handle for the message.
buffer (output)
The buffer to contain the string that is read. If data conversion is
required, this is the string after conversion.
bufferLength (input)
The length of the buffer in bytes.
If you specify XMSC_QUERY_SIZE, the string is not returned, but its
length is returned in the actualLength parameter, and the cursor is
not advanced.
If you specify XMSC_SKIP, the function skips over the string without
reading it.
actualLength (output)
The length of the string in bytes. If data conversion is required,
this is the length of the string after conversion. If you specify a
null pointer on input, the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

Notes:
1. If the buffer is not large enough to store the whole string, XMS returns
the string truncated to the length of the buffer, sets the actualLength
parameter to the actual length of the string, and returns an error. XMS
does not advance the internal cursor.
2. If any other error occurs while attempting to read the string, XMS
reports the error but does not set the actualLength parameter or
advance the internal cursor.

Chapter 14. C classes 139

 xmsBytesMsgReset – Reset
Interface:
xmsRC xmsBytesMsgReset(xmsHMsg message,
xmsHErrorBlock errorBlock);

Put the body of the message into read-only mode and reposition the cursor at the
beginning of the bytes message stream.
Parameters:
message (input)
The handle for the message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION

xmsBytesMsgWriteBoolean – Write Boolean Value

Interface:
xmsRC xmsBytesMsgWriteBoolean(xmsHMsg message,
xmsBOOL value,
xmsHErrorBlock errorBlock);

Write a boolean value to the bytes message stream.

Parameters:
message (input)
The handle for the message.
value (input)
The boolean value to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteByte – Write Byte

Interface:
xmsRC xmsBytesMsgWriteByte(xmsHMsg message,
xmsSBYTE value,
xmsHErrorBlock errorBlock);

Write a byte to the bytes message stream.

Parameters:

140 Message Service Client for C/C++

 message (input)
The handle for the message.
value (input)
The byte to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteBytes – Write Bytes

Interface:
xmsRC xmsBytesMsgWriteBytes(xmsHMsg message,
xmsSBYTE *value,
xmsINT length,
xmsHErrorBlock errorBlock);

Write an array of bytes to the bytes message stream.

Parameters:
message (input)
The handle for the message.
value (input)
The array of bytes to be written.
length (input)
The number of bytes in the array.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteChar – Write Character

Interface:
xmsRC xmsBytesMsgWriteChar(xmsHMsg message,
xmsCHAR16 value,
xmsHErrorBlock errorBlock);

Write a character to the bytes message stream as 2 bytes, high order byte first.
Parameters:
message (input)
The handle for the message.
value (input)
The character to be written.

Chapter 14. C classes 141

 errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteDouble – Write Double Precision Floating

Point Number
Interface:
xmsRC xmsBytesMsgWriteDouble(xmsHMsg message,
xmsDOUBLE value,
xmsHErrorBlock errorBlock);

Convert a double precision floating point number to a long integer and write the
long integer to the bytes message stream as 8 bytes, high order byte first.
Parameters:
message (input)
The handle for the message.
value (input)
The double precision floating point number to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteFloat – Write Floating Point Number

Interface:
xmsRC xmsBytesMsgWriteFloat(xmsHMsg message,
xmsFLOAT value,
xmsHErrorBlock errorBlock);

Convert a floating point number to an integer and write the integer to the bytes
message stream as 4 bytes, high order byte first.
Parameters:
message (input)
The handle for the message.
value (input)
The floating point number to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

142 Message Service Client for C/C++

xmsBytesMsgWriteInt – Write Integer
Interface:
xmsRC xmsBytesMsgWriteInt(xmsHMsg message,
xmsINT value,
xmsHErrorBlock errorBlock);

Write an integer to the bytes message stream as 4 bytes, high order byte first.
Parameters:
message (input)
The handle for the message.
value (input)
The integer to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteLong – Write Long Integer

Interface:
xmsRC xmsBytesMsgWriteLong(xmsHMsg message,
xmsLONG value,
xmsHErrorBlock errorBlock);

Write a long integer to the bytes message stream as 8 bytes, high order byte first.
Parameters:
message (input)
The handle for the message.
value (input)
The long integer to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteShort – Write Short Integer

Interface:
xmsRC xmsBytesMsgWriteShort(xmsHMsg message,
xmsSHORT value,
xmsHErrorBlock errorBlock);

Write a short integer to the bytes message stream as 2 bytes, high order byte first.

Chapter 14. C classes 143

 Parameters:
message (input)
The handle for the message.
value (input)
The short integer to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsBytesMsgWriteUTF – Write UTF String

Interface:
xmsRC xmsBytesMsgWriteUTF(xmsHMsg message,
xmsCHAR *value,
xmsINT length,
xmsHErrorBlock errorBlock);

Write a string, encoded in UTF-8, to the bytes message stream. If required, XMS
converts the characters in the string from the local code page into UTF-8.
Parameters:
message (input)
The handle for the message.
value (input)
A character array containing the string to be written.
length (input)
The length of the string in bytes. If the string is null terminated
with no embedded null characters, you can specify
XMSC_CALCULATE_STRING_SIZE instead and allow XMS to calculate
its length.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

Connection
A Connection object represents an application’s active connection to a broker.

For a list of the XMS defined properties of a Connection object, see “Properties of
Connection” on page 403.

Functions
xmsConnClose – Close Connection
Interface:

144 Message Service Client for C/C++

 xmsRC xmsConnClose(xmsHConn *connection,
xmsHErrorBlock errorBlock);

Close the connection.

If an application tries to close a connection that is already closed, the call is

ignored.
Parameters:
connection (input/output)
On input, the handle for the connection. On output, the function
returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsConnCreateSession – Create Session

Interface:
xmsRC xmsConnCreateSession(xmsHConn connection,
xmsBOOL transacted,
xmsINT acknowledgeMode,
xmsHSess *session,
xmsHErrorBlock errorBlock);

Create a session.
Parameters:
connection (input)
The handle for the connection.
transacted (input)
The value xmsTRUE means that the session is transacted. The value
xmsFALSE means that the session is not transacted.
For a real-time connection to a broker, the value must be xmsFALSE.
acknowledgeMode (input)
Indicates how messages received by an application are
acknowledged. The value must be one of the following
acknowledgement modes:
XMSC_AUTO_ACKNOWLEDGE
XMSC_CLIENT_ACKNOWLEDGE
XMSC_DUPS_OK_ACKNOWLEDGE
For a real-time connection to a broker, the value must be
XMSC_AUTO_ACKNOWLEDGE or XMSC_DUPS_OK_ACKNOWLEDGE.

This parameter is ignored if the session is transacted. For more

information about acknowledgement modes, see “Message
acknowledgement” on page 39.
session (output)
The handle for the session.

Chapter 14. C classes 145

 errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsConnGetClientID – Get Client ID

Interface:
xmsRC xmsConnGetClientID(xmsHConn connection,
xmsCHAR *clientID,
xmsINT length,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);

Get the client identifier for the connection.

This function is not valid for a real-time connection to a broker.

For more information about how to use this function, see “C functions that return
a string by value” on page 64.
Parameters:
connection (input)
The handle for the connection.
clientID (output)
The buffer to contain the client identifier.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the client identifier is not returned, but its length is
returned in the actualLength parameter.
actualLength (output)
The length of the client identifier in bytes. If data conversion is
required, this is the length of the client identifier after conversion.
If you specify a null pointer on input, the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsConnGetExceptionListener – Get Exception Listener

Interface:
xmsRC xmsConnGetExceptionListener(xmsHConn connection,
fpXMS_EXCEPTION_CALLBACK *lsr,
xmsCONTEXT *context,
xmsHErrorBlock errorBlock);

Get pointers to the exception listener function and context data that are registered
with the connection.

146 Message Service Client for C/C++

For more information about using exception listener functions, see “Exception
listener functions in C” on page 69.
Parameters:
connection (input)
The handle for the connection.
lsr (output)
A pointer to the exception listener function. If no exception listener
function is registered with the connection, the call returns a null
pointer.
context (output)
A pointer to the context data. If no exception listener function is
registered with the connection, the call returns a null pointer.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsConnGetMetaData – Get Metadata

Interface:
xmsRC xmsConnGetMetaData(xmsHConn connection,
xmsHConnMetaData *connectionMetaData,
xmsHErrorBlock errorBlock);

Get the metadata for the connection.

Parameters:
connection (input)
The handle for the connection.
connectionMetaData (output)
The handle for the connection metadata.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsConnSetClientID – Set Client ID

Interface:
xmsRC xmsConnSetClientID(xmsHConn connection,
xmsCHAR *clientID,
xmsINT length,
xmsHErrorBlock errorBlock)

Set a client identifier for the connection. A client identifier is used only to support
durable subscriptions in the publish/subscribe domain, and is ignored in the
point-to-point domain.

Chapter 14. C classes 147

 If an application calls this function to set a client identifier for a connection, the
application must do so immediately after creating the connection, and before
performing any other operation on the connection. If the application tries to call
the function after this point, the function returns exception
XMS_X_ILLEGAL_STATE_EXCEPTION.

This method is not valid for a real-time connection to a broker.

Parameters:
connection (input)
The handle for the connection.
clientID (input)
The client identifier as a character array.
length (input)
The length of the client identifier in bytes. If the client identifier is
null terminated with no embedded null characters, you can specify
XMSC_CALCULATE_STRING_SIZE instead and allow XMS to calculate
its length.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_ILLEGAL_STATE_EXCEPTION
v XMS_X_INVALID_CLIENTID_EXCEPTION

xmsConnSetExceptionListener – Set Exception Listener

Interface:
xmsRC xmsConnSetExceptionListener(xmsHConn connection,
fpXMS_EXCEPTION_CALLBACK lsr,
xmsCONTEXT context,
xmsHErrorBlock errorBlock);

Register an exception listener function and context data with the connection.

For more information about using exception listener functions, see “Exception
listener functions in C” on page 69.
Parameters:
connection (input)
The handle for the connection.
lsr (input)
A pointer to the exception listener function. If an exception listener
function is already registered with the connection, you can cancel
the registration by specifying a null pointer instead.
context (input)
A pointer to the context data.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:

148 Message Service Client for C/C++

 v XMS_X_GENERAL_EXCEPTION

xmsConnStart – Start Connection

Interface:
xmsRC xmsConnStart(xmsHConn connection,
xmsHErrorBlock errorBlock);

Start, or restart the delivery of incoming messages for the connection. The call is
ignored if the connection is already started.
Parameters:
connection (input)
The handle for the connection.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsConnStop – Stop Connection

Interface:
xmsRC xmsConnStop(xmsHConn connection,
xmsHErrorBlock errorBlock);

Stop the delivery of incoming messages for the connection. The call is ignored if
the connection is already stopped.
Parameters:
connection (input)
The handle for the connection.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

ConnectionFactory
An application uses a connection factory to create a connection.

For a list of the XMS defined properties of a ConnectionFactory object, see

“Properties of ConnectionFactory” on page 404.

Functions
xmsConnFactCreate – Create Connection Factory
Interface:
xmsRC xmsConnFactCreate(xmsHConnFact *factory,
xmsHErrorBlock errorBlock);

Chapter 14. C classes 149

 Create a connection factory with the default properties.
Parameters:
factory (output)
The handle for the connection factory.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsConnFactCreateConnection – Create Connection (using the

default user identity)
Interface:
xmsRC xmsConnFactCreateConnection(xmsHConnFact factory,
xmsHConn *connection,
xmsHErrorBlock errorBlock);

Create a connection using the default user identity.

If you are connecting to WebSphere MQ, and you set the XMSC_USERID property
of the connection factory, it must match the userid of the logged on user. If you do
not set these properties, the queue manager will use the userid of the logged on
user by default. If you require further connection-level authentication of individual
users you can write a client authentication exit which is configured in WebSphere
MQ. You can learn more about creating a client authentication exit in the
Authentication topic in the WebSphere MQ Clients manual.

The connection is created in stopped mode. No messages are delivered until the
application calls xmsConnStart().
Parameters:
factory (input)
The handle for the connection factory.
connection (output)
The handle for the connection.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_SECURITY_EXCEPTION

xmsConnFactCreateConnectionForUser – Create Connection

(using a specified user identity)
Interface:
xmsRC xmsConnFactCreateConnectionForUser(xmsHConnFact factory,
xmsCHAR *userID,
xmsCHAR *password,
xmsHConn *connection,
xmsHErrorBock errorBlock);

150 Message Service Client for C/C++

Create a connection using a specified user identity.

If you are connecting to WebSphere MQ, and you set the XMSC_USERID property
of the connection factory, it must match the userid of the logged on user. If you do
not set these properties, the queue manager will use the userid of the logged on
user by default. If you require further connection-level authentication of individual
users you can write a client authentication exit which is configured in WebSphere
MQ. You can learn more about creating a client authentication exit in the
Authentication topic in the WebSphere MQ Clients manual.

The connection is created in stopped mode. No messages are delivered until the
application calls xmsConnStart().
Parameters:
factory (input)
The handle for the connection factory.
userID (input)
The user identifier to be used to authenticate the application. The
user identifier is in the format of a null terminated string. If the
user identifier is null, the connection factory property
XMSC_USERID is used instead.
password (input)
The password to be used to authenticate the application. The
password is in the format of a null terminated string. If the
password is null, the connection factory property
XMSC_PASSWORD is used instead.
connection (output)
The handle for the connection.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_SECURITY_EXCEPTION

xmsConnFactDispose – Delete Connection Factory

Interface:
xmsRC xmsConnFactDispose(xmsHConnFact *factory,
xmsHErrorBlock errorBlock);

Delete the connection factory.

If an application tries to delete a connection factory that is already deleted, the call
is ignored.
Parameters:
factory (input/output)
On input, the handle for the connection factory. On output, the
function returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.

Chapter 14. C classes 151

 Exceptions:
v XMS_X_GENERAL_EXCEPTION

ConnectionMetaData
A ConnectionMetaData object provides information about a connection.

For a list of the XMS defined properties of a ConnectionMetaData object, see

“Properties of ConnectionMetaData” on page 408.

Functions
xmsConnMetaDataGetJMSXProperties – Get JMS Defined
Message Properties
Interface:
xmsRC
xmsConnMetaDataGetJMSXProperties(xmsHConnMetaData connectionMetaData,
xmsHIterator *iterator,
xmsHErrorBlock errorBlock);

Get a list of the names of the JMS defined message properties supported by the
connection.

The function returns an iterator that encapsulates a list of Property objects, where
each Property object encapsulates the name of a JMS defined message property.
The application can then use the iterator to retrieve the name of each JMS defined
message property in turn.

JMS defined message properties are not supported by a real-time connection to a

broker.

Note: The equivalent JMS method performs a slightly different function. The JMS
method returns an enumeration of the names of the JMS defined message
properties.
Parameters:
connectionMetaData (input)
The handle for the connection metadata.
iterator (output)
The handle for the iterator.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Destination
A destination is where an application sends messages, or it is a source from which
an application receives messages, or both.

For a list of the XMS defined properties of a Destination object, see “Properties of
Destination” on page 409.

152 Message Service Client for C/C++

Functions
xmsDestCreate – Create Destination (using a URI)
Interface:
xmsRC xmsDestCreate(xmsCHAR *URI,
xmsHDest *destination,
xmsHErrorBlock errorBlock);

Create a destination using the specified uniform resource identifier (URI).

Properties of the destination that are not specified by the URI take the default
values.

For a destination that is a queue, this function does not create the queue in the
messaging server. You must create the queue before an application can call this
function.
Parameters:
URI (input)
The URI in the format of a null terminated string.
destination (output)
The handle for the destination.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsDestCreateByType – Create Destination (specifying a type

and name)
Interface:
xmsRC xmsDestCreateByType(xmsDESTINATION_TYPE destinationType,
xmsCHAR *destinationName,
xmsHDest *destination,
xmsHErrorBlock errorBlock);

Create a destination using the specified destination type and name.

For a destination that is a queue, this function does not create the queue in the
messaging server. You must create the queue before an application can call this
function.
Parameters:
destinationType (input)
The type of the destination, which must be one of the following
values:
XMS_DESTINATION_TYPE_QUEUE
XMS_DESTINATION_TYPE_TOPIC
destinationName (input)
The name of the destination, which can be the name of a queue or
the name of a topic. The name is in the format of a null terminated
string.

Chapter 14. C classes 153

 If the destination is a WebSphere MQ queue, you can specify the
name of the destination in either of the following ways:
QName
QMgrName/QName
where QName is the name of a WebSphere MQ queue, and QMgrName
is the name of a WebSphere MQ queue manager. The WebSphere
MQ queue name resolution process uses the values of QName and
QMgrName to determine the actual destination queue. For more
information about the queue name resolution process, see the
WebSphere MQ Application Programming Guide.
destination (output)
The handle for the destination.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsDestCreateTemporaryByType – Create Temporary Destination

Interface:
xmsRC xmsDestCreateTemporaryByType(xmsDESTINATION_TYPE destinationType,
xmsHSess session,
xmsHDest *destination,
xmsHErrorBlock errorBlock);

Create a temporary destination.

The scope of the temporary destination is the connection. Only the sessions created
by the connection can use the temporary destination.

The temporary destination remains until it is explicitly deleted, or the connection

ends, whichever is the sooner.

For more information about temporary destinations, see “Temporary destinations”

on page 45.
Parameters:
destinationType (input)
The type of the temporary destination, which must be one of the
following values:
XMS_DESTINATION_TYPE_QUEUE
XMS_DESTINATION_TYPE_TOPIC
session (input)
The handle for the session.
destination (output)
The handle for the temporary destination.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
154 Message Service Client for C/C++
xmsDestDispose – Delete Destination
Interface:
xmsRC xmsDestDispose(xmsHDest *destination,
xmsHErrorBlock errorBlock);

Delete the destination.

For a destination that is a queue, this function does not delete the queue in the
messaging server unless the queue was created for an XMS temporary queue.

If an application tries to delete a destination that is already deleted, the call is

ignored.
Parameters:
destination (input/output)
On input, the handle for the destination. On output, the function
returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsDestGetName – Get Destination Name

Interface:
xmsRC xmsDestGetName(xmsHDest destination,
xmsCHAR *destinationName,
xmsINT length,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);

Get the name of the destination.

For more information about how to use this function, see “C functions that return
a string by value” on page 64.
Parameters:
destination (input)
The handle for the destination.
destinationName (output)
The buffer to contain the name of the destination. The name is
either the name of a queue or the name of a topic.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the name of the destination is not returned, but its length
is returned in the actualLength parameter.
actualLength (output)
The length of the name of the destination in bytes. If you specify a
null pointer on input, the length is not returned.

Chapter 14. C classes 155

 errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsDestGetTypeId – Get Destination Type

Interface:
xmsRC xmsDestGetTypeId(xmsHDest destination,
xmsDESTINATION_TYPE *destinationType,
xmsHErrorBlock errorBlock);

Get the type of the destination.

Parameters:
destination (input)
The handle for the destination.
destinationType (output)
The type of the destination, which is one of the following values:
XMS_DESTINATION_TYPE_QUEUE
XMS_DESTINATION_TYPE_TOPIC
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsDestToString – Get Destination Name as URI

Interface:
xmsRC xmsDestToString(xmsHDest destination,
xmsCHAR *destinationName,
xmsINT length,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);

Get the name of the destination in the format of a uniform resource identifier
(URI).

For more information about how to use this function, see “C functions that return
a string by value” on page 64.
Parameters:
destination (input)
The handle for the destination.
destinationName (output)
The buffer to contain the URI. The URI is either a queue URI or a
topic URI.

156 Message Service Client for C/C++

 length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the URI is not returned, but its length is returned in the
actualLength parameter.
actualLength (output)
The length of the URI in bytes. If you specify a null pointer on
input, the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

ErrorBlock
If a C function call fails, XMS can store information about why the call failed in an
error block.

For more information about the error block and its contents, see “The error block”
on page 67.

Functions in this class return the following return codes:

Return code Meaning

XMS_OK The call completed successfully.
Any other value The call failed, for example, because the
error block that was passed to the function
was not valid.

This class is a helper class.

Functions
xmsErrorClear – Clear Error Block
Interface:
xmsRC xmsErrorClear(xmsHErrorBlock errorBlock);

Clear the contents of the error block.

Note that XMS automatically clears the contents of an error block that is passed by
an API function call.
Parameters:
errorBlock (input)
The handle for the error block.
Thread context:
Any

xmsErrorCreate – Create Error Block

Interface:
xmsRC xmsErrorCreate(xmsHErrorBlock *errorBlock);

Chapter 14. C classes 157

 Create an error block.

In a newly created error block, the exception code is XMS_X_NO_EXCEPTION.

Parameters:
errorBlock (output)
The handle for the error block.
Thread context:
Any

xmsErrorDispose – Delete Error Block

Interface:
xmsRC xmsErrorDispose(xmsHErrorBlock *errorBlock);

Delete the error block.

Only the first error block in a chain of error blocks can be explicitly deleted. By
deleting the first error block in a chain, all subsequent error blocks in the chain are
also deleted.

If an application tries to delete an error block that is already deleted, the call is
ignored.
Parameters:
errorBlock (input/output)
On input, the handle for the error block. On output the function
returns a null handle.
Thread context:
Any

xmsErrorGetErrorCode – Get Error Code

Interface:
xmsRC xmsErrorGetErrorCode(xmsHErrorBlock errorBlock,
xmsINT *errorCode);

Get the error code.

For more information about the error code, see “The error block” on page 67.
Parameters:
errorBlock (input)
The handle for the error block.
errorCode (output)
The error code.
Thread context:
Any

158 Message Service Client for C/C++

xmsErrorGetErrorData – Get Error Data
Interface:
xmsRC xmsErrorGetErrorData(xmsHErrorBlock errorBlock,
xmsCHAR *buffer,
xmsINT bufferLength,
xmsINT *actualLength);

Get the error data.

For more information about the error data, see “The error block” on page 67.

For more information about how to use this function, see “C functions that return
a string by value” on page 64.
Parameters:
errorBlock (input)
The handle for the error block.
buffer (output)
The buffer to contain the error data.
bufferLength (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the error data is not returned, but its length is returned in
the actualLength parameter.
actualLength (output)
The length of the error data in bytes. If you specify a null pointer
on input, the length is not returned.
Thread context:
Any

xmsErrorGetErrorString – Get Error String

Interface:
xmsRC xmsErrorGetErrorString(xmsHErrorBlock errorBlock,
xmsCHAR *buffer,
xmsINT bufferLength,
xmsINT *actualLength);

Get the error string.

For more information about the error string, see “The error block” on page 67.

For more information about how to use this function, see “C functions that return
a string by value” on page 64.
Parameters:
errorBlock (input)
The handle for the error block.
buffer (output)
The buffer to contain the error string.

Chapter 14. C classes 159

 bufferLength (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the error string is not returned, but its length is returned
in the actualLength parameter.
actualLength (output)
The length of the error string in bytes. If you specify a null pointer
on input, the length is not returned.
Thread context:
Any

xmsErrorGetJMSException – Get Exception Code

Interface:
xmsRC xmsErrorGetJMSException(xmsHErrorBlock errorBlock,
xmsJMSEXP_TYPE *exceptionCode);

Get the exception code.

For more information about the exception code, see “The error block” on page 67.
Parameters:
errorBlock (input)
The handle for the error block.
exceptionCode (output)
The exception code. If the error block is in a chain of error blocks,
but is not the first in the chain, the exception code is always
XMS_X_GENERAL_EXCEPTION.
Thread context:
Any

xmsErrorGetLinkedError – Get Linked Error

Interface:
xmsRC xmsErrorGetLinkedError(xmsHErrorBlock errorBlock,
xmsHErrorBlock *linkedError);

Get the handle for the next error block in the chain of error blocks.
Parameters:
errorBlock (input)
The handle for the error block.
linkedError (output)
The handle for the next error block in the chain. The function
returns a null handle if there are no more error blocks in the chain.
Thread context:
Any

160 Message Service Client for C/C++

ExceptionListener
An application uses an exception listener to be notified asynchronously of a
problem with a connection.

If an application uses a connection only to consume messages asynchronously, and

for no other purpose, then the only way the application can learn about a problem
with the connection is by using an exception listener. In other situations, an
exception listener can provide a more immediate way of learning about a problem
with a connection than waiting until the next synchronous call to XMS.

Functions
onException – On Exception
Interface:
xmsVOID onException(xmsCONTEXT context,
xmsHErrorBlock errorBlock);

Notify the application of a problem with a connection.

onException() is the exception listener function that is registered with the

connection. The name of the function does not have to be onException.

For more information about using exception listener functions, see “Exception
listener functions in C” on page 69.
Parameters:
context (input)
A pointer to the context data that is registered with the connection.
errorBlock (input)
The handle for an error block created by XMS.

InitialContext
An application uses an InitialContext object to create objects from object definitions
that are retrieved from a repository of administered objects.

For a list of the XMS defined properties of an InitialContext object, see “Properties
of InitialContext” on page 410.

Functions
xmsInitialContextCreate – Create Initial Context
Interface:
xmsRC xmsInitialContextCreate(xmsCHAR *URL,
xmsHInitialContect *initalContext,
xmsHErrorBlock errorBlock);

Create an InitialContext object.

Parameters:
URL (input)
A uniform resource locator (URL) that identifies the name and

Chapter 14. C classes 161

 location of a repository containing administered objects. The URL
is in the format of a null terminated string.
initialContext (output)
The handle for the InitialContext object.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsInitialContextDispose – Delete Initial Context

Interface:
xmsRC xmsInitialContextDispose(xmsHInitialContext *initialContext,
xmsHErrorBlock errorBlock);

Delete the InitialContext object.

If an application tries to delete an InitialContext object that is already deleted, the

call is ignored.
Parameters:
initialContext (input/output)
On input, the handle for the InitialContext object. On output, the
function returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsInitialContextLookup – Look Up Object in Initial Context

Interface:
xmsRC xmsInitialContextLookup(xmsHInitialContext initialContext,
xmsCHAR *objectName,
xmsHObj *returnedObject,
xmsHANDLE_TYPE *handleType,
xmsHErrorBlock errorBlock);

Create an object from an object definition that is retrieved from the repository of
administered objects.
Parameters:
initialContext (input)
The handle for the InitialContext object.
objectName (input)
The name of the administered object in the format of a null
terminated string.
returnedObject (output)
The handle for the object that is created.

162 Message Service Client for C/C++

 handleType (output)
The type of the handle for the object that is created, which is one
of following values:
XMS_HANDLE_TYPE_CONNFACT
XMS_HANDLE_TYPE_DEST
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Iterator
An iterator encapsulates a list of objects. An application uses an iterator to access
each object in turn.

An iterator also encapsulates a cursor that maintains the current position in the
list. When an iterator is created, the position of the cursor is before the first object.

An application cannot create an iterator directly. An iterator is created only by

certain functions in order to pass a list of objects back to the application.

This class is a helper class.

Functions
xmsIteratorDispose – Delete Iterator
Interface:
xmsRC xmsIteratorDispose(xmsHIterator *iterator,
xmsHErrorBlock errorBlock);

Delete the iterator.

If an application tries to delete an iterator that is already deleted, the call is

ignored.
Parameters:
iterator (input/output)
On input, the handle for the iterator. On output, the function
returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsIteratorGetNext – Get Next Object

Interface:

Chapter 14. C classes 163

 xmsRC xmsIteratorGetNext(xmsHIterator iterator,
xmsHObj *object,
xmsHErrorBlock errorBlock);

Move the cursor to the next object and get the object at the new position of the
cursor.
Parameters:
iterator (input)
The handle for the iterator.
object (output)
The handle for the object.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsIteratorHasNext – Check for More Objects

Interface:
xmsRC xmsIteratorHasNext(xmsHIterator iterator,
xmsBOOL *moreProperties,
xmsHErrorBlock errorBlock);

Check whether there are any more objects beyond the current position of the
cursor. The call does not move the cursor.
Parameters:
iterator (input)
The handle for the iterator.
moreProperties (output)
The value is xmsTRUE if there are more objects beyond the current
position of the cursor. The value is xmsFALSE if there are no more
objects beyond the current position of the cursor.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsIteratorReset – Reset Iterator

Interface:
xmsRC xmsIteratorReset(xmsHIterator iterator,
xmsHErrorBlock errorBlock);

Move the cursor back to a position before the first object.

164 Message Service Client for C/C++
 Parameters:
iterator (input)
The handle for the iterator.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

MapMessage
A map message is a message whose body comprises a set of name-value pairs,
where each value has an associated data type.

When an application gets the value of name-value pair, the value can be converted
by XMS into another data type. For more information about this form of implicit
conversion, see “Map messages” on page 104.

Functions
xmsMapMsgGetBoolean – Get Boolean Value
Interface:
xmsRC xmsMapMsgGetBoolean(xmsHMsg message,
xmsCHAR *name,
xmsBOOL *value,
xmsHErrorBlock errorBlock);

Get the boolean value identified by name from the body of the map message.
Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the boolean value. The name is in the
format of a null terminated string.
value (output)
The boolean value retrieved from the body of the map message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetByte – Get Byte

Interface:
xmsRC xmsMapMsgGetByte(xmsHMsg message,
xmsCHAR *name,
xmsSBYTE *value,
xmsHErrorBlock errorBlock);

Chapter 14. C classes 165

 Get the byte identified by name from the body of the map message.
Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the byte. The name is in the format of a
null terminated string.
value (output)
The byte retrieved from the body of the map message. No data
conversion is performed on the byte.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetBytes – Get Bytes

Interface:
xmsRC xmsMapMsgGetBytes(xmsHMsg message,
xmsCHAR *name,
xmsSBYTE *buffer,
xmsINT bufferLength,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);

Get the array of bytes identified by name from the body of the map message.

For more information about how to use this function, see “C functions that return
a byte array by value” on page 65.
Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the array of bytes. The name is in the
format of a null terminated string.
buffer (output)
The buffer to contain the array of bytes. No data conversion is
performed on the bytes that are returned.
bufferLength (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the array of bytes is not returned, but its length is returned
in the actualLength parameter.
actualLength (output)
The number of bytes in the array. If you specify a null pointer on
input, the length of the array is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:

166 Message Service Client for C/C++

 v XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetBytesByRef – Get Bytes by Reference

Interface:
xmsRC xmsMapMsgGetBytesByRef(xmsHMsg message,
xmsCHAR *name,
xmsSBYTE **array,
xmsINT *length,
xmsHErrorBlock errorBlock);

Get a pointer to an array of bytes in the body of the map message and get the
length of the array. The array of bytes is identified by name.

For more information about how to use this function, see “C functions that return
a string or byte array by reference” on page 66.
Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the array of bytes. The name is in the
format of a null terminated string.
array (output)
A pointer to the array of bytes.
length (output)
The number of bytes in the array.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetChar – Get Character

Interface:
xmsRC xmsMapMsgGetChar(xmsHMsg message,
xmsCHAR *name,
xmsCHAR16 *value,
xmsHErrorBlock errorBlock);

Get the character identified by name from the body of the map message.
Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the character. The name is in the format of
a null terminated string.
value (output)
The character retrieved from the body of the map message.

Chapter 14. C classes 167

 errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetDouble – Get Double Precision Floating Point

Number
Interface:
xmsRC xmsMapMsgGetDouble(xmsHMsg message,
xmsCHAR *name,
xmsDOUBLE *value,
xmsHErrorBlock errorBlock);

Get the double precision floating point number identified by name from the body
of the map message.
Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the double precision floating point
number. The name is in the format of a null terminated string.
value (output)
The double precision floating point number retrieved from the
body of the map message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetFloat – Get Floating Point Number

Interface:
xmsRC xmsMapMsgGetFloat(xmsHMsg message,
xmsCHAR *name,
xmsFLOAT *value,
xmsHErrorBlock errorBlock);

Get the floating point number identified by name from the body of the map
message.
Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the floating point number. The name is in
the format of a null terminated string.

168 Message Service Client for C/C++

 value (output)
The floating point number retrieved from the body of the map
message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetInt – Get Integer

Interface:
xmsRC xmsMapMsgGetInt(xmsHMsg message,
xmsCHAR *name,
xmsINT *value,
xmsHErrorBlock errorBlock);

Get the integer identified by name from the body of the map message.
Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the integer. The name is in the format of a
null terminated string.
value (output)
The integer retrieved from the body of the map message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetLong – Get Long Integer

Interface:
xmsRC xmsMapMsgGetLong(xmsHMsg message,
xmsCHAR *name,
xmsLONG *value,
xmsHErrorBlock errorBlock);

Get the long integer identified by name from the body of the map message.
Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the long integer. The name is in the
format of a null terminated string.
value (output)
The long integer retrieved from the body of the map message.

Chapter 14. C classes 169

 errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetMap – Get Name-Value Pairs

Interface:
xmsRC xmsMapMsgGetMap(xmsHMsg message,
xmsHIterator *iterator,
xmsHErrorBlock errorBlock);

Get a list of the name-value pairs in the body of the map message.

The function returns an iterator that encapsulates a list of Property objects, where
each Property object encapsulates a name-value pair. The application can then use
the iterator to access each name-value pair in turn.

Note: The equivalent JMS method performs a slightly different function. The JMS
method returns an enumeration of only the names, not the values, in the
body of the map message.
Parameters:
message (input)
The handle for the message.
iterator (output)
The handle for the iterator.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetObject – Get Object

Interface:
xmsRC xmsMapMsgGetObject(xmsHMsg message,
xmsCHAR *name,
xmsSBYTE *buffer,
xmsINT bufferLength,
xmsINT *actualLength,
xmsOBJECT_TYPE *objectType,
xmsHErrorBlock errorBlock);

Get the value of a name-value pair, and its data type, from the body of the map
message. The name-value pair is identified by name.

For more information about how to use this function, see “C functions that return
a byte array by value” on page 65.
Parameters:
message (input)
The handle for the message.

170 Message Service Client for C/C++

 name (input)
The name of the name-value pair in the format of a null
terminated string.
buffer (output)
The buffer to contain the value, which is returned as an array of
bytes. If the value is a string and data conversion is required, this
is the value after conversion.
bufferLength (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the value is not returned, but its length is returned in the
actualLength parameter.
actualLength (output)
The length of the value in bytes. If the value is a string and data
conversion is required, this is the length after conversion. If you
specify a null pointer on input, the length is not returned.
objectType (output)
The data type of the value, which is one of the following object
types:
XMS_OBJECT_TYPE_BOOL
XMS_OBJECT_TYPE_BYTE
XMS_OBJECT_TYPE_BYTEARRAY
XMS_OBJECT_TYPE_CHAR
XMS_OBJECT_TYPE_DOUBLE
XMS_OBJECT_TYPE_FLOAT
XMS_OBJECT_TYPE_INT
XMS_OBJECT_TYPE_LONG
XMS_OBJECT_TYPE_SHORT
XMS_OBJECT_TYPE_STRING
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetShort – Get Short Integer

Interface:
xmsRC xmsMapMsgGetShort(xmsHMsg message,
xmsCHAR *name,
xmsSHORT *value,
xmsHErrorBlock errorBlock);

Get the short integer identified by name from the body of the map message.
Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the short integer. The name is in the
format of a null terminated string.

Chapter 14. C classes 171

 value (output)
The short integer retrieved from the body of the map message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetString – Get String

Interface:
xmsRC xmsMapMsgGetString(xmsHMsg message,
xmsCHAR *name,
xmsCHAR *buffer,
xmsINT bufferLength,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);

Get the string identified by name from the body of the map message.

For more information about how to use this function, see “C functions that return
a string by value” on page 64.
Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the string. The name is in the format of a
null terminated string.
buffer (output)
The buffer to contain the string. If data conversion is required, this
is the string after conversion.
bufferLength (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the string is not returned, but its length is returned in the
actualLength parameter.
actualLength (output)
The length of the string in bytes. If data conversion is required,
this is the length of the string after conversion. If you specify a
null pointer on input, the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMapMsgGetStringByRef – Get String by Reference

Interface:

172 Message Service Client for C/C++

 xmsRC xmsMapMsgGetStringByRef(xmsHMsg message,
xmsCHAR *name,
xmsCHAR **string,
xmsINT *length,
xmsHErrorBlock errorBlock);

Get a pointer to the string identified by name and get the length of the string.

For more information about how to use this function, see “C functions that return
a string or byte array by reference” on page 66.
Parameters:
message (input)
The handle for the message.
name (input)
The name that identifies the string. The name is in the format of a
null terminated string.
string (output)
A pointer to the string. If data conversion is required, this is the
string after conversion.
length (output)
The length of the string in bytes. If data conversion is required,
this is the length after conversion.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMapMsgItemExists – Check Name-Value Pair Exists

Interface:
xmsRC xmsMapMsgItemExists(xmsHMsg message,
xmsCHAR *name,
xmsBOOL *pairExists,
xmsHErrorBlock errorBlock);

Check whether the body of the map message contains a name-value pair with the
specified name.
Parameters:
message (input)
The handle for the message.
name (input)
The name of the name-value pair in the format of a null
terminated string.
pairExists (output)
The value is xmsTRUE if the body of the map message contains a
name-value pair with the specified name. The value is xmsFALSE if
the body of the map message does not contain a name-value pair
with the specified name.
errorBlock (input)
The handle for an error block or a null handle.
Chapter 14. C classes 173
 Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMapMsgSetBoolean – Set Boolean Value

Interface:
xmsRC xmsMapMsgSetBoolean(xmsHMsg message,
xmsCHAR *name,
xmsBOOL value,
xmsHErrorBlock errorBlock);

Set a boolean value in the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name to identify the boolean value in the body of the map
message. The name is in the format of a null terminated string.
value (input)
The boolean value to be set.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMapMsgSetByte – Set Byte

Interface:
xmsRC xmsMapMsgSetByte(xmsHMsg message,
xmsCHAR *name,
xmsSBYTE value,
xmsHErrorBlock errorBlock);

Set a byte in the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name to identify the byte in the body of the map message. The
name is in the format of a null terminated string.
value (input)
The byte to be set.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

174 Message Service Client for C/C++

xmsMapMsgSetBytes – Set Bytes
Interface:
xmsRC xmsMapMsgSetBytes(xmsHMsg message,
xmsCHAR *name,
xmsSBYTE *value,
xmsINT length,
xmsHErrorBlock errorBlock);

Set an array of bytes in the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name to identify the array of bytes in the body of the map
message. The name is in the format of a null terminated string.
value (input)
The array of bytes to be set.
length (input)
The number of bytes in the array.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMapMsgSetChar – Set Character

Interface:
xmsRC xmsMapMsgSetChar(xmsHMsg message,
xmsCHAR *name,
xmsCHAR16 value,
xmsHErrorBlock errorBlock);

Set a 2-byte character in the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name to identify the character in the body of the map
message. The name is in the format of a null terminated string.
value (input)
The character to be set.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Chapter 14. C classes 175

 xmsMapMsgSetDouble – Set Double Precision Floating Point
Number
Interface:
xmsRC xmsMapMsgSetDouble(xmsHMsg message,
xmsCHAR *name,
xmsDOUBLE value,
xmsHErrorBlock errorBlock);

Set a double precision floating point number in the body of the map message.
Parameters:
message (input)
The handle for the message.
name (input)
The name to identify the double precision floating point number in
the body of the map message. The name is in the format of a null
terminated string.
value (input)
The double precision floating point number to be set.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMapMsgSetFloat – Set Floating Point Number

Interface:
xmsRC xmsMapMsgSetFloat(xmsHMsg message,
xmsCHAR *name,
xmsFLOAT value,
xmsHErrorBlock errorBlock);

Set a floating point number in the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name to identify the floating point number in the body of the
map message. The name is in the format of a null terminated
string.
value (input)
The floating point number to be set.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

176 Message Service Client for C/C++

xmsMapMsgSetInt – Set Integer
Interface:
xmsRC xmsMapMsgSetInt(xmsHMsg message,
xmsCHAR *name,
xmsINT value,
xmsHErrorBlock errorBlock);

Set an integer in the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name to identify the integer in the body of the map message.
The name is in the format of a null terminated string.
value (input)
The integer to be set.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMapMsgSetLong – Set Long Integer

Interface:
xmsRC xmsMapMsgSetLong(xmsHMsg message,
xmsCHAR *name,
xmsLONG value,
xmsHErrorBlock errorBlock);

Set a long integer in the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name to identify the long integer in the body of the map
message. The name is in the format of a null terminated string.
value (input)
The long integer to be set.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMapMsgSetObject – Set Object

Interface:

Chapter 14. C classes 177

 xmsRC xmsMapMsgSetObject(xmsHMsg message,
xmsCHAR *name,
xmsSBYTE *value,
xmsINT length,
xmsOBJECT_TYPE objectType,
xmsHErrorBlock errorBlock);

Set a value, with a specified data type, in the body of the map message.
Parameters:
message (input)
The handle for the message.
name (input)
The name to identify the value in the body of the map message.
The name is in the format of a null terminated string.
value (input)
An array of bytes containing the value to be set.
length (input)
The number of bytes in the array.
objectType (input)
The data type of the value, which must be one of the following
object types:
XMS_OBJECT_TYPE_BOOL
XMS_OBJECT_TYPE_BYTE
XMS_OBJECT_TYPE_BYTEARRAY
XMS_OBJECT_TYPE_CHAR
XMS_OBJECT_TYPE_DOUBLE
XMS_OBJECT_TYPE_FLOAT
XMS_OBJECT_TYPE_INT
XMS_OBJECT_TYPE_LONG
XMS_OBJECT_TYPE_SHORT
XMS_OBJECT_TYPE_STRING
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMapMsgSetShort – Set Short Integer

Interface:
xmsRC xmsMapMsgSetShort(xmsHMsg message,
xmsCHAR *name,
xmsSHORT value,
xmsHErrorBlock errorBlock);

Set a short integer in the body of the map message.

Parameters:
message (input)
The handle for the message.

178 Message Service Client for C/C++

 name (input)
The name to identify the short integer in the body of the map
message. The name is in the format of a null terminated string.
value (input)
The short integer to be set.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMapMsgSetString – Set String

Interface:
xmsRC xmsMapMsgSetString(xmsHMsg message,
xmsCHAR *name,
xmsCHAR *value,
xmsINT length,
xmsHErrorBlock errorBlock);

Set a string in the body of the map message.

Parameters:
message (input)
The handle for the message.
name (input)
The name to identify the string in the body of the map message.
The name is in the format of a null terminated string.
value (input)
A character array containing the string to be set.
length (input)
The length of the string in bytes. If the string is null terminated
with no embedded null characters, you can specify
XMSC_CALCULATE_STRING_SIZE instead and allow XMS to calculate
its length.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Message
A Message object represents a message that an application sends or receives.

For a list of the JMS message header fields in a Message object, see “Header fields
in an XMS message” on page 97. For a list of the JMS defined properties of a
Message object, see “JMS-defined properties of a message” on page 99. For a list of
the IBM defined properties of a Message object, see “IBM-defined properties of a
message” on page 100.

Chapter 14. C classes 179

 Functions
xmsMsgAcknowledge – Acknowledge
Interface:
xmsRC xmsMsgAcknowledge(xmsHMsg message,
xmsHErrorBlock errorBlock);

Acknowledge this message and all previously unacknowledged messages received

by the session.

An application can call this function if the acknowledgement mode of the session
is XMSC_CLIENT_ACKNOWLEDGE. Calls to the function are ignored if the
session has any other acknowledgement mode or is transacted.

Messages that have been received but not acknowledged might be re-delivered.

For more information about acknowledging messages, see “Message

acknowledgement” on page 39.
Parameters:
message (input)
The handle for the message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_ILLEGAL_STATE_EXCEPTION

xmsMsgClearBody – Clear Body

Interface:
xmsRC xmsMsgClearBody(xmsHMsg message,
xmsHErrorBlock errorBlock);

Clear the body of the message. The header fields and message properties are not
cleared.

If an application clears a message body, the body is left in the same state as an
empty body in a newly created message. The state of an empty body in a newly
created message depends on the type of message body. For more information, see
“The body of an XMS message” on page 101.

An application can clear a message body at any time, no matter what state the
body is in. If a message body is read-only, the only way that an application can
write to the body is for the application to clear the body first.
Parameters:
message (input)
The handle for the message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:

180 Message Service Client for C/C++

 v XMS_X_GENERAL_EXCEPTION

xmsMsgClearProperties – Clear Properties

Interface:
xmsRC xmsMsgClearProperties(xmsHMsg message,
xmsHErrorBlock errorBlock);

Clear the properties of the message. The header fields and the message body are
not cleared.

If an application clears the properties of a message, the properties become readable

and writable.

An application can clear the properties of a message at any time, no matter what
state the properties are in. If the properties of a message are read-only, the only
way that the properties can become writable is for the application to clear the
properties first.
Parameters:
message (input)
The handle for the message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgDispose – Delete Message

Interface:
xmsRC xmsMsgDispose(xmsHMsg *message,
xmsHErrorBlock errorBlock);

Delete the message.

If an application tries to delete a message that is already deleted, the call is

ignored.
Parameters:
message (input)
On input, the handle for the message. On output, the function
returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgGetJMSCorrelationID – Get JMSCorrelationID

Interface:

Chapter 14. C classes 181

 xmsRC xmsMsgGetJMSCorrelationID(xmsHMsg message,
xmsCHAR *correlID,
xmsINT length,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);

Get the correlation identifier of the message.

For more information about how to use this function, see “C functions that return
a string by value” on page 64.
Parameters:
message (input)
The handle for the message.
correlID (output)
The buffer to contain the correlation identifier.
length (input)
The length of the buffer in bytes. If you specify a length of 0, the
correlation identifier is not returned, but its length is returned in
the actualLength parameter.
actualLength (output)
The length of the correlation identifier in bytes. If you specify a
null pointer on input, the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgGetJMSDeliveryMode – Get JMSDeliveryMode

Interface:
xmsRC xmsMsgGetJMSDeliveryMode(xmsHMsg message,
xmsINT *deliveryMode,
xmsHErrorBlock errorBlock);

Get the delivery mode of the message. The delivery mode is set by the
xmsMsgProducerSend() call when the message is sent.
Parameters:
message (input)
The handle for the message.
deliveryMode (output)
The delivery mode of the message, which is one of the following
values:
XMSC_DELIVERY_PERSISTENT
XMSC_DELIVERY_NOT_PERSISTENT
For a newly created message that has not been sent, the delivery
mode is XMSC_DELIVERY_PERSISTENT, except for a real-time
connection to a broker for which the delivery mode is
XMSC_DELIVERY_NOT_PERSISTENT. For a message that has been
received, the function returns the delivery mode that was set by

182 Message Service Client for C/C++

 the xmsMsgProducerSend() call when the message was sent unless
the receiving application changes the delivery mode by calling
xmsMsgSetJMSDeliveryMode().
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgGetJMSDestination – Get JMSDestination

Interface:
xmsRC xmsMsgGetJMSDestination(xmsHMsg message,
xmsHDest *destination,
xmsHErrorBlock errorBlock);

Get the destination of the message. The destination is set by the

xmsMsgProducerSend() call when the message is sent.
Parameters:
message (input)
The handle for the message.
destination (output)
The handle for the destination of the message.
For a newly created message that has not been sent, the function
returns a null handle and an error unless the sending application
sets a destination by calling xmsMsgSetJMSDestination(). For a
message that has been received, the function returns a handle for
the destination that was set by the xmsMsgProducerSend() call
when the message was sent unless the receiving application
changes the destination by calling xmsMsgSetJMSDestination().
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgGetJMSExpiration – Get JMSExpiration

Interface:
xmsRC xmsMsgGetJMSExpiration(xmsHMsg message,
xmsLONG *expiration,
xmsHErrorBlock errorBlock);

Get the expiration time of the message.

The expiration time is set by the xmsMsgProducerSend() call when the message is
sent. Its value is calculated by adding the time to live, as specified by the sending
application, to the time when the message is sent. The expiration time is expressed
in milliseconds since 00:00:00 GMT on the 1 January 1970.

Chapter 14. C classes 183

 If the time to live is 0, the xmsMsgProducerSend() call sets the expiration time to 0
to indicate that the message does not expire.

XMS discards expired messages and does not deliver them to applications.
Parameters:
message (input)
The handle for the message.
expiration (output)
The expiration time of the message.
For a newly created message that has not been sent, the expiration
time is 0 unless the sending application sets a different expiration
time by calling xmsMsgSetJMSExpiration(). For a message that has
been received, the function returns the expiration time that was set
by the xmsMsgProducerSend() call when the message was sent
unless the receiving application changes the expiration time by
calling xmsMsgSetJMSExpiration().
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgGetJMSMessageID – Get JMSMessageID

Interface:
xmsRC xmsMsgGetJMSMessageID(xmsHMsg message,
xmsCHAR *msgID,
xmsINT length,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);

Get the message identifier of the message. The message identifier is set by the
xmsMsgProducerSend() call when the message is sent.

For more information about how to use this function, see “C functions that return
a string by value” on page 64.
Parameters:
message (input)
The handle for the message.
msgID (output)
The buffer to contain the message identifier.
For a message that has been received, the function returns the
message identifier that was set by the xmsMsgProducerSend() call
when the message was sent unless the receiving application
changes the message identifier by calling
xmsMsgSetJMSMessageID().
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the message identifier is not returned, but its length is
returned in the actualLength parameter.

184 Message Service Client for C/C++

 actualLength (output)
The length of the message identifier in bytes. If you specify a null
pointer on input, the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
XMS_X_GENERAL_EXCEPTION

Notes:
1. If a message has no message identifier, the function leaves the contents
of the buffer unchanged, sets the actualLength parameter to 0, and
returns an error.

xmsMsgGetJMSPriority – Get JMSPriority

Interface:
xmsRC xmsMsgGetJMSPriority(xmsHMsg message,
xmsINT *priority,
xmsHErrorBlock errorBlock);

Get the priority of the message. The priority is set by the xmsMsgProducerSend()
call when the message is sent.
Parameters:
message (input)
The handle for the message.
priority (output)
The priority of the message. The value is an integer in the range 0,
the lowest priority, to 9, the highest priority.
For a newly created message that has not been sent, the priority is
4 unless the sending application sets a different priority by calling
xmsMsgSetJMSPriority(). For a message that has been received, the
function returns the priority that was set by the
xmsMsgProducerSend() call when the message was sent unless the
receiving application changes the priority by calling
xmsMsgSetJMSPriority().
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgGetJMSRedelivered – Get JMSRedelivered

Interface:
xmsRC xmsMsgGetJMSRedelivered(xmsHMsg message,
xmsBOOL *redelivered,
xmsHErrorBlock errorBlock);

Get an indication of whether the message is being re-delivered. The indication is

set by the xmsMsgConsumerReceive() call when the message is received.

Chapter 14. C classes 185

 Parameters:
message (input)
The handle for the message.
redelivered (output)
The value is xmsTRUE if the message is being re-delivered. The
value is xmsFALSE if the message is not being re-delivered.
For a real-time connection to a broker, the value is always
xmsFALSE.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgGetJMSReplyTo – Get JMSReplyTo

Interface:
xmsRC xmsMsgGetJMSReplyTo(xmsHMsg message,
xmsHDest *destination,
xmsHErrorBlock errorBlock);

Get the destination where a reply to the message is to be sent.

Parameters:
message (input)
The handle for the message.
destination (output)
The handle for the destination where a reply to the message is to
be sent. A null handle means that no reply is expected.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgGetJMSTimestamp – Get JMSTimestamp

Interface:
xmsRC xmsMsgGetJMSTimestamp(xmsHMsg message,
xmsLONG *timeStamp,
xmsHErrorBlock errorBlock);

Get the time when the message was sent. The time stamp is set by the
xmsMsgProducerSend() call when the message is sent and is expressed in
milliseconds since 00:00:00 GMT on the 1 January 1970.
Parameters:
message (input)
The handle for the message.
timeStamp (output)
The time when the message was sent.

186 Message Service Client for C/C++

 For a newly created message that has not been sent, the time
stamp is 0 unless the sending application sets a different time
stamp by calling xmsMsgSetJMSTimestamp(). For a message that
has been received, the function returns the time stamp that was set
by the xmsMsgProducerSend() call when the message was sent
unless the receiving application changes the time stamp by calling
xmsMsgSetJMSTimestamp().
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Note:
1. If the time stamp is undefined, the function sets the timeStamp
parameter to 0 but returns no error.

xmsMsgGetJMSType – Get JMSType

Interface:
xmsRC xmsMsgGetJMSType(xmsHMsg message,
xmsCHAR *type,
xmsINT length,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);

Get the type of the message.

For more information about how to use this function, see “C functions that return
a string by value” on page 64.
Parameters:
message (input)
The handle for the message.
type (output)
The buffer to contain the type of the message. If data conversion is
required, this is the type after conversion.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the type of the message is not returned, but its length is
returned in the actualLength parameter.
actualLength (output)
The length of the type of the message in bytes. If data conversion
is required, this is the length after conversion. If you specify a null
pointer on input, the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Chapter 14. C classes 187

 xmsMsgGetProperties – Get Properties
Interface:
xmsRC xmsMsgGetProperties(xmsHMsg message,
xmsHIterator *iterator,
xmsHErrorBlock errorBlock);

Get a list of the properties of the message.

The function returns an iterator that encapsulates a list of Property objects. The
application can then use the iterator to access each property in turn.

Note: The equivalent JMS method performs a slightly different function. The JMS
method returns an enumeration of only the names of the properties of the
message, not their values.
Parameters:
message (input)
The handle for the message.
iterator (output)
The handle for the iterator.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgGetTypeId – Get Type

Interface:
xmsRC xmsMsgGetTypeId(xmsHMsg message,
xmsMESSAGE_TYPE *type,
xmsHErrorBlock errorBlock);

Get the body type of the message.

For information about message body types, see “The body of an XMS message” on
page 101.
Parameters:
message (input)
The handle for the message.
type (output)
The body type of the message, which is one of the following
values:
XMS_MESSAGE_TYPE_BASE (the message has no body)
XMS_MESSAGE_TYPE_BYTES
XMS_MESSAGE_TYPE_MAP
XMS_MESSAGE_TYPE_OBJECT
XMS_MESSAGE_TYPE_STREAM
XMS_MESSAGE_TYPE_TEXT

188 Message Service Client for C/C++

 errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgPropertyExists – Check Property Exists

Interface:
xmsRC xmsMsgPropertyExists(xmsHMsg message,
xmsCHAR *propertyName,
xmsBOOL *propertyExists,
xmsHErrorBlock errorBlock);

Check whether the message has a property with the specified name.
Parameters:
message (input)
The handle for the message.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyExists (output)
The value is xmsTRUE if the message has a property with the
specified name. The value is xmsFALSE if the message does not have
a property with the specified name.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgSetJMSCorrelationID – Set JMSCorrelationID

Interface:
xmsRC xmsMsgSetJMSCorrelationID(xmsHMsg message,
xmsCHAR *correlID,
xmsINT length,
xmsHErrorBlock errorBlock);

Set the correlation identifier of the message.

Parameters:
message (input)
The handle for the message.
correlID (input)
The correlation identifier as a character array.
length (input)
The length of the correlation identifier in bytes. If the correlation
identifier is null terminated with no embedded null characters, you
can specify XMSC_CALCULATE_STRING_SIZE instead and allow XMS to
calculate its length.

Chapter 14. C classes 189

 errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgSetJMSDeliveryMode – Set JMSDeliveryMode

Interface:
xmsRC xmsMsgSetJMSDeliveryMode(xmsHMsg message,
xmsINT deliveryMode,
xmsHErrorBlock errorBlock);

Set the delivery mode of the message.

A delivery mode set by this function before the message is sent is ignored and
replaced by the xmsMsgProducerSend() call when the message is sent. However,
you can use this function to change the delivery mode of a message that has been
received.
Parameters:
message (input)
The handle for the message.
deliveryMode (input)
The delivery mode of the message, which must be one of the
following values:
XMSC_DELIVERY_PERSISTENT
XMSC_DELIVERY_NOT_PERSISTENT
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgSetJMSDestination – Set JMSDestination

Interface:
xmsRC xmsMsgSetJMSDestination(xmsHMsg message,
xmsHDest destination,
xmsHErrorBlock errorBlock);

Set the destination of the message.

A destination set by this function before the message is sent is ignored and
replaced by the xmsMsgProducerSend() call when the message is sent. However,
you can use this function to change the destination of a message that has been
received.
Parameters:
message (input)
The handle for the message.

190 Message Service Client for C/C++

 destination (input)
The handle for the destination of the message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgSetJMSExpiration – Set JMSExpiration

Interface:
xmsRC xmsMsgSetJMSExpiration(xmsHMsg message,
xmsLONG expiration,
xmsHErrorBlock errorBlock);

Set the expiration time of the message.

An expiration time set by this function before the message is sent is ignored and
replaced by the xmsMsgProducerSend() call when the message is sent. However,
you can use this function to change the expiration time of a message that has been
received.
Parameters:
message (input)
The handle for the message.
expiration (input)
The expiration time of the message expressed in milliseconds since
00:00:00 GMT on the 1 January 1970.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgSetJMSMessageID – Set JMSMessageID

Interface:
xmsRC xmsMsgSetJMSMessageID(xmsHMsg message,
xmsCHAR *msgID,
xmsINT length,
xmsHErrorBlock errorBlock);

Set the message identifier of the message.

A message identifier set by this function before the message is sent is ignored and
replaced by the xmsMsgProducerSend() call when the message is sent. However,
you can use this function to change the message identifier of a message that has
been received.
Parameters:
message (input)
The handle for the message.

Chapter 14. C classes 191

 msgID (input)
The message identifier as a character array.
length (input)
The length of the message identifier in bytes. If the message
identifier is null terminated with no embedded null characters, you
can specify XMSC_CALCULATE_STRING_SIZE instead and allow XMS to
calculate its length.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgSetJMSPriority – Set JMSPriority

Interface:
xmsRC xmsMsgSetJMSPriority(xmsHMsg message,
xmsINT priority,
xmsHErrorBlock errorBlock);

Set the priority of the message.

A priority set by this function before the message is sent is ignored and replaced
by the xmsMsgProducerSend() call when the message is sent. However, you can
use this function to change the priority of a message that has been received.
Parameters:
message (input)
The handle for the message.
priority (input)
The priority of the message. The value can be an integer in the
range 0, the lowest priority, to 9, the highest priority.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgSetJMSRedelivered – Set JMSRedelivered

Interface:
xmsRC xmsMsgSetJMSRedelivered(xmsHMsg message,
xmsBOOL redelivered,
xmsHErrorBlock errorBlock);

Indicate whether the message is being re-delivered.

An indication of re-delivery set by this function before the message is sent is

ignored by the xmsMsgProducerSend() call when the message is sent, and is
ignored and replaced by the xmsMsgConsumerReceive() call when the message is
received. However, you can use this function to change the indication for a
message that has been received.

192 Message Service Client for C/C++

Parameters:
message (input)
The handle for the message.
redelivered (input)
The value xmsTRUE means that the message is being re-delivered.
The value xmsFALSE means that the message is not being
re-delivered.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgSetJMSReplyTo – Set JMSReplyTo

Interface:
xmsRC xmsMsgSetJMSReplyTo(xmsHMsg message,
xmsHDest destination,
xmsHErrorBlock errorBlock);

Set the destination where a reply to the message is to be sent.

Parameters:
message (input)
The handle for the message.
destination (input)
The handle for the destination where a reply to the message is to
be sent. A null handle means that no reply is expected.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgSetJMSTimestamp – Set JMSTimestamp

Interface:
xmsRC xmsMsgSetJMSTimestamp(xmsHMsg message,
xmsLONG timeStamp,
xmsHErrorBlock errorBlock);

Set the time when the message is sent.

A time stamp set by this function before the message is sent is ignored and
replaced by the xmsMsgProducerSend() call when the message is sent. However,
you can use this function to change the time stamp of a message that has been
received.
Parameters:
message (input)
The handle for the message.

Chapter 14. C classes 193

 timeStamp (input)
The time when the message is sent expressed in milliseconds since
00:00:00 GMT on the 1 January 1970.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgSetJMSType – Set JMSType

Interface:
xmsRC xmsMsgSetJMSType(xmsHMsg message,
xmsCHAR *type,
xmsINT length,
xmsHErrorBlock errorBlock);

Set the type of the message.

Parameters:
message (input)
The handle for the message.
type (input)
The type of the message as a character array.
length (input)
The length of the type of the message in bytes. If the type of the
message is null terminated with no embedded null characters, you
can specify XMSC_CALCULATE_STRING_SIZE instead and allow XMS to
calculate its length.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

MessageConsumer
An application uses a message consumer to receive messages sent to a destination.

For a list of the XMS defined properties of a MessageConsumer object, see

“Properties of MessageConsumer” on page 415.

Functions
xmsMsgConsumerClose – Close Message Consumer
Interface:
xmsRC xmsMsgConsumerClose(xmsHMsgConsumer *consumer,
xmsHErrorBlock errorBlock);

Close the message consumer.

If an application tries to close a message consumer that is already closed, the call is
ignored.

194 Message Service Client for C/C++

Parameters:
consumer (input/output)
On input, the handle for the message consumer. On output, the
function returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgConsumerGetMessageListener – Get Message Listener

Interface:
xmsRC xmsMsgConsumerGetMessageListener(xmsHMsgConsumer consumer,
fpXMS_MESSAGE_CALLBACK *lsr,
xmsCONTEXT *context,
xmsHErrorBlock errorBlock);

Get pointers to the message listener function and context data that are registered
with the message consumer.

For more information about using message listener functions, see “Message listener
functions in C” on page 68.
Parameters:
consumer (input)
The handle for the message consumer.
lsr (output)
A pointer to the message listener function. If no message listener
function is registered with the message consumer, the call returns a
null pointer.
context (output)
A pointer to the context data. If no message listener function is
registered with the connection, the call returns a null pointer.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgConsumerGetMessageSelector – Get Message Selector

Interface:
xmsRC xmsMsgConsumerGetMessageSelector(xmsHMsgConsumer consumer,
xmsCHAR *messageSelector,
xmsINT length,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);

Get the message selector for the message consumer.

Chapter 14. C classes 195

 For more information about how to use this function, see “C functions that return
a string by value” on page 64.
Parameters:
consumer (input)
The handle for the message consumer.
messageSelector (output)
The buffer to contain the message selector expression. If data
conversion is required, this is the message selector expression after
conversion.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the message selector expression is not returned, but its
length is returned in the actualLength parameter.
actualLength (output)
The length of the message selector expression in bytes. If data
conversion is required, this is the length of the message selector
expression after conversion. If you specify a null pointer on input,
the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgConsumerReceive – Receive
Interface:
xmsRC xmsMsgConsumerReceive(xmsHMsgConsumer consumer,
xmsHMsg *message,
xmsHErrorBlock errorBlock);

Receive the next message for the message consumer. The call waits indefinitely for
a message, or until the message consumer is closed.
Parameters:
consumer (input)
The handle for the message consumer.
message (output)
The handle for the message. If the message consumer is closed
while the call is waiting for a message, the function returns a null
handle.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgConsumerReceiveNoWait – Receive with No Wait

Interface:

196 Message Service Client for C/C++

 xmsRC xmsMsgConsumerReceiveNoWait(xmsHMsgConsumer consumer,
xmsHMsg *message,
xmsHErrorBlock errorBlock);

Receive the next message for the message consumer if one is available
immediately.
Parameters:
consumer (input)
The handle for the message consumer.
message (output)
The handle for the message. If no message is available
immediately, the function returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgConsumerReceiveWithWait – Receive (with a wait

interval)
Interface:
xmsRC xmsMsgConsumerReceiveWithWait(xmsHMsgConsumer consumer,
xmsLONG waitInterval,
xmsHMsg *message,
xmsHErrorBlock errorBlock);

Receive the next message for the message consumer. The call waits only a specified
period of time for a message, or until the message consumer is closed.
Parameters:
consumer (input)
The handle for the message consumer.
waitInterval (input)
The time, in milliseconds, that the call waits for a message. If you
specify a wait interval of 0, the call waits indefinitely for a
message.
message (output)
The handle for the message. If no message arrives during the wait
interval, or if the message consumer is closed while the call is
waiting for a message, the function returns a null handle but no
error.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgConsumerSetMessageListener – Set Message Listener

Interface:

Chapter 14. C classes 197

 xmsRC xmsMsgConsumerSetMessageListener(xmsHMsgConsumer consumer,
fpXMS_MESSAGE_CALLBACK lsr,
xmsCONTEXT context,
xmsHErrorBlock errorBlock);

Register a message listener function and context data with the message consumer.

For more information about using message listener functions, see “Message listener
functions in C” on page 68.
Parameters:
consumer (input)
The handle for the message consumer.
lsr (input)
A pointer to the message listener function. If a message listener
function is already registered with the message consumer, you can
cancel the registration by specifying a null pointer instead.
context (input)
A pointer to the context data.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

MessageListener
An application uses a message listener to receive messages asynchronously.

Functions
onMessage – On Message
Interface:
xmsVOID onMessage(xmsCONTEXT context,
xmsHMsg message);

Deliver a message asynchronously to the message consumer.

onMessage() is the message listener function that is registered with the message
consumer. The name of the function does not have to be onMessage.

For more information about using message listener functions, see “Message listener
functions in C” on page 68.
Parameters:
context (input)
A pointer to the context data that is registered with the message
consumer.
message (input)
The handle for the message.

MessageProducer
An application uses a message producer to send messages to a destination.

198 Message Service Client for C/C++

 For a list of the XMS defined properties of a MessageProducer object, see
“Properties of MessageProducer” on page 416.

Functions
xmsMsgProducerClose – Close Message Producer
Interface:
xmsRC xmsMsgProducerClose(xmsHMsgProducer *producer,
xmsHErrorBlock errorBlock);

Close the message producer.

If an application tries to close a message producer that is already closed, the call is
ignored.
Parameters:
producer (input/output)
On input, the handle for the message producer. On output, the
function returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgProducerGetDeliveryMode – Get Default Delivery Mode

Interface:
xmsRC xmsMsgProducerGetDeliveryMode(xmsHMsgProducer producer,
xmsINT *deliveryMode,
xmsHErrorBlock errorBlock);

Get the default delivery mode for messages sent by the message producer.
Parameters:
producer (input)
The handle for the message producer.
deliveryMode (output)
The default delivery mode, which is one of the following values:
XMSC_DELIVERY_PERSISTENT
XMSC_DELIVERY_NOT_PERSISTENT
For a real-time connection to a broker, the value is always
XMSC_DELIVERY_NOT_PERSISTENT.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Chapter 14. C classes 199

 xmsMsgProducerGetDestination – Get Destination
Interface:
xmsRC xmsMsgProducerGetDestination(xmsHMsgProducer producer,
xmsHDest *destination,
xmsHErrorBlock errorBlock);

Get the destination for the message producer.

Parameters:
producer (input)
The handle for the message producer.
destination (output)
The handle for the destination. If the message producer does not
have a destination, the function returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgProducerGetDisableMsgID – Get Disable Message ID

Flag
Interface:
xmsRC xmsMsgProducerGetDisableMsgID(xmsHMsgProducer producer,
xmsBOOL *msgIDDisabled,
xmsHErrorBlock errorBlock);

Get an indication of whether a receiving application requires message identifiers to

be included in messages sent by the message producer.
Parameters:
producer (input)
The handle for the message producer.
msgIDDisabled (output)
The value is xmsTRUE if a receiving application does not require
message identifiers to be included in messages sent by the message
producer. The value is xmsFALSE if a receiving application does
require message identifiers.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgProducerGetDisableMsgTS – Get Disable Time Stamp

Flag
Interface:
xmsRC xmsMsgProducerGetDisableMsgTS(xmsHMsgProducer producer,
xmsBOOL *timeStampDisabled,
xmsHErrorBlock errorBlock);

200 Message Service Client for C/C++

Get an indication of whether a receiving application requires time stamps to be
included in messages sent by the message producer.
Parameters:
producer (input)
The handle for the message producer.
timeStampDisabled (output)
The value is xmsTRUE if a receiving application does not require
time stamps to be included in messages sent by the message
producer. The value is xmsFALSE if a receiving application does
require time stamps.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgProducerGetPriority – Get Default Priority

Interface:
xmsRC xmsMsgProducerGetPriority(xmsHMsgProducer producer,
xmsINT *priority,
xmsHErrorBlock errorBlock);

Get the default priority for messages sent by the message producer.
Parameters:
producer (input)
The handle for the message producer.
priority (output)
The default message priority. The value is an integer in the range
0, the lowest priority, to 9, the highest priority.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgProducerGetTimeToLive – Get Default Time to Live

Interface:
xmsRC xmsMsgProducerGetTimeToLive(xmsHMsgProducer producer,
xmsLONG *timeToLive,
xmsHErrorBlock errorBlock);

Get the default length of time that a message exists before it expires. The time is
measured from when the message producer sends the message.
Parameters:
producer (input)
The handle for the message producer.

Chapter 14. C classes 201

 timeToLive (output)
The default time to live in milliseconds. A value of 0 means that a
message never expires. For a real-time connection to a broker, the
value is always 0.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgProducerSend – Send
Interface:
xmsRC xmsMsgProducerSend(xmsHMsgProducer producer,
xmsHMsg message,
xmsHErrorBlock errorBlock);

Send a message to the destination that was specified when the message producer
was created. Send the message using the message producer’s default delivery
mode, priority, and time to live.
Parameters:
producer (input)
The handle for the message producer.
message (input)
The handle for the message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_FORMAT_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION

xmsMsgProducerSendDest – Send (to a specified destination)

Interface:
xmsRC xmsMsgProducerSendDest(xmsHMsgProducer producer,
xmsHDest destination,
xmsHMsg message,
xmsHErrorBlock errorBlock);

Send a message to a specified destination if you are using a message producer for
which no destination was specified when the message producer was created. Send
the message using the message producer’s default delivery mode, priority, and
time to live.

Typically, you specify a destination when you create a message producer but, if
you do not, you must specify a destination every time you send a message.
Parameters:

202 Message Service Client for C/C++

 producer (input)
The handle for the message producer.
destination (input)
The handle for the destination.
message (input)
The handle for the message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_FORMAT_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION

xmsMsgProducerSendDestWithAttr – Send (to a specified

destination, specifying a delivery mode, priority, and time to live)
Interface:
xmsRC xmsMsgProducerSendDestWithAttr(xmsHMsgProducer producer,
xmsHDest destination,
xmsHMsg message,
xmsINT deliveryMode,
xmsINT priority,
xmsLONG timeToLive,
xmsHErrorBlock errorBlock);

Send a message to a specified destination if you are using a message producer for
which no destination was specified when the message producer was created. Send
the message using the specified delivery mode, priority, and time to live.

Typically, you specify a destination when you create a message producer but, if
you do not, you must specify a destination every time you send a message.
Parameters:
producer (input)
The handle for the message producer.
destination (input)
The handle for the destination.
message (input)
The handle for the message.
deliveryMode (input)
The delivery mode for the message, which must be one of the
following values:
XMSC_DELIVERY_PERSISTENT
XMSC_DELIVERY_NOT_PERSISTENT
For a real-time connection to a broker, the value must be
XMSC_DELIVERY_NOT_PERSISTENT.
priority (input)
The priority of the message. The value can be an integer in the
range 0, for the lowest priority, to 9, for the highest priority. On a
real-time connection to a broker, the value is ignored.

Chapter 14. C classes 203

 timeToLive (input)
The time to live for the message in milliseconds. A value of 0
means that the message never expires. For a real-time connection
to a broker, the value must be 0.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_FORMAT_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION
v XMS_X_ILLEGAL_STATE_EXCEPTION

xmsMsgProducerSendWithAttr – Send (specifying a delivery

mode, priority, and time to live)
Interface:
xmsRC xmsMsgProducerSendWithAttr(xmsHMsgProducer producer,
xmsHMsg message,
xmsINT deliveryMode,
xmsINT priority,
xmsLONG timeToLive,
xmsHErrorBlock errorBlock);

Send a message to the destination that was specified when the message producer
was created. Send the message using the specified delivery mode, priority, and
time to live.
Parameters:
producer (input)
The handle for the message producer.
message (input)
The handle for the message.
deliveryMode (input)
The delivery mode for the message, which must be one of the
following values:
XMSC_DELIVERY_PERSISTENT
XMSC_DELIVERY_NOT_PERSISTENT
For a real-time connection to a broker, the value must be
XMSC_DELIVERY_NOT_PERSISTENT.
priority (input)
The priority of the message. The value can be an integer in the
range 0, for the lowest priority, to 9, for the highest priority. On a
real-time connection to a broker, the value is ignored.
timeToLive (input)
The time to live for the message in milliseconds. A value of 0
means that the message never expires. For a real-time connection
to a broker, the value must be 0.
errorBlock (input)
The handle for an error block or a null handle.

204 Message Service Client for C/C++

Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_FORMAT_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION
v XMS_X_ILLEGAL_STATE_EXCEPTION

xmsMsgProducerSetDeliveryMode – Set Default Delivery Mode

Interface:
xmsRC xmsMsgProducerSetDeliveryMode(xmsHMsgProducer producer,
xmsINT deliveryMode,
xmsHErrorBlock errorBlock);

Set the default delivery mode for messages sent by the message producer.
Parameters:
producer (input)
The handle for the message producer.
deliveryMode (input)
The default delivery mode, which must be one of the following
values:
XMSC_DELIVERY_PERSISTENT
XMSC_DELIVERY_NOT_PERSISTENT
For a real-time connection to a broker, the value must be
XMSC_DELIVERY_NOT_PERSISTENT.
The default value is XMSC_DELIVERY_PERSISTENT, except for a
real-time connection to a broker for which the default value is
XMSC_DELIVERY_NOT_PERSISTENT.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgProducerSetDisableMsgID – Set Disable Message ID Flag

Interface:
xmsRC xmsMsgProducerSetDisableMsgID(xmsHMsgProducer producer,
xmsBOOL msgIDDisabled,
xmsHErrorBlock errorBlock);

Indicate whether a receiving application requires message identifiers to be included

in messages sent by the message producer.

On a connection to a queue manager, or on a real-time connection to a broker, this

flag is ignored. On a connection to a service integration bus, the flag is honoured.
Parameters:
producer (input)
The handle for the message producer.

Chapter 14. C classes 205

 msgIDDisabled (input)
The value xmsTRUE means that a receiving application does not
require message identifiers to be included in messages sent by the
message producer. The value xmsFALSE means that a receiving
application does require message identifiers. The default value is
xmsFALSE.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgProducerSetDisableMsgTS – Set Disable Time Stamp

Flag
Interface:
xmsRC xmsMsgProducerSetDisableMsgTS(xmsHMsgProducer producer,
xmsBOOL timeStampDisabled,
xmsHErrorBlock errorBlock);

Indicate whether a receiving application requires time stamps to be included in

messages sent by the message producer.

On a real-time connection to a broker, this flag is ignored. On a connection to a

queue manager, or on a connection to a service integration bus, the flag is
honoured.
Parameters:
producer (input)
The handle for the message producer.
timeStampDisabled (input)
The value xmsTRUE means that a receiving application does not
require time stamps to be included in messages sent by the
message producer. The value xmsFALSE means that a receiving
application does require time stamps. The default value is
xmsFALSE.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgProducerSetPriority – Set Default Priority

Interface:
xmsRC xmsMsgProducerSetPriority(xmsHMsgProducer producer,
xmsINT priority,
xmsHErrorBlock errorBlock);

Set the default priority for messages sent by the message producer.

On a real-time connection to a broker, the priority of a message is ignored.

206 Message Service Client for C/C++

 Parameters:
producer (input)
The handle for the message producer.
priority (input)
The default message priority. The value can be an integer in the
range 0, for the lowest priority, to 9, for the highest priority. The
default value is 4.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsMsgProducerSetTimeToLive – Set Default Time to Live

Interface:
xmsRC xmsMsgProducerSetTimeToLive(xmsHMsgProducer producer,
xmsLONG timeToLive,
xmsHErrorBlock errorBlock);

Set the default length of time that a message exists before it expires. The time is
measured from when the message producer sends the message.
Parameters:
producer (input)
The handle for the message producer.
timeToLive (input)
The default time to live in milliseconds. The default value is 0,
which means that a message never expires. For a real-time
connection to a broker, the value must be 0.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

ObjectMessage
An object message is a message whose body comprises a serialized Java or .NET
object.

Functions
xmsObjectMsgGetObjectAsBytes – Get Object as Bytes
Interface:
xmsRC xmsObjectMsgGetObjectAsBytes(xmsHMsg message,
xmsSBYTE *buffer,
xmsINT bufferLength,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);

Get the object that forms the body of the object message.

Chapter 14. C classes 207

 For more information about how to use this function, see “C functions that return
a byte array by value” on page 65.
Parameters:
message (input)
The handle for the message.
buffer (output)
The buffer to contain the object, which is returned as an array of
bytes.
bufferLength (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the object is not returned, but its length is returned in the
actualLength parameter.
actualLength (output)
The length of the object in bytes. If you specify a null pointer on
input, the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

Notes:
1. If the buffer is not large enough to store the whole object, XMS returns
the object truncated to the length of the buffer, sets the actualLength
parameter to the actual length of the object, and returns an error.
2. If any other error occurs while attempting to get the object, XMS reports
the error but does not set the actualLength parameter.

xmsObjectMsgSetObjectAsBytes – Set Object as Bytes

Interface:
xmsRC xmsObjectMsgSetObjectAsBytes(xmsHMsg message,
xmsSBYTE *value,
xmsINT length,
xmsHErrorBlock errorBlock);

Set the object that forms the body of the object message.
Parameters:
message (input)
The handle for the message.
value (input)
An array of bytes representing the object to be set.
length (input)
The number of bytes in the array.
errorBlock (input)
The handle for an error block or a null handle.

208 Message Service Client for C/C++

 Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

Property
A Property object represents a property of an object.

A Property object has three attributes:

Property name
The name of the property
Property value
The value of the property
Property type
The data type of the value of the property

If an application sets the property value attribute of a Property object, the property
value replaces any previous value the attribute had.

This class is a helper class.

Functions
xmsPropertyCreate – Create Property (with no property value or
property type)
Interface:
xmsRC xmsPropertyCreate(xmsCHAR *propertyName,
xmsHProperty *property,
xmsHErrorBlock errorBlock);

Create a Property object with no property value or property type.

Parameters:
propertyName (input)
The property name in the format of a null terminated string.
property (output)
The handle for the Property object.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertyDispose – Delete Property

Interface:
xmsRC xmsPropertyDispose(xmsHProperty *property,
xmsHErrorBlock errorBlock);

Chapter 14. C classes 209

 Delete the Property object.

If an application tries to delete a Property object that is already deleted, the call is
ignored.
Parameters:
property (input/output)
On input, the handle for the Property object. On output the
function returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertyDuplicate – Copy Property

Interface:
xmsRC xmsPropertyDuplicate(xmsHProperty property,
xmsHProperty *copiedProperty,
xmsHErrorBlock errorBlock);

Copy the Property object.

Parameters:
property (input)
The handle for the Property object.
copiedProperty (output)
The handle for the copy of the Property object.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertyGetBoolean – Get Boolean Property Value

Interface:
xmsRC xmsPropertyGetBoolean(xmsHProperty property,
xmsBOOL *propertyValue,
xmsHErrorBlock errorBlock);

Get the boolean property value from the Property object.

Parameters:
property (input)
The handle for the Property object.

210 Message Service Client for C/C++

 propertyValue (output)
The boolean property value.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertyGetByte – Get Byte Property Value

Interface:
xmsRC xmsPropertyGetByte(xmsHProperty property,
xmsSBYTE *propertyValue,
xmsHErrorBlock errorBlock);

Get the byte property value from the Property object.

Parameters:
property (input)
The handle for the Property object.
propertyValue (output)
The byte property value.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertyGetByteArray – Get Byte Array Property Value

Interface:
xmsRC xmsPropertyGetByteArray(xmsHProperty property,
xmsSBYTE *propertyValue,
xmsINT length,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);

Get the byte array property value from the Property object.

For more information about how to use this function, see “C functions that return
a byte array by value” on page 65.
Parameters:
property (input)
The handle for the Property object.
propertyValue (output)
The buffer to contain the property value, which is an array of
bytes.

Chapter 14. C classes 211

 length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the property value is not returned, but its length is
returned in the actualLength parameter.
actualLength (output)
The length of the property value in bytes. If you specify a null
pointer on input, the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertyGetByteArrayByRef – Get Byte Array Property Value

by Reference
Interface:
xmsRC xmsPropertyGetByteArrayByRef(xmsHProperty property,
xmsSBYTE **propertyValue,
xmsINT *length,
xmsHErrorBlock errorBlock);

Get a pointer to the byte array property value in the Property object.

For more information about how to use this function, see “C functions that return
a string or byte array by reference” on page 66.
Parameters:
property (input)
The handle for the Property object.
propertyValue (output)
A pointer to the property value, which is an array of bytes.
length (output)
The length of the property value in bytes.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertyGetChar – Get Character Property Value

Interface:
xmsRC xmsPropertyGetChar(xmsHProperty property,
xmsCHAR16 *propertyValue,
xmsHErrorBlock errorBlock);

212 Message Service Client for C/C++

Get the 2-byte character property value from the Property object.
Parameters:
property (input)
The handle for the Property object.
propertyValue (output)
The 2-byte character property value.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertyGetDouble – Get Double Precision Floating Point

Property Value
Interface:
xmsRC xmsPropertyGetDouble(xmsHProperty property,
xmsDOUBLE *propertyValue,
xmsHErrorBlock errorBlock);

Get the double precision floating point property value from the Property object.
Parameters:
property (input)
The handle for the Property object.
propertyValue (output)
The double precision floating point property value.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertyGetFloat – Get Floating Point Property Value

Interface:
xmsRC xmsPropertyGetFloat(xmsHProperty property,
xmsFLOAT *propertyValue,
xmsHErrorBlock errorBlock);

Get the floating point property value from the Property object.
Parameters:
property (input)
The handle for the Property object.

Chapter 14. C classes 213

 propertyValue (output)
The floating point property value.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertyGetInt – Get Integer Property Value

Interface:
xmsRC xmsPropertyGetInt(xmsHProperty property,
xmsINT *propertyValue,
xmsHErrorBlock errorBlock);

Get the integer property value from the Property object.

Parameters:
property (input)
The handle for the Property object.
propertyValue (output)
The integer property value.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertyGetLong – Get Long Integer Property Value

Interface:
xmsRC xmsPropertyGetLong(xmsHProperty property,
xmsLONG *propertyValue,
xmsHErrorBlock errorBlock);

Get the long integer property value from the Property object.
Parameters:
property (input)
The handle for the Property object.
propertyValue (output)
The long integer property value.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any

214 Message Service Client for C/C++

Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertyGetName – Get Property Name

Interface:
xmsRC xmsPropertyGetName(xmsHProperty property,
xmsCHAR *propertyName,
xmsINT length,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);

Get the property name from the Property object.

For more information about how to use this function, see “C functions that return
a string by value” on page 64.
Parameters:
property (input)
The handle for the Property object.
propertyName (output)
The buffer to contain the property name.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the property name is not returned, but its length is
returned in the actualLength parameter.
actualLength (output)
The length of the property name in bytes. If you specify a null
pointer on input, the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertyGetShort – Get Short Integer Property Value

Interface:
xmsRC xmsPropertyGetShort(xmsHProperty property,
xmsSHORT *propertyValue,
xmsHErrorBlock errorBlock);

Get the short integer property value from the Property object.
Parameters:
property (input)
The handle for the Property object.
propertyValue (output)
The short integer property value.

Chapter 14. C classes 215

 errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertyGetString – Get String Property Value

Interface:
xmsRC xmsPropertyGetString(xmsHProperty property,
xmsCHAR *propertyValue,
xmsINT length,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);

Get the string property value from the Property object.

For more information about how to use this function, see “C functions that return
a string by value” on page 64.
Parameters:
property (input)
The handle for the Property object.
propertyValue (output)
The buffer to contain the string property value. If data conversion
is required, this is the value after conversion.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the property value is not returned, but its length is
returned in the actualLength parameter.
actualLength (output)
The length of the property value in bytes. If data conversion is
required, this is the length after conversion. If you specify a null
pointer on input, the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertyGetStringByRef – Get String Property Value by

Reference
Interface:
xmsRC xmsPropertyGetStringByRef(xmsHProperty property,
xmsCHAR **propertyValue,
xmsINT *length,
xmsHErrorBlock errorBlock);

216 Message Service Client for C/C++

Get a pointer to the string property value in the Property object.

For more information about how to use this function, see “C functions that return
a string or byte array by reference” on page 66.
Parameters:
property (input)
The handle for the Property object.
propertyValue (output)
A pointer to the string property value. If data conversion is
required, this is the value after conversion.
Note that the property value must be a string. The function makes
no attempt to convert a property value with another data type into
a string. If an application calls this function to get a pointer to a
property value that is not a string, XMS returns an error.
length (output)
The length of the property value in bytes. If data conversion is
required, this is the length after conversion.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertyGetTypeId – Get Property Type

Interface:
xmsRC xmsPropertyGetTypeId(xmsHProperty property,
xmsPROPERTY_TYPE *propertyType,
xmsHErrorBlock errorBlock);

Get the property type from the Property object.

Parameters:
property (input)
The handle for the Property object.
propertyType (output)
The property type, which is one of the following values:
XMS_PROPERTY_TYPE_UNKNOWN
XMS_PROPERTY_TYPE_BOOL
XMS_PROPERTY_TYPE_BYTE
XMS_PROPERTY_TYPE_BYTEARRAY
XMS_PROPERTY_TYPE_CHAR
XMS_PROPERTY_TYPE_STRING
XMS_PROPERTY_TYPE_SHORT
XMS_PROPERTY_TYPE_INT
XMS_PROPERTY_TYPE_LONG
XMS_PROPERTY_TYPE_FLOAT

Chapter 14. C classes 217

 XMS_PROPERTY_TYPE_DOUBLE
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertyIsTypeId – Check Property Type

Interface:
xmsRC xmsPropertyIsTypeId(xmsHProperty property,
xmsPROPERTY_TYPE propertyType,
xmsBOOL *isType,
xmsHErrorBlock errorBlock);

Check whether the Property object has the specified property type.
Parameters:
property (input)
The handle for the Property object.
propertyType (input)
The property type, which must be one of the following values:
XMS_PROPERTY_TYPE_UNKNOWN
XMS_PROPERTY_TYPE_BOOL
XMS_PROPERTY_TYPE_BYTE
XMS_PROPERTY_TYPE_BYTEARRAY
XMS_PROPERTY_TYPE_CHAR
XMS_PROPERTY_TYPE_STRING
XMS_PROPERTY_TYPE_SHORT
XMS_PROPERTY_TYPE_INT
XMS_PROPERTY_TYPE_LONG
XMS_PROPERTY_TYPE_FLOAT
XMS_PROPERTY_TYPE_DOUBLE
isType (output)
The value is xmsTRUE if the Property object has the specified
property type. The value is xmsFALSE if the Property object does not
have the specified property type.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

218 Message Service Client for C/C++

xmsPropertySetBoolean – Set Boolean Property Value
Interface:
xmsRC xmsPropertySetBoolean(xmsHProperty property,
xmsBOOL propertyValue,
xmsHErrorBlock errorBlock);

Set a boolean property value in the Property object and set the property type.
Parameters:
property (input)
The handle for the Property object.
propertyValue (input)
The boolean property value.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertySetByte – Set Byte Property Value

Interface:
xmsRC xmsPropertySetByte(xmsHProperty property,
xmsSBYTE propertyValue,
xmsHErrorBlock errorBlock);

Set a byte property value in the Property object and set the property type.
Parameters:
property (input)
The handle for the Property object.
propertyValue (input)
The byte property value.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertySetByteArray – Set Byte Array Property Value

Interface:
xmsRC xmsPropertySetByteArray(xmsHProperty property,
xmsSBYTE *propertyValue,
xmsINT length,
xmsHErrorBlock errorBlock);

Chapter 14. C classes 219

 Set a byte array property value in the Property object and set the property type.
Parameters:
property (input)
The handle for the Property object.
propertyValue (input)
The property value, which is an array of bytes.
length (input)
The length of the property value in bytes.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertySetChar – Set Character Property Value

Interface:
xmsRC xmsPropertySetChar(xmsHProperty Property,
xmsCHAR16 propertyValue,
xmsHErrorBlock errorBlock);

Set a 2-byte character property value in the Property object and set the property
type.
Parameters:
property (input)
The handle for the Property object.
propertyValue (input)
The 2-byte character property value.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertySetDouble – Set Double Precision Floating Point

Property Value
Interface:
xmsRC xmsPropertySetDouble(xmsHProperty property,
xmsDOUBLE propertyValue,
xmsHErrorBlock errorBlock);

Set a double precision floating point property value in the Property object and set
the property type.

220 Message Service Client for C/C++

Parameters:
property (input)
The handle for the Property object.
propertyValue (input)
The double precision floating point property value.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertySetFloat – Set Floating Point Property Value

Interface:
xmsRC xmsPropertySetFloat(xmsHProperty property,
xmsFLOAT propertyValue,
xmsHErrorBlock errorBlock);

Set a floating point property value in the Property object and set the property type.
Parameters:
property (input)
The handle for the Property object.
propertyValue (input)
The floating point property value.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertySetInt – Set Integer Property Value

Interface:
xmsRC xmsPropertySetInt(xmsHProperty property,
xmsINT propertyValue,
xmsHErrorBlock errorBlock);

Set an integer property value in the Property object and set the property type.
Parameters:
property (input)
The handle for the Property object.
propertyValue (input)
The integer property value.

Chapter 14. C classes 221

 errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertySetLong – Set Long Integer Property Value

Interface:
xmsRC xmsPropertySetLong(xmsHProperty property,
xmsLONG propertyValue,
xmsHErrorBlock errorBlock);

Set a long integer property value in the Property object and set the property type.
Parameters:
property (input)
The handle for the Property object.
propertyValue (input)
The long integer property value.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsPropertySetShort – Set Short Integer Property Value

Interface:
xmsRC xmsPropertySetShort(xmsHProperty property,
xmsSHORT propertyValue,
xmsHErrorBlock errorBlock);

Set a short integer property value in the Property object and set the property type.
Parameters:
property (input)
The handle for the Property object.
propertyValue (input)
The short integer property value.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

222 Message Service Client for C/C++

 xmsPropertySetString – Set String Property Value
Interface:
xmsRC xmsPropertySetString(xmsHProperty property,
xmsCHAR *propertyValue,
xmsINT length,
xmsHErrorBlock errorBlock);

Set a string property value in the Property object and set the property type.
Parameters:
property (input)
The handle for the Property object.
propertyValue (input)
The string property value as a character array.
length (input)
The length of the property value in bytes. If the property value is
null terminated with no embedded null characters, you can specify
XMSC_CALCULATE_STRING_SIZE instead and allow XMS to calculate
its length.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

PropertyContext
The PropertyContext class contains functions that get and set properties. These
functions can operate on any object that can have properties.

All objects can have properties except ErrorBlock, Iterator, and Property objects.

Functions
xmsGetBooleanProperty – Get Boolean Property
Interface:
xmsRC xmsGetBooleanProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsBOOL *propertyValue,
xmsHErrorBlock errorBlock);

Get the value of the boolean property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.

Chapter 14. C classes 223

 propertyValue (output)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsGetByteArrayProperty – Get Byte Array Property

Interface:
xmsRC xmsGetByteArrayProperty(xmsHObj object
xmsCHAR *propertyName,
xmsSBYTE *propertyValue,
xmsINT length,
xmsINT *actualLength
xmsHErrorBlock errorBlock) const;

Get the value of the byte array property identified by name.

For more information about how to use this function, see “C functions that return
a byte array by value” on page 65.
Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
The buffer to contain the value of the property, which is an array
of bytes.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the array of bytes is not returned, but its length is returned
in the actualLength parameter.
actualLength (output)
The number of bytes in the array. If you specify a null pointer on
input, the length of the array is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION

224 Message Service Client for C/C++

xmsGetByteArrayPropertyByRef – Get Byte Array Property by
Reference
Interface:
xmsRC xmsGetByteArrayPropertyByRef(xmsHObj object
xmsCHAR *propertyName,
xmsSBYTE **propertyValue,
xmsINT *length,
xmsHErrorBlock errorBlock) const;

Get a pointer to the value of the byte array property identified by name.

For more information about how to use this function, see “C functions that return
a string or byte array by reference” on page 66.
Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
A pointer to the value of the property, which is an array of bytes.
length (output)
The number of bytes in the array.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsGetByteProperty – Get Byte Property

Interface:
xmsRC xmsGetByteProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsSBYTE *propertyValue,
xmsHErrorBlock errorBlock);

Get the value of the byte property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.

Chapter 14. C classes 225

 Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsGetCharProperty – Get Character Property

Interface:
xmsRC xmsGetCharProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsCHAR16 *propertyValue,
xmsHErrorBlock errorBlock);

Get the value of the 2-byte character property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsGetDoubleProperty – Get Double Precision Floating Point

Property
Interface:
xmsRC xmsGetDoubleProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsDOUBLE *propertyValue,
xmsHErrorBlock errorBlock);

Get the value of the double precision floating point property identified by name.
Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.

226 Message Service Client for C/C++

Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsGetFloatProperty – Get Floating Point Property

Interface:
xmsRC xmsGetFloatProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsFLOAT *propertyValue,
xmsHErrorBlock errorBlock);

Get the value of the floating point property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsGetHandleTypeId – Get Handle Type

Interface:
xmsRC xmsGetHandleTypeId(xmsHObj object,
xmsHANDLE_TYPE *handleType,
xmsHErrorBlock errorBlock);

Get the type of the handle for the object.

Parameters:
object (input)
The handle for the object.
handleType (output)
The type of the handle for the object, which is one of the following
values:
XMS_HANDLE_TYPE_CONN
XMS_HANDLE_TYPE_CONNFACT
XMS_HANDLE_TYPE_CONNMETADATA
XMS_HANDLE_TYPE_DEST
XMS_HANDLE_TYPE_ERRORBLOCK

Chapter 14. C classes 227

 XMS_HANDLE_TYPE_INITIALCONTEXT
XMS_HANDLE_TYPE_ITERATOR
XMS_HANDLE_TYPE_MSG
XMS_HANDLE_TYPE_MSGCONSUMER
XMS_HANDLE_TYPE_MSGPRODUCER
XMS_HANDLE_TYPE_QUEUEBROWSER
XMS_HANDLE_TYPE_PROPERTY
XMS_HANDLE_TYPE_REQUESTOR
XMS_HANDLE_TYPE_SESS
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsGetIntProperty – Get Integer Property

Interface:
xmsRC xmsGetIntProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsINT *propertyValue,
xmsHErrorBlock errorBlock);

Get the value of the integer property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsGetLongProperty – Get Long Integer Property

Interface:
xmsRC xmsGetLongProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsLONG *propertyValue,
xmsHErrorBlock errorBlock);

228 Message Service Client for C/C++

Get the value of the long integer property identified by name.
Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsGetObjectProperty – Get Object Property

Interface:
xmsRC xmsGetObjectProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsSBYTE *propertyValue,
xmsINT length,
xmsINT *actualLength,
xmsOBJECT_TYPE *objectType,
xmsHErrorBlock errorBlock);

Get the value and data type of the property identified by name.

For more information about how to use this function, see “C functions that return
a byte array by value” on page 65.
Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
The buffer to contain the value of the property, which is returned
as an array of bytes. If the value is a string and data conversion is
required, this is the value after conversion.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the value of the property is not returned, but its length is
returned in the actualLength parameter.
actualLength (output)
The length of the value of the property in bytes. If the value is a
string and data conversion is required, this is the length after
conversion. If you specify a null pointer on input, the length is not
returned.

Chapter 14. C classes 229

 objectType (output)
The data type of the value of the property, which is one of the
following object types:
XMS_OBJECT_TYPE_BOOL
XMS_OBJECT_TYPE_BYTE
XMS_OBJECT_TYPE_BYTEARRAY
XMS_OBJECT_TYPE_CHAR
XMS_OBJECT_TYPE_DOUBLE
XMS_OBJECT_TYPE_FLOAT
XMS_OBJECT_TYPE_INT
XMS_OBJECT_TYPE_LONG
XMS_OBJECT_TYPE_SHORT
XMS_OBJECT_TYPE_STRING
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsGetProperty – Get Property

Interface:
xmsRC xmsGetProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsHProperty *property,
xmsHErrorBlock errorBlock);

Get a Property object for the property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
property (output)
The handle for the Property object.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsGetShortProperty – Get Short Integer Property

Interface:

230 Message Service Client for C/C++

 xmsRC xmsGetShortProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsLONG *propertyValue,
xmsHErrorBlock errorBlock);

Get the value of the short integer property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsGetStringProperty – Get String Property

Interface:
xmsRC xmsGetStringProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsCHAR *propertyValue,
xmsINT length,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);

Get the value of the string property identified by name.

For more information about how to use this function, see “C functions that return
a string by value” on page 64.
Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
The buffer to contain the value of the property. If data conversion
is required, this is the value after conversion.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the value of the property is not returned, but its length is
returned in the actualLength parameter.
actualLength (output)
The length of the value of the property in bytes. If data conversion

Chapter 14. C classes 231

 is required, this is the length after conversion. If you specify a null
pointer on input, the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsGetStringPropertyByRef – Get String Property by Reference

Interface:
xmsRC xmsMsgGetStringPropertyByRef(xmsHObj object,
xmsCHAR *propertyName,
xmsCHAR **propertyValue,
xmsINT *length,
xmsHErrorBlock errorBlock);

Get a pointer to the value of the string property identified by name.

For more information about how to use this function, see “C functions that return
a string or byte array by reference” on page 66.
Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
A pointer to the value of the property. If data conversion is
required, this is the value after conversion.
Note that the value of the property must be a string. The function
makes no attempt to convert a value with another data type into a
string. If an application calls this function to get a pointer to a
value that is not a string, XMS returns an error.
length (output)
The length of the value of the property in bytes. If data conversion
is required, this is the length after conversion.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsSetBooleanProperty – Set Boolean Property

Interface:

232 Message Service Client for C/C++

 xmsRC xmsSetBooleanProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsBOOL propertyValue,
xmsHErrorBlock errorBlock);

Set the value of the boolean property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsSetByteProperty – Set Byte Property

Interface:
xmsRC xmsSetByteProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsSBYTE propertyValue,
xmsHErrorBlock errorBlock);

Set the value of the byte property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

Chapter 14. C classes 233

 xmsSetByteArrayProperty – Set Byte Array Property
Interface:
xmsRC xmsSetByteArrayProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsSBYTE *propertyValue,
xmsINT length
xmsHErrorBlock errorBlock);

Set the value of the byte array property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property, which is an array of bytes.
length (input)
The number of bytes in the array.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsSetCharProperty – Set Character Property

Interface:
xmsRC xmsSetCharProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsCHAR16 propertyValue,
xmsHErrorBlock errorBlock);

Set the value of the 2-byte character property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:

234 Message Service Client for C/C++

 v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsSetDoubleProperty – Set Double Precision Floating Point

Property
Interface:
xmsRC xmsSetDoubleProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsDOUBLE propertyValue,
xmsHErrorBlock errorBlock);

Set the value of the double precision floating point property identified by name.
Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsSetFloatProperty – Set Floating Point Property

Interface:
xmsRC xmsSetFloatProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsFLOAT propertyValue,
xmsHErrorBlock errorBlock);

Set the value of the floating point property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.

Chapter 14. C classes 235

 Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsSetIntProperty – Set Integer Property

Interface:
xmsRC xmsSetIntProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsINT propertyValue,
xmsHErrorBlock errorBlock);

Set the value of the integer property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsSetLongProperty – Set Long Integer Property

Interface:
xmsRC xmsSetLongProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsLONG propertyValue,
xmsHErrorBlock errorBlock);

Set the value of the long integer property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property.

236 Message Service Client for C/C++

 errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsSetObjectProperty – Set Object Property

Interface:
xmsRC xmsSetObjectProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsSBYTE *propertyValue,
xmsINT length,
xmsOBJECT_TYPE objectType,
xmsHErrorBlock errorBlock);

Set the value and data type of a property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property as an array of bytes.
length (input)
The number of bytes in the array.
objectType (input)
The data type of the value of the property, which must be one of
the following object types:
XMS_OBJECT_TYPE_BOOL
XMS_OBJECT_TYPE_BYTE
XMS_OBJECT_TYPE_BYTEARRAY
XMS_OBJECT_TYPE_CHAR
XMS_OBJECT_TYPE_DOUBLE
XMS_OBJECT_TYPE_FLOAT
XMS_OBJECT_TYPE_INT
XMS_OBJECT_TYPE_LONG
XMS_OBJECT_TYPE_SHORT
XMS_OBJECT_TYPE_STRING
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Chapter 14. C classes 237

 v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsSetProperty – Set Property

Interface:
xmsRC xmsSetProperty(xmsHObj object,
xmsHProperty property,
xmsHErrorBlock errorBlock);

Set the value of a property using a Property object.

Parameters:
object (input)
The handle for the object.
property (input)
The handle for the Property object.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsSetShortProperty – Set Short Integer Property

Interface:
xmsRC xmsSetShortProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsSHORT propertyValue,
xmsHErrorBlock errorBlock);

Set the value of the short integer property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

238 Message Service Client for C/C++

 xmsSetStringProperty – Set String Property
Interface:
xmsRC xmsSetStringProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsCHAR *propertyValue,
xmsINT length,
xmsHErrorBlock errorBlock);

Set the value of the string property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property as a character array.
length (input)
The length of the value of the property in bytes. If the value of the
property is null terminated with no embedded null characters, you
can specify XMSC_CALCULATE_STRING_SIZE instead and allow XMS to
calculate its length.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

QueueBrowser
An application uses a queue browser to browse messages on a queue without
removing them.

Functions
xmsQueueBrowserClose – Close Queue Browser
Interface:
xmsRC xmsQueueBrowserClose(xmsHQueueBrowser *browser,
xmsHErrorBlock errorBlock);

Close the queue browser.

If an application tries to close a queue browser that is already closed, the call is
ignored.
Parameters:

Chapter 14. C classes 239

 browser (input/output)
On input, the handle for the queue browser. On output, the
function returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsQueueBrowserGetEnumeration – Get Messages

Interface:
xmsRC xmsQueueBrowserGetEnumeration(xmsHQueueBrowser browser,
xmsHIterator *iterator,
xmsHErrorBlock errorBlock);

Get a list of the messages on the queue.

The function returns an iterator that encapsulates a list of Message objects. The
order of the Message objects in the list is the same as the order in which the
messages would be retrieved from the queue. The application can then use the
iterator to browse each message in turn.

The iterator is updated dynamically as messages are put on the queue and
removed from the queue. Each time the application calls xmsIteratorGetNext() to
browse the next message on the queue, the message returned reflects the current
contents of the queue.

If an application calls this function more than once for a given queue browser, each
call returns a new iterator. The application can therefore use more than one iterator
to browse the messages on a queue and maintain multiple positions within the
queue.
Parameters:
browser (input)
The handle for the queue browser.
iterator (output)
The handle for the iterator.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsQueueBrowserGetMessageSelector – Get Message Selector

Interface:
xmsRC xmsQueueBrowserGetMessageSelector(xmsHQueueBrowser browser,
xmsCHAR *messageSelector,
xmsINT length,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);

240 Message Service Client for C/C++

 Get the message selector for the queue browser.

For more information about how to use this function, see “C functions that return
a string by value” on page 64.
Parameters:
browser (input)
The handle for the queue browser.
messageSelector (output)
The buffer to contain the message selector expression. If data
conversion is required, this is the message selector expression after
conversion.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the message selector expression is not returned, but its
length is returned in the actualLength parameter.
actualLength (output)
The length of the message selector expression in bytes. If data
conversion is required, this is the length of the message selector
expression after conversion. If you specify a null pointer on input,
the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsQueueBrowserGetQueue – Get Queue

Interface:
xmsRC xmsQueueBrowserGetQueue(xmsHQueueBrowser browser,
xmsHDest *queue,
xmsHErrorBlock errorBlock);

Get the queue associated with the queue browser.

Parameters:
browser (input)
The handle for the queue browser.
queue (output)
The handle for a Destination object representing the queue.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Requestor
An application uses a requestor to send a request message and then wait for, and
receive, the reply.

Chapter 14. C classes 241

 Functions
xmsRequestorClose – Close Requestor
Interface:
xmsRC xmsRequestorClose(xmsHRequestor *requestor,
xmsHErrorBlock errorBlock);

Close the requestor.

If an application tries to close a requestor that is already closed, the call is ignored.

Note: When an application closes a requestor, the associated session does not close
as well. In this respect, XMS behaves differently compared to JMS.
Parameters:
requestor (input/output)
On input, the handle for the requestor. On output, the function
returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsRequestorCreate – Create Requestor

Interface:
xmsRC xmsRequestorCreate(xmsHSess session,
xmsHDest destination,
xmsHRequestor *requestor
xmsHErrorBlock errorBlock);

Create a requestor.
Parameters:
session (input)
The handle for a session. The session must not be transacted and
must have one of the following acknowledgement modes:
XMSC_AUTO_ACKNOWLEDGE
XMSC_DUPS_OK_ACKNOWLEDGE
destination (input)
The handle for the destination where the application can send
request messages.
requestor (output)
The handle for the requestor.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
The session associated with the requestor

242 Message Service Client for C/C++

 Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsRequestorRequest – Request
Interface:
xmsRC xmsRequestorRequest(xmsHRequestor requestor,
xmsHMsg requestMessage,
xmsHMsg *replyMessage,
xmsHErrorBlock errorBlock);

Send a request message and then wait for, and receive, a reply from the application
that receives the request message.

A call to this function blocks until a reply is received or until the session ends,
whichever is the sooner.
Parameters:
requestor (input)
The handle for the requestor.
requestMessage (input)
The handle for the request message.
replyMessage (output)
The handle for the reply message.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
The session associated with the requestor
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Session
A session is a single threaded context for sending and receiving messages.

For a list of the XMS defined properties of a Session, see “Properties of Session” on
page 416.

Functions
xmsSessClose – Close Session
Interface:
xmsRC xmsSessClose(xmsHSess *session,
xmsHErrorBlock errorBlock);

Close the session. If the session is transacted, any transaction in progress is rolled
back.

All objects dependent on the session are deleted. For information about which
objects are deleted, see “Object Deletion” on page 51.

Chapter 14. C classes 243

 If an application tries to close a session that is already closed, the call is ignored.
Parameters:
session (input/output)
On input, the handle for the session. On output, the function
returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsSessCommit – Commit
Interface:
xmsRC xmsSessCommit(xmsHSess session,
xmsHErrorBlock errorBlock);

Commit all messages processed in the current transaction.

Parameters:
session (input)
The handle for the session. The session must be a transacted
session.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_ILLEGAL_STATE_EXCEPTION
v XMS_X_TRANSACTION_ROLLED_BACK_EXCEPTION

xmsSessCreateBrowser – Create Queue Browser

Interface:
xmsRC xmsSessCreateBrowser(xmsHSess session,
xmsHDest queue,
xmsHQueueBrowser *browser
xmsHErrorBlock errorBlock);

Create a queue browser for the specified queue.

Parameters:
session (input)
The handle for the session.
queue (input)
The handle for a Destination object representing the queue.
browser (output)
The handle for the queue browser.

244 Message Service Client for C/C++

 errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION

xmsSessCreateBrowserSelector – Create Queue Browser (with

message selector)
Interface:
xmsRC xmsSessCreateBrowserSelector(xmsHSess session,
xmsHDest queue,
xmsCHAR *messageSelector,
xmsINT length,
xmsHQueueBrowser *browser
xmsHErrorBlock errorBlock);

Create a queue browser for the specified queue using a message selector.
Parameters:
session (input)
The handle for the session.
queue (input)
The handle for a Destination object representing the queue.
messageSelector (input)
A message selector expression as a character array. Only those
messages with properties that match the message selector
expression are delivered to the queue browser.
A value of null or an empty string means that there is no message
selector for the queue browser.
length (input)
The length of the message selector expression in bytes. If the
message selector expression is null terminated with no embedded
null characters, you can specify XMSC_CALCULATE_STRING_SIZE
instead and allow XMS to calculate its length.
browser (output)
The handle for the queue browser.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION
v XMS_X_INVALID_SELECTOR_EXCEPTION

xmsSessCreateBytesMessage – Create Bytes Message

Interface:

Chapter 14. C classes 245

 xmsRC xmsSessCreateBytesMessage(xmsHSess session,
xmsHMsg *message,
xmsHErrorBlock errorBlock);

Create a bytes message.

Parameters:
session (input)
The handle for the session.
message (output)
The handle for the bytes message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsSessCreateConsumer – Create Consumer

Interface:
xmsRC xmsSessCreateConsumer(xmsHSess session,
xmsHDest destination,
xmsHMsgConsumer *consumer,
xmsHErrorBlock errorBlock);

Create a message consumer for the specified destination.

Parameters:
session (input)
The handle for the session.
destination (input)
The handle for the destination.
consumer (output)
The handle for the message consumer.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION

xmsSessCreateConsumerSelector – Create Consumer (with

message selector)
Interface:
xmsRC xmsSessCreateConsumerSelector(xmsHSess session,
xmsHDest destination,
xmsCHAR *messageSelector,
xmsINT length,
xmsHMsgConsumer *consumer,
xmsHErrorBlock errorBlock);

Create a message consumer for the specified destination using a message selector.

246 Message Service Client for C/C++

Parameters:
session (input)
The handle for the session.
destination (input)
The handle for the destination.
messageSelector (input)
A message selector expression as a character array. Only those
messages with properties that match the message selector
expression are delivered to the message consumer.
A value of null or an empty string means that there is no message
selector for the message consumer.
length (input)
The length of the message selector expression in bytes. If the
message selector expression is null terminated with no embedded
null characters, you can specify XMSC_CALCULATE_STRING_SIZE
instead and allow XMS to calculate its length.
consumer (output)
The handle for the message consumer.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION
v XMS_X_INVALID_SELECTOR_EXCEPTION

xmsSessCreateConsumerSelectorLocal – Create Consumer (with

message selector and local message flag)
Interface:
xmsRC xmsSessCreateConsumerSelectorLocal(xmsHSess session,
xmsHDest destination,
xmsCHAR *messageSelector,
xmsINT length,
xmsBOOL noLocal,
xmsHMsgConsumer *consumer,
xmsHErrorBlock errorBlock);

Create a message consumer for the specified destination using a message selector
and, if the destination is a topic, specifying whether the message consumer
receives the messages published by its own connection.
Parameters:
session (input)
The handle for the session.
destination (input)
The handle for the destination.
messageSelector (input)
A message selector expression as a character array. Only those
messages with properties that match the message selector
expression are delivered to the message consumer.

Chapter 14. C classes 247

 A value of null or an empty string means that there is no message
selector for the message consumer.
length (input)
The length of the message selector expression in bytes. If the
message selector expression is null terminated with no embedded
null characters, you can specify XMSC_CALCULATE_STRING_SIZE
instead and allow XMS to calculate its length.
noLocal (input)
The value xmsTRUE means that the message consumer does not
receive the messages published by its own connection. The value
xmsFALSE means that the message consumer does receive the
messages published by its own connection. The default value is
xmsFALSE.
consumer (output)
The handle for the message consumer.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION
v XMS_X_INVALID_SELECTOR_EXCEPTION

xmsSessCreateDurableSubscriber – Create Durable Subscriber

Interface:
xmsRC xmsSessCreateDurableSubscriber(xmsHSess session,
xmsHDest topic,
xmsCHAR *subscriptionName
xmsHMsgConsumer *subscriber,
xmsHErrorBlock errorBlock);

Create a durable subscriber for the specified topic.

This function is not valid for a real-time connection to a broker.

For more information about durable subscribers, see “Durable subscribers” on page
46.
Parameters:
session (input)
The handle for the session.
topic (input)
The handle for a Destination object representing the topic. The
topic must not be a temporary topic.
subscriptionName (input)
A name that identifies the durable subscription. The name must be
unique within the client identifier for the connection, and is in the
format of a null terminated string.

248 Message Service Client for C/C++

 subscriber (output)
The handle for the MessageConsumer object representing the
durable subscriber.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION

xmsSessCreateDurableSubscriberSelector – Create Durable

Subscriber (with message selector and local message flag)
Interface:
xmsRC xmsSessCreateDurableSubscriberSelector(xmsHSess session,
xmsHDest topic,
xmsCHAR *subscriptionName
xmsCHAR *messageSelector,
xmsINT length,
xmsBOOL noLocal,
xmsHMsgConsumer *subscriber,
xmsHErrorBlock errorBlock);

Create a durable subscriber for the specified topic using a message selector and
specifying whether the durable subscriber receives the messages published by its
own connection.

This function is not valid for a real-time connection to a broker.

For more information about durable subscribers, see “Durable subscribers” on page
46.
Parameters:
session (input)
The handle for the session.
topic (input)
The handle for a Destination object representing the topic. The
topic must not be a temporary topic.
subscriptionName (input)
A name that identifies the durable subscription. The name must be
unique within the client identifier for the connection, and is in the
format of a null terminated string.
messageSelector (input)
A message selector expression as a character array. Only those
messages with properties that match the message selector
expression are delivered to the durable subscriber.
A value of null or an empty string means that there is no message
selector for the durable subscriber.
length (input)
The length of the message selector expression in bytes. If the
message selector expression is null terminated with no embedded
null characters, you can specify XMSC_CALCULATE_STRING_SIZE
instead and allow XMS to calculate its length.

Chapter 14. C classes 249

 noLocal (input)
The value xmsTRUE means that the durable subscriber does not
receive the messages published by its own connection. The value
xmsFALSE means that the durable subscriber does receive the
messages published by its own connection. The default value is
xmsFALSE.
subscriber (output)
The handle for the MessageConsumer object representing the
durable subscriber.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION
v XMS_X_INVALID_SELECTOR_EXCEPTION

xmsSessCreateMapMessage – Create Map Message

Interface:
xmsRC xmsSessCreateMapMessage(xmsHSess session,
xmsHMsg *message,
xmsHErrorBlock errorBlock);

Create a map message.

Parameters:
session (input)
The handle for the session.
message (output)
The handle for the map message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsSessCreateMessage – Create Message

Interface:
xmsRC xmsSessCreateMessage(xmsHSess session,
xmsHMsg *message,
xmsHErrorBlock errorBlock);

Create a message that has no body.

Parameters:
session (input)
The handle for the session.
message (output)
The handle for the message.

250 Message Service Client for C/C++

 errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsSessCreateObjectMessage – Create Object Message

Interface:
xmsRC xmsSessCreateObjectMessage(xmsHSess session,
xmsHMsg *message,
xmsHErrorBlock errorBlock);

Create an object message.

Parameters:
session (input)
The handle for the session.
message (output)
The handle for the object message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsSessCreateProducer – Create Producer

Interface:
xmsRC xmsSessCreateProducer(xmsHSess session,
xmsHDest destination,
xmsHMsgProducer *producer,
xmsHErrorBlock errorBlock);

Create a message producer to send messages to the specified destination.

Parameters:
session (input)
The handle for the session.
destination (input)
The handle for the destination.
If you specify a null handle, the message producer is created
without a destination. In this case, the application must specify a
destination every time it uses the message producer to send a
message.
producer (output)
The handle for the message producer.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Chapter 14. C classes 251

 v XMS_X_INVALID_DESTINATION_EXCEPTION

xmsSessCreateStreamMessage – Create Stream Message

Interface:
xmsRC xmsSessCreateStreamMessage(xmsHSess session,
xmsHMsg *message,
xmsHErrorBlock errorBlock);

Create a stream message.

Parameters:
session (input)
The handle for the session.
message (output)
The handle for the stream message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsSessCreateTextMessage – Create Text Message

Interface:
xmsRC xmsSessCreateTextMessage(xmsHSess session,
xmsHMsg *message,
xmsHErrorBlock errorBlock);

Create a text message with an empty body.

Parameters:
session (input)
The handle for the session.
message (output)
The handle for the text message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsSessCreateTextMessageInit – Create Text Message

(initialized)
Interface:
xmsRC xmsSessCreateTextMessageInit(xmsHSess session,
xmsCHAR *text
xmsINT length
xmsHMsg *message,
xmsHErrorBlock errorBlock);

252 Message Service Client for C/C++

Create a text message whose body is initialized with the specified text.
Parameters:
session (input)
The handle for the session.
text (input)
A character array containing the text to initialize the body of the
text message.
length (input)
The length of the text in bytes. If the text is null terminated with
no embedded null characters, you can specify
XMSC_CALCULATE_STRING_SIZE instead and allow XMS to calculate
its length.
message (output)
The handle for the text message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsSessGetAcknowledgeMode – Get Acknowledgement Mode

Interface:
xmsRC xmsSessGetAcknowledgeMode(xmsHSess session,
xmsINT *acknowledgeMode,
xmsHErrorBlock errorBlock);

Get the acknowledgement mode for the session. The acknowledgement mode is
specified when the session is created.

A session that is transacted has no acknowledgement mode.

For more information about acknowledgement modes, see “Message

acknowledgement” on page 39.
Parameters:
session (input)
The handle for the session.
acknowledgeMode (output)
The acknowledgement mode. Provided the session is not
transacted, the acknowledgement mode is one of the following
values:
XMSC_AUTO_ACKNOWLEDGE
XMSC_CLIENT_ACKNOWLEDGE
XMSC_DUPS_OK_ACKNOWLEDGE
If the session is transacted, the function returns
XMSC_SESSION_TRANSACTED instead.
errorBlock (input)
The handle for an error block or a null handle.

Chapter 14. C classes 253

 Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsSessGetTransacted – Determine Whether Transacted

Interface:
xmsRC xmsSessGetTransacted(xmsHSess session,
xmsBOOL *transacted,
xmsHErrorBlock errorBlock);

Determine whether the session is transacted.

Parameters:
session (input)
The handle for the session.
transacted (output)
The value is xmsTRUE if the session is transacted. The value is
xmsFALSE if the session is not transacted.
For a real-time connection to a broker, the value is always
xmsFALSE.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsSessRecover – Recover
Interface:
xmsRC xmsSessRecover(xmsHSess session,
xmsHErrorBlock errorBlock);

Recover the session. Message delivery is stopped and then restarted with the
oldest unacknowledged message.

The session must not be a transacted session.

For more information about recovering a session, see “Message acknowledgement”

on page 39.
Parameters:
session (input)
The handle for the session.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_ILLEGAL_STATE_EXCEPTION

254 Message Service Client for C/C++

xmsSessRollback – Rollback
Interface:
xmsRC xmsSessRollback(xmsHSess session,
xmsHErrorBlock errorBlock);

Rollback all messages processed in the current transaction.

Parameters:
session (input)
The handle for the session. The session must be a transacted
session.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_ILLEGAL_STATE_EXCEPTION

xmsSessUnsubscribe – Unsubscribe
Interface:
xmsRC xmsSessUnsubscribe(xmsHSess session,
xmsCHAR *subscriptionName,
xmsHErrorBlock errorBlock);

Delete a durable subscription. The messaging server deletes the record of the
durable subscription that it is maintaining and does not send any more messages
to the durable subscriber.

An application cannot delete a durable subscription in any of the following

circumstances:
v While there is an active message consumer for the durable subscription
v While a consumed message is part of a pending transaction
v While a consumed message has not been acknowledged

This function is not valid for a real-time connection to a broker.

Parameters:
session (input)
The handle for the session.
subscriptionName (input)
The name that identifies the durable subscription. The name is in
the format of a null terminated string.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION
v XMS_X_ILLEGAL_STATE_EXCEPTION

Chapter 14. C classes 255

StreamMessage
A stream message is a message whose body comprises a stream of values, where
each value has an associated data type.

The contents of the body are written to and read sequentially.

When an application reads a value from the message stream, the value can be
converted by XMS into another data type. For more information about this form of
implicit conversion, see “Stream messages” on page 105.

Functions
xmsStreamMsgReadBoolean – Read Boolean Value
Interface:
xmsRC xmsStreamMsgReadBoolean(xmsHMsg message,
xmsBOOL *value,
xmsHErrorBlock errorBlock);

Read a boolean value from the message stream.

Parameters:
message (input)
The handle for the message.
value (output)
The boolean value that is read. If you specify a null pointer on
input, the call skips over the boolean value without reading it.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgReadByte – Read Byte

Interface:
xmsRC xmsStreamMsgReadByte(xmsHMsg message,
xmsSBYTE *value,
xmsHErrorBlock errorBlock);

Read a signed 8-bit integer from the message stream.

Parameters:
message (input)
The handle for the message.
value (output)
The byte that is read. If you specify a null pointer on input, the call
skips over the byte without reading it.
errorBlock (input)
The handle for an error block or a null handle.

256 Message Service Client for C/C++

Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgReadBytes – Read Bytes

Interface:
xmsRC xmsStreamMsgReadBytes(xmsHMsg message,
xmsSBYTE *buffer,
xmsINT bufferLength,
xmsINT *returnedLength,
xmsHErrorBlock errorBlock);

Read an array of bytes from the message stream.

Parameters:
message (input)
The handle for the message.
buffer (output)
The buffer to contain the array of bytes that is read.
If the number of bytes in the array is less than or equal to the
length of the buffer, the whole array is read into the buffer. If the
number of bytes in the array is greater than the length of the
buffer, the buffer is filled with part of the array, and an internal
cursor marks the position of the next byte to be read. A subsequent
call to xmsStreamMsgReadBytes() reads bytes from the array
starting from the current position of the cursor.
If you specify a null pointer on input, the call skips over the array
of bytes without reading it.
bufferLength (input)
The length of the buffer in bytes.
returnedLength (output)
The number of bytes that are read into the buffer. If the buffer is
partially filled, the value is less than the length of the buffer,
indicating that there are no more bytes in the array remaining to be
read. If there are no bytes remaining to be read from the array
before the call, the value is XMSC_END_OF_BYTEARRAY.
If you specify a null pointer on input, the function returns no
value.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

Chapter 14. C classes 257

 xmsStreamMsgReadBytesByRef – Read Bytes by Reference
Interface:
xmsRC xmsStreamMsgReadBytesByRef(xmsHMsg message,
xmsSBYTE **array,
xmsINT *length,
xmsHErrorBlock errorBlock);

Get a pointer to an array of bytes in the message stream, and get the length of the
array.

For more information about how to use this function, see “C functions that return
a string or byte array by reference” on page 66.
Parameters:
message (input)
The handle for the message.
array (output)
A pointer to the array of bytes.
length (output)
The number of bytes in the array.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgReadChar – Read Character

Interface:
xmsRC xmsStreamMsgReadChar(xmsHMsg message,
xmsCHAR16 *value,
xmsHErrorBlock errorBlock);

Read a 2-byte character from the message stream.

Parameters:
message (input)
The handle for the message.
value (output)
The character that is read. If you specify a null pointer on input,
the call skips over the bytes without reading them.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

258 Message Service Client for C/C++

xmsStreamMsgReadDouble – Read Double Precision Floating
Point Number
Interface:
xmsRC xmsStreamMsgReadDouble(xmsHMsg message,
xmsDOUBLE *value,
xmsHErrorBlock errorBlock);

Read an 8-byte double precision floating point number from the message stream.
Parameters:
message (input)
The handle for the message.
value (output)
The double precision floating point number that is read. If you
specify a null pointer on input, the call skips over the bytes
without reading them.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgReadFloat – Read Floating Point Number

Interface:
xmsRC xmsStreamMsgReadFloat(xmsHMsg message,
xmsFLOAT *value,
xmsHErrorBlock errorBlock);

Read a 4-byte floating point number from the message stream.

Parameters:
message (input)
The handle for the message.
value (output)
The floating point number that is read. If you specify a null pointer
on input, the call skips over the bytes without reading them.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgReadInt – Read Integer

Interface:

Chapter 14. C classes 259

 xmsRC xmsStreamMsgReadInt(xmsHMsg message,
xmsINT *value,
xmsHErrorBlock errorBlock);

Read a signed 32-bit integer from the message stream.

Parameters:
message (input)
The handle for the message.
value (output)
The integer that is read. If you specify a null pointer on input, the
call skips over the bytes without reading them.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgReadLong – Read Long Integer

Interface:
xmsRC xmsStreamMsgReadLong(xmsHMsg message,
xmsLONG *value,
xmsHErrorBlock errorBlock);

Read a signed 64-bit integer from the message stream.

Parameters:
message (input)
The handle for the message.
value (output)
The long integer that is read. If you specify a null pointer on input,
the call skips over the bytes without reading them.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgReadObject – Read Object

Interface:
xmsRC xmsstreamMsgReadObject(xmsHMsg message,
xmsSBYTE *buffer,
xmsINT bufferLength,
xmsINT *actualLength,
xmsOBJECT_TYPE *objectType,
xmsHErrorBlock errorBlock);

260 Message Service Client for C/C++

Read a value from the message stream, and return its data type.

For more information about how to use this function, see “C functions that return
a byte array by value” on page 65.
Parameters:
message (input)
The handle for the message.
buffer (output)
The buffer to contain the value, which is returned as an array of
bytes. If the value is a string and data conversion is required, this
is the value after conversion.
If you specify a null pointer on input, the call skips over the value
without reading it.
bufferLength (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the value is not returned, but its length is returned in the
actualLength parameter.
actualLength (output)
The length of the value in bytes. If the value is a string and data
conversion is required, this is the length after conversion. If you
specify a null pointer on input, the length is not returned.
objectType (output)
The data type of the value, which is one of the following object
types:
XMS_OBJECT_TYPE_BOOL
XMS_OBJECT_TYPE_BYTE
XMS_OBJECT_TYPE_BYTEARRAY
XMS_OBJECT_TYPE_CHAR
XMS_OBJECT_TYPE_DOUBLE
XMS_OBJECT_TYPE_FLOAT
XMS_OBJECT_TYPE_INT
XMS_OBJECT_TYPE_LONG
XMS_OBJECT_TYPE_SHORT
XMS_OBJECT_TYPE_STRING
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsStreamMsgReadShort – Read Short Integer

Interface:
xmsRC xmsStreamMsgReadShort(xmsHMsg message,
xmsSHORT *value,
xmsHErrorBlock errorBlock);

Read a signed 16-bit integer from the message stream.

Chapter 14. C classes 261

 Parameters:
message (input)
The handle for the message.
value (output)
The short integer that is read. If you specify a null pointer on
input, the call skips over the bytes without reading them.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgReadString – Read String

Interface:
xmsRC xmsStreamMsgReadString(xmsHMsg message,
xmsCHAR *buffer,
xmsINT bufferLength,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);

Read a string from the message stream. If required, XMS converts the characters in
the string into the local code page.

For more information about how to use this function, see “C functions that return
a string by value” on page 64.
Parameters:
message (input)
The handle for the message.
buffer (output)
The buffer to contain the string that is read. If data conversion is
required, this is the string after conversion.
bufferLength (input)
The length of the buffer in bytes.
If you specify XMSC_QUERY_SIZE, the string is not returned, but its
length is returned in the actualLength parameter, and the cursor is
not advanced.
If you specify XMSC_SKIP, the function skips over the string without
reading it.
actualLength (output)
The length of the string in bytes. If data conversion is required,
this is the length of the string after conversion. If you specify a
null pointer on input, the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

262 Message Service Client for C/C++

 v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

Notes:
1. If the buffer is not large enough to store the whole string, XMS returns
the string truncated to the length of the buffer, sets the actualLength
parameter to the actual length of the string, and returns an error. XMS
does not advance the internal cursor.
2. If any other error occurs while attempting to read the string, XMS
reports the error but does not set the actualLength parameter or
advance the internal cursor.

xmsStreamMsgReset – Reset
Interface:
xmsRC xmsStreamMsgReset(xmsHMsg message,
xmsHErrorBlock errorBlock);

Put the body of the message into read-only mode and reposition the cursor at the
beginning of the message stream.
Parameters:
message (input)
The handle for the message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

xmsStreamMsgWriteBoolean – Write Boolean Value

Interface:
xmsRC xmsStreamMsgWriteBoolean(xmsHMsg message,
xmsBOOL value,
xmsHErrorBlock errorBlock);

Write a boolean value to the message stream.

Parameters:
message (input)
The handle for the message.
value (input)
The boolean value to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Chapter 14. C classes 263

 v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsStreamMsgWriteByte – Write Byte

Interface:
xmsRC xmsStreamMsgWriteByte(xmsHMsg message,
xmsSBYTE value,
xmsHErrorBlock errorBlock);

Write a byte to the message stream.

Parameters:
message (input)
The handle for the message.
value (input)
The byte to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsStreamMsgWriteBytes – Write Bytes

Interface:
xmsRC xmsStreamMsgWriteBytes(xmsHMsg message,
xmsSBYTE *value,
xmsINT length,
xmsHErrorBlock errorBlock);

Write an array of bytes to the message stream.

Parameters:
message (input)
The handle for the message.
value (input)
The array of bytes to be written.
length (input)
The number of bytes in the array.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsStreamMsgWriteChar – Write Character

Interface:

264 Message Service Client for C/C++

 xmsRC xmsStreamMsgWriteChar(xmsHMsg message,
xmsCHAR16 value,
xmsHErrorBlock errorBlock);

Write a character to the message stream as 2 bytes, high order byte first.
Parameters:
message (input)
The handle for the message.
value (input)
The character to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsStreamMsgWriteDouble – Write Double Precision Floating

Point Number
Interface:
xmsRC xmsStreamMsgWriteDouble(xmsHMsg message,
xmsDOUBLE value,
xmsHErrorBlock errorBlock);

Convert a double precision floating point number to a long integer and write the
long integer to the message stream as 8 bytes, high order byte first.
Parameters:
message (input)
The handle for the message.
value (input)
The double precision floating point number to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsStreamMsgWriteFloat – Write Floating Point Number

Interface:
xmsRC xmsStreamMsgWriteFloat(xmsHMsg message,
xmsFLOAT value,
xmsHErrorBlock errorBlock);

Convert a floating point number to an integer and write the integer to the message
stream as 4 bytes, high order byte first.
Parameters:

Chapter 14. C classes 265

 message (input)
The handle for the message.
value (input)
The floating point number to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsStreamMsgWriteInt – Write Integer

Interface:
xmsRC xmsStreamMsgWriteInt(xmsHMsg message,
xmsINT value,
xmsHErrorBlock errorBlock);

Write an integer to the message stream as 4 bytes, high order byte first.
Parameters:
message (input)
The handle for the message.
value (input)
The integer to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsStreamMsgWriteLong – Write Long Integer

Interface:
xmsRC xmsStreamMsgWriteLong(xmsHMsg message,
xmsLONG value,
xmsHErrorBlock errorBlock);

Write a long integer to the message stream as 8 bytes, high order byte first.
Parameters:
message (input)
The handle for the message.
value (input)
The long integer to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

266 Message Service Client for C/C++

 v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsStreamMsgWriteObject – Write Object

Interface:
xmsRC xmsStreamMsgWriteObject(xmsHMsg message,
xmsSBYTE *value,
xmsINT length,
xmsOBJECT_TYPE objectType,
xmsHErrorBlock errorBlock);

Write a value, with a specified data type, to the message stream.

Parameters:
message (input)
The handle for the message.
value (input)
An array of bytes containing the value to be written.
length (input)
The number of bytes in the array.
objectType (input)
The data type of the value, which must be one of the following
objecttypes:
XMS_OBJECT_TYPE_BOOL
XMS_OBJECT_TYPE_BYTE
XMS_OBJECT_TYPE_BYTEARRAY
XMS_OBJECT_TYPE_CHAR
XMS_OBJECT_TYPE_DOUBLE
XMS_OBJECT_TYPE_FLOAT
XMS_OBJECT_TYPE_INT
XMS_OBJECT_TYPE_LONG
XMS_OBJECT_TYPE_SHORT
XMS_OBJECT_TYPE_STRING
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsStreamMsgWriteShort – Write Short Integer

Interface:
xmsRC xmsStreamMsgWriteShort(xmsHMsg message,
xmsSHORT value,
xmsHErrorBlock errorBlock);

Write a short integer to the message stream as 2 bytes, high order byte first.
Parameters:

Chapter 14. C classes 267

 message (input)
The handle for the message.
value (input)
The short integer to be written.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsStreamMsgWriteString – Write String

Interface:
xmsRC xmsStreamMsgWriteString(xmsHMsg message,
xmsCHAR *value,
xmsINT length,
xmsHErrorBlock errorBlock);

Write a string to the message stream.

Parameters:
message (input)
The handle for the message.
value (input)
A character array containing the string to be written.
length (input)
The length of the string in bytes. If the string is null terminated
with no embedded null characters, you can specify
XMSC_CALCULATE_STRING_SIZE instead and allow XMS to calculate
its length.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

TextMessage
A text message is a message whose body comprises a string.

Functions
xmsTextMsgGetText – Get Text
Interface:
xmsRC xmsTextMsgGetText(xmsHMsg message,
xmsCHAR *buffer,
xmsINT bufferLength,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);

268 Message Service Client for C/C++

Get the string that forms the body of the text message. If required, XMS converts
the characters in the string into the local code page.

For more information about how to use this function, see “C functions that return
a string by value” on page 64.
Parameters:
message (input)
The handle for the message.
buffer (output)
The buffer to contain the string. If data conversion is required, this
is the string after conversion.
bufferLength (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the string is not returned, but its length is returned in the
actualLength parameter.
actualLength (output)
The length of the string in bytes. If data conversion is required,
this is the length of the string after conversion. If you specify a
null pointer on input, the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

Notes:
1. If the buffer is not large enough to store the whole string, XMS returns
the string truncated to the length of the buffer, sets the actualLength
parameter to the actual length of the string, and returns an error.
2. If any other error occurs while attempting to get the string, XMS reports
the error but does not set the actualLength parameter.

xmsTextMsgSetText – Set Text

Interface:
xmsRC xmsTextMsgSetText(xmsHMsg message,
xmsCHAR *value,
xmsINT length,
xmsHErrorBlock errorBlock);

Set the string that forms the body of the text message.
Parameters:
message (input)
The handle for the message.
value (input)
A character array containing the string to be set.

Chapter 14. C classes 269

 length (input)
The length of the string in bytes. If the string is null terminated
with no embedded null characters, you can specify
XMSC_CALCULATE_STRING_SIZE instead and allow XMS to calculate
its length.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

270 Message Service Client for C/C++

Chapter 15. Additional C functions
This section documents the C functions that do not belong to any class.

The topic contains the following subtopic:

v “Process CCSID functions”

Process CCSID functions

This section documents the functions for getting and setting the process coded
character set identifier (CCSID) for an application.

For information about how to use these functions, see “Coded character set
identifiers” on page 56.

Functions
xmsGetClientCCSID – Get Process CCSID
Interface:
xmsRC xmsGetClientCCSID(xmsINT *ccsid,
xmsHErrorBlock errorBlock);

Get the process CCSID for the application.

Parameters:
ccsid (output)
The process CCSID.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

xmsSetClientCCSID – Set Process CCSID

Interface:
xmsRC xmsSetClientCCSID(xmsINT ccsid,
xmsHErrorBlock errorBlock);

Set the process CCSID for the application.

Parameters:
ccsid (input)
The process CCSID.
The following named constants are defined for the specified
Unicode CCSIDs:

© Copyright IBM Corp. 2005, 2009 271

 Named constant CCSID
XMSC_CCSID_UTF8 The UTF-8 representation of Unicode data
XMSC_CCSID_UTF16 The UTF-16 representation of Unicode data
XMSC_CCSID_UTF32 The UTF-32 representation of Unicode data

errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

272 Message Service Client for C/C++

Chapter 16. C++ classes
This section documents the C++ classes and their methods.

The following table summarizes all the classes.

Table 32. Summary of the C++ classes
Class Description
“BytesMessage” on page 275 A bytes message is a message whose body comprises a
stream of bytes.
“Connection” on page 284 A Connection object represents an application’s active
connection to a broker.
“ConnectionFactory” on page 289 An application uses a connection factory to create a
connection.
“ConnectionMetaData” on page 292 A ConnectionMetaData object provides information
about a connection.
“Destination” on page 293 A destination is where an application sends messages, or
it is a source from which an application receives
messages, or both.
“Exception” on page 297 If XMS detects an error while processing a call to a
method, XMS throws an exception. An exception is an
object that encapsulates information about the error.

There are different types of XMS exception, and an

Exception object is just one type of exception. However,
the Exception class is a superclass of the other XMS
exception classes. XMS throws an Exception object in
situations where none of the other types of exception are
appropriate.
“ExceptionListener” on page 300 An application uses an exception listener to be notified
asynchronously of a problem with a connection.
“IllegalStateException” on page 301 XMS throws this exception if an application calls a
method at an incorrect or inappropriate time, or if XMS
is not in an appropriate state for the requested operation.
“InitialContext” on page 301 An application uses an InitialContext object to create
objects from object definitions that are retrieved from a
repository of administered objects.
“InvalidClientIDException” on page 303 XMS throws this exception if an application attempts to
set a client identifier for a connection, but the client
identifier is not valid or is already in use.
“InvalidDestinationException” on page 303 XMS throws this exception if an application specifies a
destination that is not valid.
“InvalidSelectorException” on page 304 XMS throws this exception if an application provides a
message selector expression whose syntax is not valid.
“Iterator” on page 304 An iterator encapsulates a list of objects. An application
uses an iterator to access object in turn.
“MapMessage” on page 306 A map message is a message whose body comprises a
set of name-value pairs, where each value has an
associated data type.

© Copyright IBM Corp. 2005, 2009 273

Table 32. Summary of the C++ classes (continued)
Class Description
“Message” on page 317 A Message object represents a message that an
application sends or receives.
“MessageConsumer” on page 329 An application uses a message consumer to receive
messages sent to a destination.
“MessageEOFException” on page 333 XMS throws this exception if XMS encounters the end of
a bytes message stream when an application is reading
the body of a bytes message.
“MessageFormatException” on page 333 XMS throws this exception if XMS encounters a message
with a format that is not valid.
“MessageListener” on page 333 An application uses a message listener to receive
messages asynchronously.
“MessageNotReadableException” on page 334 XMS throws this exception if an application attempts to
read the body of a message that is write-only.
“MessageNotWritableException” on page 334 XMS throws this exception if an application attempts to
write to the body of a message that is read-only.
“MessageProducer” on page 335 An application uses a message producer to send
messages to a destination.
“ObjectMessage” on page 343 An object message is a message whose body comprises a
serialized Java or .NET object.
“Property” on page 345 A Property object represents a property of an object.
“PropertyContext” on page 357 PropertyContext is an abstract superclass that contains
methods that get and set properties. These methods are
inherited by other classes.
“QueueBrowser” on page 368 An application uses a queue browser to browse messages
on a queue without removing them.
“Requestor” on page 370 An application uses a requestor to send a request
message and then wait for, and receive, the reply.
“ResourceAllocationException” on page 373 XMS throws this exception if XMS cannot allocate the
resources required by a method.
“SecurityException” on page 373 XMS throws this exception if the user identifer and
password provided to authenticate an application are
rejected. XMS also throws this exception if an authority
check fails and prevents a method from completing.
“Session” on page 373 A session is a single threaded context for sending and
receiving messages.
“StreamMessage” on page 385 A stream message is a message whose body comprises a
stream of values, where each value has an associated
data type.
“String” on page 395 A String object encapsulates a string.
“TextMessage” on page 399 A text message is a message whose body comprises a
string.
“TransactionInProgressException” on page 400 XMS throws this exception if an application requests an
operation that is not valid because a transaction is in
progress.
“TransactionRolledBackException” on page 400 XMS throws this exception if an application calls
Session.commit() to commit the current transaction, but
the transaction is subsequently rolled back.

274 Message Service Client for C/C++

 The definition of each method lists the exception codes that XMS might return if it
detects an error while processing a call to the method. Each exception code is
represented by its named constant. The following table lists the exception codes
and their corresponding C++ exceptions.
Table 33. Exception codes and their corresponding C++ exceptions
Exception code Corresponding C++ exception
XMS_X_GENERAL_EXCEPTION “Exception” on page 297
XMS_X_ILLEGAL_STATE_EXCEPTION “IllegalStateException” on page 301
XMS_X_INVALID_CLIENTID_EXCEPTION “InvalidClientIDException” on page 303
XMS_X_INVALID_DESTINATION_EXCEPTION “InvalidDestinationException” on page 303
XMS_X_INVALID_SELECTOR_EXCEPTION “InvalidSelectorException” on page 304
XMS_X_MESSAGE_EOF_EXCEPTION “MessageEOFException” on page 333
XMS_X_MESSAGE_FORMAT_EXCEPTION “MessageFormatException” on page 333
XMS_X_MESSAGE_NOT_READABLE_EXCEPTION “MessageNotReadableException” on page 334
XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION “MessageNotWritableException” on page 334
XMS_X_RESOURCE_ALLOCATION_EXCEPTION “ResourceAllocationException” on page 373
XMS_X_SECURITY_EXCEPTION “SecurityException” on page 373
XMS_X_TRANSACTION_IN_PROGRESS_EXCEPTION “TransactionInProgressException” on page 400
XMS_X_TRANSACTION_ROLLED_BACK_EXCEPTION “TransactionRolledBackException” on page 400

BytesMessage
A bytes message is a message whose body comprises a stream of bytes.
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::Message
|
+----xms::BytesMessage

Methods
getBodyLength – Get Body Length
Interface:
xmsLONG getBodyLength() const;

Get the length of the body of the message when the body of the message is
read-only.
Parameters:
None
Returns:
The length of the body of the message in bytes. The method returns the
length of the whole body regardless of where the cursor for reading the
message is currently positioned.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION

Chapter 16. C++ classes 275

 readBoolean – Read Boolean Value
Interface:
xmsBOOL readBoolean() const;

Read a boolean value from the bytes message stream.

Parameters:
None
Returns:
The boolean value that is read.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

readByte – Read Byte

Interface:
xmsSBYTE readByte() const;

Read the next byte from the bytes message stream as a signed 8-bit integer.
Parameters:
None
Returns:
The byte that is read.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

readBytes – Read Bytes

Interface:
xmsINT readBytes(xmsSBYTE *buffer,
const xmsINT bufferLength,
xmsINT *returnedLength) const;

Read an array of bytes from the bytes message stream starting from the current
position of the cursor.
Parameters:
buffer (output)
The buffer to contain the array of bytes that is read. If the number
of bytes remaining to be read from the stream before the call is
greater than or equal to the length of the buffer, the buffer is filled.
Otherwise, the buffer is partially filled with all the remaining
bytes.

276 Message Service Client for C/C++

 If you specify a null pointer on input, the method skips over the
bytes without reading them. If the number of bytes remaining to
be read from the stream before the call is greater than or equal to
the length of the buffer, the number of bytes skipped is equal to
the length of the buffer. Otherwise, all the remaining bytes are
skipped.
bufferLength (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, no bytes are read into the buffer, but the number of bytes
remaining in the stream, starting from the current position of the
cursor, is returned in the returnedLength parameter, and the cursor
is not advanced.
returnedLength (output)
The number of bytes that are read into the buffer. If the buffer is
partially filled, the value is less than the length of the buffer,
indicating that there are no more bytes remaining to be read. If
there are no bytes remaining to be read from the stream before the
call, the value is XMSC_END_OF_STREAM.
If you specify a null pointer on input, the method returns no value.
Returns:
See the description of the returnedLength parameter.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION

readChar – Read Character

Interface:
xmsCHAR16 readChar() const;

Read the next 2 bytes from the bytes message stream as a character.
Parameters:
None
Returns:
The character that is read.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

readDouble – Read Double Precision Floating Point Number

Interface:
xmsDOUBLE readDouble() const;

Read the next 8 bytes from the bytes message stream as a double precision floating
point number.

Chapter 16. C++ classes 277

 Parameters:
None
Returns:
The double precision floating point number that is read.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

readFloat – Read Floating Point Number

Interface:
xmsFLOAT readFloat() const;

Read the next 4 bytes from the bytes message stream as a floating point number.
Parameters:
None
Returns:
The floating point number that is read.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

readInt – Read Integer

Interface:
xmsINT readInt() const;

Read the next 4 bytes from the bytes message stream as a signed 32-bit integer.
Parameters:
None
Returns:
The integer that is read.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

readLong – Read Long Integer

Interface:
xmsLONG readLong() const;

Read the next 8 bytes from the bytes message stream as a signed 64-bit integer.

278 Message Service Client for C/C++

Parameters:
None
Returns:
The long integer that is read.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

readShort – Read Short Integer

Interface:
xmsSHORT readShort() const;

Read the next 2 bytes from the bytes message stream as a signed 16-bit integer.
Parameters:
None
Returns:
The short integer that is read.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

readUnsignedByte – Read Unsigned Byte

Interface:
xmsBYTE readUnsignedByte() const;

Read the next byte from the bytes message stream as an unsigned 8-bit integer.
Parameters:
None
Returns:
The byte that is read.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

readUnsignedShort – Read Unsigned Short Integer

Interface:
xmsUSHORT readUnsignedShort() const;

Read the next 2 bytes from the bytes message stream as an unsigned 16-bit integer.

Chapter 16. C++ classes 279

 Parameters:
None
Returns:
The unsigned short integer that is read.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

readUTF – Read UTF String

Interface:
String readUTF() const;

Read a string, encoded in UTF-8, from the bytes message stream. If required, XMS
converts the characters in the string from UTF-8 into the local code page.
Parameters:
None
Returns:
A String object encapsulating the string that is read. If data conversion is
required, this is the string after conversion.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

reset – Reset
Interface:
xmsVOID reset() const;

Put the body of the message into read-only mode and reposition the cursor at the
beginning of the bytes message stream.
Parameters:
None
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION

writeBoolean – Write Boolean Value

Interface:
xmsVOID writeBoolean(const xmsBOOL value);

280 Message Service Client for C/C++

Write a boolean value to the bytes message stream.
Parameters:
value (input)
The boolean value to be written.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeByte – Write Byte

Interface:
xmsVOID writeByte(const xmsSBYTE value);

Write a byte to the bytes message stream.

Parameters:
value (input)
The byte to be written.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeBytes – Write Bytes

Interface:
xmsVOID writeBytes(const xmsSBYTE *value,
const xmsINT length);

Write an array of bytes to the bytes message stream.

Parameters:
value (input)
The array of bytes to be written.
length (input)
The number of bytes in the array.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

Chapter 16. C++ classes 281

 writeChar – Write Character
Interface:
xmsVOID writeChar(const xmsCHAR16 value);

Write a character to the bytes message stream as 2 bytes, high order byte first.
Parameters:
value (input)
The character to be written.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeDouble – Write Double Precision Floating Point Number

Interface:
xmsVOID writeDouble(const xmsDOUBLE value);

Convert a double precision floating point number to a long integer and write the
long integer to the bytes message stream as 8 bytes, high order byte first.
Parameters:
value (input)
The double precision floating point number to be written.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeFloat – Write Floating Point Number

Interface:
xmsVOID writeFloat(const xmsFLOAT value);

Convert a floating point number to an integer and write the integer to the bytes
message stream as 4 bytes, high order byte first.
Parameters:
value (input)
The floating point number to be written.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

282 Message Service Client for C/C++

writeInt – Write Integer
Interface:
xmsVOID writeInt(const xmsINT value);

Write an integer to the bytes message stream as 4 bytes, high order byte first.
Parameters:
value (input)
The integer to be written.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeLong – Write Long Integer

Interface:
xmsVOID writeLong(const xmsLONG value);

Write a long integer to the bytes message stream as 8 bytes, high order byte first.
Parameters:
value (input)
The long integer to be written.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeShort – Write Short Integer

Interface:
xmsVOID writeShort(const xmsSHORT value);

Write a short integer to the bytes message stream as 2 bytes, high order byte first.
Parameters:
value (input)
The short integer to be written.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

Chapter 16. C++ classes 283

 writeUTF – Write UTF String
Interface:
xmsVOID writeUTF(const String & value);

Write a string, encoded in UTF-8, to the bytes message stream. If required, XMS
converts the characters in the string from the local code page into UTF-8.
Parameters:
value (input)
A String object encapsulating the string to be written.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

Inherited methods
The following methods are inherited from the Message class:
clearBody, clearProperties, getHandle,
getJMSCorrelationID,getJMSDeliveryMode, getJMSDestination,
getJMSExpiration, getJMSMessageID, getJMSPriority, getJMSRedelivered,
getJMSReplyTo, getJMSTimestamp, getJMSType, getProperties, isNull,
propertyExists, setJMSCorrelationID, setJMSDeliveryMode, setJMSDestination,
setJMSExpiration, setJMSMessageID, setJMSPriority, setJMSRedelivered,
setJMSReplyTo, setJMSTimestamp, setJMSType

The following methods are inherited from the PropertyContext class:

getBooleanProperty, getByteProperty, getBytesProperty, getCharProperty,
getDoubleProperty, getFloatProperty, getIntProperty, getLongProperty,
getObjectProperty, getProperty, getShortProperty, getStringProperty,
setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty,
setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty,
setObjectProperty, setProperty, setShortProperty, setStringProperty

Connection
A Connection object represents an application’s active connection to a broker.
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::Connection

For a list of the XMS defined properties of a Connection object, see “Properties of
Connection” on page 403.

284 Message Service Client for C/C++

Methods
close – Close Connection
Interface:
xmsVOID close();

Close the connection.

If an application tries to close a connection that is already closed, the call is

ignored.
Parameters:
None
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

createSession – Create Session

Interface:
Session createSession(const xmsBOOL transacted,
const xmsINT acknowledgeMode);

Create a session.
Parameters:
transacted (input)
The value xmsTRUE means that the session is transacted. The value
xmsFALSE means that the session is not transacted.
For a real-time connection to a broker, the value must be xmsFALSE.
acknowledgeMode (input)
Indicates how messages received by an application are
acknowledged. The value must be one of the following
acknowledgement modes:
XMSC_AUTO_ACKNOWLEDGE
XMSC_CLIENT_ACKNOWLEDGE
XMSC_DUPS_OK_ACKNOWLEDGE
For a real-time connection to a broker, the value must be
XMSC_AUTO_ACKNOWLEDGE or XMSC_DUPS_OK_ACKNOWLEDGE

This parameter is ignored if the session is transacted. For more

information about acknowledgement modes, see “Message
acknowledgement” on page 39.
Returns:
The Session object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Chapter 16. C++ classes 285

 getClientID – Get Client ID
Interface:
String getClientID() const;

Get the client identifier for the connection.

This method is not valid for a real-time connection to a broker.

Parameters:
None
Returns:
A String object encapsulating the client identifier.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getExceptionListener – Get Exception Listener

Interface:
ExceptionListener * getExceptionListener() const;

Get a pointer to the exception listener that is registered with the connection.

For more information about using exception listeners, see “Exception listeners in
C++” on page 80.
Parameters:
None
Returns:
A pointer to the exception listener. If no exception listener is registered
with the connection, the method returns a null pointer.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getHandle – Get Handle

Interface:
xmsHConn getHandle() const;

Get the handle that a C application would use to access the connection.
Parameters:
None
Returns:
The handle for the connection.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

286 Message Service Client for C/C++

getMetaData – Get Metadata
Interface:
ConnectionMetaData getMetaData() const;

Get the metadata for the connection.

Parameters:
None
Returns:
The ConnectionMetaData object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

isNull – Check Whether Null

Interface:
xmsBOOL isNull() const;

Determine whether the Connection object is a null object.

Parameters:
None
Returns:
v xmsTRUE, if the Connection object is a null object.
v xmsFALSE, if the Connection object is not a null object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setClientID – Set Client ID

Interface:
xmsVOID setClientID(const String & clientID);

Set a client identifier for the connection. A client identifier is used only to support
durable subscriptions in the publish/subscribe domain, and is ignored in the
point-to-point domain.

If an application calls this method to set a client identifier for a connection, the
application must do so immediately after creating the connection, and before
performing any other operation on the connection. If the application tries to call
the method after this point, the call throws exception
XMS_X_ILLEGAL_STATE_EXCEPTION.

This method is not valid for a real-time connection to a broker.

Parameters:
clientID (input)
A String object encapsulating the client identifier.
Returns:
Void

Chapter 16. C++ classes 287

 Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_ILLEGAL_STATE_EXCEPTION
v XMS_X_INVALID_CLIENTID_EXCEPTION

setExceptionListener – Set Exception Listener

Interface:
xmsVOID setExceptionListener(const ExceptionListener *lsr);

Register an exception listener with the connection.

For more information about using exception listeners, see “Exception listeners in
C++” on page 80.
Parameters:
lsr (input)
A pointer to the exception listener.
If an exception listener is already registered with the connection,
you can cancel the registration by specifying a null pointer instead.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

start – Start Connection

Interface:
xmsVOID start() const;

Start, or restart, the delivery of incoming messages for the connection. The call is
ignored if the connection is already started.
Parameters:
None
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

stop – Stop Connection

Interface:
xmsVOID stop() const;

Stop the delivery of incoming messages for the connection. The call is ignored if
the connection is already stopped.

288 Message Service Client for C/C++

 Parameters:
None
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Inherited methods
The following methods are inherited from the PropertyContext class:
getBooleanProperty, getByteProperty, getBytesProperty, getCharProperty,
getDoubleProperty, getFloatProperty, getIntProperty, getLongProperty,
getObjectProperty, getProperty, getShortProperty, getStringProperty,
setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty,
setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty,
setObjectProperty, setProperty, setShortProperty, setStringProperty

ConnectionFactory
An application uses a connection factory to create a connection.
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::ConnectionFactory

For a list of the XMS defined properties of a ConnectionFactory object, see

“Properties of ConnectionFactory” on page 404.

Constructors
ConnectionFactory – Create Connection Factory
Interface:
ConnectionFactory();

Create a connection factory with the default properties.

Parameters:
None
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Methods
~ConnectionFactory – Delete Connection Factory
Interface:
virtual ~ConnectionFactory();

Delete the connection factory.

If an application tries to delete a connection factory that is already deleted, the call
is ignored.

Chapter 16. C++ classes 289

 Parameters:
None
Exceptions:
v XMS_X_GENERAL_EXCEPTION

createConnection – Create Connection (using the default user

identity)
Interface:
Connection createConnection();

Create a connection using the default user identity.

The connection factory properties XMSC_USERID and XMSC_PASSWORD, if they

are set, are used to authenticate the application. If these properties are not set, the
connection is created without authenticating the application, provided the
messaging server permits a connection without authentication. The properties are
ignored if the application connects to a WebSphere MQ queue manager in bindings
mode.

The connection is created in stopped mode. No messages are delivered until the
application calls Connection.start().
Parameters:
None
Returns:
The Connection object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_SECURITY_EXCEPTION

createConnection – Create Connection (using a specified user

identity)
Interface:
Connection createConnection(const String & userID,
const String & password);

Create a connection using a specified user identity.

The specified user identifier and password are used to authenticate the application.
The connection factory properties XMSC_USERID and XMSC_PASSWORD, if they
are set, are ignored. The user identifier and password are ignored if the application
connects to a WebSphere MQ queue manager in bindings mode.

The connection is created in stopped mode. No messages are delivered until the
application calls Connection.start().
Parameters:
userID (input)
A String object encapsulating the user identifier to be used to

290 Message Service Client for C/C++

 authenticate the application. If you specify a null String object, the
connection factory property XMSC_USERID is used instead.
password (input)
A String object encapsulating the password to be used to
authenticate the application. If you specify a null String object, the
connection factory property XMSC_PASSWORD is used instead.
Returns:
The Connection object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_SECURITY_EXCEPTION

getHandle – Get Handle

Interface:
xmsHConnFact getHandle() const;

Get the handle that a C application would use to access the connection factory.
Parameters:
None
Returns:
The handle for the connection factory.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

isNull – Check Whether Null

Interface:
xmsBOOL isNull() const;

Determine whether the ConnectionFactory object is a null object.

Parameters:
None
Returns:
v xmsTRUE, if the ConnectionFactory object is a null object.
v xmsFALSE, if the ConnectionFactory object is not a null object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Inherited methods
The following methods are inherited from the PropertyContext class:
getBooleanProperty, getByteProperty, getBytesProperty, getCharProperty,
getDoubleProperty, getFloatProperty, getIntProperty, getLongProperty,
getObjectProperty, getProperty, getShortProperty, getStringProperty,
setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty,

Chapter 16. C++ classes 291

 setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty,
setObjectProperty, setProperty, setShortProperty, setStringProperty

ConnectionMetaData
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::ConnectionMetaData

A ConnectionMetaData object provides information about a connection.

For a list of the XMS defined properties of a ConnectionMetaData object, see

“Properties of ConnectionMetaData” on page 408.

Methods
getHandle – Get Handle
Interface:
xmsHConnMetaData getHandle() const;

Get the handle that a C application would use to access the connection metadata.
Parameters:
None
Returns:
The handle for the connection metadata.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getJMSXProperties – Get JMS Defined Message Properties

Interface:
Iterator getJMSXProperties() const;

Get a list of the names of the JMS defined message properties supported by the
connection.

The method returns an iterator that encapsulates a list of Property objects, where
each Property object encapsulates the name of a JMS defined message property.
The application can then use the iterator to retrieve the name of each JMS defined
message property in turn.

JMS defined message properties are not supported by a real-time connection to a

broker.

Note: The equivalent JMS method performs a slightly different function. The JMS
method returns an enumeration of the names of the JMS defined message
properties.
Parameters:
None

292 Message Service Client for C/C++

 Returns:
The Iterator object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

isNull – Check Whether Null

Interface:
xmsBOOL isNull() const;

Determine whether the ConnectionMetaData object is a null object.

Parameters:
None
Returns:
v xmsTRUE, if the ConnectionMetaData object is a null object.
v xmsFALSE, if the ConnectionMetaData object is not a null object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Inherited methods
The following methods are inherited from the PropertyContext class:
getBooleanProperty, getByteProperty, getBytesProperty, getCharProperty,
getDoubleProperty, getFloatProperty, getIntProperty, getLongProperty,
getObjectProperty, getProperty, getShortProperty, getStringProperty,
setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty,
setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty,
setObjectProperty, setProperty, setShortProperty, setStringProperty

Destination
A destination is where an application sends messages, or it is a source from which
an application receives messages, or both.
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::Destination

For a list of the XMS defined properties of a Destination object, see “Properties of
Destination” on page 409.

Constructors
Destination – Create Destination (specifying a type and name)
Interface:
Destination(const xmsDESTINATION_TYPE destinationType,
const String & destinationName);

Create a destination using the specified destination type and name.

Chapter 16. C++ classes 293

 For a destination that is a queue, this constructor does not create the queue in the
messaging server. You must create the queue before an application can call this
constructor.
Parameters:
destinationType (input)
The type of the destination, which must be one of the following
values:
XMS_DESTINATION_TYPE_QUEUE
XMS_DESTINATION_TYPE_TOPIC
destinationName (input)
A String object encapsulating the name of the destination, which
can be the name of a queue or the name of a topic.
If the destination is a WebSphere MQ queue, you can specify the
name of the destination in either of the following ways:
QName
QMgrName/QName
where QName is the name of a WebSphere MQ queue, and QMgrName
is the name of a WebSphere MQ queue manager. The WebSphere
MQ queue name resolution process uses the values of QName and
QMgrName to determine the actual destination queue. For more
information about the queue name resolution process, see the
WebSphere MQ Application Programming Guide.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Destination – Create Destination (using a URI)

Interface:
Destination(const String & URI);

Create a destination using the specified uniform resource identifier (URI).

Properties of the destination that are not specified by the URI take the default
values.

For a destination that is a queue, this constructor does not create the queue in the
messaging server. You must create the queue before an application can call this
constructor.
Parameters:
URI (input)
A String object encapsulating the URI.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Methods
~Destination – Delete Destination
Interface:
virtual ~Destination();

294 Message Service Client for C/C++

Delete the destination.

For a destination that is a queue, this method does not delete the queue in the
messaging server unless the queue was created for an XMS temporary queue.

If an application tries to delete a destination that is already deleted, the call is

ignored.
Parameters:
None
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getHandle – Get Handle

Interface:
xmsHDest getHandle() const;

Get the handle that a C application would use to access the destination.
Parameters:
None
Returns:
The handle for the destination.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getName – Get Destination Name

Interface:
String getName() const;

Get the name of the destination.

Parameters:
None
Returns:
A String object encapsulating the name of the destination. The name is
either the name of a queue or the name of a topic.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getTypeId – Get Destination Type

Interface:
xmsDESTINATION_TYPE getTypeId();

Get the type of the destination.

Chapter 16. C++ classes 295

 Parameters:
None
Returns:
The type of the destination, which is one of the following values:
XMS_DESTINATION_TYPE_QUEUE
XMS_DESTINATION_TYPE_TOPIC
Exceptions:
v XMS_X_GENERAL_EXCEPTION

isNull – Check Whether Null

Interface:
xmsBOOL isNull() const;

Determine whether the Destination object is a null object.

Parameters:
None
Returns:
v xmsTRUE, if the Destination object is a null object.
v xmsFALSE, if the Destination object is not a null object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

toString – Get Destination Name as URI

Interface:
String toString() const;

Get the name of the destination in the format of a uniform resource identifier
(URI).
Parameters:
None
Returns:
A String object encapsulating the URI. The URI is either a queue URI or a
topic URI.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Inherited methods
The following methods are inherited from the PropertyContext class:
getBooleanProperty, getByteProperty, getBytesProperty, getCharProperty,
getDoubleProperty, getFloatProperty, getIntProperty, getLongProperty,
getObjectProperty, getProperty, getShortProperty, getStringProperty,
setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty,
setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty,
setObjectProperty, setProperty, setShortProperty, setStringProperty

296 Message Service Client for C/C++

Exception
If XMS detects an error while processing a call to a method, XMS throws an
exception. An exception is an object that encapsulates information about the error.
Inheritance hierarchy:
std::exception
|
+----xms::Exception

There are different types of XMS exception, and an Exception object is just one
type of exception. However, the Exception class is a superclass of the other XMS
exception classes. XMS throws an Exception object in situations where none of the
other types of exception are appropriate.

Methods
~Exception – Delete Exception
Interface:
virtual ~Exception() throw();

Delete the exception and any linked exceptions.

Parameters:
None
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

dump – Dump Exception

Interface:
xmsVOID dump(std::ostream outputStream) const;

Dump the exception to the specified C++ output stream as formatted text.
Parameters:
outputStream (input)
The C++ output stream.
Returns:
Void
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Chapter 16. C++ classes 297

 getErrorCode – Get Error Code
Interface:
xmsINT getErrorCode() const;

Get the error code.

Parameters:
None
Returns:
The error code.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getErrorData – Get Error Data

Interface:
String getErrorData() const;

Get the free format data that provides additional information about the error.
Parameters:
None
Returns:
A String object encapsulating the error data.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getErrorString – Get Error String

Interface:
String getErrorString() const;

Get the string of characters that describes the error. The characters in the string are
the same as those in the named constant that represents the error code.
Parameters:
None
Returns:
A String object encapsulating the error string.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

298 Message Service Client for C/C++

getHandle – Get Handle
Interface:
xmsHErrorBlock getHandle() const;

Get the handle for the internal error block that XMS creates for the exception.
Parameters:
None
Returns:
The handle for the error block.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getJMSException – Get Exception Code

Interface:
xmsJMSEXP_TYPE getJMSException() const;

Get the exception code.

Parameters:
None
Returns:
The exception code.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getLinkedException – Get Linked Exception

Interface:
Exception * getLinkedException() const;

Get a pointer to the next exception in the chain of exceptions.

Parameters:
None
Returns:
A pointer to an exception. The method returns a null pointer if there are no
more exceptions in the chain.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Chapter 16. C++ classes 299

 isNull – Check Whether Null
Interface:
xmsBOOL isNull() const;

Determine whether the Exception object is a null object.

Parameters:
None
Returns:
v xmsTRUE, if the Exception object is a null object.
v xmsFALSE, if the Exception object is not a null object.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

ExceptionListener
An application uses an exception listener to be notified asynchronously of a
problem with a connection.
Inheritance hierarchy:
None

If an application uses a connection only to consume messages asynchronously, and

for no other purpose, then the only way the application can learn about a problem
with the connection is by using an exception listener. In other situations, an
exception listener can provide a more immediate way of learning about a problem
with a connection than waiting until the next synchronous call to XMS.

Methods
onException – On Exception
Interface:
virtual xmsVOID onException(Exception *exception);

Notify the application of a problem with a connection.

onException() is a method of the exception listener that is registered with the

connection. The name of the method must be onException.

For more information about using exception listeners, see “Exception listeners in
C++” on page 80.
Parameters:
exception (input)
A pointer to an exception created by XMS.
Returns:
Void

300 Message Service Client for C/C++

IllegalStateException
XMS throws this exception if an application calls a method at an incorrect or
inappropriate time, or if XMS is not in an appropriate state for the requested
operation.
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::IllegalStateException

Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull

InitialContext
An application uses an InitialContext object to create objects from object definitions
that are retrieved from a repository of administered objects.
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::InitialContext

For a list of the XMS defined properties of an InitialContext object, see “Properties
of InitialContext” on page 410.

Constructors
InitialContext – Create Initial Context
Interface:
InitialContext( const String & uri);
InitialContext & create( const String & uri);

Create an InitialContext object.

Note: The creation of the InitialContext object is done separately from the
connection to the repository containing administered objects. This allows
properties to be set on the InitialContext object prior to connection. For
further details, see “InitialContext properties” on page 86.
Parameters:
uri (input)
A String object encapsulating a URI that identifies the name and
location of a repository containing administered objects. The exact
syntax of the URI depends on the context type. For further
information, see “URI format for XMS initial contexts” on page 87.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Chapter 16. C++ classes 301

 Methods
~InitialContext – Delete Initial Context
Interface:
InitialContext:: ~InitialContext();

Delete the InitialContext object. This frees all resources associated with the
InitialContext object.

If an application tries to delete an InitialContext object that is already deleted, the

call is ignored.
Parameters:
None
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getHandle – Get Handle

Interface:
xmsHInitialContext getHandle() const;

Get the handle that a C application would use to access the InitialContext object.
Parameters:
None
Returns:
The handle for the InitialContext object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

isNull – Check Whether Null

Interface:
xmsBOOL isNull() const;

Determine whether the InitialContext object is a null object.

Parameters:
None
Returns:
v xmsTRUE, if the InitialContext object is a null object.
v xmsFALSE, if the InitialContext object is not a null object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

302 Message Service Client for C/C++

 lookup – Look Up Object in Initial Context
Interface:
PropertyContext * lookup(const String & objectName) const;

Create an object from an object definition that is retrieved from the repository of
administered objects.
Parameters:
objectName (input)
A String object encapsulating the name of the administered object.
The name can be either a simple name or a complex name. For
further details, see “Retrieval of administered objects” on page 89.
Returns:
A pointer to the object that is created.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Inherited methods
The following methods are inherited from the PropertyContext class:
getBooleanProperty, getByteProperty, getBytesProperty, getCharProperty,
getDoubleProperty, getFloatProperty, getIntProperty, getLongProperty,
getObjectProperty, getProperty, getShortProperty, getStringProperty,
setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty,
setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty,
setObjectProperty, setProperty, setShortProperty, setStringProperty

InvalidClientIDException
XMS throws this exception if an application attempts to set a client identifier for a
connection, but the client identifier is not valid or is already in use.
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::InvalidClientIDException

Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull

InvalidDestinationException
XMS throws this exception if an application specifies a destination that is not valid.
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::InvalidDestinationException

Chapter 16. C++ classes 303

 Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull

InvalidSelectorException
XMS throws this exception if an application provides a message selector expression
whose syntax is not valid.
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::InvalidSelectorException

Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull

Iterator
An iterator encapsulates a list of objects. An application uses an iterator to access
object in turn.
Inheritance hierarchy:
None

An iterator also encapsulates a cursor that maintains the current position in the
list. When an iterator is created, the position of the cursor is before the first object.

An application cannot create an iterator directly using a constructor. An iterator is

created only by certain methods in order to pass a list of objects back to the
application.

This class is a helper class.

Methods
~Iterator – Delete Iterator
Interface:
virtual ~Iterator();

Delete the iterator.

If an application tries to delete an iterator that is already deleted, the call is

ignored.
Parameters:
None

304 Message Service Client for C/C++

Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getHandle – Get Handle

Interface:
xmsHIterator getHandle() const;

Get the handle that a C application would use to access the iterator.
Parameters:
None
Returns:
The handle for the iterator.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getNext – Get Next Object

Interface:
xmsVOID * getNext() const;

Move the cursor to the next object and get the object at the new position of the
cursor.
Parameters:
None
Returns:
A pointer to the object.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

hasNext – Check for More Objects

Interface:
xmsBOOL hasNext();

Check whether there are any more objects beyond the current position of the
cursor. The call does not move the cursor.
Parameters:
None

Chapter 16. C++ classes 305

 Returns:
v xmsTRUE, if there are more objects beyond the current position of the
cursor.
v xmsFALSE, if there are no more objects beyond the current position of the
cursor.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

isNull – Check Whether Null

Interface:
xmsBOOL isNull() const;

Determine whether the Iterator object is a null object.

Parameters:
None
Returns:
v xmsTRUE, if the Iterator object is a null object.
v xmsFALSE, if the Iterator object is not a null object.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

reset – Reset Iterator

Interface:
xmsVOID reset();

Move the cursor back to a position before the first object.

Parameters:
None
Returns:
Void
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

MapMessage
A map message is a message whose body comprises a set of name-value pairs,
where each value has an associated data type.
Inheritance hierarchy:

306 Message Service Client for C/C++

 xms::PropertyContext
|
+----xms::Message
|
+----xms::MapMessage

When an application gets the value of name-value pair, the value can be converted
by XMS into another data type. For more information about this form of implicit
conversion, see “Map messages” on page 104.

Methods
getBoolean – Get Boolean Value
Interface:
xmsBOOL getBoolean(const String & name) const;

Get the boolean value identified by name from the body of the map message.
Parameters:
name (input)
A String object encapsulating the name that identifies the boolean
value.
Returns:
The boolean value retrieved from the body of the map message.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getByte – Get Byte

Interface:
xmsSBYTE getByte(const String & name) const;

Get the byte identified by name from the body of the map message.
Parameters:
name (input)
A String object encapsulating the name that identifies the byte.
Returns:
The byte retrieved from the body of the map message. No data conversion
is performed on the byte.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getBytes – Get Bytes

Interface:
xmsINT getBytes(const String & name,
xmsSBYTE *buffer,
const xmsINT bufferLength,
xmsINT *actualLength) const;

Chapter 16. C++ classes 307

 Get the array of bytes identified by name from the body of the map message.

For more information about how to use this method, see “C++ methods that return
a byte array” on page 72.
Parameters:
name (input)
A String object encapsulating the name that identifies the array of
bytes.
buffer (output)
The buffer to contain the array of bytes. No data conversion is
performed on the bytes that are returned.
bufferLength (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the array of bytes is not returned, but its length is returned
in the actualLength parameter.
actualLength (output)
The number of bytes in the array. If you specify a null pointer on
input, the length of the array is not returned.
Returns:
The number of bytes in the array.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getChar – Get Character

Interface:
xmsCHAR16 getChar(const String & name) const;

Get the character identified by name from the body of the map message.
Parameters:
name (input)
A String object encapsulating the name that identifies the character.
Returns:
The character retrieved from the body of the map message.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getDouble – Get Double Precision Floating Point Number

Interface:
xmsDOUBLE getDouble(const String & name) const;

Get the double precision floating point number identified by name from the body
of the map message.
Parameters:

308 Message Service Client for C/C++

 name (input)
A String object encapsulating the name that identifies the double
precision floating point number.
Returns:
The double precision floating point number retrieved from the body of the
map message.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getFloat – Get Floating Point Number

Interface:
xmsFLOAT getFloat(const String & name) const;

Get the floating point number identified by name from the body of the map
message.
Parameters:
name (input)
A String object encapsulating the name that identifies the floating
point number.
Returns:
The floating point number retrieved from the body of the map message.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getInt – Get Integer

Interface:
xmsINT getInt(const String & name) const;

Get the integer identified by name from the body of the map message.
Parameters:
name (input)
A String object encapsulating the name that identifies the integer.
Returns:
The integer retrieved from the body of the map message.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getLong – Get Long Integer

Interface:
xmsLONG getLong(const String & name) const;

Get the long integer identified by name from the body of the map message.

Chapter 16. C++ classes 309

 Parameters:
name (input)
A String object encapsulating the name that identifies the long
integer.
Returns:
The long integer retrieved from the body of the map message.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getMap – Get Name-Value Pairs

Interface:
Iterator getMap() const;

Get a list of the name-value pairs in the body of the map message.

The method returns an iterator that encapsulates a list of Property objects, where
each Property object encapsulates a name-value pair. The application can then use
the iterator to access each name-value pair in turn.

Note: The equivalent JMS method performs a slightly different function. The JMS
method returns an enumeration of only the names, not the values, in the
body of the map message.
Parameters:
None
Returns:
The Iterator object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getObject – Get Object

Interface:
xmsOBJECT_TYPE getObject(const String & name,
xmsSBYTE *buffer,
const xmsINT bufferLength,
xmsINT *actualLength) const;

Get the value of a name-value pair, and its data type, from the body of the map
message. The name-value pair is identified by name.

For more information about how to use this method, see “C++ methods that return
a byte array” on page 72.
Parameters:
name (input)
A String object encapsulating the name of the name-value pair.

310 Message Service Client for C/C++

 buffer (output)
The buffer to contain the value, which is returned as an array of
bytes. If the value is a string and data conversion is required, this
is the value after conversion.
bufferLength (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the value is not returned, but its length is returned in the
actualLength parameter.
actualLength (output)
The length of the value in bytes. If the value is a string and data
conversion is required, this is the length after conversion. If you
specify a null pointer on input, the length is not returned.
Returns:
The data type of the value, which is one of the following object types:
XMS_OBJECT_TYPE_BOOL
XMS_OBJECT_TYPE_BYTE
XMS_OBJECT_TYPE_BYTEARRAY
XMS_OBJECT_TYPE_CHAR
XMS_OBJECT_TYPE_DOUBLE
XMS_OBJECT_TYPE_FLOAT
XMS_OBJECT_TYPE_INT
XMS_OBJECT_TYPE_LONG
XMS_OBJECT_TYPE_SHORT
XMS_OBJECT_TYPE_STRING
Exceptions:
XMS_X_GENERAL_EXCEPTION

getShort – Get Short Integer

Interface:
xmsSHORT getShort(const String & name) const;

Get the short integer identified by name from the body of the map message.
Parameters:
name (input)
A String object encapsulating the name that identifies the short
integer.
Returns:
The short integer retrieved from the body of the map message.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getString – Get String

Interface:
String getString(const String & name) const;

Chapter 16. C++ classes 311

 Get the string identified by name from the body of the map message.
Parameters:
name (input)
A String object encapsulating the name that identifies the string in
the body of the map message.
Returns:
A String object encapsulating the string retrieved from the body of the map
message. If data conversion is required, this is the string after conversion.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

itemExists – Check Name-Value Pair Exists

Interface:
xmsBOOL itemExists(const String & name) const;

Check whether the body of the map message contains a name-value pair with the
specified name.
Parameters:
name (input)
A String object encapsulating the name of the name-value pair.
Returns:
v xmsTRUE, if the body of the map message contains a name-value pair
with the specified name.
v xmsFALSE, if the body of the map message does not contain a name-value
pair with the specified name.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setBoolean – Set Boolean Value

Interface:
xmsVOID setBoolean(const String & name,
const xmsBOOL value);

Set a boolean value in the body of the map message.

Parameters:
name (input)
A String object encapsulating the name to identify the boolean
value in the body of the map message.
value (input)
The boolean value to be set.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
312 Message Service Client for C/C++
setByte – Set Byte
Interface:
xmsVOID setByte(const String & name,
const xmsSBYTE value);

Set a byte in the body of the map message.

Parameters:
name (input)
A String object encapsulating the name to identify the byte in the
body of the map message.
value (input)
The byte to be set.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setBytes – Set Bytes

Interface:
xmsVOID setBytes(const String & name,
const xmsSBYTE *value,
const xmsINT length);

Set an array of bytes in the body of the map message.

Parameters:
name (input)
A String object encapsulating the name to identify the array of
bytes in the body of the map message.
value (input)
The array of bytes to be set.
length (input)
The number of bytes in the array.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setChar – Set Character

Interface:
xmsVOID setChar(const String & name,
const xmsCHAR16 value);

Set a 2-byte character in the body of the map message.

Chapter 16. C++ classes 313

 Parameters:
name (input)
A String object encapsulating the name to identify the character in
the body of the map message.
value (input)
The character to be set.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setDouble – Set Double Precision Floating Point Number

Interface:
xmsVOID setDouble(const String & name,
const xmsDOUBLE value);

Set a double precision floating point number in the body of the map message.
Parameters:
name (input)
A String object encapsulating the name to identify the double
precision floating point number in the body of the map message.
value (input)
The double precision floating point number to be set.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setFloat – Set Floating Point Number

Interface:
xmsVOID setFloat(const String & name,
const xmsFLOAT value);

Set a floating point number in the body of the map message.

Parameters:
name (input)
A String object encapsulating the name to identify the floating
point number in the body of the map message.
value (input)
The floating point number to be set.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

314 Message Service Client for C/C++

setInt – Set Integer
Interface:
xmsVOID setInt(const String & name,
const xmsINT value);

Set an integer in the body of the map message.

Parameters:
name (input)
A String object encapsulating the name to identify the integer in
the body of the map message.
value (input)
The integer to be set.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setLong – Set Long Integer

Interface:
xmsVOID setLong(const String & name,
const xmsLONG value);

Set a long integer in the body of the map message.

Parameters:
name (input)
A String object encapsulating the name to identify the long integer
in the body of the map message.
value (input)
The long integer to be set.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setObject – Set Object

Interface:
xmsVOID setObject(const String & name,
const xmsOBJECT_TYPE objectType,
const xmsSBYTE *value,
const xmsINT length);

Set a value, with a specified data type, in the body of the map message.
Parameters:

Chapter 16. C++ classes 315

 name (input)
A String object encapsulating the name to identify the value in the
body of the map message.
objectType (input)
The data type of the value, which must be one of the following
object types:
XMS_OBJECT_TYPE_BOOL
XMS_OBJECT_TYPE_BYTE
XMS_OBJECT_TYPE_BYTEARRAY
XMS_OBJECT_TYPE_CHAR
XMS_OBJECT_TYPE_DOUBLE
XMS_OBJECT_TYPE_FLOAT
XMS_OBJECT_TYPE_INT
XMS_OBJECT_TYPE_LONG
XMS_OBJECT_TYPE_SHORT
XMS_OBJECT_TYPE_STRING
value (input)
An array of bytes containing the value to be set.
length (input)
The number of bytes in the array.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setShort – Set Short Integer

Interface:
xmsVOID setShort(const String & name,
const xmsSHORT value);

Set a short integer in the body of the map message.

Parameters:
name (input)
A String object encapsulating the name to identify the short integer
in the body of the map message.
value (input)
The short integer to be set.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

316 Message Service Client for C/C++

 setString – Set String
Interface:
xmsVOID setString(const String & name,
const String value);

Set a string in the body of the map message.

Parameters:
name (input)
A String object encapsulating the name to identify the string in the
body of the map message.
value (input)
A String object encapsulating the string to be set.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Inherited methods
The following methods are inherited from the Message class:
clearBody, clearProperties, getHandle,
getJMSCorrelationID,getJMSDeliveryMode, getJMSDestination,
getJMSExpiration, getJMSMessageID, getJMSPriority, getJMSRedelivered,
getJMSReplyTo, getJMSTimestamp, getJMSType, getProperties, isNull,
propertyExists, setJMSCorrelationID, setJMSDeliveryMode, setJMSDestination,
setJMSExpiration, setJMSMessageID, setJMSPriority, setJMSRedelivered,
setJMSReplyTo, setJMSTimestamp, setJMSType

The following methods are inherited from the PropertyContext class:

getBooleanProperty, getByteProperty, getBytesProperty, getCharProperty,
getDoubleProperty, getFloatProperty, getIntProperty, getLongProperty,
getObjectProperty, getProperty, getShortProperty, getStringProperty,
setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty,
setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty,
setObjectProperty, setProperty, setShortProperty, setStringProperty

Message
A Message object represents a message that an application sends or receives.
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::Message

For a list of the JMS message header fields in a Message object, see “Header fields
in an XMS message” on page 97. For a list of the JMS defined properties of a
Message object, see “JMS-defined properties of a message” on page 99. For a list of
the IBM defined properties of a Message object, see “IBM-defined properties of a
message” on page 100.

Chapter 16. C++ classes 317

 Methods
~Message – Delete Message
Interface:
virtual ~Message();

Delete the message.

If an application tries to delete a message that is already deleted, the call is

ignored.
Parameters:
None
Exceptions:
v XMS_X_GENERAL_EXCEPTION

acknowledge – Acknowledge
Interface:
xmsVOID acknowledge();

Acknowledge this message and all previously unacknowledged messages received

by the session.

An application can call this method if the acknowledgement mode of the session is
XMSC_CLIENT_ACKNOWLEDGE. Calls to the method are ignored if the session
has any other acknowledgement mode or is transacted.

Messages that have been received but not acknowledged might be re-delivered.

For more information about acknowledging messages, see “Message

acknowledgement” on page 39.
Parameters:
None
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_ILLEGAL_STATE_EXCEPTION

clearBody – Clear Body

Interface:
xmsVOID clearBody();

Clear the body of the message. The header fields and message properties are not
cleared.

If an application clears a message body, the body is left in the same state as an
empty body in a newly created message. The state of an empty body in a newly

318 Message Service Client for C/C++

created message depends on the type of message body. For more information, see
“The body of an XMS message” on page 101.

An application can clear a message body at any time, no matter what state the
body is in. If a message body is read-only, the only way that an application can
write to the body is for the application to clear the body first.
Parameters:
None
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

clearProperties – Clear Properties

Interface:
xmsVOID clearProperties();

Clear the properties of the message. The header fields and the message body are
not cleared.

If an application clears the properties of a message, the properties become readable

and writable.

An application can clear the properties of a message at any time, no matter what
state the properties are in. If the properties of a message are read-only, the only
way that the properties can become writable is for the application to clear the
properties first.
Parameters:
None
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getHandle – Get Handle

Interface:
xmsHMsg getHandle() const;

Get the handle that a C application would use to access the message.
Parameters:
None
Returns:
The handle for the message.
Thread context:
Any
Exceptions:

Chapter 16. C++ classes 319

 v XMS_X_GENERAL_EXCEPTION

getJMSCorrelationID – Get JMSCorrelationID

Interface:
String getJMSCorrelationID() const;

Get the correlation identifier of the message.

Parameters:
None
Returns:
A String object encapsulating the correlation identifier.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getJMSDeliveryMode – Get JMSDeliveryMode

Interface:
xmsINT getJMSDeliveryMode() const;

Get the delivery mode of the message. The delivery mode is set by the
MessageProducer.send() call when the message is sent.
Parameters:
None
Returns:
The delivery mode of the message, which is one of the following values:
XMSC_DELIVERY_PERSISTENT
XMSC_DELIVERY_NOT_PERSISTENT
For a newly created message that has not been sent, the delivery mode is
XMSC_DELIVERY_PERSISTENT, except for a real-time connection to a broker for
which the delivery mode is XMSC_DELIVERY_NOT_PERSISTENT. For a message
that has been received, the method returns the delivery mode that was set
by the MessageProducer.send() call when the message was sent unless the
receiving application changes the delivery mode by calling
setJMSDeliveryMode().
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getJMSDestination – Get JMSDestination

Interface:
Destination getJMSDestination() const;

Get the destination of the message. The destination is set by the

MessageProducer.send() call when the message is sent.
Parameters:
None

320 Message Service Client for C/C++

Returns:
The Destination object.
For a newly created message that has not been sent, the method returns a
null Destination object and throws an exception unless the sending
application sets a destination by calling setJMSDestination(). For a message
that has been received, the method returns a Destination object for the
destination that was set by the MessageProducer.send() call when the
message was sent unless the receiving application changes the destination
by calling setJMSDestination().
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getJMSExpiration – Get JMSExpiration

Interface:
xmsLONG getJMSExpiration() const;

Get the expiration time of the message.

The expiration time is set by the MessageProducer.send() call when the message is
sent. Its value is calculated by adding the time to live, as specified by the sending
application, to the time when the message is sent. The expiration time is expressed
in milliseconds since 00:00:00 GMT on the 1 January 1970.

If the time to live is 0, the MessageProducer.send() call sets the expiration time to 0
to indicate that the message does not expire.

XMS discards expired messages and does not deliver them to applications.
Parameters:
None
Returns:
The expiration time of the message.
For a newly created message that has not been sent, the expiration time is
0 unless the sending application sets a different expiration time by calling
setJMSExpiration(). For a message that has been received, the method
returns the expiration time that was set by the MessageProducer.send() call
when the message was sent unless the receiving application changes the
expiration time by calling setJMSExpiration().
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getJMSMessageID – Get JMSMessageID

Interface:
String getJMSMessageID() const;

Get the message identifier of the message. The message identifier is set by the
MessageProducer.send() call when the message is sent.

Chapter 16. C++ classes 321

 Parameters:
None
Returns:
A String object encapsulating the message identifier.
For a message that has been received, the method returns the message
identifier that was set by the MessageProducer.send() call when the
message was sent unless the receiving application changes the message
identifier by calling setJMSMessageID().
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Notes:
1. If a message has no message identifier, the method throws an exception.

getJMSPriority – Get JMSPriority

Interface:
xmsINT getJMSPriority() const;

Get the priority of the message. The priority is set by the MessageProducer.send()
call when the message is sent.
Parameters:
None
Returns:
The priority of the message. The value is an integer in the range 0, the
lowest priority, to 9, the highest priority.
For a newly created message that has not been sent, the priority is 4 unless
the sending application sets a different priority by calling setJMSPriority().
For a message that has been received, the method returns the priority that
was set by the MessageProducer.send() call when the message was sent
unless the receiving application changes the priority by calling
setJMSPriority().
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getJMSRedelivered – Get JMSRedelivered

Interface:
xmsBOOL getJMSRedelivered() const;

Get an indication of whether the message is being re-delivered. The indication is

set by the MessageConsumer.receive() call when the message is received.
Parameters:
None
Returns:
v xmsTRUE, if the message is being re-delivered.
v xmsFALSE, if the message is not being re-delivered.

322 Message Service Client for C/C++

 For a real-time connection to a broker, the method always returns
xmsFALSE.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getJMSReplyTo – Get JMSReplyTo

Interface:
Destination getJMSReplyTo() const;

Get the destination where a reply to the message is to be sent.

Parameters:
None
Returns:
A Destination object for the destination where a reply to the message is to
be sent. A null Destination object means that no reply is expected.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getJMSTimestamp – Get JMSTimestamp

Interface:
xmsLONG getJMSTimestamp() const;

Get the time when the message was sent. The time stamp is set by the
MessageProducer.send() call when the message is sent and is expressed in
milliseconds since 00:00:00 GMT on the 1 January 1970.
Parameters:
None
Returns:
The time when the message was sent.
For a newly created message that has not been sent, the time stamp is 0
unless the sending application sets a different time stamp by calling
setJMSTimestamp(). For a message that has been received, the method
returns the time stamp that was set by the MessageProducer.send() call
when the message was sent unless the receiving application changes the
time stamp by calling setJMSTimestamp().
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Notes:
1. If the time stamp is undefined, the method returns 0 but throws no
exception.

Chapter 16. C++ classes 323

 getJMSType – Get JMSType
Interface:
String getJMSType() const;

Get the type of the message.

Parameters:
None
Returns:
A String encapsulating the type of the message. If data conversion is
required, this is the type after conversion.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getProperties – Get Properties

Interface:
Iterator getProperties() const;

Get a list of the properties of the message.

The method returns an iterator that encapsulates a list of Property objects. The
application can then use the iterator to access each property in turn.

Note: The equivalent JMS method performs a slightly different function. The JMS
method returns an enumeration of only the names of the properties of the
message, not their values.
Parameters:
None
Returns:
The Iterator object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

isNull – Check Whether Null

Interface:
xmsBOOL isNull() const;

Determine whether the Message object is a null object.

Parameters:
None
Returns:
v xmsTRUE, if the Message object is a null object.
v xmsFALSE, if the Message object is not a null object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

324 Message Service Client for C/C++

propertyExists – Check Property Exists
Interface:
xmsBOOL propertyExists(const String & propertyName) const;

Check whether the message has a property with the specified name.
Parameters:
propertyName (input)
A String object encapsulating the name of the property.
Returns:
v xmsTRUE, if the message has a property with the specified name.
v xmsFALSE, if the message does not have a property with the specified
name.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setJMSCorrelationID – Set JMSCorrelationID

Interface:
xmsVOID setJMSCorrelationID(const String correlID);

Set the correlation identifier of the message.

Parameters:
correlID (input)
A String object encapsulating the correlation identifier.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setJMSDeliveryMode – Set JMSDeliveryMode

Interface:
xmsVOID setJMSDeliveryMode(const xmsINT deliveryMode);

Set the delivery mode of the message.

A delivery mode set by this method before the message is sent is ignored and
replaced by the MessageProducer.send() call when the message is sent. However,
you can use this method to change the delivery mode of a message that has been
received.
Parameters:
deliveryMode (input)
The delivery mode of the message, which must be one of the
following values:

Chapter 16. C++ classes 325

 XMSC_DELIVERY_PERSISTENT
XMSC_DELIVERY_NOT_PERSISTENT
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setJMSDestination – Set JMSDestination

Interface:
xmsVOID setJMSDestination(const Destination & destination);

Set the destination of the message.

A destination set by this method before the message is sent is ignored and replaced
by the MessageProducer.send() call when the message is sent. However, you can
use this method to change the destination of a message that has been received.
Parameters:
destination (input)
A Destination object representing the destination of the message.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setJMSExpiration – Set JMSExpiration

Interface:
xmsVOID setJMSExpiration(const xmsLONG expiration);

Set the expiration time of the message.

An expiration time set by this method before the message is sent is ignored and
replaced by the MessageProducer.send() call when the message is sent. However,
you can use this method to change the expiration time of a message that has been
received.
Parameters:
expiration (input)
The expiration time of the message expressed in milliseconds since
00:00:00 GMT on the 1 January 1970.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

326 Message Service Client for C/C++

setJMSMessageID – Set JMSMessageID
Interface:
xmsVOID setJMSMessageID(const String & msgID);

Set the message identifier of the message.

A message identifier set by this method before the message is sent is ignored and
replaced by the MessageProducer.send() call when the message is sent. However,
you can use this method to change the message identifier of a message that has
been received.
Parameters:
msgID (input)
A String object encapsulating the message identifier.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setJMSPriority – Set JMSPriority

Interface:
xmsVOID setJMSPriority(const xmsINT priority);

Set the priority of the message.

A priority set by this method before the message is sent is ignored and replaced by
the MessageProducer.send() call when the message is sent. However, you can use
this method to change the priority of a message that has been received.
Parameters:
priority (input)
The priority of the message. The value can be an integer in the
range 0, the lowest priority, to 9, the highest priority.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setJMSRedelivered – Set JMSRedelivered

Interface:
xmsVOID setJMSRedelivered(const xmsBOOL redelivered);

Indicate whether the message is being re-delivered.

An indication of re-delivery set by this method before the message is sent is

ignored by the MessageProducer.send() call when the message is sent, and is

Chapter 16. C++ classes 327

 ignored and replaced by the MessageConsumer.receive() call when the message is
received. However, you can use this method to change the indication for a message
that has been received.
Parameters:
redelivered (input)
The value xmsTRUE means that the message is being re-delivered.
The value xmsFALSE means that the message is not being
re-delivered.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setJMSReplyTo – Set JMSReplyTo

Interface:
xmsVOID setJMSReplyTo(const Destination & destination);

Set the destination where a reply to the message is to be sent.

Parameters:
destination (input)
A Destination object representing the destination where a reply to
the message is to be sent. A null Destination object means that no
reply is expected.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setJMSTimestamp – Set JMSTimestamp

Interface:
xmsVOID setJMSTimestamp(const xmsLONG timeStamp);

Set the time when the message is sent.

A time stamp set by this method before the message is sent is ignored and
replaced by the MessageProducer.send() call when the message is sent. However,
you can use this method to change the time stamp of a message that has been
received.
Parameters:
timeStamp (input)
The time when the message is sent expressed in milliseconds since
00:00:00 GMT on the 1 January 1970.
Returns:
Void
Exceptions:

328 Message Service Client for C/C++

 v XMS_X_GENERAL_EXCEPTION

setJMSType – Set JMSType

Interface:
xmsVOID setJMSType(const String & type);

Set the type of the message.

Parameters:
type (input)
A String object encapsulating the type of the message.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Inherited methods
The following methods are inherited from the PropertyContext class:
getBooleanProperty, getByteProperty, getBytesProperty, getCharProperty,
getDoubleProperty, getFloatProperty, getIntProperty, getLongProperty,
getObjectProperty, getProperty, getShortProperty, getStringProperty,
setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty,
setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty,
setObjectProperty, setProperty, setShortProperty, setStringProperty

MessageConsumer
An application uses a message consumer to receive messages sent to a destination.
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::MessageConsumer

For a list of the XMS defined properties of a MessageConsumer object, see

“Properties of MessageConsumer” on page 415.

Methods
close – Close Message Consumer
Interface:
xmsVOID close();

Close the message consumer.

If an application tries to close a message consumer that is already closed, the call is
ignored.
Parameters:
None

Chapter 16. C++ classes 329

 Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getHandle – Get Handle

Interface:
xmsHMsgConsumer getHandle() const;

Get the handle that a C application would use to access the message consumer.
Parameters:
None
Returns:
The handle for the message consumer.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getMessageListener – Get Message Listener

Interface:
MessageListener * getMessageListener() const;

Get a pointer to the message listener that is registered with the message consumer.

For more information about using message listeners, see “Message listeners in
C++” on page 78.
Parameters:
None
Returns:
A pointer to the message listener. If no message listener is registered with
the message consumer, the method returns a null pointer.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getMessageSelector – Get Message Selector

Interface:
String getMessageSelector() const;

Get the message selector for the message consumer.

Parameters:
None

330 Message Service Client for C/C++

Returns:
A String object encapsulating the message selector expression. If data
conversion is required, this is the message selector expression after
conversion. If the message consumer does not have a message selector, the
method returns a null String object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

isNull – Check Whether Null

Interface:
xmsBOOL isNull() const;

Determine whether the MessageConsumer object is a null object.

Parameters:
None
Returns:
v xmsTRUE, if the MessageConsumer object is a null object.
v xmsFALSE, if the MessageConsumer object is not a null object.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

receive – Receive
Interface:
Message * receive() const;

Receive the next message for the message consumer. The call waits indefinitely for
a message, or until the message consumer is closed.
Parameters:
None
Returns:
A pointer to the Message object. If the message consumer is closed while
the call is waiting for a message, the method returns a pointer to a null
Message object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

receive – Receive (with a wait interval)

Interface:
Message * receive(const xmsLONG waitInterval) const;

Chapter 16. C++ classes 331

 Receive the next message for the message consumer. The call waits only a specified
period of time for a message, or until the message consumer is closed.
Parameters:
waitInterval (input)
The time, in milliseconds, that the call waits for a message. If you
specify a wait interval of 0, the call waits indefinitely for a
message.
Returns:
A pointer to the Message object. If no message arrives during the wait
interval, or if the message consumer is closed while the call is waiting for a
message, the method returns a pointer to a null Message object but throws
no exception.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

receiveNoWait – Receive with No Wait

Interface:
Message * receiveNoWait() const;

Receive the next message for the message consumer if one is available
immediately.
Parameters:
None
Returns:
A pointer to a Message object. If no message is available immediately, the
method returns a pointer to a null Message object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setMessageListener – Set Message Listener

Interface:
xmsVOID setMessageListener(const MessageListener *lsr);

Register a message listener with the message consumer.

For more information about using message listeners, see “Message listeners in
C++” on page 78.
Parameters:
lsr (input)
A pointer to the message listener. If a message listener is already
registered with the message consumer, you can cancel the
registration by specifying a null pointer instead.
Returns:
Void
Exceptions:

332 Message Service Client for C/C++

 v XMS_X_GENERAL_EXCEPTION

Inherited methods
The following methods are inherited from the PropertyContext class:
getBooleanProperty, getByteProperty, getBytesProperty, getCharProperty,
getDoubleProperty, getFloatProperty, getIntProperty, getLongProperty,
getObjectProperty, getProperty, getShortProperty, getStringProperty,
setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty,
setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty,
setObjectProperty, setProperty, setShortProperty, setStringProperty

MessageEOFException
XMS throws this exception if XMS encounters the end of a bytes message stream
when an application is reading the body of a bytes message.
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::MessageEOFException

Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull

MessageFormatException
XMS throws this exception if XMS encounters a message with a format that is not
valid.
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::MessageFormatException

Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull

MessageListener
An application uses a message listener to receive messages asynchronously.
Inheritance hierarchy:
None

Chapter 16. C++ classes 333

 Methods
onMessage – On Message
Interface:
virtual xmsVOID onMessage(Message *message);

Deliver a message asynchronously to the message consumer.

onMessage() is a method of the message listener that is registered with the

message consumer. The name of the method must be onMessage.

For more information about using message listeners, see “Message listeners in
C++” on page 78.
Parameters:
message (input)
A pointer to the Message object.
Returns:
Void

MessageNotReadableException
XMS throws this exception if an application attempts to read the body of a
message that is write-only.
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::MessageNotReadableException

Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull

MessageNotWritableException
XMS throws this exception if an application attempts to write to the body of a
message that is read-only.
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::MessageNotWritableException

Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull

334 Message Service Client for C/C++

MessageProducer
An application uses a message producer to send messages to a destination.
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::MessageProducer

For a list of the XMS defined properties of a MessageProducer object, see

“Properties of MessageProducer” on page 416.

Methods
close – Close Message Producer
Interface:
xmsVOID close();

Close the message producer.

If an application tries to close a message producer that is already closed, the call is
ignored.
Parameters:
None
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getDeliveryMode – Get Default Delivery Mode

Interface:
xmsINT getDeliveryMode() const;

Get the default delivery mode for messages sent by the message producer.
Parameters:
None
Returns:
The default delivery mode, which is one of the following values:
XMSC_DELIVERY_PERSISTENT
XMSC_DELIVERY_NOT_PERSISTENT
For a real-time connection to a broker, the method always returns
XMSC_DELIVERY_NOT_PERSISTENT.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Chapter 16. C++ classes 335

 getDestination – Get Destination
Interface:
Destination getDestination() const;

Get the destination for the message producer.

Parameters:
None
Returns:
The Destination object. If the message producer does not have a
destination, the method returns a null Destination object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getDisableMsgID – Get Disable Message ID Flag

Interface:
xmsBOOL getDisableMsgID() const;

Get an indication of whether a receiving application requires message identifiers to

be included in messages sent by the message producer.
Parameters:
None
Returns:
v xmsTRUE, if a receiving application does not require message identifiers to
be included in messages sent by the message producer.
v xmsFALSE, if a receiving application does require message identifiers to be
included in messages sent by the message producer.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getDisableMsgTS – Get Disable Time Stamp Flag

Interface:
xmsBOOL getDisableMsgTS() const;

Get an indication of whether a receiving application requires time stamps to be

included in messages sent by the message producer.
Parameters:
None
Returns:
v xmsTRUE, if a receiving application does not require time stamps to be
included in messages sent by the message producer.
v xmsFALSE, if a receiving application does require time stamps to be
included in messages sent by the message producer.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

336 Message Service Client for C/C++

getHandle – Get Handle
Interface:
xmsHMsgProducer getHandle() const;

Get the handle that a C application would use to access the message producer.
Parameters:
None
Returns:
The handle for the message producer.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getPriority – Get Default Priority

Interface:
xmsINT getPriority() const;

Get the default priority for messages sent by the message producer.
Parameters:
None
Returns:
The default message priority. The value is an integer in the range 0, the
lowest priority, to 9, the highest priority.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getTimeToLive – Get Default Time to Live

Interface:
xmsLONG getTimeToLive() const;

Get the default length of time that a message exists before it expires. The time is
measured from when the message producer sends the message.
Parameters:
None
Returns:
The default time to live in milliseconds. A value of 0 means that a message
never expires.
For a real-time connection to a broker, the method always returns 0.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Chapter 16. C++ classes 337

 isNull – Check Whether Null
Interface:
xmsBOOL isNull() const;

Determine whether the MessageProducer object is a null object.

Parameters:
None
Returns:
v xmsTRUE, if the MessageProducer object is a null object.
v xmsFALSE, if the MessageProducer object is not a null object.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

send – Send
Interface:
xmsVOID send(const Message & message) const;

Send a message to the destination that was specified when the message producer
was created. Send the message using the message producer’s default delivery
mode, priority, and time to live.
Parameters:
message (input)
The Message object.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_FORMAT_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION

send – Send (specifying a delivery mode, priority, and time to

live)
Interface:
xmsVOID send(const Message & message,
const xmsINT deliveryMode,
const xmsINT priority,
const xmsLONG timeToLive) const;

Send a message to the destination that was specified when the message producer
was created. Send the message using the specified delivery mode, priority, and
time to live.

338 Message Service Client for C/C++

Parameters:
message (input)
The Message object.
deliveryMode (input)
The delivery mode for the message, which must be one of the
following values:
XMSC_DELIVERY_PERSISTENT
XMSC_DELIVERY_NOT_PERSISTENT
For a real-time connection to a broker, the value must be
XMSC_DELIVERY_NOT_PERSISTENT.
priority (input)
The priority of the message. The value can be an integer in the
range 0, for the lowest priority, to 9, for the highest priority. On a
real-time connection to a broker, the value is ignored.
timeToLive (input)
The time to live for the message in milliseconds. A value of 0
means that the message never expires. For a real-time connection
to a broker, the value must be 0.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_FORMAT_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION
v XMS_X_ILLEGAL_STATE_EXCEPTION

send – Send (to a specified destination)

Interface:
xmsVOID send(const Destination & destination,
const Message & message) const;

Send a message to a specified destination if you are using a message producer for
which no destination was specified when the message producer was created. Send
the message using the message producer’s default delivery mode, priority, and
time to live.

Typically, you specify a destination when you create a message producer but, if
you do not, you must specify a destination every time you send a message.
Parameters:
destination (input)
The Destination object.
message (input)
The Message object.
Returns:
Void
Exceptions:

Chapter 16. C++ classes 339

 v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_FORMAT_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION

send – Send (to a specified destination, specifying a delivery

mode, priority, and time to live)
Interface:
xmsVOID send(const Destination & destination,
const Message & message,
const xmsINT deliveryMode,
const xmsINT priority,
const xmsLONG timeToLive) const;

Send a message to a specified destination if you are using a message producer for
which no destination was specified when the message producer was created. Send
the message using the specified delivery mode, priority, and time to live.

Typically, you specify a destination when you create a message producer but, if
you do not, you must specify a destination every time you send a message.
Parameters:
destination (input)
The Destination object.
message (input)
The Message object.
deliveryMode (input)
The delivery mode for the message, which must be one of the
following values:
XMSC_DELIVERY_PERSISTENT
XMSC_DELIVERY_NOT_PERSISTENT
For a real-time connection to a broker, the value must be
XMSC_DELIVERY_NOT_PERSISTENT.
priority (input)
The priority of the message. The value can be an integer in the
range 0, for the lowest priority, to 9, for the highest priority. On a
real-time connection to a broker, the value is ignored.
timeToLive (input)
The time to live for the message in milliseconds. A value of 0
means that the message never expires. For a real-time connection
to a broker, the value must be 0.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_FORMAT_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION
v XMS_X_ILLEGAL_STATE_EXCEPTION

340 Message Service Client for C/C++

setDeliveryMode – Set Default Delivery Mode
Interface:
xmsVOID setDeliveryMode(const xmsINT deliveryMode);

Set the default delivery mode for messages sent by the message producer.
Parameters:
deliveryMode (input)
The default delivery mode, which must be one of the following
values:
XMSC_DELIVERY_PERSISTENT
XMSC_DELIVERY_NOT_PERSISTENT
For a real-time connection to a broker, the value must be
XMSC_DELIVERY_NOT_PERSISTENT.
The default value is XMSC_DELIVERY_PERSISTENT, except for a
real-time connection to a broker for which the default value is
XMSC_DELIVERY_NOT_PERSISTENT.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setDisableMsgID – Set Disable Message ID Flag

Interface:
xmsVOID setDisableMsgID(const xmsBOOL msgIDDisabled);

Indicate whether a receiving application requires message identifiers to be included

in messages sent by the message producer.

On a connection to a queue manager, or on a real-time connection to a broker, this

flag is ignored. On a connection to a service integration bus, the flag is honoured.
Parameters:
msgIDDisabled (input)
The value xmsTRUE means that a receiving application does not
require message identifiers to be included in messages sent by the
message producer. The value xmsFALSE means that a receiving
application does require message identifiers. The default value is
xmsFALSE.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Chapter 16. C++ classes 341

 setDisableMsgTS – Set Disable Time Stamp Flag
Interface:
xmsVOID setDisableMsgTS(const xmsBOOL timeStampDisabled);

Indicate whether a receiving application requires time stamps to be included in

messages sent by the message producer.

On a real-time connection to a broker, this flag is ignored. On a connection to a

queue manager, or on a connection to a service integration bus, the flag is
honoured.
Parameters:
timeStampDisabled (input)
The value xmsTRUE means that a receiving application does not
require time stamps to be included in messages sent by the
message producer. The value xmsFALSE means that a receiving
application does require time stamps. The default value is
xmsFALSE.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setPriority – Set Default Priority

Interface:
xmsVOID setPriority(const xmsINT priority);

Set the default priority for messages sent by the message producer.

On a real-time connection to a broker, the priority of a message is ignored.

Parameters:
priority (input)
The default message priority. The value can be an integer in the
range 0, for the lowest priority, to 9, for the highest priority. The
default value is 4.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setTimeToLive – Set Default Time to Live

Interface:
xmsVOID setTimeToLive(const xmsLONG timeToLive);

Set the default length of time that a message exists before it expires. The time is
measured from when the message producer sends the message.

342 Message Service Client for C/C++

 Parameters:
timeToLive (input)
The default time to live in milliseconds. The default value is 0,
which means that a message never expires. For a real-time
connection to a broker, the value must be 0.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Inherited methods
The following methods are inherited from the PropertyContext class:
getBooleanProperty, getByteProperty, getBytesProperty, getCharProperty,
getDoubleProperty, getFloatProperty, getIntProperty, getLongProperty,
getObjectProperty, getProperty, getShortProperty, getStringProperty,
setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty,
setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty,
setObjectProperty, setProperty, setShortProperty, setStringProperty

ObjectMessage
An object message is a message whose body comprises a serialized Java or .NET
object.
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::Message
|
+----xms::ObjectMessage

Methods
getObject – Get Object as Bytes
Interface:
xmsINT getObject(xmsSBYTE *buffer,
xmsINT bufferLength,
xmsINT *actualLength);

Get the object that forms the body of the object message.

For more information about how to use this method, see “C++ methods that return
a byte array” on page 72.
Parameters:
buffer (output)
The buffer to contain the object, which is returned as an array of
bytes.
bufferLength (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the object is not returned, but its length is returned in the
actualLength parameter.

Chapter 16. C++ classes 343

 actualLength (output)
The length of the object in bytes. If you specify a null pointer on
input, the length is not returned.
Returns:
The length of the object in bytes.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

Notes:
1. If the buffer is not large enough to store the whole object, XMS returns
the object truncated to the length of the buffer, sets the actualLength
parameter to the actual length of the object, and returns an error.
2. If any other error occurs while attempting to get the object, XMS reports
the error but does not set the actualLength parameter.

setObject – Set Object as Bytes

Interface:
xmsVOID setObject(xmsSBYTE *value,
xmsINT length);

Set the string that forms the body of the object message.
Parameters:
value (input)
An array of bytes representing the object to be set.
length (input)
The number of bytes in the array.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

Inherited methods
The following methods are inherited from the Message class:
clearBody, clearProperties, getHandle,
getJMSCorrelationID,getJMSDeliveryMode, getJMSDestination,
getJMSExpiration, getJMSMessageID, getJMSPriority, getJMSRedelivered,
getJMSReplyTo, getJMSTimestamp, getJMSType, getProperties, isNull,
propertyExists, setJMSCorrelationID, setJMSDeliveryMode, setJMSDestination,
setJMSExpiration, setJMSMessageID, setJMSPriority, setJMSRedelivered,
setJMSReplyTo, setJMSTimestamp, setJMSType

The following methods are inherited from the PropertyContext class:

getBooleanProperty, getByteProperty, getBytesProperty, getCharProperty,
getDoubleProperty, getFloatProperty, getIntProperty, getLongProperty,

344 Message Service Client for C/C++

 getObjectProperty, getProperty, getShortProperty, getStringProperty,
setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty,
setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty,
setObjectProperty, setProperty, setShortProperty, setStringProperty

Property
A Property object represents a property of an object.
Inheritance hierarchy:
None

A Property object has three attributes:

Property name
The name of the property
Property value
The value of the property
Property type
The data type of the value of the property

If an application sets the property value attribute of a Property object, the property
value replaces any previous value the attribute had.

This class is a helper class.

Constructors
Property – Copy Property
Interface:
Property(const Property & property);

Property & duplicate(const Property & property);

Copy the Property object.

Parameters:
property (input)
The Property object.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Property – Create Property

Interface:
Property(const String & propertyName,
const xmsBOOL propertyValue);

Property(const String & propertyName,

const xmsSBYTE *propertyValue,
xmsINT length);

Chapter 16. C++ classes 345

 Property(const String & propertyName,
const xmsSBYTE propertyValue);

Property(const String & propertyName,

const xmsCHAR16 propertyValue);

Property(const String & propertyName,

const xmsDOUBLE propertyValue);

Property(const String & propertyName,

const xmsFLOAT propertyValue);

Property(const String & propertyName,

const xmsINT propertyValue);

Property(const String & propertyName,

const xmsLONG propertyValue);

Property(const String & propertyName,

const xmsSHORT propertyValue);

Property(const String & propertyName,

const String & propertyValue);

Create a Property object with a property name, a property value, and a property
type.
Parameters:
propertyName (input)
A String object encapsulating the property name.
propertyValue (input)
The property value. The property type is determined by the data
type of the property value.
length (input)
The length of the property value in bytes. This parameter is
applicable only if the property value is an array of bytes.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Property – Create Property (with no property value or property

type)
Interface:
Property(const String & propertyName);

Property & create(const String & propertyName);

Create a Property object with no property value or property type.

Parameters:
propertyName (input)
A String object encapsulating the property name.
Thread context:
Any

346 Message Service Client for C/C++

 Exceptions:
v XMS_X_GENERAL_EXCEPTION

Methods
~Property – Delete Property
Interface:
virtual ~Property();

Delete the Property object.

If an application tries to delete a Property object that is already deleted, the call is
ignored.
Parameters:
None
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getBoolean – Get Boolean Property Value

Interface:
xmsBOOL getBoolean() const;

Get the boolean property value from the Property object.

Parameters:
None
Returns:
The boolean property value.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getByte – Get Byte Property Value

Interface:
xmsSBYTE getByte() const;

Get the byte property value from the Property object.

Parameters:
None
Returns:
The byte property value.
Thread context:
Any

Chapter 16. C++ classes 347

 Exceptions:
v XMS_X_GENERAL_EXCEPTION

getByteArray – Get Byte Array Property Value

Interface:
xmsINT getByteArray(xmsSBYTE *propertyValue,
const xmsINT length,
xmsINT *actualLength) const;

Get the byte array property value from the Property object.

For more information about how to use this method, see “C++ methods that return
a byte array” on page 72.
Parameters:
propertyValue (output)
The buffer to contain the property value, which is an array of
bytes.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the property value is not returned, but its length is
returned in the actualLength parameter.
actualLength (output)
The length of the property value in bytes. If you specify a null
pointer on input, the length is not returned.
Returns:
The length of the property value in bytes.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getChar – Get Character Property Value

Interface:
xmsCHAR16 getChar() const;

Get the 2-byte character property value from the Property object.
Parameters:
None
Returns:
The 2-byte character property value.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

348 Message Service Client for C/C++

getDouble – Get Double Precision Floating Point Property Value
Interface:
xmsDOUBLE getDouble() const;

Get the double precision floating point property value from the Property object.
Parameters:
None
Returns:
The double precision floating point property value.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getFloat – Get Floating Point Property Value

Interface:
xmsFLOAT getFloat() const;

Get the floating point property value from the Property object.
Parameters:
None
Returns:
The floating point property value.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getHandle – Get Handle

Interface:
xmsHProperty getHandle() const;

Get the handle that a C application would use to access the Property object.
Parameters:
None
Returns:
The handle for the Property object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Chapter 16. C++ classes 349

 getInt – Get Integer Property Value
Interface:
xmsINT getInt() const;

Get the integer property value from the Property object.

Parameters:
None
Returns:
The integer property value.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getLong – Get Long Integer Property Value

Interface:
xmsLONG getLong() const;

Get the long integer property value from the Property object.
Parameters:
None
Returns:
The long integer property value.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getShort – Get Short Integer Property Value

Interface:
xmsSHORT getShort() const;

Get the short integer property value from the Property object.
Parameters:
None
Returns:
The short integer property value.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

350 Message Service Client for C/C++

getString – Get String Property Value
Interface:
String getString() const;

Get the string property value from the Property object.

Parameters:
None
Returns:
A String object encapsulating the string property value. If data conversion
is required, this is the string after conversion.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getTypeId – Get Property Type

Interface:
xmsPROPERTY_TYPE getTypeId() const;

Get the property type from the Property object.

Parameters:
None
Returns:
The property type, which is one of the following values:
XMS_PROPERTY_TYPE_UNKNOWN
XMS_PROPERTY_TYPE_BOOL
XMS_PROPERTY_TYPE_BYTE
XMS_PROPERTY_TYPE_BYTEARRAY
XMS_PROPERTY_TYPE_CHAR
XMS_PROPERTY_TYPE_STRING
XMS_PROPERTY_TYPE_SHORT
XMS_PROPERTY_TYPE_INT
XMS_PROPERTY_TYPE_LONG
XMS_PROPERTY_TYPE_FLOAT
XMS_PROPERTY_TYPE_DOUBLE
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

isNull – Check Whether Null

Interface:
xmsBOOL isNull() const;

Chapter 16. C++ classes 351

 Determine whether the Property object is a null object.
Parameters:
None
Returns:
v xmsTRUE, if the Property object is a null object.
v xmsFALSE, if the Property object is not a null object.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

isTypeId – Check Property Type

Interface:
xmsBOOL isTypeId(const xmsPROPERTY_TYPE propertyType) const;

Check whether the Property object has the specified property type.
Parameters:
propertyType (input)
The property type, which must be one of the following values:
XMS_PROPERTY_TYPE_UNKNOWN
XMS_PROPERTY_TYPE_BOOL
XMS_PROPERTY_TYPE_BYTE
XMS_PROPERTY_TYPE_BYTEARRAY
XMS_PROPERTY_TYPE_CHAR
XMS_PROPERTY_TYPE_STRING
XMS_PROPERTY_TYPE_SHORT
XMS_PROPERTY_TYPE_INT
XMS_PROPERTY_TYPE_LONG
XMS_PROPERTY_TYPE_FLOAT
XMS_PROPERTY_TYPE_DOUBLE
Returns:
v xmsTRUE, if the Property object has the specified property type.
v xmsFALSE, if the Property object does not have the specified property
type.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

name – Get Property Name

Interface:
String name() const;

352 Message Service Client for C/C++

Get the property name from the Property object.
Parameters:
None
Returns:
A String object encapsulating the property name.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setBoolean – Set Boolean Property Value

Interface:
xmsVOID setBoolean(const xmsBOOL propertyValue);

Set a boolean property value in the Property object and set the property type.
Parameters:
propertyValue (input)
The boolean property value.
Returns:
Void
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setByte – Set Byte Property Value

Interface:
xmsVOID setByte(const xmsSBYTE propertyValue);

Set a byte property value in the Property object and set the property type.
Parameters:
propertyValue (input)
The byte property value.
Returns:
Void
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Chapter 16. C++ classes 353

 setByteArray – Set Byte Array Property Value
Interface:
xmsVOID setByteArray(const xmsBYTE *propertyValue,
const xmsINT length);

Set a byte array property value in the Property object and set the property type.
Parameters:
propertyValue (input)
The property value, which is an array of bytes.
length (input)
The length of the property value in bytes.
Returns:
Void
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setChar – Set Character Property Value

Interface:
xmsVOID setChar(const xmsCHAR16 propertyValue);

Set a 2-byte character property value in the Property object and set the property
type.
Parameters:
propertyValue (input)
The 2-byte character property value.
Returns:
Void
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setDouble – Set Double Precision Floating Point Property Value

Interface:
xmsVOID setDouble(const xmsDOUBLE propertyValue);

Set a double precision floating point property value in the Property object and set
the property type.
Parameters:
propertyValue (input)
The double precision floating point property value.

354 Message Service Client for C/C++

Returns:
Void
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setFloat – Set Floating Point Property Value

Interface:
xmsVOID setFloat(const xmsFLOAT propertyValue);

Set a floating point property value in the Property object and set the property type.
Parameters:
propertyValue (input)
The floating point property value.
Returns:
Void
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setInt – Set Integer Property Value

Interface:
xmsVOID setInt(const xmsINT propertyValue);

Set an integer property value in the Property object and set the property type.
Parameters:
propertyValue (input)
The integer property value.
Returns:
Void
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setLong – Set Long Integer Property Value

Interface:
xmsVOID setLong(const xmsLONG propertyValue);

Set a long integer property value in the Property object and set the property type.

Chapter 16. C++ classes 355

 Parameters:
propertyValue (input)
The long integer property value.
Returns:
Void
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setShort – Set Short Integer Property Value

Interface:
xmsVOID setShort(const xmsSHORT propertyValue);

Set a short integer property value in the Property object and set the property type.
Parameters:
propertyValue (input)
The short integer property value.
Returns:
Void
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setString – Set String Property Value

Interface:
xmsVOID setString(const String & propertyValue);

Set a string property value in the Property object and set the property type.
Parameters:
propertyValue (input)
A String object encapsulating the string property value.
Returns:
Void
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

356 Message Service Client for C/C++

PropertyContext
PropertyContext is an abstract superclass that contains methods that get and set
properties. These methods are inherited by other classes.
Inheritance hierarchy:
None

Methods
getBooleanProperty – Get Boolean Property
Interface:
xmsBOOL getBooleanProperty(const String & propertyName) const;

Get the value of the boolean property identified by name.

Parameters:
propertyName (input)
A String object encapsulating the name of the property.
Returns:
The value of the property.
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getByteProperty – Get Byte Property

Interface:
xmsSBYTE getByteProperty(const String & propertyName) const;

Get the value of the byte property identified by name.

Parameters:
propertyName (input)
A String object encapsulating the name of the property.
Returns:
The value of the property.
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getBytesProperty – Get Byte Array Property

Interface:
xmsINT getBytesProperty(const String & propertyName,
xmsSBYTE *propertyValue,
const xmsINT length,
xmsINT *actualLength) const;

Chapter 16. C++ classes 357

 Get the value of the byte array property identified by name.

For more information about how to use this method, see “C++ methods that return
a byte array” on page 72.
Parameters:
propertyName (input)
A String object encapsulating the name of the property.
propertyValue (output)
The buffer to contain the value of the property, which is an array
of bytes.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the array of bytes is not returned, but its length is returned
in the actualLength parameter.
actualLength (output)
The number of bytes in the array. If you specify a null pointer on
input, the length of the array is not returned.
Returns:
The number of bytes in the array.
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getCharProperty – Get Character Property

Interface:
xmsCHAR16 getCharProperty(const String & propertyName) const;

Get the value of the 2-byte character property identified by name.

Parameters:
propertyName (input)
A String object encapsulating the name of the property.
Returns:
The value of the property.
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getDoubleProperty – Get Double Precision Floating Point

Property
Interface:
xmsDOUBLE getDoubleProperty(const String & propertyName) const;

358 Message Service Client for C/C++

Get the value of the double precision floating point property identified by name.
Parameters:
propertyName (input)
A String object encapsulating the name of the property.
Returns:
The value of the property.
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getFloatProperty – Get Floating Point Property

Interface:
xmsFLOAT getFloatProperty(const String & propertyName) const;

Get the value of the floating point property identified by name.

Parameters:
propertyName (input)
A String object encapsulating the name of the property.
Returns:
The value of the property.
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getIntProperty – Get Integer Property

Interface:
xmsINT getIntProperty(const String & propertyName) const;

Get the value of the integer property identified by name.

Parameters:
propertyName (input)
A String object encapsulating the name of the property.
Returns:
The value of the property.
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Chapter 16. C++ classes 359

 getLongProperty – Get Long Integer Property
Interface:
xmsLONG getLongProperty(const String & propertyName) const;

Get the value of the long integer property identified by name.

Parameters:
propertyName (input)
A String object encapsulating the name of the property.
Returns:
The value of the property.
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getObjectProperty – Get Object Property

Interface:
xmsOBJECT_TYPE getObjectProperty(const String & propertyName,
xmsSBYTE *propertyValue,
const xmsINT length,
xmsINT *actualLength);

Get the value and data type of the property identified by name.

For more information about how to use this method, see “C++ methods that return
a byte array” on page 72.
Parameters:
propertyName (input)
A String object encapsulating the name of the property.
propertyValue (output)
The buffer to contain the value of the property, which is returned
as an array of bytes. If the value is a string and data conversion is
required, this is the value after conversion.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the value of the property is not returned, but its length is
returned in the actualLength parameter.
actualLength (output)
The length of the value of the property in bytes. If the value is a
string and data conversion is required, this is the length after
conversion. If you specify a null pointer on input, the length is not
returned.
Returns:
The data type of the value of the property, which is one of the following
object types:
XMS_OBJECT_TYPE_BOOL
XMS_OBJECT_TYPE_BYTE

360 Message Service Client for C/C++

 XMS_OBJECT_TYPE_BYTEARRAY
XMS_OBJECT_TYPE_CHAR
XMS_OBJECT_TYPE_DOUBLE
XMS_OBJECT_TYPE_FLOAT
XMS_OBJECT_TYPE_INT
XMS_OBJECT_TYPE_LONG
XMS_OBJECT_TYPE_SHORT
XMS_OBJECT_TYPE_STRING
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getProperty – Get Property

Interface:
virtual Property getProperty(const String & propertyName) const;

Get a Property object for the property identified by name.

Parameters:
propertyName (input)
A String object encapsulating the name of the property.
Returns:
The Property object.
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getShortProperty – Get Short Integer Property

Interface:
xmsSHORT getShortProperty(const String & propertyName) const;

Get the value of the short integer property identified by name.

Parameters:
propertyName (input)
A String object encapsulating the name of the property.
Returns:
The value of the property.
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Chapter 16. C++ classes 361

 getStringProperty – Get String Property
Interface:
String getStringProperty(const String & propertyName) const;

Get the value of the string property identified by name.

Parameters:
propertyName (input)
A String object encapsulating the name of the property.
Returns:
A String object encapsulating the string that is the value of the property. If
data conversion is required, this is the string after conversion.
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION

setBooleanProperty – Set Boolean Property

Interface:
xmsVOID setBooleanProperty(const String & propertyName,
const xmsBOOL propertyValue);

Set the value of the boolean property identified by name.

Parameters:
propertyName (input)
A String object encapsulating the name of the property.
propertyValue (input)
The value of the property.
Returns:
Void
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

setByteProperty – Set Byte Property

Interface:
xmsVOID setByteProperty(const String & propertyName,
const xmsSBYTE propertyValue);

Set the value of the byte property identified by name.

Parameters:

362 Message Service Client for C/C++

 propertyName (input)
A String object encapsulating the name of the property.
propertyValue (input)
The value of the property.
Returns:
Void
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

setBytesProperty – Set Byte Array Property

Interface:
xmsVOID setBytesProperty(const String & propertyName,
const xmsSBYTE *propertyValue,
const xmsINT length);

Set the value of the byte array property identified by name.

Parameters:
propertyName (input)
A String object encapsulating the name of the property.
propertyValue (input)
The value of the property, which is an array of bytes.
length (input)
The number of bytes in the array.
Returns:
Void
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

setCharProperty – Set Character Property

Interface:
xmsVOID setCharProperty(const String & propertyName,
const xmsCHAR16 propertyValue);

Set the value of the 2-byte character property identified by name.

Parameters:
propertyName (input)
A String object encapsulating the name of the property.

Chapter 16. C++ classes 363

 propertyValue (input)
The value of the property.
Returns:
Void
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

setDoubleProperty – Set Double Precision Floating Point

Property
Interface:
xmsVOID setDoubleProperty(const String & propertyName,
const xmsDOUBLE propertyValue);

Set the value of the double precision floating point property identified by name.
Parameters:
propertyName (input)
A String object encapsulating the name of the property.
propertyValue (input)
The value of the property.
Returns:
Void
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

setFloatProperty – Set Floating Point Property

Interface:
xmsVOID setFloatProperty(const String & propertyName,
const xmsFLOAT propertyValue);

Set the value of the floating point property identified by name.

Parameters:
propertyName (input)
A String object encapsulating the name of the property.
propertyValue (input)
The value of the property.
Returns:
Void

364 Message Service Client for C/C++

Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

setIntProperty – Set Integer Property

Interface:
xmsVOID setIntProperty(const String & propertyName,
const xmsINT propertyValue);

Set the value of the integer property identified by name.

Parameters:
propertyName (input)
A String object encapsulating the name of the property.
propertyValue (input)
The value of the property.
Returns:
Void
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

setLongProperty – Set Long Integer Property

Interface:
xmsVOID setLongProperty(const String & propertyName,
const xmsLONG propertyValue);

Set the value of the long integer property identified by name.

Parameters:
propertyName (input)
A String object encapsulating the name of the property.
propertyValue (input)
The value of the property.
Returns:
Void
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

Chapter 16. C++ classes 365

 setObjectProperty – Set Object Property
Interface:
xmsVOID setObjectProperty(const String & propertyName,
const xmsOBJECT_TYPE objectType,
const xmsSBYTE *propertyValue,
const xmsINT length);

Set the value and data type of a property identified by name.

Parameters:
propertyName (input)
A String object encapsulating the name of the property.
objectType (input)
The data type of the value of the property, which must be one of
the following object types:
XMS_OBJECT_TYPE_BOOL
XMS_OBJECT_TYPE_BYTE
XMS_OBJECT_TYPE_BYTEARRAY
XMS_OBJECT_TYPE_CHAR
XMS_OBJECT_TYPE_DOUBLE
XMS_OBJECT_TYPE_FLOAT
XMS_OBJECT_TYPE_INT
XMS_OBJECT_TYPE_LONG
XMS_OBJECT_TYPE_SHORT
XMS_OBJECT_TYPE_STRING
propertyValue (input)
The value of the property as an array of bytes.
length (input)
The number of bytes in the array.
Returns:
Void
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

setProperty – Set Property

Interface:
virtual xmsVOID setProperty(const Property & property);

Set the value of a property using a Property object.

Parameters:
property (input)
The Property object.

366 Message Service Client for C/C++

Returns:
Void
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

setShortProperty – Set Short Integer Property

Interface:
xmsVOID setShortProperty(const String & propertyName,
const xmsSHORT propertyValue);

Set the value of the short integer property identified by name.

Parameters:
propertyName (input)
A String object encapsulating the name of the property.
propertyValue (input)
The value of the property.
Returns:
Void
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

setStringProperty – Set String Property

Interface:
xmsVOID setStringProperty(const String & propertyName,
const String & propertyValue);

Set the value of the string property identified by name.

Parameters:
propertyName (input)
A String object encapsulating the name of the property.
propertyValue (input)
A String object encapsulating the string that is the value of the
property.
Returns:
Void
Thread context:
Determined by the subclass
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Chapter 16. C++ classes 367

 v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

QueueBrowser
An application uses a queue browser to browse messages on a queue without
removing them.
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::QueueBrowser

Methods
close – Close Queue Browser
Interface:
xmsVOID close();

Close the queue browser.

If an application tries to close a queue browser that is already closed, the call is
ignored.
Parameters:
None
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getEnumeration – Get Messages

Interface:
Iterator getEnumeration() const;

Get a list of the messages on the queue.

The method returns an iterator that encapsulates a list of Message objects. The
order of the Message objects in the list is the same as the order in which the
messages would be retrieved from the queue. The application can then use the
iterator to browse each message in turn.

The iterator is updated dynamically as messages are put on the queue and
removed from the queue. Each time the application calls Iterator.getNext() to
browse the next message on the queue, the message returned reflects the current
contents of the queue.

If an application calls this method more than once for a given queue browser, each
call returns a new iterator. The application can therefore use more than one iterator
to browse the messages on a queue and maintain multiple positions within the
queue.
Parameters:
None

368 Message Service Client for C/C++

Returns:
The Iterator object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getHandle – Get Handle

Interface:
xmsHQueueBrowser getHandle() const;

Get the handle that a C application would use to access the queue browser.
Parameters:
None
Returns:
The handle for the queue browser.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getMessageSelector – Get Message Selector

Interface:
String getMessageSelector() const;

Get the message selector for the queue browser.

Parameters:
None
Returns:
A String object encapsulating the message selector expression. If data
conversion is required, this is the message selector expression after
conversion. If the queue browser does not have a message selector, the
method returns a null String object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getQueue – Get Queue

Interface:
Destination getQueue() const;

Get the queue associated with the queue browser.

Parameters:
None
Returns:
A Destination object representing the queue.

Chapter 16. C++ classes 369

 Exceptions:
v XMS_X_GENERAL_EXCEPTION

isNull – Check Whether Null

Interface:
xmsBOOL isNull() const;

Determine whether the QueueBrowser object is a null object.

Parameters:
None
Returns:
v xmsTRUE, if the QueueBrowser object is a null object.
v xmsFALSE, if the QueueBrowser object is not a null object.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Inherited methods
The following methods are inherited from the PropertyContext class:
getBooleanProperty, getByteProperty, getBytesProperty, getCharProperty,
getDoubleProperty, getFloatProperty, getIntProperty, getLongProperty,
getObjectProperty, getProperty, getShortProperty, getStringProperty,
setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty,
setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty,
setObjectProperty, setProperty, setShortProperty, setStringProperty

Requestor
An application uses a requestor to send a request message and then wait for, and
receive, the reply.
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::Requestor

Constructors
Requestor – Create Requestor
Interface:
Requestor(const Session & session,
const Destination & destination);

Create a requestor.
Parameters:

370 Message Service Client for C/C++

 session (input)
A Session object. The session must not be transacted and must
have one of the following acknowledgement modes:
XMSC_AUTO_ACKNOWLEDGE
XMSC_DUPS_OK_ACKNOWLEDGE
destination (input)
A Destination object representing the destination where the
application can send request messages.
Thread context:
The session associated with the requestor
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Methods
close – Close Requestor
Interface:
xmsVOID close();

Close the requestor.

If an application tries to close a requestor that is already closed, the call is ignored.

Note: When an application closes a requestor, the associated session does not close
as well. In this respect, XMS behaves differently compared to JMS.
Parameters:
None
Returns:
Void
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getHandle – Get Handle

Interface:
xmsHRequestor getHandle() const;

Get the handle that a C application would use to access the requestor.
Parameters:
None
Returns:
The handle for the requestor.
Thread context:
Any
Exceptions:

Chapter 16. C++ classes 371

 v XMS_X_GENERAL_EXCEPTION

isNull – Check Whether Null

Interface:
xmsBOOL isNull() const;

Determine whether the Requestor object is a null object.

Parameters:
None
Returns:
v xmsTRUE, if the Requestor object is a null object.
v xmsFALSE, if the Requestor object is not a null object.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

request – Request
Interface:
Message * request(const Message & requestMessage) const;

Send a request message and then wait for, and receive, a reply from the application
that receives the request message.

A call to this method blocks until a reply is received or until the session ends,
whichever is the sooner.
Parameters:
requestMessage (input)
The Message object encapsulating the request message.
Returns:
A pointer to the Message object encapsulating the reply message.
Thread context:
The session associated with the requestor
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Inherited methods
The following methods are inherited from the PropertyContext class:
getBooleanProperty, getByteProperty, getBytesProperty, getCharProperty,
getDoubleProperty, getFloatProperty, getIntProperty, getLongProperty,
getObjectProperty, getProperty, getShortProperty, getStringProperty,
setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty,
setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty,
setObjectProperty, setProperty, setShortProperty, setStringProperty

372 Message Service Client for C/C++

ResourceAllocationException
XMS throws this exception if XMS cannot allocate the resources required by a
method.
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::ResourceAllocationException

Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull

SecurityException
XMS throws this exception if the user identifer and password provided to
authenticate an application are rejected. XMS also throws this exception if an
authority check fails and prevents a method from completing.
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::SecurityException

Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull

Session
A session is a single threaded context for sending and receiving messages.
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::Session

For a list of the XMS defined properties of a Session object, see “Properties of
Session” on page 416.

Methods
close – Close Session
Interface:
xmsVOID close();

Chapter 16. C++ classes 373

 Close the session. If the session is transacted, any transaction in progress is rolled
back.

All objects dependent on the session are deleted. For information about which
objects are deleted, see “Object Deletion” on page 51.

If an application tries to close a session that is already closed, the call is ignored.
Parameters:
None
Returns:
Void
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

commit – Commit
Interface:
xmsVOID commit();

Commit all messages processed in the current transaction.

The session must be a transacted session.

Parameters:
None
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_ILLEGAL_STATE_EXCEPTION
v XMS_X_TRANSACTION_ROLLED_BACK_EXCEPTION

createBrowser – Create Queue Browser

Interface:
QueueBrowser createBrowser(const Destination & queue) const;

Create a queue browser for the specified queue.

Parameters:
queue (input)
A Destination object representing the queue.
Returns:
The QueueBrowser object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

374 Message Service Client for C/C++

 v XMS_X_INVALID_DESTINATION_EXCEPTION

createBrowser – Create Queue Browser (with message selector)

Interface:
QueueBrowser createBrowser(const Destination & queue
const String & messageSelector) const;

Create a queue browser for the specified queue using a message selector.
Parameters:
queue (input)
A Destination object representing the queue.
messageSelector (input)
A String object encapsulating a message selector expression. Only
those messages with properties that match the message selector
expression are delivered to the queue browser.
A null String object means that there is no message selector for the
queue browser.
Returns:
The QueueBrowser object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION
v XMS_X_INVALID_SELECTOR_EXCEPTION

createBytesMessage – Create Bytes Message

Interface:
BytesMessage createBytesMessage() const;

Create a bytes message.

Parameters:
None
Returns:
The BytesMessage object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

createConsumer – Create Consumer

Interface:
MessageConsumer createConsumer(const Destination & destination) const;

Create a message consumer for the specified destination.

Parameters:

Chapter 16. C++ classes 375

 destination (input)
The Destination object.
Returns:
The MessageConsumer object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION

createConsumer – Create Consumer (with message selector)

Interface:
MessageConsumer createConsumer(const Destination & destination,
const String & messageSelector) const;

Create a message consumer for the specified destination using a message selector.
Parameters:
destination (input)
The Destination object.
messageSelector (input)
A String object encapsulating a message selector expression. Only
those messages with properties that match the message selector
expression are delivered to the message consumer.
A null String object means that there is no message selector for the
message consumer.
Returns:
The MessageConsumer object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION
v XMS_X_INVALID_SELECTOR_EXCEPTION

createConsumer – Create Consumer (with message selector and

local message flag)
Interface:
MessageConsumer createConsumer(const Destination & destination,
const String & messageSelector,
const xmsBOOL noLocal) const;

Create a message consumer for the specified destination using a message selector
and, if the destination is a topic, specifying whether the message consumer
receives the messages published by its own connection.
Parameters:
destination (input)
The Destination object.
messageSelector (input)
A String object encapsulating a message selector expression. Only

376 Message Service Client for C/C++

 those messages with properties that match the message selector
expression are delivered to the message consumer.
A null String object means that there is no message selector for the
message consumer.
noLocal (input)
The value xmsTRUE means that the message consumer does not
receive the messages published by its own connection. The value
xmsFALSE means that the message consumer does receive the
messages published by its own connection. The default value is
xmsFALSE.
Returns:
The MessageConsumer object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION
v XMS_X_INVALID_SELECTOR_EXCEPTION

createDurableSubscriber – Create Durable Subscriber

Interface:
MessageConsumer
createDurableSubscriber(const Destination & topic,
const String & subscriptionName) const;

Create a durable subscriber for the specified topic.

This method is not valid for a real-time connection to a broker.

For more information about durable subscribers, see “Durable subscribers” on page
46.
Parameters:
topic (input)
A Destination object representing the topic. The topic must not be a
temporary topic.
subscriptionName (input)
A String object encapsulating a name that identifies the durable
subscription. The name must be unique within the client identifier
for the connection.
Returns:
The MessageConsumer object representing the durable subscriber.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION

createDurableSubscriber – Create Durable Subscriber (with

message selector and local message flag)
Interface:

Chapter 16. C++ classes 377

 MessageConsumer createDurableSubscriber(const Destination & topic,
const String & subscriptionName;
const String & messageSelector,
const xmsBOOL noLocal) const;

Create a durable subscriber for the specified topic using a message selector and
specifying whether the durable subscriber receives the messages published by its
own connection.

This method is not valid for a real-time connection to a broker.

For more information about durable subscribers, see “Durable subscribers” on page
46.
Parameters:
topic (input)
A Destination object representing the topic. The topic must not be a
temporary topic.
subscriptionName (input)
A String object encapsulating a name that identifies the durable
subscription. The name must be unique within the client identifier
for the connection.
messageSelector (input)
A String object encapsulating a message selector expression. Only
those messages with properties that match the message selector
expression are delivered to the durable subscriber.
A null String object means that there is no message selector for the
durable subscriber.
noLocal (input)
The value xmsTRUE means that the durable subscriber does not
receive the messages published by its own connection. The value
xmsFALSE means that the durable subscriber does receive the
messages published by its own connection. The default value is
xmsFALSE.
Returns:
The MessageConsumer object representing the durable subscriber.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION
v XMS_X_INVALID_SELECTOR_EXCEPTION

createMapMessage – Create Map Message

Interface:
MapMessage createMapMessage() const;

Create a map message.

Parameters:
None

378 Message Service Client for C/C++

Returns:
The MapMessage object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

createMessage – Create Message

Interface:
Message createMessage() const;

Create a message that has no body.

Parameters:
None
Returns:
The Message object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

createObjectMessage – Create Object Message

Interface:
ObjectMessage createObjectMessage() const;

Create an object message.

Parameters:
None
Returns:
The ObjectMessage object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

createProducer – Create Producer

Interface:
MessageProducer createProducer(const Destination & destination) const;

Create a message producer to send messages to the specified destination.

Parameters:
destination (input)
The Destination object.
If you specify a null Destination object, the message producer is
created without a destination. In this case, the application must
specify a destination every time it uses the message producer to
send a message.

Chapter 16. C++ classes 379

 Returns:
The MessageProducer object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION

createQueue – Create Queue

Interface:
Destination createQueue(const String & queueName) const;

Create a Destination object to represent a queue in the messaging server.

This method does not create the queue in the messaging server. You must create
the queue before an application can call this method.
Parameters:
queueName (input)
A String object encapsulating the name of the queue, or
encapsulating a uniform resource identifier (URI) that identifies the
queue.
Returns:
The Destination object representing the queue.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

createStreamMessage – Create Stream Message

Interface:
StreamMessage createStreamMessage() const;

Create a stream message.

Parameters:
None
Returns:
The StreamMessage object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

createTemporaryQueue – Create Temporary Queue

Interface:
Destination createTemporaryQueue() const;

Create a temporary queue.

The scope of the temporary queue is the connection. Only the sessions created by
the connection can use the temporary queue.

380 Message Service Client for C/C++

The temporary queue remains until it is explicitly deleted, or the connection ends,
whichever is the sooner.

For more information about temporary queues, see “Temporary destinations” on

page 45.
Parameters:
None
Returns:
The Destination object representing the temporary queue.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

createTemporaryTopic – Create Temporary Topic

Interface:
Destination createTemporaryTopic() const;

Create a temporary topic.

The scope of the temporary topic is the connection. Only the sessions created by
the connection can use the temporary topic.

The temporary topic remains until it is explicitly deleted, or the connection ends,
whichever is the sooner.

For more information about temporary topics, see “Temporary destinations” on

page 45.
Parameters:
None
Returns:
The Destination object representing the temporary topic.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

createTextMessage – Create Text Message

Interface:
TextMessage createTextMessage() const;

Create a text message with an empty body.

Parameters:
None
Returns:
The TextMessage object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Chapter 16. C++ classes 381

 createTextMessage – Create Text Message (initialized)
Interface:
TextMessage createTextMessage(const String & text) const;

Create a text message whose body is initialized with the specified text.
Parameters:
text (input)
A String object encapsulating the text to initialize the body of the
text message.

None
Returns:
The TextMessage object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

createTopic – Create Topic

Interface:
Destination createTopic(const String & topicName) const;

Create a Destination object to represent a topic.

Parameters:
topicName (input)
A String object encapsulating the name of the topic, or
encapsulating a uniform resource identifier (URI) that identifies the
topic.
Returns:
The Destination object representing the topic.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getAcknowledgeMode – Get Acknowledgement Mode

Interface:
xmsINT getAcknowledgeMode() const;

Get the acknowledgement mode for the session. The acknowledgement mode is
specified when the session is created.

A session that is transacted has no acknowledgement mode.

For more information about acknowledgement modes, see “Message

acknowledgement” on page 39.
Parameters:
None

382 Message Service Client for C/C++

Returns:
The acknowledgement mode. Provided the session is not transacted, the
acknowledgement mode is one of the following values:
XMSC_AUTO_ACKNOWLEDGE
XMSC_CLIENT_ACKNOWLEDGE
XMSC_DUPS_OK_ACKNOWLEDGE
If the session is transacted, the method returns XMSC_SESSION_TRANSACTED
instead.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getHandle – Get Handle

Interface:
xmsHSess getHandle() const;

Get the handle that a C application would use to access the session.
Parameters:
None
Returns:
The handle for the session.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

getTransacted – Determine Whether Transacted

Interface:
xmsBOOL getTransacted() const;

Determine whether the session is transacted.

Parameters:
None
Returns:
v xmsTRUE, if the session is transacted.
v xmsFALSE, if the session is not transacted.
For a real-time connection to a broker, the method always returns
xmsFALSE.
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Chapter 16. C++ classes 383

 isNull – Check Whether Null
Interface:
xmsBOOL isNull() const;

Determine whether the Session object is a null object.

Parameters:
None
Returns:
v xmsTRUE, if the Session object is a null object.
v xmsFALSE, if the Session object is not a null object.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

recover – Recover
Interface:
xmsVOID recover() const;

Recover the session. Message delivery is stopped and then restarted with the
oldest unacknowledged message.

The session must not be a transacted session.

For more information about recovering a session, see “Message acknowledgement”

on page 39.
Parameters:
None
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_ILLEGAL_STATE_EXCEPTION

rollback – Rollback
Interface:
xmsVOID rollback() const;

Rollback all messages processed in the current transaction.

The session must be a transacted session.

Parameters:
None
Returns:
Void

384 Message Service Client for C/C++

 Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_ILLEGAL_STATE_EXCEPTION

unsubscribe – Unsubscribe
Interface:
xmsVOID unsubscribe(const String & subscriptionName) const;

Delete a durable subscription. The messaging server deletes the record of the
durable subscription that it is maintaining and does not send any more messages
to the durable subscriber.

An application cannot delete a durable subscription in any of the following

circumstances:
v While there is an active message consumer for the durable subscription
v While a consumed message is part of a pending transaction
v While a consumed message has not been acknowledged

This method is not valid for a real-time connection to a broker.

Parameters:
subscriptionName (input)
A String object encapsulating the name that identifies the durable
subscription.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_INVALID_DESTINATION_EXCEPTION
v XMS_X_ILLEGAL_STATE_EXCEPTION

Inherited methods
The following methods are inherited from the PropertyContext class:
getBooleanProperty, getByteProperty, getBytesProperty, getCharProperty,
getDoubleProperty, getFloatProperty, getIntProperty, getLongProperty,
getObjectProperty, getProperty, getShortProperty, getStringProperty,
setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty,
setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty,
setObjectProperty, setProperty, setShortProperty, setStringProperty

StreamMessage
A stream message is a message whose body comprises a stream of values, where
each value has an associated data type.
Inheritance hierarchy:

Chapter 16. C++ classes 385

 xms::PropertyContext
|
+----xms::Message
|
+----xms::StreamMessage

The contents of the body are written and read sequentially.

When an application reads a value from the message stream, the value can be
converted by XMS into another data type. For more information about this form of
implicit conversion, see “Stream messages” on page 105.

Methods
readBoolean – Read Boolean Value
Interface:
xmsBOOL readBoolean() const;

Read a boolean value from the message stream.

Parameters:
None
Returns:
The boolean value that is read.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

readByte – Read Byte

Interface:
xmsSBYTE readByte() const;

Read a signed 8-bit integer from the message stream.

Parameters:
None
Returns:
The byte that is read.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

readBytes – Read Bytes

Interface:
xmsINT readBytes(xmsSBYTE *buffer,
const xmsINT bufferLength,
xmsINT *returnedLength) const;

386 Message Service Client for C/C++

Read an array of bytes from the message stream.
Parameters:
buffer (output)
The buffer to contain the array of bytes that is read.
If the number of bytes in the array is less than or equal to the
length of the buffer, the whole array is read into the buffer. If the
number of bytes in the array is greater than the length of the
buffer, the buffer is filled with part of the array, and an internal
cursor marks the position of the next byte to be read. A subsequent
call to readBytes() reads bytes from the array starting from the
current position of the cursor.
If you specify a null pointer on input, the call skips over the array
of bytes without reading it.
bufferLength (input)
The length of the buffer in bytes.
returnedLength (output)
The number of bytes that are read into the buffer. If the buffer is
partially filled, the value is less than the length of the buffer,
indicating that there are no more bytes in the array remaining to be
read. If there are no bytes remaining to be read from the array
before the call, the value is XMSC_END_OF_BYTEARRAY.
If you specify a null pointer on input, the method returns no value.
Returns:
See the description of the returnedLength parameter.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

readChar – Read Character

Interface:
xmsCHAR16 readChar() const;

Read a 2-byte character from the message stream.

Parameters:
None
Returns:
The character that is read.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

Chapter 16. C++ classes 387

 readDouble – Read Double Precision Floating Point Number
Interface:
xmsDOUBLE readDouble() const;

Read an 8-byte double precision floating point number from the message stream.
Parameters:
None
Returns:
The double precision floating point number that is read.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

readFloat – Read Floating Point Number

Interface:
xmsFLOAT readFloat() const;

Read a 4-byte floating point number from the message stream.

Parameters:
None
Returns:
The floating point number that is read.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

readInt – Read Integer

Interface:
xmsINT readInt() const;

Read a signed 32-bit integer from the message stream.

Parameters:
None
Returns:
The integer that is read.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

388 Message Service Client for C/C++

readLong – Read Long Integer
Interface:
xmsLONG readLong() const;

Read a signed 64-bit integer from the message stream.

Parameters:
None
Returns:
The long integer that is read.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

readObject – Read Object

Interface:
xmsOBJECT_TYPE readObject(xmsSBYTE *buffer,
const xmsINT bufferLength,
xmsINT *actualLength) const;

Read a value from the message stream, and return its data type.

For more information about how to use this method, see “C++ methods that return
a byte array” on page 72.
Parameters:
buffer (output)
The buffer to contain the value, which is returned as an array of
bytes. If the value is a string and data conversion is required, this
is the value after conversion.
If you specify a null pointer on input, the call skips over the value
without reading it.
bufferLength (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the value is not returned, but its length is returned in the
actualLength parameter.
actualLength (output)
The length of the value in bytes. If the value is a string and data
conversion is required, this is the length after conversion. If you
specify a null pointer on input, the length is not returned.
Returns:
The data type of the value, which is one of the following object types:
XMS_OBJECT_TYPE_BOOL
XMS_OBJECT_TYPE_BYTE
XMS_OBJECT_TYPE_BYTEARRAY
XMS_OBJECT_TYPE_CHAR
XMS_OBJECT_TYPE_DOUBLE

Chapter 16. C++ classes 389

 XMS_OBJECT_TYPE_FLOAT
XMS_OBJECT_TYPE_INT
XMS_OBJECT_TYPE_LONG
XMS_OBJECT_TYPE_SHORT
XMS_OBJECT_TYPE_STRING
Exceptions:
XMS_X_GENERAL_EXCEPTION

readShort – Read Short Integer

Interface:
xmsSHORT readShort() const;

Read a signed 16-bit integer from the message stream.

Parameters:
None
Returns:
The short integer that is read.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

readString – Read String

Interface:
String readString() const;

Read a string from the message stream. If required, XMS converts the characters in
the string into the local code page.
Parameters:
None
Returns:
A String object encapsulating the string that is read. If data conversion is
required, this is the string after conversion.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

reset – Reset
Interface:
xmsVOID reset() const;

390 Message Service Client for C/C++

Put the body of the message into read-only mode and reposition the cursor at the
beginning of the message stream.
Parameters:
None
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

writeBoolean – Write Boolean Value

Interface:
xmsVOID writeBoolean(const xmsBOOL value);

Write a boolean value to the message stream.

Parameters:
value (input)
The boolean value to be written.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeByte – Write Byte

Interface:
xmsVOID writeByte(const xmsSBYTE value);

Write a byte to the message stream.

Parameters:
value (input)
The byte to be written.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeBytes – Write Bytes

Interface:

Chapter 16. C++ classes 391

 xmsVOID writeBytes(const xmsSBYTE *value,
const xmsINT length);

Write an array of bytes to the message stream.

Parameters:
value (input)
The array of bytes to be written.
length (input)
The number of bytes in the array.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeChar – Write Character

Interface:
xmsVOID writeChar(const xmsCHAR16 value);

Write a character to the message stream as 2 bytes, high order byte first.
Parameters:
value (input)
The character to be written.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeDouble – Write Double Precision Floating Point Number

Interface:
xmsVOID writeDouble(const xmsDOUBLE value);

Convert a double precision floating point number to a long integer and write the
long integer to the message stream as 8 bytes, high order byte first.
Parameters:
value (input)
The double precision floating point number to be written.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

392 Message Service Client for C/C++

writeFloat – Write Floating Point Number
Interface:
xmsVOID writeFloat(const xmsFLOAT value);

Convert a floating point number to an integer and write the integer to the message
stream as 4 bytes, high order byte first.
Parameters:
value (input)
The floating point number to be written.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeInt – Write Integer

Interface:
xmsVOID writeInt(const xmsINT value);

Write an integer to the message stream as 4 bytes, high order byte first.
Parameters:
value (input)
The integer to be written.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeLong – Write Long Integer

Interface:
xmsVOID writeLong(const xmsLONG value);

Write a long integer to the message stream as 8 bytes, high order byte first.
Parameters:
value (input)
The long integer to be written.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Chapter 16. C++ classes 393

 v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeObject – Write Object

Interface:
xmsVOID writeObject(const xmsOBJECT_TYPE objectType,
const xmsSBYTE *value,
const xmsINT length);

Write a value, with a specified data type, to the message stream.

Parameters:
objectType (input)
The data type of the value, which must be one of the following
object types:
XMS_OBJECT_TYPE_BOOL
XMS_OBJECT_TYPE_BYTE
XMS_OBJECT_TYPE_BYTEARRAY
XMS_OBJECT_TYPE_CHAR
XMS_OBJECT_TYPE_DOUBLE
XMS_OBJECT_TYPE_FLOAT
XMS_OBJECT_TYPE_INT
XMS_OBJECT_TYPE_LONG
XMS_OBJECT_TYPE_SHORT
XMS_OBJECT_TYPE_STRING
value (input)
An array of bytes containing the value to be written.
length (input)
The number of bytes in the array.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION

writeShort – Write Short Integer

Interface:
xmsVOID writeShort(const xmsSHORT value);

Write a short integer to the message stream as 2 bytes, high order byte first.
Parameters:
value (input)
The short integer to be written.
Returns:
Void
Exceptions:

394 Message Service Client for C/C++

 v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

writeString – Write String

Interface:
xmsVOID writeString(const String & value);

Write a string to the message stream.

Parameters:
value (input)
A String object encapsulating the string to be written.
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

Inherited methods
The following methods are inherited from the Message class:
clearBody, clearProperties, getHandle,
getJMSCorrelationID,getJMSDeliveryMode, getJMSDestination,
getJMSExpiration, getJMSMessageID, getJMSPriority, getJMSRedelivered,
getJMSReplyTo, getJMSTimestamp, getJMSType, getProperties, isNull,
propertyExists, setJMSCorrelationID, setJMSDeliveryMode, setJMSDestination,
setJMSExpiration, setJMSMessageID, setJMSPriority, setJMSRedelivered,
setJMSReplyTo, setJMSTimestamp, setJMSType

The following methods are inherited from the PropertyContext class:

getBooleanProperty, getByteProperty, getBytesProperty, getCharProperty,
getDoubleProperty, getFloatProperty, getIntProperty, getLongProperty,
getObjectProperty, getProperty, getShortProperty, getStringProperty,
setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty,
setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty,
setObjectProperty, setProperty, setShortProperty, setStringProperty

String
A String object encapsulates a string. This class is a helper class.
Inheritance hierarchy:
None

Constructors
String – Create String
Interface:
String();

Create a String object that encapsulates a null string.

Chapter 16. C++ classes 395

 Parameters:
None
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

String – Create String (from a byte array)

Interface:
String(const xmsSBYTE *value,
const xmsINT length);

Create a String object from an array of bytes.

Parameters:
value (input)
The array of bytes that is copied to form the string encapsulated by
the String object.
length (input)
The number of bytes in the array.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

String – Create String (from a character array)

Interface:
String(const xmsCHAR *value);

Create a String object from an array of characters.

Parameters:
value (input)
The null terminated array of characters that is copied to form the
string encapsulated by the String object.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

Methods
~String – Delete String
Interface:
virtual ~String();

396 Message Service Client for C/C++

Delete the String object.
Parameters:
None
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

c_str – Get Pointer to String

Interface:
xmsCHAR * c_str() const;

Get a pointer to the string encapsulated by the String object.

Parameters:
None
Returns:
A pointer to the string encapsulated by the String object.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

concatenate – Concatenate Strings

Interface:
String & concatenate(const String & string) const;

Concatenate the string encapsulated by the String object with the string
encapsulated by a second String object.
Parameters:
string (input)
The second String object.
Returns:
The original String object encapsulating the concatenated strings.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

equalTo – Compare Strings

Interface:
xmsBOOL equalTo(const String & string) const;

Chapter 16. C++ classes 397

 Determine whether the string encapsulated by the String object is equal to the
string encapsulated by a second String object.
Parameters:
string (input)
The second String object.
Returns:
v xmsTRUE, if the two strings are equal.
v xmsFALSE, if the two strings are not equal.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

get – Get String

Interface:
xmsVOID get(xmsSBYTE *value,
const xmsINT length,
xmsINT *actualLength) const;

Get the string encapsulated by the String object.

For more information about how to use this method, see “C++ methods that return
a byte array” on page 72.
Parameters:
value (output)
The buffer to contain the string.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE
instead, the string is not returned, but its length is returned in the
actualLength parameter.
actualLength (output)
The length of the string in bytes. If you specify a null pointer on
input, the length is not returned.
Returns:
Void
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

isNull – Check Whether Null

Interface:
xmsBOOL isNull() const;

398 Message Service Client for C/C++

 Determine whether the String object is a null object.
Parameters:
None
Returns:
v xmsTRUE, if the String object is a null object.
v xmsFALSE, if the String object is not a null object.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION

TextMessage
A text message is a message whose body comprises a string.
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::Message
|
+----xms::TextMessage

Methods
getText – get Text
Interface:
String getText() const;

Get the string that forms the body of the text message. If required, XMS converts
the characters in the string into the local code page.
Parameters:
None
Returns:
A String object encapsulating the string that is read. If data conversion is
required, this is the string after conversion.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_EXCEPTION

setText – Set Text

Interface:
xmsVOID setText(const String & value);

Set the string that forms the body of the text message.
Parameters:
value (input)
A String object encapsulating the string to be set.

Chapter 16. C++ classes 399

 Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

Inherited methods
The following methods are inherited from the Message class:
clearBody, clearProperties, getHandle,
getJMSCorrelationID,getJMSDeliveryMode, getJMSDestination,
getJMSExpiration, getJMSMessageID, getJMSPriority, getJMSRedelivered,
getJMSReplyTo, getJMSTimestamp, getJMSType, getProperties, isNull,
propertyExists, setJMSCorrelationID, setJMSDeliveryMode, setJMSDestination,
setJMSExpiration, setJMSMessageID, setJMSPriority, setJMSRedelivered,
setJMSReplyTo, setJMSTimestamp, setJMSType

The following methods are inherited from the PropertyContext class:

getBooleanProperty, getByteProperty, getBytesProperty, getCharProperty,
getDoubleProperty, getFloatProperty, getIntProperty, getLongProperty,
getObjectProperty, getProperty, getShortProperty, getStringProperty,
setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty,
setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty,
setObjectProperty, setProperty, setShortProperty, setStringProperty

TransactionInProgressException
XMS throws this exception if an application requests an operation that is not valid
because a transaction is in progress.
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::TransactionInProgressException

Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull

TransactionRolledBackException
XMS throws this exception if an application calls Session.commit() to commit the
current transaction, but the transaction is subsequently rolled back.
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::TransactionRolledBackException

400 Message Service Client for C/C++

Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull

Chapter 16. C++ classes 401

402 Message Service Client for C/C++
Chapter 17. Properties of XMS objects
This chapter documents the object properties defined by XMS.

The chapter contains the following sections:

v “Properties of Connection”
v “Properties of ConnectionFactory” on page 404
v “Properties of ConnectionMetaData” on page 408
v “Properties of Destination” on page 409
v “Properties of InitialContext” on page 410
v “Properties of Message” on page 410
v “Properties of MessageConsumer” on page 415
v “Properties of MessageProducer” on page 416
v “Properties of Session” on page 416
Each section lists the properties of an object of the specified type and provides a
short description of each property.

This chapter also contains the following section:

v “Property definitions” on page 416
which provides a definition of each property.

If an application defines its own properties of the objects discussed in this chapter,
it does not cause an error, but it might cause unpredictable results.

Properties of Connection
An overview of the properties of the Connection object, with links to more detailed
reference information.
Table 34. Properties of Connection
Name of property Description
XMSC_CLIENT_CCSID The identifier (CCSID) of the coded character set, or code
page, used by a connection, session, message producer, or
message consumer.
XMSC_WPM_CONNECTION_PROTOCOL The communications protocol used for the connection to the
messaging engine. This property is read-only.
XMSC_WPM_HOST_NAME The host name or IP address of the system that contains the
messaging engine to which the application is connected. This
property is read-only.
XMSC_WPM_ME_NAME The name of the messaging engine to which the application is
connected. This property is read-only.
XMSC_WPM_PORT The number of the port listened on by the messaging engine
to which the application is connected. This property is
read-only.

A Connection object also has read-only properties that are derived from the
properties of the connection factory that was used to create the connection. These

© Copyright IBM Corp. 2005, 2009 403

 properties are derived not only from the connection factory properties that were
set at the time the connection was created, but also from the default values of the
properties that were not set. The properties include only those that are relevant for
the type of messaging server that the application is connected to. The names of the
properties are the same as the names of the connection factory properties.

Properties of ConnectionFactory
An overview of the properties of the ConnectionFactory object, with links to more
detailed reference information.
Table 35. Properties of ConnectionFactory
Name of property Description
XMSC_ASYNC_EXCEPTIONS This property determines whether XMS informs an
ExceptionListener only when a connection is broken, or when
any exception occurs asynchronously to a XMS API call. This
applies to all Connections created from this
ConnectionFactory that have an ExceptionListener registered.
XMSC_CLIENT_CCSID The identifier (CCSID) of the coded character set, or code
page, used by a connection, session, message producer, or
message consumer.
XMSC_CLIENT_ID The client identifier for a connection.
XMSC_CONNECTION_TYPE The type of messaging server to which an application
connects.
XMSC_PASSWORD A password that can be used to authenticate the application
when it attempts to connect to a messaging server.
XMSC_RTT_CONNECTION_PROTOCOL The communications protocol used for a real-time connection
to a broker.
XMSC_RTT_HOST_NAME The host name or IP address of the system on which a broker
resides.
XMSC_RTT_LOCAL_ADDRESS The host name or IP address of the local network interface to
be used for a real-time connection to a broker.
XMSC_RTT_MULTICAST The multicast setting for a connection factory or destination.
XMSC_RTT_PORT The number of the port on which a broker listens for
incoming requests.
XMSC_USERID A user identifier that can be used to authenticate the
application when it attempts to connect to a messaging server.
XMSC_WMQ_BROKER_CONTROLQ The name of the control queue used by a broker.
Note: This property has no effect for an application
connected to a WebSphere MQ V7.0 and above queue
manager unless the XMSC_WMQ_PROVIDER_VERSION
property of the connection factory is set to a version number
less than 7.
XMSC_WMQ_BROKER_PUBQ The name of the queue monitored by a broker where
applications send messages that they publish.
Note: This property has no effect for an application
connected to a WebSphere MQ V7.0 and above queue
manager unless the XMSC_WMQ_PROVIDER_VERSION
property of the connection factory is set to a version number
less than 7.

404 Message Service Client for C/C++

Table 35. Properties of ConnectionFactory (continued)
Name of property Description
XMSC_WMQ_BROKER_QMGR The name of the queue manager to which a broker is
connected.
Note: This property has no effect for an application
connected to a WebSphere MQ V7.0 and above queue
manager unless the XMSC_WMQ_PROVIDER_VERSION
property of the connection factory is set to a version number
less than 7.
XMSC_WMQ_BROKER_SUBQ The name of the subscriber queue for a nondurable message
consumer.
Note: This property has no effect for an application
connected to a WebSphere MQ V7.0 and above queue
manager unless the XMSC_WMQ_PROVIDER_VERSION
property of the connection factory is set to a version number
less than 7.
XMSC_WMQ_BROKER_VERSION The type of broker used by the application for a connection or
for the destination.
Note: This property has no effect for an application
connected to a WebSphere MQ V7.0 and above queue
manager unless the XMSC_WMQ_PROVIDER_VERSION
property of the connection factory is set to a version number
less than 7.
XMSC_WMQ_CHANNEL The name of the channel to be used for a connection.
XMSC_WMQ_CONNECTION_MODE The mode by which an application connects to a queue
manager.
XMSC_WMQ_FAIL_IF_QUIESCE Whether calls to certain methods fail if the queue manager to
which the application is connected is in a quiescing state.
XMSC_WMQ_HOST_NAME The host name or IP address of the system on which a queue
manager resides.
XMSC_WMQ_LOCAL_ADDRESS For a connection to a queue manager, this property specifies
the local network interface to be used, or the local port or
range of local ports to be used, or both.
XMSC_WMQ_MESSAGE_SELECTION Determines whether message selection is done by the XMS
client or by the broker.
Note: This property has no effect for an application
connected to a WebSphere MQ V7.0 and above queue
manager unless the XMSC_WMQ_PROVIDER_VERSION
property of the connection factory is set to a version number
less than 7.
XMSC_WMQ_MSG_BATCH_SIZE The maximum number of messages to be retrieved from a
queue in one batch when using asynchronous message
delivery.
Note: This property has no effect for an application
connected to a WebSphere MQ V7.0 and above queue
manager unless the XMSC_WMQ_PROVIDER_VERSION
property of the connection factory is set to a version number
less than 7.

Chapter 17. Properties of XMS objects 405

Table 35. Properties of ConnectionFactory (continued)
Name of property Description
XMSC_WMQ_POLLING_INTERVAL If each message listener within a session has no suitable
message on its queue, this is the maximum interval, in
milliseconds, that elapses before each message listener tries
again to get a message from its queue.
Note: This property has no effect for an application
connected to a WebSphere MQ V7.0 and above queue
manager unless the XMSC_WMQ_PROVIDER_VERSION
property of the connection factory is set to a version number
less than 7.
XMSC_WMQ_PORT The number of the port on which a queue manager listens for
incoming requests.
XMSC_WMQ_PROVIDER_VERSION The version, release, modification level and fix pack of the
queue manager to which the application intends to connect.
XMSC_WMQ_PUB_ACK_INTERVAL The number of messages published by a publisher before the
XMS client requests an acknowledgement from the broker.
Note: This property has no effect for an application
connected to a WebSphere MQ V7.0 and above queue
manager unless the XMSC_WMQ_PROVIDER_VERSION
property of the connection factory is set to a version number
less than 7.
XMSC_WMQ_QMGR_CCSID The identifier (CCSID) of the coded character set, or code
page, in which fields of character data defined in the Message
Queue Interface (MQI) are exchanged between the XMS client
and the WebSphere MQ client.
XMSC_WMQ_QUEUE_MANAGER The name of the queue manager to connect to.
XMSC_WMQ_RECEIVE_EXIT Identifies a channel receive exit, or a sequence of channel
receive exits, to be run in succession.
XMSC_WMQ_RECEIVE_EXIT_INIT The user data that is passed to channel receive exits when
they are called.
XMSC_WMQ_SECURITY_EXIT Identifies a channel security exit.
XMSC_WMQ_SECURITY_EXIT_INIT The user data that is passed to a channel security exit when it
is called.
XMSC_WMQ_SEND_EXIT Identifies a channel send exit, or a sequence of channel send
exits, to be run in succession.
XMSC_WMQ_SEND_EXIT_INIT The user data that is passed to channel send exits when they
are called.
XMSC_WMQ_SEND_CHECK_COUNT The number of send calls to allow between checking for
asynchronous put errors, within a single non-transacted XMS
session.
XMSC_WMQ_SHARE_CONV_ALLOWED Whether a client connection can share its socket with other
top-level XMS connections from the same process to the same
queue manager, if the channel definitions match. This
property is provided to allow complete isolation of
Connections in separate sockets if required for application
development, maintenance or operational reasons.
XMSC_WMQ_SSL_CERT_STORES The locations of the servers that hold the certificate revocation
lists (CRLs) to be used on an SSL connection to a queue
manager.
XMSC_WMQ_SSL_CIPHER_SPEC The name of the cipher spec to be used on a secure
connection to a queue manager.

406 Message Service Client for C/C++

Table 35. Properties of ConnectionFactory (continued)
Name of property Description
XMSC_WMQ_SSL_CIPHER_SUITE The name of the CipherSuite to be used on an SSL or TLS
connection to a queue manager. The protocol used in
negotiating the secure connection depends on the specified
CipherSuite.
XMSC_WMQ_SSL_CRYPTO_HW Configuration details for the cryptographic hardware
connected to the client system.
XMSC_WMQ_SSL_FIPS_REQUIRED The value of this property determines whether an application
can or cannot use non-FIPS compliant cipher suites. If this
property is set to true, only FIPS algorithms are used for the
client-server connection.
XMSC_WMQ_SSL_KEY_REPOSITORY The location of the key database file in which keys and
certificates are stored.
XMSC_WMQ_SSL_KEY_RESETCOUNT The KeyResetCount represents the total number of
unencrypted bytes sent and received within an SSL
conversation before the secret key is renegotiated.
XMSC_WMQ_SSL_PEER_NAME The peer name to be used on an SSL connection to a queue
manager.
XMSC_WMQ_SYNCPOINT_ALL_GETS Whether all messages must be retrieved from queues within
syncpoint control.
XMSC_WMQ_TEMP_Q_PREFIX The prefix used to form the name of the WebSphere MQ
dynamic queue that is created when the application creates an
XMS temporary queue.
XMSC_WMQ_TEMP_TOPIC_PREFIX When creating temporary topics, XMS will generate a topic
string of the form “TEMP/TEMPTOPICPREFIX/unique_id”,
or if this property is left with the default value, just
“TEMP/unique_id”. Specifying a non-empty value allows
specific model queues to be defined for creating the managed
queues for subscribers to temporary topics created under this
connection.
XMSC_WMQ_TEMPORARY_MODEL The name of the WebSphere MQ model queue from which a
dynamic queue is created when the application creates an
XMS temporary queue.
XMSC_WMQ_WILDCARD_FORMAT This property determines which version of wildcard syntax is
to be used.
XMSC_WPM_BUS_NAME For a connection factory, the name of the service integration
bus that the application connects to or, for a destination, the
name of the service integration bus in which the destination
exists.
XMSC_WPM_CONNECTION_PROXIMITY The connection proximity setting for the connection.
XMSC_WPM_DUR_SUB_HOME The name of the messaging engine where all durable
subscriptions for a connection or a destination are managed.
XMSC_WPM_LOCAL_ADDRESS For a connection to a service integration bus, this property
specifies the local network interface to be used, or the local
port or range of local ports to be used, or both.
XMSC_WPM_NON_PERSISTENT_MAP The reliability level of nonpersistent messages that are sent
using the connection.
XMSC_WPM_PERSISTENT_MAP The reliability level of persistent messages that are sent using
the connection.
XMSC_WPM_PROVIDER_ENDPOINTS A sequence of one or more endpoint addresses of bootstrap
servers.

Chapter 17. Properties of XMS objects 407

Table 35. Properties of ConnectionFactory (continued)
Name of property Description
XMSC_WPM_SSL_CIPHER_SUITE The name of the CipherSuite to be used on an SSL or TLS
connection to a WebSphere service integration bus messaging
engine. The protocol used in negotiating the secure
connection depends on the specified CipherSuite.
XMSC_WPM_SSL_KEY_REPOSITORY A path to the file that is the keyring file containing the public
or private keys to be used in the secure connection.
XMSC_WPM_SSL_KEYRING_LABEL The certificate to be used when authenticating with the server.
XMSC_WPM_SSL_KEYRING_PW The password for the keyring file.
XMSC_WPM_SSL_KEYRING_STASH_FILE The name of a binary file containing the password of the key
repository file.
XMSC_WPM_SSL_FIPS_REQUIRED The value of this property determines whether an application
can or cannot use non-FIPS compliant cipher suites. If this
property is set to true, only FIPS algorithms are used for the
client-server connection.
XMSC_WPM_TARGET_GROUP The name of a target group of messaging engines.
XMSC_WPM_TARGET_SIGNIFICANCE The significance of the target group of messaging engines.
XMSC_WPM_TARGET_TRANSPORT_CHAIN The name of the inbound transport chain that the application
must use to connect to a messaging engine.
XMSC_WPM_TARGET_TYPE The type of the target group of messaging engines.
XMSC_WPM_TEMP_Q_PREFIX The prefix used to form the name of the temporary queue
that is created in the service integration bus when the
application creates an XMS temporary queue.
XMSC_WPM_TEMP_TOPIC_PREFIX The prefix used to form the name of a temporary topic that is
created by the application.

Properties of ConnectionMetaData
An overview of the properties of the ConnectionMetaData object, with links to
more detailed reference information.
Table 36. Properties of ConnectionMetaData
Name of property Description
XMSC_JMS_MAJOR_VERSION The major version number of the JMS specification upon
which XMS is based. This property is read-only.
XMSC_JMS_MINOR_VERSION The minor version number of the JMS specification upon
which XMS is based. This property is read-only.
XMSC_JMS_VERSION The version identifier of the JMS specification upon which
XMS is based. This property is read-only.
XMSC_MAJOR_VERSION The version number of the XMS client. This property is
read-only.
XMSC_MINOR_VERSION The release number of the XMS client. This property is
read-only.
XMSC_PROVIDER_NAME The provider of the XMS client. This property is read-only.
XMSC_VERSION The version identifier of the XMS client. This property is
read-only.

408 Message Service Client for C/C++

Properties of Destination
An overview of the properties of the Destination object, with links to more detailed
reference information.
Table 37. Properties of Destination
Name of property Description
XMSC_DELIVERY_MODE The delivery mode of messages sent to the destination.
XMSC_PRIORITY The priority of messages sent to the destination.
XMSC_RTT_MULTICAST The multicast setting for a connection factory or destination.
XMSC_TIME_TO_LIVE The time to live for messages sent to the destination.
XMSC_WMQ_BROKER_VERSION The type of broker used by the application for a connection or
for the destination.
XMSC_WMQ_CCSID The identifier (CCSID) of the coded character set, or code
page, that the strings of character data in the body of a
message will be in when the XMS client forwards the
message to the destination.
XMSC_WMQ_DUR_SUBQ The name of the subscriber queue for a durable subscriber
that is receiving messages from the destination.
Note: This property has no effect for an application
connected to a WebSphere MQ V7.0 (and above) queue
manager unless the XMSC_WMQ_PROVIDER_VERSION
property of the connection factory is set to a version number
less than 7.
XMSC_WMQ_ENCODING How numerical data in the body of a message will be
represented when the XMS client forwards the message to the
destination.
XMSC_WMQ_FAIL_IF_QUIESCE Whether calls to certain methods fail if the queue manager to
which the application is connected is in a quiescing state.
XMSC_WMQ_MESSAGE_BODY This property determines whether a XMS application
processes the MQRFH2 of a WebSphere MQ message as part
of the message payload (that is, as part of the message body).
XMSC_WMQ_MQMD_MESSAGE_CONTEXT Determines what level of message context is to be set by the
XMS application. The application must be running with
appropriate context authority for this property to take effect.
XMSC_WMQ_MQMD_READ_ENABLED This property determines whether a XMS application can
extract the values of MQMD fields or not.
XMSC_WMQ_MQMD_WRITE_ENABLED This property determines whether a XMS application can set
the values of MQMD fields or not.
XMSC_WMQ_READ_AHEAD_CLOSE_POLICY This property determines, for messages being delivered to an
asynchronous message listener, what happens to messages in
the internal read ahead buffer when the message consumer is
closed.
XMSC_WMQ_READ_AHEAD_ALLOWED This property determines whether message consumers and
queue browsers are allowed to use read ahead to get
non-persistent, non-transactional messages from this
destination into an internal buffer before receiving them.
XMSC_WMQ_PUT_ASYNC_ALLOWED This property determines whether message producers are
allowed to use asynchronous puts to send messages to this
destination.
XMSC_WMQ_WILDCAD_FORMAT This property determines which version of wildcard syntax is
to be used.

Chapter 17. Properties of XMS objects 409

Table 37. Properties of Destination (continued)
Name of property Description
XMSC_WMQ_TARGET_CLIENT Whether messages sent to the destination contain an
MQRFH2 header.
XMSC_WMQ_TEMP_TOPIC_PREFIX When creating temporary topics, XMS will generate a topic
string of the form “TEMP/TEMPTOPICPREFIX/unique_id”,
or if this property is left with the default value, just
“TEMP/unique_id”. Specifying a non-empty value allows
specific model queues to be defined for creating the managed
queues for subscribers to temporary topics created under this
connection.
XMSC_WPM_BUS_NAME For a connection factory, the name of the service integration
bus that the application connects to or, for a destination, the
name of the service integration bus in which the destination
exists.
XMSC_WPM_TOPIC_SPACE The name of the topic space that contains the topic.

Properties of InitialContext
An overview of the properties of the InitialContext object, with links to more
detailed reference information.
Table 38. Properties of InitialContext
Name of property Description
XMSC_IC_PROVIDER_URL Used to locate the JNDI naming directory so that the COS
naming service does not need to be on the same machine as
the web service.
XMSC_IC_SECURITY_AUTHENTICATION Based on the Java Context interface
SECURITY_AUTHENTICATION. This property is only
applicable to the COS naming context.
XMSC_IC_SECURITY_CREDENTIALS Based on the Java Context interface
SECURITY_CREDENTIALS. This property is only applicable
to the COS naming context.
XMSC_IC_SECURITY_PRINCIPAL Based on the Java Context interface SECURITY_PRINCIPAL.
This property is only applicable to the COS naming context.
XMSC_IC_SECURITY_PROTOCOL Based on the Java Context interface SECURITY_PROTOCOL
This property is only applicable to the COS naming context.
XMSC_IC_URL For LDAP and FileSystem contexts, the address of the
repository containing administered objects. For COS naming
contexts, the address of the web service that looks up the
objects in the directory.

Properties of Message
An overview of the properties of the Message object, with links to more detailed
reference information.

410 Message Service Client for C/C++

Table 39. Properties of Message
Name of property Description
“JMS_IBM_ArmCorrelator” on page 417 The Open Group Application Response Measurement
Correlator property, set on a message. This IBM-defined
property associates a unique Id with the application data in
the message. Use JMS_TOG_ARM_Correlator in preference to
this property.
JMS_IBM_CHARACTER_SET The identifier (CCSID) of the coded character set, or code
page, that the strings of character data in the body of the
message will be in when the XMS client forwards the
message to its intended destination. In XMS this property has
a numeric value and maps to CCSID. However, this property
is based on a JMS property so has a string type value and
maps to the Java character set that represents this numeric
CCSID.
JMS_IBM_ENCODING How numerical data in the body of the message will be
represented when the XMS client forwards the message to its
intended destination.
JMS_IBM_EXCEPTIONMESSAGE Text that describes why the message was sent to the exception
destination. This property is read-only.
JMS_IBM_EXCEPTIONPROBLEMDESTINATION The name of the destination that the message was at before
the message was sent to the exception destination.
JMS_IBM_EXCEPTIONREASON A reason code indicating the reason why the message was
sent to the exception destination.
JMS_IBM_EXCEPTIONTIMESTAMP The time when the message was sent to the exception
destination.
JMS_IBM_FEEDBACK A code that indicates the nature of a report message.
JMS_IBM_FORMAT The nature of the application data in the message.
JMS_IBM_LAST_MSG_IN_GROUP Indicate whether the message is the last message in a message
group.
JMS_IBM_MSGTYPE The type of the message.
JMS_IBM_PUTAPPLTYPE The type of application that sent the message.
JMS_IBM_PUTDATE The date when the message was sent.
JMS_IBM_PUTTIME The time when the message was sent.
JMS_IBM_REPORT_COA Request confirm on arrival report messages, specifying how
much application data from the original message must be
included in a report message.
JMS_IBM_REPORT_COD Request confirm on delivery report messages, specifying how
much application data from the original message must be
included in a report message.
JMS_IBM_REPORT_DISCARD_MSG Request that the message is discarded if it cannot be delivered
to its intended destination.
JMS_IBM_REPORT_EXCEPTION Request exception report messages, specifying how much
application data from the original message must be included
in a report message.
JMS_IBM_REPORT_EXPIRATION Request expiration report messages, specifying how much
application data from the original message must be included
in a report message.
JMS_IBM_REPORT_NAN Request negative action notification report messages.
JMS_IBM_REPORT_PAN Request positive action notification report messages.

Chapter 17. Properties of XMS objects 411

Table 39. Properties of Message (continued)
Name of property Description
JMS_IBM_REPORT_PASS_CORREL_ID Request that the correlation identifier of any report or reply
message is the same as that of the original message.
JMS_IBM_REPORT_PASS_MSG_ID Request that the message identifier of any report or reply
message is the same as that of the original message.
JMS_IBM_RETAIN Setting this property indicates to the queue manager to treat a
message as Retained Publication.
JMS_IBM_SYSTEM_MESSAGEID An identifier that identifies the message uniquely within the
service integration bus. This property is read-only.
“JMS_TOG_ARM_Correlator” on page 427 The Open Group Application Response Measurement
Correlator property, set on a message. Associates a unique Id
with the application data in the message.
JMSX_APPID The name of the application that sent the message.
JMSX_DELIVERY_COUNT The number of attempts to deliver the message.
JMSX_GROUPID The identifier of the message group to which the message
belongs.
JMSX_GROUPSEQ The sequence number of the message within a message
group.
JMSX_USERID The user identifier associated with the application that sent
the message.

JMS_IBM_MQMD* properties

IBM Message Service Client for C/C++ enables client applications to read/write
MQMD fields using APIs. It also allows access to MQ message data. By default
access to MQMD is disabled and must be enabled explicitly by the application
using Destination properties XMSC_WMQ_MQMD_WRITE_ENABLED and
XMSC_WMQ_MQMD_READ_ENABLED. These two properties are independent of
each other.

All MQMD fields except StrucId and Version are exposed as additional Message
object properties and are prefixed JMS_IBM_MQMD.

JMS_IBM_MQMD* properties take higher precedence over other properties like

JMS_IBM* described in the above table.

Sending messages

All MQMD fields except StrucId and Version are represented. These properties
refer only to the MQMD fields; where a property occurs both in the MQMD and in
the MQRFH2 header, the version in the MQRFH2 is not set or extracted. Any of
these properties can be set, except JMS_IBM_MQMD_BackoutCount. Any value set
for JMS_IBM_MQMD_BackoutCount is ignored.

If a property has a maximum length and you supply a value that is too long, the
value is truncated.

For certain properties, you must also set the WMQ_MQMD_MESSAGE_CONTEXT

property on the Destination object. The application must be running with
appropriate context authority for this property to take effect. If you do not set
WMQ_MQMD_MESSAGE_CONTEXT to an appropriate value, the property value

412 Message Service Client for C/C++

 is ignored. If you set WMQ_MQMD_MESSAGE_CONTEXT to an appropriate
value but you do not have sufficient context authority for the queue manager, an
exception is issued. Properties requiring specific values of
WMQ_MQMD_MESSAGE_CONTEXT are as follows.

The following properties require WMQ_MQMD_MESSAGE_CONTEXT to be set to

WMQ_MDCTX_SET_IDENTITY_CONTEXT or
WMQ_MDCTX_SET_ALL_CONTEXT:
v JMS_IBM_MQMD_UserIdentifier
v JMS_IBM_MQMD_AccountingToken
v JMS_IBM_MQMD_ApplIdentityData

The following properties require WMQ_MQMD_MESSAGE_CONTEXT to be set to

WMQ_MDCTX_SET_ALL_CONTEXT:
v JMS_IBM_MQMD_PutApplType
v JMS_IBM_MQMD_PutApplName
v JMS_IBM_MQMD_PutDate
v JMS_IBM_MQMD_PutTime
v JMS_IBM_MQMD_ApplOriginData

Receiving messages

All these properties are available on a received message if

WMQ_MQMD_READ_ENABLED property is set to true, irrespective of the actual
properties the producing application has set. An application cannot modify the
properties of a received message unless all properties are cleared first, according to
the JMS specification. The received message can be forwarded without modifying
the properties.

Note: If your application receives a message from a destination with

WMQ_MQMD_READ_ENABLED property set to true, and forwards it to a
destination with WMQ_MQMD_WRITE_ENABLED set to true, this results
in all the MQMD field values of the received message being copied into the
forwarded message. Table of properties
Table 40. Properties of the Message object representing the MQMD fields
Property Description Type
JMS_IBM_MQMD_REPORT Options for report messages xmsINT
JMS_IBM_MQMD_MSGTYPE Message type xmsINT
JMS_IBM_MQMD_EXPIRY message lifetime xmsINT
JMS_IBM_MQMD_FEEDBACK Feedback or reason code xmsINT
JMS_IBM_MQMD_ENCODING Numeric encoding of message data xmsINT
JMS_IBM_MQMD_CODEDCHARSETID Character set identifier of message xmsINT
data
JMS_IBM_MQMD_FORMAT Format name of message data String
JMS_IBM_MQMD_PRIORITY Message priority xmsINT
Note: If you assign a value to
JMS_IBM_MQMD_PRIORITY that is not
within the range 0-9, this violates the JMS
specification.
JMS_IBM_MQMD_PERSISTENCE Message persistence xmsINT

Chapter 17. Properties of XMS objects 413

Table 40. Properties of the Message object representing the MQMD fields (continued)
Property Description Type
JMS_IBM_MQMD_MSGID Message identifier Byte Array
Note: The JMS specification states that the Note: The use of byte array
message ID must be set by the JMS provider properties on a message
and that it must either be unique or null. If violates the JMS
you assign a value to specification.
JMS_IBM_MQMD_MSGID, this value is
copied to the JMSMessageID. Thus it is not
set by the JMS provider and might not be
unique: this violates the JMS specification.
JMS_IBM_MQMD_CORRELID Correlation identifier Byte Array
Note: If you assign a value to Note: The use of byte array
JMS_IBM_MQMD_CORRELID that starts properties on a message
with the string ’ID:’, this violates the JMS violates the JMS
specification. specification.
JMS_IBM_MQMD_BACKOUTCOUNT Backout counter xmsINT
JMS_IBM_MQMD_REPLYTOQ Name of reply queue String
JMS_IBM_MQMD_REPLYTOQMGR Name of reply queue manager String
JMS_IBM_MQMD_USERIDENTIFIER User identifier String
JMS_IBM_MQMD_ACCOUNTINGTOKEN Accounting token Byte Array
Note: The use of byte array
properties on a message
violates the JMS
specification.
JMS_IBM_MQMD_APPLIDENTITYDATA Application data relating to identity String
JMS_IBM_MQMD_PUTAPPLTYPE Type of application that put the xmsINT
message
JMS_IBM_MQMD_PUTAPPLNAME Name of the application that put the String
message
JMS_IBM_MQMD_PUTDATE Date when message was put String
JMS_IBM_MQMD_PUTTIME Time when message was put String
JMS_IBM_MQMD_APPLORIGINDATA Application data relating to origin String
JMS_IBM_MQMD_GROUPID Group identifier Byte Array
Note: The use of byte array
properties on a message
violates the JMS
specification.
JMS_IBM_MQMD_MSGSEQNUMBER Sequence number of local message xmsINT
within group
JMS_IBM_MQMD_OFFSET Offset of data in physical message xmsINT
from start of logical message
JMS_IBM_MQMD_MSGFLAGS Message flags xmsINT
JMS_IBM_MQMD_ORIGINALLENGTH Length of original message xmsINT

For further details on MQMD please refer WebSphere MQ v7.0 Application

Programming Reference.

414 Message Service Client for C/C++

 Examples

This example results in a message being put to a queue or topic with

MQMD.UserIdentifier set to “JoeBloggs”.
// Create a ConnectionFactory, connection, session, producer, message
// ...

// Create a destination
// ...

// Enable MQMD write

dest.setBooleanProperty(XMSC_WMQ_MQMD_WRITE_ENABLED, XMSC_WMQ_MQMD_WRITE_ENABLED_YES);

// Optionally, set a message context if applicable for this MD field

dest.setIntProperty(XMSC_WMQ_MQMD_MESSAGE_CONTEXT,
XMSC_WMQ_MDCTX_SET_IDENTITY_CONTEXT);

// On the message, set property to provide custom UserId

msg.setStringProperty(JMS_IBM_MQMD_USERIDENTIFIER, "JoeBloggs");

// Send the message

// ...

It is necessary to set XMSC_WMQ_MQMD_MESSAGE_CONTEXT before setting

JMS_IBM_MQMD_USERIDENTIFIER. For more information about the use of
XMSC_WMQ_MQMD_MESSAGE_CONTEXT, see Message object properties.

Similarly, you can extract the contents of the MQMD fields by setting
XMSC_WMQ_MQMD_READ_ENABLED to true before receiving a message and
then using the get methods of the message, such as getStringProperty. Any
properties received are read-only.

This example results in the value field holding the value of the
MQMD.ApplIdentityData field of a message got from a queue or a topic.
// Create a ConnectionFactory, connection, session, consumer
// ...

// Create a destination
// ...

// Enable MQMD read

dest.setBooleanProperty(XMSC_WMQ_MQMD_READ_ENABLED, XMSC_WMQ_MQMD_READ_ENABLED_YES);

// Receive a message
// ...

// Get desired MQMD field value using a property

String value = rcvMsg.getStringProperty(JMS_IBM_MQMD_APPLIDENTITYDATA);

Properties of MessageConsumer
An overview of the properties of the MessageConsumer object, with links to more
detailed reference information.
Table 41. Properties of MessageConsumer
Name of property Description
XMSC_CLIENT_CCSID The identifier (CCSID) of the coded character set, or code
page, used by a connection, session, message producer,
or message consumer.

Chapter 17. Properties of XMS objects 415

Table 41. Properties of MessageConsumer (continued)
Name of property Description
XMSC_IS_SUBSCRIPTION_MULTICAST Indicates whether messages are being delivered to the
message consumer using WebSphere MQ Multicast
Transport. This property is read-only.
XMSC_IS_SUBSCRIPTION_RELIABLE_MULTICAST Indicates whether messages are being delivered to the
message consumer using WebSphere MQ Multicast
Transport with a reliable quality of service. This property
is read-only.

Properties of MessageProducer
An overview of the properties of the MessageProducer object, with links to more
detailed reference information.
Table 42. Properties of MessageProducer
Name of property Description
XMSC_CLIENT_CCSID The identifier (CCSID) of the coded character set, or code
page, used by a connection, session, message producer, or
message consumer.

Properties of Session
An overview of the properties of the Session object, with links to more detailed
reference information.
Table 43. Properties of Session
Name of property Description
XMSC_CLIENT_CCSID The identifier (CCSID) of the coded character set, or code
page, used by a connection, session, message producer, or
message consumer.

Property definitions
This section provides a definition of each object property.

Each property definition includes the following information:

v The data type of the property
v The types of object that have the property
v For a property of Destination, the name that can be used in a uniform resource
identifier (URI)
v A more detailed description of the property
v The valid values of the property
v The default value of the property

Properties whose names commence with one of the following prefixes are relevant
only for the specified type of connection:

416 Message Service Client for C/C++

 XMSC_RTT
The properties are relevant only for a real-time connection to a broker. The
names of the properties are defined as named constants in the header file
xmsc_rtt.h.
XMSC_WMQ
The properties are relevant only when an application connects to a
WebSphere MQ queue manager. The names of the properties are defined as
named constants in the header file xmsc_wmq.h.
XMSC_WPM
The properties are relevant only when an application connects to a
WebSphere service integration bus. The names of the properties are defined
as named constants in the header file xmsc_wpm.h.

Unless stated otherwise in their definitions, the remaining properties are relevant
for all types of connection. The names of the properties are defined as named
constants in the header file xmsc.h. Properties whose names commence with the
prefix JMSX are JMS defined properties of a message, and properties whose names
commence with the prefix JMS_IBM are IBM defined properties of a message. For
more information about the properties of messages, see “Properties of an XMS
message” on page 98.

Unless stated otherwise in its definition, each property is relevant in both the
point-to-point and publish/subscribe domains.

An application can get and set the value of any property, unless the property is
designated as read-only.

JMS_IBM_ArmCorrelator
Data type:
String
Property of:
Message

The Open Group Application Response Measurement Correlator property, set on a

message. This IBM-defined property associates a unique Id with the application
data in the message. Use JMS_TOG_ARM_Correlator in preference to this property.

JMS_IBM_ArmCorrelator is a synonym of JMS_TOG_ARM_Correlator. This

property is available for compatibility with some existing JMS programs.

This property can be set by using the xmsSetStringProperty method:

xmsSetStringProperty(xmsHMsg, JMS_IBM_ArmCorrelator, “ARM_Correlator”,

sizeof(“ARM_Correlator”), xmsHError);

By default, the property is not set.

The value for this property can be obtained using the GetStringProperty method.

This property is not valid for Real Time Transport.

Chapter 17. Properties of XMS objects 417

 JMS_IBM_CHARACTER_SET
Data type:
xmsINT
Property of:
Message

The identifier (CCSID) of the coded character set, or code page, that the strings of
character data in the body of the message will be in when the XMS client forwards
the message to its intended destination. In XMS this property has a numeric value
and maps to CCSID. However, this property is based on a JMS property so has a
string type value and maps to the Java character set that represents this numeric
CCSID. This property overrides any CCSID specified for the destination by the
XMSC_WMQ_CCSID property.

By default, the property is not set.

This property is not relevant when an application connects to a service integration

bus.

JMS_IBM_ENCODING
Data type:
xmsINT
Property of:
Message

How numerical data in the body of the message will be represented when the XMS
client forwards the message to its intended destination. This property overrides
any encoding specified for the destination by the XMSC_WMQ_ENCODING
property. The property specifies the representation of binary integers, packed
decimal integers, and floating point numbers.

The valid values of the property are the same as the values that can be specified in
the Encoding field of a message descriptor. For more information about the
Encoding field, see the WebSphere MQ Application Programming Reference.

An application can use the following named constants to set the property:

Named constant Meaning

MQENC_INTEGER_NORMAL Normal integer encoding
MQENC_INTEGER_REVERSED Reversed integer encoding
MQENC_DECIMAL_NORMAL Normal packed decimal encoding
MQENC_DECIMAL_REVERSED Reversed packed decimal encoding
MQENC_FLOAT_IEEE_NORMAL Normal IEEE floating point encoding
MQENC_FLOAT_IEEE_REVERSED Reversed IEEE floating point encoding
MQENC_FLOAT_S390 zSeries® (System/390®) architecture floating
point encoding
MQENC_NATIVE Native machine encoding

To form a value for the property, the application can add together three of these
constants as follows:
v A constant whose name commences with MQENC_INTEGER, to specify the
representation of binary integers

418 Message Service Client for C/C++

 v A constant whose name commences with MQENC_DECIMAL, to specify the
representation of packed decimal integers
v A constant whose name commences with MQENC_FLOAT, to specify the
representation of floating point numbers
Alternatively, the application can set the property to MQENC_NATIVE, whose
value is environment dependent.

By default, the property is not set.

This property is not relevant when an application connects to a service integration

bus.

JMS_IBM_EXCEPTIONMESSAGE
Data type:
String
Property of:
Message

Text that describes why the message was sent to the exception destination. This
property is read-only.

This property is relevant only when an application connects to a service integration

bus and receives a message from an exception destination.

JMS_IBM_EXCEPTIONPROBLEMDESTINATION
Data type:
String
Property of:
Message

The name of the destination that the message was at before the message was sent
to the exception destination.

This property is relevant only when an application connects to a service integration

bus and receives a message from an exception destination.

JMS_IBM_EXCEPTIONREASON
Data type:
xmsINT
Property of:
Message

A reason code indicating the reason why the message was sent to the exception
destination.

For a list of all possible reason codes, see the definition of the
com.ibm.websphere.sib.SIRCConstants class in the documentation generated by the
Javadoc tool, as supplied with WebSphere Application Server.

This property is relevant only when an application connects to a service integration

bus and receives a message from an exception destination.

Chapter 17. Properties of XMS objects 419

 JMS_IBM_EXCEPTIONTIMESTAMP
Data type:
xmsLONG
Property of:
Message

The time when the message was sent to the exception destination.

The time is expressed in milliseconds since 00:00:00 GMT on the 1 January 1970.

This property is relevant only when an application connects to a service integration

bus and receives a message from an exception destination.

JMS_IBM_FEEDBACK
Data type:
xmsINT
Property of:
Message

A code that indicates the nature of a report message.

The valid values of the property are the feedback codes and reason codes that can
be specified in the Feedback field of a message descriptor. For more information
about the Feedback field, see the WebSphere MQ Application Programming Reference.

By default, the property is not set.

JMS_IBM_FORMAT
Data type:
String
Property of:
Message

The nature of the application data in the message.

The valid values of the property are the same as the values that can be specified in
the Format field of a message descriptor. For more information about the Format
field, see the WebSphere MQ Application Programming Reference.

By default, the property is not set.

This property is not relevant when an application connects to a service integration

bus.

JMS_IBM_LAST_MSG_IN_GROUP
Data type:
xmsBOOL
Property of:
Message

Indicate whether the message is the last message in a message group.

420 Message Service Client for C/C++

 Set the property to xmsTRUE if the message is the last message in a message
group. Otherwise, set the property to xmsFALSE, or do not set the property. By
default, the property is not set.

The value xmsTRUE corresponds to the status flag

MQMF_LAST_MSG_IN_GROUP, which can be specified in the MsgFlags field of a
message descriptor. For more information about this flag, see the WebSphere MQ
Application Programming Reference.

This property is ignored in the publish/subscribe domain and is not relevant when
an application connects to a service integration bus.

JMS_IBM_MSGTYPE
Data type:
xmsINT
Property of:
Message

The type of the message.

The valid values of the property are as follows:

Valid value Meaning

MQMT_DATAGRAM The message is one that does not require a reply.
MQMT_REQUEST The message is one that requires a reply.
MQMT_REPLY The message is a reply message.
MQMT_REPORT The message is a report message.

These values correspond to the message types that can be specified in the MsgType
field of a message descriptor. For more information about the MsgType field, see the
WebSphere MQ Application Programming Reference.

By default, the property is not set.

This property is not relevant when an application connects to a service integration

bus.

JMS_IBM_PUTAPPLTYPE
Data type:
xmsINT
Property of:
Message

The type of application that sent the message.

The valid values of the property are the application types that can be specified in
the PutApplType field of a message descriptor. For more information about the
PutApplType field, see the WebSphere MQ Application Programming Reference.

By default, the property is not set.

This property is not relevant when an application connects to a service integration

bus.

Chapter 17. Properties of XMS objects 421

 JMS_IBM_PUTDATE
Data type:
String
Property of:
Message

The date when the message was sent.

The valid values of the property are the same as the values that can be specified in
the PutDate field of a message descriptor. For more information about the PutDate
field, see the WebSphere MQ Application Programming Reference.

By default, the property is not set.

This property is not relevant when an application connects to a service integration

bus.

JMS_IBM_PUTTIME
Data type:
String
Property of:
Message

The time when the message was sent.

The valid values of the property are the same as the values that can be specified in
the PutTime field of a message descriptor. For more information about the PutTime
field, see the WebSphere MQ Application Programming Reference.

By default, the property is not set.

This property is not relevant when an application connects to a service integration

bus.

JMS_IBM_REPORT_COA
Data type:
xmsINT
Property of:
Message

Request confirm on arrival report messages, specifying how much application data
from the original message must be included in a report message.

The valid values of the property are as follows:

Valid value Meaning

MQRO_COA Request confirm on arrival report messages,
with no application data from the original
message included in a report message.

422 Message Service Client for C/C++

 Valid value Meaning
MQRO_COA_WITH_DATA Request confirm on arrival report messages,
with the first 100 bytes of application data
from the original message included in a report
message.
MQRO_COA_WITH_FULL_DATA Request confirm on arrival report messages,
with all the application data from the original
message included in a report message.

These values correspond to report options that can be specified in the Report field
of a message descriptor. For more information about these options, see the
WebSphere MQ Application Programming Reference.

By default, the property is not set.

JMS_IBM_REPORT_COD
Data type:
xmsINT
Property of:
Message

Request confirm on delivery report messages, specifying how much application

data from the original message must be included in a report message.

The valid values of the property are as follows:

Valid value Meaning

MQRO_COD Request confirm on delivery report messages,
with no application data from the original
message included in a report message.
MQRO_COD_WITH_DATA Request confirm on delivery report messages,
with the first 100 bytes of application data
from the original message included in a report
message.
MQRO_COD_WITH_FULL_DATA Request confirm on delivery report messages,
with all the application data from the original
message included in a report message.

These values correspond to report options that can be specified in the Report field
of a message descriptor. For more information about these options, see the
WebSphere MQ Application Programming Reference.

By default, the property is not set.

JMS_IBM_REPORT_DISCARD_MSG
Data type:
xmsINT
Property of:
Message

Request that the message is discarded if it cannot be delivered to its intended

destination.

Chapter 17. Properties of XMS objects 423

 Set the property to MQRO_DISCARD_MSG to request that the message is
discarded if it cannot be delivered to its intended destination. If you require the
message to be put on a dead letter queue instead, or sent to an exception
destination, do not set the property. By default, the property is not set.

The value MQRO_DISCARD_MSG corresponds to a report option that can be

specified in the Report field of a message descriptor. For more information about
this option, see the WebSphere MQ Application Programming Reference.

JMS_IBM_REPORT_EXCEPTION
Data type:
xmsINT
Property of:
Message

Request exception report messages, specifying how much application data from the
original message must be included in a report message.

The valid values of the property are as follows:

Valid value Meaning

MQRO_EXCEPTION Request exception report messages,
with no application data from the
original message included in a report
message.
MQRO_EXCEPTION_WITH_DATA Request exception report messages,
with the first 100 bytes of application
data from the original message
included in a report message.
MQRO_EXCEPTION_WITH_FULL_DATA Request exception report messages,
with all the application data from the
original message included in a report
message.

These values correspond to report options that can be specified in the Report field
of a message descriptor. For more information about these options, see the
WebSphere MQ Application Programming Reference.

By default, the property is not set.

JMS_IBM_REPORT_EXPIRATION
Data type:
xmsINT
Property of:
Message

Request expiration report messages, specifying how much application data from
the original message must be included in a report message.

424 Message Service Client for C/C++

 The valid values of the property are as follows:

Valid value Meaning

MQRO_EXPIRATION Request expiration report messages,
with no application data from the
original message included in a report
message.
MQRO_EXPIRATION_WITH_DATA Request expiration report messages,
with the first 100 bytes of application
data from the original message
included in a report message.
MQRO_EXPIRATION_WITH_FULL_DATA Request expiration report messages,
with all the application data from the
original message included in a report
message.

These values correspond to report options that can be specified in the Report field
of a message descriptor. For more information about these options, see the
WebSphere MQ Application Programming Reference.

By default, the property is not set.

JMS_IBM_REPORT_NAN
Data type:
xmsINT
Property of:
Message

Request negative action notification report messages.

Set the property to MQRO_NAN to request negative action notification report

messages. If you do not require negative action notification report messages, do
not set the property. By default, the property is not set.

The value MQRO_NAN corresponds to a report option that can be specified in the
Report field of a message descriptor. For more information about this option, see
the WebSphere MQ Application Programming Reference.

JMS_IBM_REPORT_PAN
Data type:
xmsINT
Property of:
Message

Request positive action notification report messages.

Set the property to MQRO_PAN to request positive action notification report

messages. If you do not require positive action notification report messages, do not
set the property. By default, the property is not set.

The value MQRO_PAN corresponds to a report option that can be specified in the
Report field of a message descriptor. For more information about this option, see
the WebSphere MQ Application Programming Reference.

Chapter 17. Properties of XMS objects 425

 JMS_IBM_REPORT_PASS_CORREL_ID
Data type:
xmsINT
Property of:
Message

Request that the correlation identifier of any report or reply message is the same as
that of the original message.

The valid values of the property are as follows:

Valid value Meaning

MQRO_PASS_CORREL_ID Request that the correlation identifier
of any report or reply message is the
same as that of the original message.
MQRO_COPY_MSG_ID_TO_CORREL_ID Request that the correlation identifier
of any report or reply message is the
same as the message identifier of the
original message.

These values correspond to report options that can be specified in the Report field
of a message descriptor. For more information about these options, see the
WebSphere MQ Application Programming Reference.

The default value of the property is MQRO_COPY_MSG_ID_TO_CORREL_ID.

JMS_IBM_REPORT_PASS_MSG_ID
Data type:
xmsINT
Property of:
Message

Request that the message identifier of any report or reply message is the same as
that of the original message.

The valid values of the property are as follows:

Valid value Meaning

MQRO_PASS_MSG_ID Request that the message identifier of any report or
reply message is the same as that of the original
message.
MQRO_NEW_MSG_ID Request that a new message identifier is generated for
each report or reply message.

These values correspond to report options that can be specified in the Report field
of a message descriptor. For more information about these options, see the
WebSphere MQ Application Programming Reference.

The default value of the property is MQRO_NEW_MSG_ID.

JMS_IBM_RETAIN
Data type:
xmsINT
426 Message Service Client for C/C++
 Property of:
Message

Setting this property indicates to the queue manager to treat a message as Retained
Publication. When a subscriber receives messages from topics, it may receive
additional messages immediately after subscribing, beyond those that would have
been received in previous releases. These are the optional retained publication(s)
for the topic(s) subscribed. For each topic matching the subscription, if there is a
retained publication it will be made available for delivery to the subscribing
message consumer.

RETAIN_PUBLICATION is the only valid value for this property. By default this
property is not set.

Note: This property is relevant only in publish/subscribe domain only

JMS_IBM_SYSTEM_MESSAGEID
Data type:
String
Property of:
Message

An identifier that identifies the message uniquely within the service integration
bus. This property is read-only.

This property is relevant only when an application connects to a service integration

bus.

JMS_TOG_ARM_Correlator
Data type:
String
Property of:
Message

The Open Group Application Response Measurement Correlator property, set on a

message. Associates a unique Id with the application data in the message.

This is a JMS property and is a synonym of JMS_IBM_ArmCorrelator.

Use JMS_TOG_ARM_Correlator in preference to JMS_IBM_ArmCorrelator.

JMS_IBM_ArmCorrelator is available for compatibility with some existing JMS
programs.

This property can be set by using the xmsSetStringProperty method:

xmsSetStringProperty(xmsHMsg, JMS_TOG_ARM_Correlator, “ARM_Correlator”,

sizeof(“ARM_Correlator”), xmsHError);

By default, the property is not set.

The value for this property can be obtained using the GetStringProperty method.

This property is not valid for Real Time Transport.

Chapter 17. Properties of XMS objects 427

 JMSX_APPID
Data type:
String
Property of:
Message

The name of the application that sent the message.

This property is the JMS defined property with the JMS name JMSXAppID. For
more information about the property, see the Java Message Service Specification,
Version 1.1.

By default, the property is not set.

This property is not valid for a real-time connection to a broker.

JMSX_DELIVERY_COUNT
Data type:
xmsINT
Property of:
Message

The number of attempts to deliver the message.

This property is the JMS defined property with the JMS name JMSXDeliveryCount.
For more information about the property, see the Java Message Service Specification,
Version 1.1.

By default, the property is not set.

This property is not valid for a real-time connection to a broker.

JMSX_GROUPID
Data type:
String
Property of:
Message

The identifier of the message group to which the message belongs.

This property is the JMS defined property with the JMS name JMSXGroupID. For
more information about the property, see the Java Message Service Specification,
Version 1.1.

By default, the property is not set.

This property is not valid for a real-time connection to a broker.

JMSX_GROUPSEQ
Data type:
xmsINT

428 Message Service Client for C/C++

 Property of:
Message

The sequence number of the message within a message group.

This property is the JMS defined property with the JMS name JMSXGroupSeq. For
more information about the property, see the Java Message Service Specification,
Version 1.1.

By default, the property is not set.

This property is not valid for a real-time connection to a broker.

JMSX_USERID
Data type:
String
Property of:
Message

The user identifier associated with the application that sent the message.

This property is the JMS defined property with the JMS name JMSXUserID. For
more information about the property, see the Java Message Service Specification,
Version 1.1.

By default, the property is not set.

This property is not valid for a real-time connection to a broker.

XMSC_ASYNC_EXCEPTIONS
Data type:
xmsINT
Property of:
ConnectionFactory

This property determines whether XMS informs an ExceptionListener only when a

connection is broken, or when any exception occurs asynchronously to a XMS API
call. This applies to all Connections created from this ConnectionFactory that have
an ExceptionListener registered.

Valid values for this property are:

XMSC_ASYNC_EXCEPTIONS_ALL
Any exception detected asynchronously, outside the scope of a
synchronous API call, and all connection broken exceptions are sent to the
ExceptionListener.
XMSC_ASYNC_EXCEPTIONS_CONNECTIONBROKEN
Only exceptions indicating a broken connection are sent to the
ExceptionListener. Any other exceptions occurring during asynchronous
processing are not reported to the ExceptionListener, and hence the
application is not informed of these exceptions.

By default this property is set to XMSC_ASYNC_EXCEPTIONS_ALL.

Chapter 17. Properties of XMS objects 429

 XMSC_CLIENT_CCSID
Data type:
xmsINT
Property of:
Connection, ConnectionFactory, Session, MessageProducer, and
MessageConsumer

The identifier (CCSID) of the coded character set, or code page, used by a
connection, session, message producer, or message consumer. This property is used
in C and C++ only: it is not required in .NET. For further information, see “Coded
character set identifiers” on page 56.

The following named constants are defined for certain Unicode CCSIDs and can be
used when setting the property:

Named constant CCSID

XMSC_CCSID_UTF8 The UTF-8 representation of Unicode data
XMSC_CCSID_UTF16 The UTF-16 representation of Unicode data
XMSC_CCSID_UTF32 The UTF-32 representation of Unicode data

Instead of a CCSID, the property can have one of the following special values:
XMSC_CCSID_PROCESS
The object is using the code page identified by the process CCSID.
XMSC_CCSID_HOST
The object is using the code page identified by the CCSID that is derived
from the environment in which the application is running.
XMSC_CCSID_NO_CONVERSION
The character data in messages received by the object is not converted.

For more information about the property, including how it is set, see “Coded
character set identifiers” on page 56.

XMSC_CLIENT_ID
Data type:
String
Property of:
ConnectionFactory

The client identifier for a connection.

A client identifier is used only to support durable subscriptions in the

publish/subscribe domain, and is ignored in the point-to-point domain. For further
information about setting client identifiers, see “ConnectionFactories and
Connection objects” on page 36.

This property is not relevant for a real-time connection to a broker.

XMSC_CONNECTION_TYPE
Data type:
xmsINT

430 Message Service Client for C/C++

 Property of:
ConnectionFactory

The type of messaging server to which an application connects.

The valid values of the property are as follows:

Valid value Meaning

XMSC_CT_RTT A real-time connection to a broker.
XMSC_CT_WMQ A connection to a WebSphere MQ queue
manager.
XMSC_CT_WPM A connection to a WebSphere service integration
bus.

By default, the property is not set.

XMSC_DELIVERY_MODE
Data type:
xmsINT
Property of:
Destination
Name used in a URI:
persistence (for a WebSphere MQ destination)
deliveryMode (for a WebSphere default messaging provider destination)

The delivery mode of messages sent to the destination.

The valid values of the property are as follows:

Valid value Meaning

XMSC_DELIVERY_NOT_PERSISTENT A message sent to the destination is
nonpersistent. The default delivery
mode of the message producer, or any
delivery mode specified on the Send
call, is ignored. If the destination is a
WebSphere MQ queue, the value of the
queue attribute DefPersistence is also
ignored.
XMSC_DELIVERY_PERSISTENT A message sent to the destination is
persistent. The default delivery mode of
the message producer, or any delivery
mode specified on the Send call, is
ignored. If the destination is a
WebSphere MQ queue, the value of the
queue attribute DefPersistence is also
ignored.

Chapter 17. Properties of XMS objects 431

 Valid value Meaning
XMSC_DELIVERY_AS_APP A message sent to the destination has
the delivery mode specified on the Send
call. If the Send call specifies no delivery
mode, the default delivery mode of the
message producer is used instead. If the
destination is a WebSphere MQ queue,
the value of the queue attribute
DefPersistence is ignored.
XMSC_DELIVERY_AS_DEST If the destination is a WebSphere MQ
queue, a message put on the queue has
the delivery mode specified by the value
of the queue attribute DefPersistence.
The default delivery mode of the
message producer, or any delivery mode
specified on the Send call, is ignored.

If the destination is not a WebSphere

MQ queue, the meaning is the same as
that of XMSC_DELIVERY_AS_APP.

The default value is XMSC_DELIVERY_AS_APP.

XMSC_IC_PROVIDER_URL
Data type:
String
Property of:
InitialContext

Used to locate the JNDI naming directory so that the COS naming service does not
need to be on the same machine as the web service.

XMSC_IC_SECURITY_AUTHENTICATION
Data type:
String
Property of:
InitialContext

Based on the Java Context interface SECURITY_AUTHENTICATION. This

property is only applicable to the COS naming context.

XMSC_IC_SECURITY_CREDENTIALS
Data type:
String
Property of:
InitialContext

Based on the Java Context interface SECURITY_CREDENTIALS. This property is

only applicable to the COS naming context.

432 Message Service Client for C/C++

XMSC_IC_SECURITY_PRINCIPAL
Data type:
String
Property of:
InitialContext

Based on the Java Context interface SECURITY_PRINCIPAL. This property is only

applicable to the COS naming context.

XMSC_IC_SECURITY_PROTOCOL
Data type:
String
Property of:
InitialContext

Based on the Java Context interface SECURITY_PROTOCOL This property is only

applicable to the COS naming context.

XMSC_IC_URL
Data type:
String
Property of:
InitialContext

For LDAP and FileSystem contexts, the address of the repository containing
administered objects.

For COS naming contexts, the address of the web service that looks up the objects
in the directory.

XMSC_IS_SUBSCRIPTION_MULTICAST
Data type:
xmsBOOL
Property of:
MessageConsumer

Indicates whether messages are being delivered to the message consumer using
WebSphere MQ Multicast Transport. This property is read-only.

The value of the property is xmsTRUE if messages are being delivered to the
message consumer using WebSphere MQ Multicast Transport. Otherwise, the value
is xmsFALSE.

This property is relevant only for a real-time connection to a broker.

XMSC_IS_SUBSCRIPTION_RELIABLE_MULTICAST
Data type:
xmsBOOL

Chapter 17. Properties of XMS objects 433

 Property of:
MessageConsumer

Indicates whether messages are being delivered to the message consumer using
WebSphere MQ Multicast Transport with a reliable quality of service. This property
is read-only.

The value of the property is xmsTRUE if messages are being delivered to the
message consumer using WebSphere MQ Multicast Transport with a reliable
quality of service. Otherwise, the value is xmsFALSE.

This property is relevant only for a real-time connection to a broker.

XMSC_JMS_MAJOR_VERSION
Data type:
xmsINT
Property of:
ConnectionMetaData

The major version number of the JMS specification upon which XMS is based. This
property is read-only.

XMSC_JMS_MINOR_VERSION
Data type:
xmsINT
Property of:
ConnectionMetaData

The minor version number of the JMS specification upon which XMS is based. This
property is read-only.

XMSC_JMS_VERSION
Data type:
String
Property of:
ConnectionMetaData

The version identifier of the JMS specification upon which XMS is based. This
property is read-only.

XMSC_MAJOR_VERSION
Data type:
xmsINT
Property of:
ConnectionMetaData

The version number of the XMS client. This property is read-only.

434 Message Service Client for C/C++

XMSC_MINOR_VERSION
Data type:
xmsINT
Property of:
ConnectionMetaData

The release number of the XMS client. This property is read-only.

XMSC_PASSWORD
Data type:
Byte array
Property of:
ConnectionFactory

A password that can be used to authenticate the application when it attempts to

connect to a messaging server. The password is used in conjunction with the
XMSC_USERID property.

By default, the property is not set.

If you are connecting to WebSphere MQ, and you set the XMSC_USERID property
of the connection factory, it must match the userid of the logged on user. If you do
not set these properties, the queue manager will use the userid of the logged on
user by default. If you require further connection-level authentication of individual
users you can write a client authentication exit which is configured in WebSphere
MQ. You can learn more about creating a client authentication exit in the
Authentication topic in the WebSphere MQ Clients manual.

XMSC_PRIORITY
Data type:
xmsINT
Property of:
Destination
Name used in a URI:
priority

The priority of messages sent to the destination.

The valid values of the property are as follows:

Valid value Meaning

An integer in the range 0, the A message sent to the destination has the specified
lowest priority, to 9, the priority. The default priority of the message
highest priority producer, or any priority specified on the Send call,
is ignored. If the destination is a WebSphere MQ
queue, the value of the queue attribute DefPriority
is also ignored.

Chapter 17. Properties of XMS objects 435

 Valid value Meaning
XMSC_PRIORITY_AS_APP A message sent to the destination has the priority
specified on the Send call. If the Send call specifies
no priority, the default priority of the message
producer is used instead. If the destination is a
WebSphere MQ queue, the value of the queue
attribute DefPriority is ignored.
XMSC_PRIORITY_AS_DEST If the destination is a WebSphere MQ queue, a
message put on the queue has the priority specified
by the value of the queue attribute DefPriority.
The default priority of the message producer, or
any priority specified on the Send call, is ignored.

If the destination is not a WebSphere MQ queue,

the meaning is the same as that of
XMSC_PRIORITY_AS_APP.

The default value is XMSC_PRIORITY_AS_APP.

WebSphere MQ Real-Time Transport and WebSphere MQ Multicast Transport take

no action based upon the priority of a message.

XMSC_PROVIDER_NAME
Data type:
String
Property of:
ConnectionMetaData

The provider of the XMS client. This property is read-only.

XMSC_RTT_CONNECTION_PROTOCOL
Data type:
xmsINT
Property of:
ConnectionFactory

The communications protocol used for a real-time connection to a broker.

The value of the property must be XMSC_RTT_CP_TCP, which means a real-time

connection to a broker over TCP/IP. The default value is XMSC_RTT_CP_TCP.

XMSC_RTT_HOST_NAME
Data type:
String
Property of:
ConnectionFactory

The host name or IP address of the system on which a broker resides.

This property is used in conjunction with the XMSC_RTT_PORT property to

identify the broker.

436 Message Service Client for C/C++

 By default, the property is not set.
Related reference
“Network stack selection mechanism” on page 58
This section describes the network stack selection mechanism when both IPv4 and
IPv6 network stacks are enabled on a machine.

XMSC_RTT_LOCAL_ADDRESS
Data type:
String
Property of:
ConnectionFactory

The host name or IP address of the local network interface to be used for a
real-time connection to a broker.

This property is useful only if the system on which the application is running has
two or more network interfaces and you need to be able to specify which interface
must be used for a real-time connection. If the system has only one network
interface, only that interface can be used. If the system has two or more network
interfaces and the property is not set, the interface is selected at random.

By default, the property is not set.

Related reference
“Network stack selection mechanism” on page 58
This section describes the network stack selection mechanism when both IPv4 and
IPv6 network stacks are enabled on a machine.

XMSC_RTT_MULTICAST
Data type:
xmsINT
Property of:
ConnectionFactory and Destination
Name used in a URI:
mulicast

The multicast setting for a connection factory or destination. Only a destination

that is a topic can have this property.

An application uses this property to enable multicast in association with a

real-time connection to a broker and, if multicast is enabled, to specify the precise
way in which multicast is used to deliver messages from the broker to a message
consumer. The property has no effect on how a message producer sends messages
to the broker.

Chapter 17. Properties of XMS objects 437

 The valid values of the property are as follows:

Valid value Meaning

XMSC_RTT_MULTICAST_DISABLED Messages are not delivered to a
message consumer using WebSphere
MQ Multicast Transport. This is the
default value for a ConnectionFactory
object.
XMSC_RTT_MULTICAST_ASCF Messages are delivered to a message
consumer according to the multicast
setting for the connection factory
associated with the message
consumer. The multicast setting for
the connection factory is noted at the
time that the connection is created.
This value is valid only for a
Destination object, and is the default
value for a Destination object.
XMSC_RTT_MULTICAST_ENABLED If the topic is configured for multicast
in the broker, messages are delivered
to a message consumer using
WebSphere MQ Multicast Transport.
A reliable quality of service is used if
the topic is configured for reliable
multicast.
XMSC_RTT_MULTICAST_RELIABLE If the topic is configured for reliable
multicast in the broker, messages are
delivered to a message consumer
using WebSphere MQ Multicast
Transport with a reliable quality of
service. If the topic is not configured
for reliable multicast, you cannot
create a message consumer for the
topic.
XMSC_RTT_MULTICAST_NOT_RELIABLE If the topic is configured for multicast
in the broker, messages are delivered
to a message consumer using
WebSphere MQ Multicast Transport.
A reliable quality of service is not
used even if the topic is configured
for reliable multicast.

XMSC_RTT_PORT
Data type:
xmsINT
Property of:
ConnectionFactory

The number of the port on which a broker listens for incoming requests. On the
broker, you must configure a Real-timeInput or Real-timeOptimizedFlow message
processing node to listen on this port.

438 Message Service Client for C/C++

 This property is used in conjunction with the XMSC_RTT_HOST_NAME property
to identify the broker.

The default value of the property is XMSC_RTT_DEFAULT_PORT, or 1506.

XMSC_TIME_TO_LIVE
Data type:
xmsINT
Property of:
Destination
Name used in a URI:
expiry (for a WebSphere MQ destination)
timeToLive (for a WebSphere default messaging provider destination)

The time to live for messages sent to the destination.

The valid values of the property are as follows:

Valid value Meaning

0 A message sent to the destination never expires.
A positive integer A message sent to the destination has the
specified time to live in milliseconds. The default
time to live of the message producer, or any time
to live specified on the Send call, is ignored.
XMSC_TIME_TO_LIVE_AS_APP A message sent to the destination has the time to
live specified on the Send call. If the Send call
specifies no time to live, the default time to live
of the message producer is used instead.

The default value is XMSC_TIME_TO_LIVE_AS_APP.

XMSC_USERID
Data type:
String
Property of:
ConnectionFactory

A user identifier that can be used to authenticate the application when it attempts
to connect to a messaging server. The user identifier is used in conjunction with
the XMSC_PASSWORD property.

By default, the property is not set.

If you are connecting to WebSphere MQ, and you set the XMSC_USERID property
of the connection factory, it must match the userid of the logged on user. If you do
not set these properties, the queue manager will use the userid of the logged on
user by default. If you require further connection-level authentication of individual
users you can write a client authentication exit which is configured in WebSphere
MQ. You can learn more about creating a client authentication exit in the
Authentication topic in the WebSphere MQ Clients manual.

Chapter 17. Properties of XMS objects 439

 XMSC_VERSION
Data type:
String
Property of:
ConnectionMetaData

The version identifier of the XMS client. This property is read-only.

XMSC_WMQ_BROKER_CONTROLQ
Data type:
String
Property of:
ConnectionFactory

The name of the control queue used by a broker.

The default value of the property is SYSTEM.BROKER.CONTROL.QUEUE.

This property is relevant only in the publish/subscribe domain.

XMSC_WMQ_BROKER_PUBQ
Data type:
String
Property of:
ConnectionFactory

The name of the queue monitored by a broker where applications send messages
that they publish.

The default value of the property is SYSTEM.BROKER.DEFAULT.STREAM.

This property is relevant only in the publish/subscribe domain.

XMSC_WMQ_BROKER_QMGR
Data type:
String
Property of:
ConnectionFactory

The name of the queue manager to which a broker is connected.

By default, the property is not set.

This property is relevant only in the publish/subscribe domain.

XMSC_WMQ_BROKER_SUBQ
Data type:
String

440 Message Service Client for C/C++

 Property of:
ConnectionFactory

The name of the subscriber queue for a nondurable message consumer.

The name of the subscriber queue must start with the following characters:
SYSTEM.JMS.ND.

If you want all nondurable message consumers to share the same subscriber queue,
specify the complete name of the shared queue. A queue with the specified name
must exist before an application can create a nondurable message consumer.

If you want each nondurable message consumer to retrieve messages from its own
exclusive subscriber queue, specify a queue name that ends with an asterisk (*).
Subsequently, when an application creates a nondurable message consumer, the
XMS client creates a dynamic queue for exclusive use by the message consumer.
The XMS client uses the value of the property to set the contents of the
DynamicQName field in the object descriptor that is used to create the dynamic
queue.

The default value of the property is SYSTEM.JMS.ND.SUBSCRIBER.QUEUE, which

means that XMS uses the shared queue approach by default.

This property is relevant only in the publish/subscribe domain.

XMSC_WMQ_BROKER_VERSION
Data type:
xmsINT
Property of:
ConnectionFactory and Destination
Name used in a URI:
brokerVersion

The type of broker used by the application for a connection or for the destination.
Only a destination that is a topic can have this property.

The valid values of the property are as follows:

Valid value Meaning

XMSC_WMQ_BROKER_V1 The application is using a WebSphere MQ Publish/Subscribe
broker.

The application can also use this value if you have migrated
from WebSphere MQ Publish/Subscribe to WebSphere Event
Broker or WebSphere Message Broker but have not changed
the application.
XMSC_WMQ_BROKER_V2 The application is using a broker of WebSphere Event Broker
or WebSphere Message Broker.
XMSC_WMQ_BROKER_UNSPECIFIED After the broker has been migrated from Version 6 to Version
7, set this property so that RFH2 headers are no longer used.
After migration this property is no longer relevant.

The default value for a connectionfactory is

Chapter 17. Properties of XMS objects 441

 XMSC_WMQ_BROKER_UNSPECIFIED but, by default, the property is not set for
a destination. Setting the property for a destination overrides any value specified
by the connection factory property.

XMSC_WMQ_CCSID
Data type:
xmsINT
Property of:
Destination
Name used in a URI:
CCSID

The identifier (CCSID) of the coded character set, or code page, that the strings of
character data in the body of a message will be in when the XMS client forwards
the message to the destination. If set for an individual message, the
JMS_IBM_CHARACTER_SET property overrides the CCSID specified for the
destination by this property.

The default value of the property is 1208.

This property is relevant only to messages sent to the destination, not to messages
received from the destination.

XMSC_WMQ_CHANNEL
Data type:
String
Property of:
ConnectionFactory

The name of the channel to be used for a connection.

By default, the property is not set.

This property is relevant only when an application connects to a queue manager in

client mode.

XMSC_WMQ_CONNECTION_MODE
Data type:
xmsINT
Property of:
ConnectionFactory

The mode by which an application connects to a queue manager.

The valid values of the property are as follows:

Valid value Meaning

XMSC_WMQ_CM_BINDINGS A connection to a queue manager in bindings mode, for
optimal performance. This is the default value for C/C++.
XMSC_WMQ_CM_CLIENT A connection to a queue manager in client mode, to ensure
a fully managed stack.

442 Message Service Client for C/C++

XMSC_WMQ_DUR_SUBQ
Data type:
String
Property of:
Destination

The name of the subscriber queue for a durable subscriber that is receiving
messages from the destination. Only a destination that is a topic can have this
property.

The name of the subscriber queue must start with the following characters:
SYSTEM.JMS.D.

If you want all durable subscribers to share the same subscriber queue, specify the
complete name of the shared queue. A queue with the specified name must exist
before an application can create a durable subscriber.

If you want each durable subscriber to retrieve messages from its own exclusive
subscriber queue, specify a queue name that ends with an asterisk (*).
Subsequently, when an application creates a durable subscriber, the XMS client
creates a dynamic queue for exclusive use by the durable subscriber. The XMS
client uses the value of the property to set the contents of the DynamicQName field in
the object descriptor that is used to create the dynamic queue.

The default value of the property is SYSTEM.JMS.D.SUBSCRIBER.QUEUE, which

means that XMS uses the shared queue approach by default.

This property is relevant only in the publish/subscribe domain.

XMSC_WMQ_ENCODING
Data type:
xmsINT
Property of:
Destination

How numerical data in the body of a message will be represented when the XMS
client forwards the message to the destination. If set for an individual message, the
JMS_IBM_ENCODING property overrides the encoding specified for the
destination by this property. The property specifies the representation of binary
integers, packed decimal integers, and floating point numbers.

The valid values of the property are the same as the values that can be specified in
the Encoding field of a message descriptor. For more information about the
Encoding field, see the WebSphere MQ Application Programming Reference.

An application can use the following named constants to set the property:

Named constant Meaning

MQENC_INTEGER_NORMAL Normal integer encoding
MQENC_INTEGER_REVERSED Reversed integer encoding
MQENC_DECIMAL_NORMAL Normal packed decimal encoding
MQENC_DECIMAL_REVERSED Reversed packed decimal encoding
MQENC_FLOAT_IEEE_NORMAL Normal IEEE floating point encoding

Chapter 17. Properties of XMS objects 443

 Named constant Meaning
MQENC_FLOAT_IEEE_REVERSED Reversed IEEE floating point encoding
MQENC_FLOAT_S390 zSeries (System/390) architecture floating
point encoding
MQENC_NATIVE Native machine encoding

To form a value for the property, the application can add together three of these
constants as follows:
v A constant whose name commences with MQENC_INTEGER, to specify the
representation of binary integers
v A constant whose name commences with MQENC_DECIMAL, to specify the
representation of packed decimal integers
v A constant whose name commences with MQENC_FLOAT, to specify the
representation of floating point numbers
Alternatively, the application can set the property to MQENC_NATIVE, whose
value is environment dependent.

The default value of the property is MQENC_NATIVE.

This property is relevant only to messages sent to the destination, not to messages
received from the destination.

XMSC_WMQ_FAIL_IF_QUIESCE
Data type:
xmsINT
Property of:
ConnectionFactory and Destination
Name used in a URI:
failIfQuiesce

Whether calls to certain methods fail if the queue manager to which the
application is connected is in a quiescing state.

The valid values of the property are as follows:

Valid value Meaning

XMSC_WMQ_FIQ_YES Calls to certain methods fail if the queue manager is in a quiescing state.
When the application detects that the queue manager is quiescing, the
application can complete its immediate task and close the connection,
allowing the queue manager to stop.
XMSC_WMQ_FIQ_NO No method calls fail because the queue manager is in a quiescing state. If
you specify this value, the application cannot detect that the queue
manager is quiescing. The application might continue to perform
operations against the queue manager and therefore prevent the queue
manager from stopping.

The default value for a connection factory is XMSC_WMQ_FIQ_YES but, by

default, the property is not set for a destination. Setting the property for a
destination overrides any value specified by the connection factory property.

444 Message Service Client for C/C++

 For information about the different ways in which a queue manager can be
stopped, see the WebSphere MQ System Administration Guide.

XMSC_WMQ_MESSAGE_BODY
Data type:
xmsINT
Property of:
Destination

This property determines whether a XMS application processes the MQRFH2 of a

WebSphere MQ message as part of the message payload (that is, as part of the
message body).

Note: When sending messages to a destination, XMSC_WMQ_MESSAGE_BODY

property supersedes existing XMS Destination property
XMSC_WMQ_TARGET_CLIENT.

Valid values for this property are:

XMSC_WMQ_MESSAGE_BODY_JMS
Receive: The inbound XMS message type and body are determined by the
contents of the MQRFH2 (if present) or the MQMD (if there is no
MQRFH2) in the received MQ message.
Send: The outbound XMS message body contains a pre-pended and
auto-generated MQRFH2 header based on XMS Message properties and
header fields.
XMSC_WMQ_MESSAGE_BODY_MQ
Receive: The inbound XMS message type is always ByteMessage,
irrespective of the contents of received WebSphere MQ message or the
format field of the received MQMD. The XMS message body is the
unaltered message data returned by the underlying messaging provider
API call. The character set and encoding of the data in the message body is
determined by the CodedCharSetId and Encoding fields of the MQMD.
The format of the data in the message body is determined by the Format
field of the MQMD.
Send: The outbound XMS message body contains the application payload
as-is; and no auto-generated WMQ header is added to the body.
XMSC_WMQ_MESSAGE_BODY_UNSPECIFIED
Receive: The XMS client determines a suitable value for this property. On
receive path, this is simply WMQ_MESSAGE_BODY_JMS property value.
Send: The XMS client determines a suitable value for this property. On
send path, this is the value of XMSC_WMQ_TARGET_CLIENT property.

By default this property is set to XMSC_WMQ_MESSAGE_BODY_UNSPECIFIED.

Note: This property is not relevant only when an application connects to Service
integration bus

XMSC_WMQ_MQMD_MESSAGE_CONTEXT
Data type:
xmsINT

Chapter 17. Properties of XMS objects 445

 Property of:
Destination

Determines what level of message context is to be set by the XMS application. The
application must be running with appropriate context authority for this property to
take effect.

The valid values for this property are:

XMSC_WMQ_MDCTX_DEFAULT
For outbound messages, the MQOPEN API call and the MQPMO structure
will specify no explicit message context options.
XMSC_WMQ_MDCTX_SET_IDENTITY_CONTEXT
The MQOPEN API call specifies the message context option
MQOO_SET_IDENTITY_CONTEXT and the MQPMO structure specifies
MQPMO_SET_IDENTITY_CONTEXT.
XMSC_WMQ_MDCTX_SET_ALL_CONTEXT
The MQOPEN API call specifies the message context option
MQOO_SET_ALL_CONTEXT and the MQPMO structure specifies
MQPMO_SET_ALL_CONTEXT.

By default this property will be set to XMSC_WMQ_MDCTX_DEFAULT.

Note: This property is not relevant when an application connects to System

Integration Bus.

Following properties require XMSC_WMQ_MQMD_MESSAGE_CONTEXT

property to be set to XMSC_WMQ_MDCTX_SET_IDENTITY_CONTEXT property
value or XMSC_WMQ_MDCTX_SET_ALL_CONTEXT property value when
sending a message for in order to have desired effect:
v JMS_IBM_MQMD_USERIDENTIFIER
v JMS_IBM_MQMD_ACCOUNTINGTOKEN
v JMS_IBM_MQMD_APPLIDENTITYDATA

Following properties require XMSC_WMQ_MQMD_MESSAGE_CONTEXT

property to be set to XMSC_WMQ_MDCTX_SET_ALL_CONTEXT property value
when sending a message for in order to have desired effect:
v JMS_IBM_MQMD_PUTAPPLTYPE
v JMS_IBM_MQMD_PUTAPPLNAME
v JMS_IBM_MQMD_PUTDATE
v JMS_IBM_MQMD_PUTTIME
v JMS_IBM_MQMD_APPLORIGINDATA

For further information about the Message Context, see WebSphere MQ

Application Programming Guide book and WebSphere MQ Application
Programming Reference book.

XMSC_WMQ_MQMD_READ_ENABLED
Data type:
xmsINT
Property of:
Destination

446 Message Service Client for C/C++

 This property determines whether a XMS application can extract the values of
MQMD fields or not.

The valid values for this property are:

XMSC_WMQ_READ_ENABLED_NO
When sending messages, the JMS_IBM_MQMD* properties on a sent
message are not updated to reflect the updated field values in the MQMD.
When receiving messages, none of the JMS_IBM_MQMD* properties are
available on a received message, even if the sender had set some or all of
them.
XMSC_WMQ_READ_ENABLED_YES
When sending messages, all of the JMS_IBM_MQMD* properties on a sent
message are updated to reflect the updated field values in the MQMD,
including those that the sender did not set explicitly.
When receiving messages, all of the JMS_IBM_MQMD* properties are
available on a received message, including those that the sender did not
set explicitly.

By default this property is set to XMSC_WMQ_READ_ENABLED_NO.

XMSC_WMQ_MQMD_WRITE_ENABLED
Data type:
xmsINT
Property of:
Destination

This property determines whether a XMS application can set the values of MQMD
fields or not.

The valid values for this property are:

XMSC_WMQ_WRITE_ENABLED_NO
All JMS_IBM_MQMD* properties are ignored and their values are not
copied into the underlying MQMD structure.
XMSC_WMQ_WRITE_ENABLED_YES
JMS_IBM_MQMD* properties are processed. Their values are copied into
the underlying MQMD structure.

By default this property is set to XMSC_WMQ_WRITE_ENABLED_NO.

XMSC_WMQ_PUT_ASYNC_ALLOWED
Data type:
xmsINT
Property of:
Destination

This property determines whether message producers are allowed to use

asynchronous puts to send messages to this destination.

The valid values for this property are:

Chapter 17. Properties of XMS objects 447

 XMSC_WMQ _PUT_ASYNC_ALLOWED_AS_DEST
Determine whether asynchronous puts are allowed by referring to the
queue or topic definition.
XMSC_WMQ _PUT_ASYNC_ALLOWED_AS_Q_DEF
Determine whether asynchronous puts are allowed by referring to the
queue definition.
XMSC_WMQ _PUT_ASYNC_ALLOWED_AS_TOPIC_DEF
Determine whether asynchronous puts are allowed by referring to the topic
definition.
XMSC_WMQ _PUT_ASYNC_ALLOWED_DISABLED
Asynchronous puts are not allowed.
XMSC_WMQ _PUT_ASYNC_ALLOWED_ENABLED
Asynchronous puts are allowed.

By default this property is set to XMSC_WMQ

_PUT_ASYNC_ALLOWED_AS_DEST.

Note: This property is not relevant when an application is connecting to System

Integration Bus.

XMSC_WMQ_READ_AHEAD_ALLOWED
Data type:
xmsINT
Property of:
Destination

This property determines whether message consumers and queue browsers are
allowed to use read ahead to get non-persistent, non-transactional messages from
this destination into an internal buffer before receiving them.

The valid values for this property are:

XMSC_WMQ_READ_AHEAD_ALLOWED_AS_Q_DEF
Determine whether read ahead is allowed by referring to the queue
definition.
XMSC_WMQ_READ_AHEAD_ALLOWED_AS_ TOPIC _DEF
Determine whether read ahead is allowed by referring to the topic
definition.
XMSC_WMQ_READ_AHEAD_ALLOWED_AS_DEST
Determine whether read ahead is allowed by referring to the queue or
topic definition.
XMSC_WMQ_READ_AHEAD_ALLOWED_DISABLED
Read ahead is not allowed while consuming or browsing messages
XMSC_WMQ_READ_AHEAD_ALLOWED_ENABLED
Read ahead is allowed.

By default this property is set to XMSC_WMQ

_READ_AHEAD_ALLOWED_AS_DEST.

448 Message Service Client for C/C++

XMSC_WMQ_READ_AHEAD_CLOSE_POLICY
Data type:
xmsINT
Property of:
Destination

This property determines, for messages being delivered to an asynchronous

message listener, what happens to messages in the internal read ahead buffer when
the message consumer is closed.

This property is applicable in specifying closing queue options when consuming

messages from a destination and not applicable when sending messages to a
destination.

This property will be ignored for Queue Browsers since during browse the
messages will still be available in the queues.

The valid values for this property are:

XMSC_WMQ_READ_AHEAD_CLOSE_POLICY_DELIVER_CURRENT
Only the current message listener invocation completes before returning,
potentially leaving messages in the internal read ahead buffer, which are
then discarded.
XMSC_WMQ_READ_AHEAD_CLOSE_POLICY_DELIVER_ALL
All messages in the internal read ahead buffer are delivered to the
application’s message listener before returning. Please see Notes below.

By default this property is set to XMSC_WMQ

_READ_AHEAD_CLOSE_POLICY_DELIVER_CURRENT.

Notes:
v Abnormal application termination
All the messages in the read ahead buffer will be lost when a XMS application
terminates abruptly.
v Implications on Transactions
The read ahead will be disabled when the applications use transaction. So, the
application will not be seeing any difference in the behavior when they use
transacted sessions.
v Implications of Session Acknowledgement modes
The read ahead will be enabled when the on a non transacted session when the
acknowledgement modes are either XMSC_AUTO_ACKNOWLEDGE or
XMSC_DUPS_OK_ACKNOWLEDGE. The read ahead will be disabled if the
session acknowledgement mode is XMSC_CLIENT_ACKNOWLEDGE
irrespective of transacted or non transacted sessions.
v Implications on Queue Browsers and Queue Browser Selectors
The Queue Browsers and Queue Browser Selectors, used in XMS applications,
will get the performance advantage from read ahead. Closing the Queue
Browser won’t impact, since the message is still available in the queue for ay
further operations. There will not be any other implication on queue browsers
and queue browser selectors apart from performance benefits of read ahead.
v Implications of read ahead destination properties on WebSphere Message
Broker v6 or earlier queue managers

Chapter 17. Properties of XMS objects 449

 Specifying destination properties XMSC_WMQ_READ_AHEAD_ALLOWED and
XMSC_WMQ_READ_AHEAD_CLOSE_POLICY, when XMS application uses the
WebSphere Message Broker V6 queue manager will not be able to use the
specified values. These destination property values will be silently ignored and
the applications continue to work without read ahead. There will not be any
errors thrown when used with V6 queue managers.
v Consumer close
Closing a consumer that has been created with
XMSC_WMQ_READ_AHEAD_CLOSE_POLICY_DELIVER_ALL option after
stopping the connection might result in loss of messages which have already
been streamed.
v Connection close
Closing a connection without explicitly closing a consumer which has been
created with XMSC_WMQ_READ_AHEAD_CLOSE_POLICY_DELIVER_ALL
option might result in loss of messages which have already been streamed.

For further information about the Read Ahead, see WebSphere MQ Application
Programming Guide book and WebSphere MQ Application Programming
Reference book.

XMSC_WMQ_HOST_NAME
Data type:
String
Property of:
ConnectionFactory

The host name or IP address of the system on which a queue manager resides.

This property is used only when an application connects to a queue manager in

client mode. The property is used in conjunction with the XMSC_WMQ_PORT
property to identify the queue manager.

The default value of the property is localhost.

Related reference
“Network stack selection mechanism” on page 58
This section describes the network stack selection mechanism when both IPv4 and
IPv6 network stacks are enabled on a machine.

XMSC_WMQ_LOCAL_ADDRESS
Data type:
String
Property of:
ConnectionFactory

For a connection to a queue manager, this property specifies the local network
interface to be used, or the local port or range of local ports to be used, or both.

The value of the property is a string with the following format:

[host_name][(low_port)[,high_port])]

The meanings of the variables are as follows:

450 Message Service Client for C/C++

 host_name
The host name or IP address of the local network interface to be used for
the connection.
Providing this information is necessary only if the system on which the
application is running has two or more network interfaces and you need to
be able to specify which interface must be used for the connection. If the
system has only one network interface, only that interface can be used. If
the system has two or more network interfaces and you do not specify
which interface must be used, the interface is selected at random.
low_port
The number of the local port to be used for the connection.
If high_port is also specified, low_port is interpreted the lowest port number
in a range of port numbers.
high_port
The highest port number in a range of port numbers. One of the ports in
the specified range must be used for the connection.

The maximum length of the string is 48 characters.

Here are some examples of valid values of the property:

JUPITER
9.20.4.98
JUPITER(1000)
9.20.4.98(1000,2000)
(1000)
(1000,2000)
fecc:0:0:a2::2
fecc:0:0:a2::2(1000,2000)

By default, the property is not set.

This property is relevant only when an application connects to a queue manager in

client mode.
Related reference
“Network stack selection mechanism” on page 58
This section describes the network stack selection mechanism when both IPv4 and
IPv6 network stacks are enabled on a machine.

XMSC_WMQ_MESSAGE_SELECTION
Data type:
xmsINT
Property of:
ConnectionFactory

Determines whether message selection is done by the XMS client or by the broker.

The valid values of the property are as follows:

Valid value Meaning

XMSC_WMQ_MSEL_CLIENT Message selection is done by the XMS client.

Chapter 17. Properties of XMS objects 451

Valid value Meaning
XMSC_WMQ_MSEL_BROKER Message selection is done by the broker.

The default value is XMSC_WMQ_MSEL_CLIENT.

This property is relevant only in the publish/subscribe domain. Message selection

by the broker is not supported if the XMSC_WMQ_BROKER_VERSION property is
set to XMSC_WMQ_BROKER_V1.

XMSC_WMQ_MSG_BATCH_SIZE
Data type:
xmsINT
Property of:
ConnectionFactory

The maximum number of messages to be retrieved from a queue in one batch

when using asynchronous message delivery.

When an application is using asynchronous message delivery, under certain

conditions, the XMS client retrieves a batch of messages from a queue before
forwarding each message individually to the application. This property specifies
the maximum number of messages that can be in the batch.

The value of the property is a positive integer, and the default value is 10. Only
consider setting the property to a different value if you have a specific
performance problem that you need to address.

If an application is connected to a queue manager over a network, raising the

value of this property can reduce network overheads and response times, but
increase the amount of memory required to store the messages on the client
system. Conversely, lowering the value of this property might increase network
overheads and response times, but reduce the amount of memory required to store
the messages.

XMSC_WMQ_POLLING_INTERVAL
Data type:
xmsINT
Property of:
ConnectionFactory

If each message listener within a session has no suitable message on its queue, this
is the maximum interval, in milliseconds, that elapses before each message listener
tries again to get a message from its queue.

If it frequently happens that no suitable message is available for any of the

message listeners in a session, consider increasing the value of this property.

The value of the property is a positive integer. The default value is 5000.

XMSC_WMQ_PORT
Data type:
xmsINT

452 Message Service Client for C/C++

 Property of:
ConnectionFactory

The number of the port on which a queue manager listens for incoming requests.

This property is used only when an application connects to a queue manager in

client mode. The property is used in conjunction with the
XMSC_WMQ_HOST_NAME property to identify the queue manager.

The default value of the property is XMSC_WMQ_DEFAULT_CLIENT_PORT, or

1414.

XMSC_WMQ_PROVIDER_VERSION
Data type:
String
Property of:
ConnectionFactory

The version, release, modification level and fix pack of the queue manager to
which the application intends to connect. Valid values for this property are:
v Unspecified
Or a string in one of the following formats
v V.R.M.F
v V.R.M
v V.R
v V

Where V, R, M and F are integer values greater than or equal to zero.

A value of 7 or greater indicates that this is intended as a WebSphere MQ Version

7.0 ConnectionFactory for connections to a WebSphere MQ Version 7.0 queue
manager. A value lower than 7 (for example ″6.0.2.0″), indicates that it is intended
for use with queue managers earlier than Version 7.0. The default value,
unspecified, allows connections to any level of queue manager, determining the
applicable properties and functionality available based on the queue manager’s
capabilities.

By default this property is set to “unspecified”.

Note:
v No socket sharing happens if XMSC_WMQ_PROVIDER_VERSION is set
to 6. 2.
v Connection will fail if XMSC_WMQ_PROVIDER_VERSION is set to 7 and
on the server SHARECNV for the channel has been set 0.
v MQ v7 specific features will be disabled if
XMSC_WMQ_PROVIDER_VERSION is set to UNSPECIFIED and
SHARECNV is set to 0.

The version of WebSphere MQ Client also plays major role in whether a XMS
client application can use WebSphere MQ version 7 specific features. The following
table describes the behavior.

Chapter 17. Properties of XMS objects 453

 Note: A system property XMSC_WMQ_OVERRIDEPROVIDERVERSION has been
provided to override XMSC_WMQ_PROVIDER_VERSION property. This
can be used if you are unable to change connection factory setting.
Table 44. XMS client - Ability to use WebSphere MQ v7 specific features.
# XMSC_WMQ_PROVIDER_VERSION WebSphere MQ Client Version WebSphere MQ v7 features
1 unspecified 7 ON
2 unspecified 6 OFF
3 7 7 ON
4 7 6 Exception
5 6 6 OFF
6 6 7 OFF

XMSC_WMQ_PUB_ACK_INTERVAL
Data type:
xmsINT
Property of:
ConnectionFactory

The number of messages published by a publisher before the XMS client requests
an acknowledgement from the broker.

If you lower the value of this property, the client requests acknowledgements more
often, and therefore the performance of the publisher decreases. If you raise the
value, the client takes a longer time to throw an exception if the broker fails.

The value of the property is a positive integer. The default value is 25.

XMSC_WMQ_QMGR_CCSID
Data type:
xmsINT
Property of:
ConnectionFactory

The identifier (CCSID) of the coded character set, or code page, in which fields of
character data defined in the Message Queue Interface (MQI) are exchanged
between the XMS client and the WebSphere MQ client. This property does not
apply to the strings of character data in the bodies of messages.

When an XMS application connects to a queue manager in client mode, the XMS
client links to the WebSphere MQ client. The information exchanged between the
two clients contains fields of character data that are defined in the MQI. Under
normal circumstances, the WebSphere MQ client assumes that these fields are in
the code page of the system on which the clients are running. If the XMS client
provides and expects to receive these fields in a different code page, you must set
this property to inform the WebSphere MQ client.

When the WebSphere MQ client forwards these fields of character data to the
queue manager, the data in them must be converted if necessary into the code
page used by the queue manager. Similarly, when the WebSphere MQ client

454 Message Service Client for C/C++

 receives these fields from the queue manager, the data in them must be converted
if necessary into the code page in which the XMS client expects to receive the data.
The WebSphere MQ client uses this property to perform these data conversions.

By default, the property is not set.

Setting this property is equivalent to setting the MQCCSID environment variable

for a WebSphere MQ client that is supporting native WebSphere MQ client
applications. For more information about this environment variable, see WebSphere
MQ Clients.

XMSC_WMQ_QUEUE_MANAGER
Data type:
String
Property of:
ConnectionFactory

The name of the queue manager to connect to.

By default, the property is not set.

XMSC_WMQ_RECEIVE_EXIT
Data type:
String
Property of:
ConnectionFactory

Identifies a channel receive exit, or a sequence of channel receive exits, to be run in

succession.

The value of the property is a string of one or more items separated by commas,
where each item identifies a channel receive exit and has the following format:
libraryName(entryPointName)
For more information about the format of the string that identifies an individual
channel receive exit, see WebSphere MQ Intercommunication.

By default, the property is not set.

This property is relevant only when an application connects to a queue manager in

client mode.

XMSC_WMQ_RECEIVE_EXIT_INIT
Data type:
String
Property of:
ConnectionFactory

The user data that is passed to channel receive exits when they are called.

The value of the property is a string of one or more items of user data separated
by commas. By default, the property is not set.

Chapter 17. Properties of XMS objects 455

 Note the following rules when specifying user data that is passed to a sequence of
channel receive exits:
v If the number of items of user data in the string is more than the number of
channel receive exits in the sequence, the excess items of user data are ignored.
v If the number of items of user data in the string is less than the number of
channel receive exits in the sequence, each unspecified item of user data is set to
the empty string.
v Two commas is succession within the string, or a comma at the beginning of the
string, also denotes an unspecified item of user data.

This property is relevant only when an application connects to a queue manager in

client mode.

XMSC_WMQ_SECURITY_EXIT
Data type:
String
Property of:
ConnectionFactory

Identifies a channel security exit.

The value of the property is a string that identifies a channel security exit and has
the following format:
libraryName(entryPointName)
For more information about the format of the string that identifies a channel
security exit, see WebSphere MQ Intercommunication. The maximum length of the
string is 128 characters.

By default, the property is not set.

This property is relevant only when an application connects to a queue manager in

client mode.

XMSC_WMQ_SECURITY_EXIT_INIT
Data type:
String
Property of:
ConnectionFactory

The user data that is passed to a channel security exit when it is called.

The maximum length of the string of user data is 32 characters.

By default, the property is not set.

This property is relevant only when an application connects to a queue manager in

client mode.

XMSC_WMQ_SEND_EXIT
Data type:
String

456 Message Service Client for C/C++

 Property of:
ConnectionFactory

Identifies a channel send exit, or a sequence of channel send exits, to be run in

succession.

The value of the property is a string of one or more items separated by commas,
where each item identifies a channel send exit and has the following format:
libraryName(entryPointName)
For more information about the format of the string that identifies an individual
channel send exit, see WebSphere MQ Intercommunication.

By default, the property is not set.

This property is relevant only when an application connects to a queue manager in

client mode.

XMSC_WMQ_SEND_EXIT_INIT
Data type:
String
Property of:
ConnectionFactory

The user data that is passed to channel send exits when they are called.

The value of the property is a string of one or more items of user data separated
by commas. By default, the property is not set.

The rules for specifying user data that is passed to a sequence of channel send
exits are the same as those for specifying user data that is passed to a sequence of
channel receive exits. For the rules therefore, see
“XMSC_WMQ_RECEIVE_EXIT_INIT” on page 455.

This property is relevant only when an application connects to a queue manager in

client mode.

XMSC_WMQ_SEND_CHECK_COUNT
Data type:
xmsINT
Property of:
ConnectionFactory

The number of send calls to allow between checking for asynchronous put errors,
within a single non-transacted XMS session.

By default this property is set to 0.

XMSC_WMQ_SHARE_CONV_ALLOWED
Data type:
xmsINT

Chapter 17. Properties of XMS objects 457

 Property of:
ConnectionFactory

Whether a client connection can share its socket with other top-level XMS
connections from the same process to the same queue manager, if the channel
definitions match. This property is provided to allow complete isolation of
Connections in separate sockets if required for application development,
maintenance or operational reasons. Setting this property merely indicates to XMS
to make the underlying socket shared. It does not indicate how many connections
will share a single socket. The number of connections sharing a socket is
determined by SHARECONV value which is negotiated between MQI Client and
WMQ Server.

An application can set the following named constants to set the property:
v XMSC_WMQ_SHARE_CONV_ALLOWED_DISABLED - Connections will not
share a socket.
v XMSC_WMQ_SHARE_CONV_ALLOWED_ENABLED - Connections share a
socket.

By default the property is set to

XMSC_WMQ_SHARE_CONV_ALLOWED_ENABLED.

This property is relevant only when an application connects to a queue manager in

client mode.

XMSC_WMQ_SSL_CERT_STORES
Data type:
String
Property of:
ConnectionFactory

The locations of the servers that hold the certificate revocation lists (CRLs) to be
used on an SSL connection to a queue manager.

The value of the property is a list of one or more URLs separated by commas.
Each URL has the following format:
[user[/password]@]ldap://[serveraddress][:portnum][,...]

This format is compatible with, but extended from, the basic MQJMS format.

It is valid to have an empty ’serveraddress’. In this case, XMS assumes that the
value is the string ″localhost″.

An example list is:

myuser/mypassword@ldap://server1.mycom.com:389
ldap://server1.mycom.com
ldap://
ldap://:389

By default, the property is not set.

458 Message Service Client for C/C++

XMSC_WMQ_SSL_CIPHER_SPEC
Data type:
String
Property of:
ConnectionFactory

The name of the cipher spec to be used on a secure connection to a queue

manager.

The canonical values of this property that apply to XMS are:

v DES_SHA_EXPORT
v DES_SHA_EXPORT1024
v FIPS_WITH_3DES_EDE_CBC_SHA
v FIPS_WITH_DES_CBC_SHA
v NULL_MD5
v NULL_SHA
v RC2_MD5_EXPORT
v RC4_56_SHA_EXPORT1024
v RC4_MD5_EXPORT
v RC4_MD5_US
v RC4_SHA_US
v TLS_RSA_WITH_3DES_EDE_CBC_SHA
v TLS_RSA_WITH_AES_128_CBC_SHA
v TLS_RSA_WITH_AES_256_CBC_SHA
v TLS_RSA_WITH_DES_CBC_SHA
v TRIPLE_DES_SHA_US

For additional information about these values, see WebSphere MQ Security.

The following example shows how this value is supplied at the MQI:
strncpy(pChDef->SSLCipherSpec, "TRIPLE_DES_SHA_US", sizeof(pChDef->SSLCipherSpec));

XMS takes a copy of the first 32 bytes of the string in the correct single-byte code
page into the SSLCipherSpec field of the channel definition structure, MQCD
before calling MQCONNX.

If a value is specified for the XMSC_WMQ_SSL_CIPHER_SPEC property, this value

overrides any value that is specified for the XMSC_WMQ_SSL_CIPHER_SUITE
property. If neither of these properties has a specified value, the
MQCD.SSLCipherSpec field is filled with space characters.

The XMSC_WMQ_SSL_CIPHER_SPEC property is relevant only if the application

connects to a queue manager in client mode.

By default, the property is not set.

XMSC_WMQ_SSL_CIPHER_SUITE
Data type:
String

Chapter 17. Properties of XMS objects 459

 Property of:
ConnectionFactory

The name of the CipherSuite to be used on an SSL or TLS connection to a queue

manager. The protocol used in negotiating the secure connection depends on the
specified CipherSuite.

This property has the following canonical values:

v SSL_RSA_WITH_DES_CBC_SHA
v SSL_RSA_EXPORT1024_WITH_DES_CBC_SHA
v SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA
v SSL_RSA_FIPS_WITH_DES_CBC_SHA
v SSL_RSA_WITH_NULL_MD5
v SSL_RSA_WITH_NULL_SHA
v SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5
v SSL_RSA_EXPORT1024_WITH_RC4_56_SHA
v SSL_RSA_EXPORT_WITH_RC4_40_MD5
v SSL_RSA_WITH_RC4_128_MD5
v SSL_RSA_WITH_RC4_128_SHA
v SSL_RSA_WITH_3DES_EDE_CBC_SHA
v SSL_RSA_WITH_AES_128_CBC_SHA
v SSL_RSA_WITH_AES_256_CBC_SHA
v SSL_RSA_WITH_DES_CBC_SHA
v SSL_RSA_WITH_3DES_EDE_CBC_SHA

This value can be supplied as an alternative to XMSC_WMQ_SSL_CIPHER_SPEC.

If a non-empty value is specified for XMSC_WMQ_SSL_CIPHER_SPEC, this value

overrides the setting for XMSC_WMQ_SSL_CIPHER_SUITE. If
XMSC_WMQ_SSL_CIPHER_SPEC does not have a value, the value of
XMSC_WMQ_SSL_CIPHER_SUITE is used as the cipher suite to be given to GSKit.
In this case, the value is mapped on to the equivalent CipherSpec value, as
described in “CipherSuite and CipherSpec name mappings for connections to a
WebSphere MQ queue manager” on page 92.

If both XMSC_WMQ_SSL_CIPHER_SPEC and XMSC_WMQ_SSL_CIPHER_SUITE

are empty, the field pChDef->SSLCipherSpec is filled with spaces.

By default, the property is not set.

XMSC_WMQ_SSL_CRYPTO_HW
Data type:
String
Property of:
ConnectionFactory

Configuration details for the cryptographic hardware connected to the client

system.

This property has the following canonical values:

460 Message Service Client for C/C++

 v GSK_ACCELERATOR_RAINBOW_CS_OFF
v GSK_ACCELERATOR_RAINBOW_CS_ON
v GSK_ACCELERATOR_NCIPHER_NF_OFF
v GSK_ACCELERATOR_NCIPHER_NF_ON

There is a special format for PKCS11 cryptogragraphic hardware (where

DriverPath, TokenLabel and TokenPassword are user-specified strings):
GSK_PKCS11=PKCS#11 DriverPath; PKCS#11 TokenLabel;PKCS#11 TokenPassword

For additional information about the format of this property, see WebSphere MQ
Application Programming Reference.

XMS does not interpret or alter the contents of the string. It simply copies the
value supplied, up to a limit of 256 single-byte characters, into the
MQSCO.CryptoHardware field.

By default, the property is not set.

XMSC_WMQ_SSL_FIPS_REQUIRED
Data type:
Boolean
Property of:
ConnectionFactory

The value of this property determines whether an application can or cannot use
non-FIPS compliant cipher suites. If this property is set to true, only FIPS
algorithms are used for the client-server connection.

This property can have the following values, which translate to the two canonical
values for MQSCO.FipsRequired:
Table 45. Table of values for MQSCO.FlipsRequired property
Corresponding value of
Value Description MQSCO.FipsRequired
xmsFALSE Any CipherSpec can be used. MQSSL_FIPS_NO (the default)
xmsTRUE Only FIPS-certified cryptographic MQSSL_FIPS_YES
algorithms can be used in the
CipherSpec applying to this client
connection.

XMS copies the relevant value into MQSCO.FipsRequired before calling

MQCONNX.

The parameter MQSCO.FipsRequired is only available from WebSphere MQ

version 6. In the case of WebSphere MQ version 5.3, if this property is set, XMS
does not attempt to make the connection to the queue manager, and throws an
appropriate exception instead.

XMSC_WMQ_SSL_KEY_REPOSITORY
Data type:
String

Chapter 17. Properties of XMS objects 461

 Property of:
ConnectionFactory

The location of the key database file in which keys and certificates are stored.

XMS copies the string, up to a limit of 256 single-byte characters, into the
MQSCO.KeyRepository field. WebSphere MQ interprets this string as a filename,
including the full path.

By default, the property is not set.

XMSC_WMQ_SSL_KEY_RESETCOUNT
Data type:
xmsINT
Property of:
ConnectionFactory

The KeyResetCount represents the total number of unencrypted bytes sent and
received within an SSL conversation before the secret key is renegotiated. The
number of bytes includes control information sent by the MCA.

XMS copies the value that you supply for this property into
MQSCO.KeyResetCount before calling MQCONNX.

The parameter MQSCO.KeyRestCount is only available from WebSphere MQ

version 6. In the case of WebSphere MQ version 5.3, if this property is set, XMS
does not attempt to make the connection to the queue manager, and throws an
appropriate exception instead.

The default value of this property is zero, which means that secret keys are never
renegotiated. For further information, see the WebSphere MQ Application
Programming Reference.

XMSC_WMQ_SSL_PEER_NAME
Data type:
String
Property of:
ConnectionFactory

The peer name to be used on an SSL connection to a queue manager.

There is no list of canonical values for this property. Instead, you must build this
string according to the rules for SSLPEER described in WebSphere MQ Using Java
and WebSphere MQ Security.

An example of a peer name is:

"CN=John Smith, O=IBM ,OU=Test , C=GB"

XMS copies the string into the correct single-byte code page, and places the correct
values into MQCD.SSLPeerNamePtr and MQCD.SSLPeerNameLength before
calling MQCONNX.

462 Message Service Client for C/C++

 This property is relevant only if the application connects to a queue manager in
client mode.

By default, the property is not set.

XMSC_WMQ_SYNCPOINT_ALL_GETS
Data type:
xmsBOOL
Property of:
ConnectionFactory

Whether all messages must be retrieved from queues within syncpoint control.

The valid values of the property are as follows:

Valid value Meaning

xmsFALSE When the circumstances are appropriate, the
XMS client can retrieve messages from queues
outside of syncpoint control.
xmsTRUE The XMS client must retrieve all messages
from queues within syncpoint control.

The default value is xmsFALSE.

XMSC_WMQ_TARGET_CLIENT
Data type:
xmsINT
Property of:
Destination
Name used in a URI:
targetClient

Whether messages sent to the destination contain an MQRFH2 header.

If an application sends a message containing an MQRFH2 header, the receiving

application must be able to handle the header.

The valid values of the property are as follows:

Valid value Meaning

XMSC_WMQ_TARGET_DEST_JMS Messages sent to the destination contain an MQRFH2 header.
Specify this value if the application is sending the messages to
another XMS application, a WebSphere JMS application, or a
native WebSphere MQ application that has been designed to
handle an MQRFH2 header.
XMSC_WMQ_TARGET_DEST_MQ Messages sent to the destination do not contain an MQRFH2
header. Specify this value if the application is sending the
messages to a native WebSphere MQ application that has not
been designed to handle an MQRFH2 header.

The default value is XMSC_WMQ_TARGET_DEST_JMS.

Chapter 17. Properties of XMS objects 463

 XMSC_WMQ_TEMP_Q_PREFIX
Data type:
String
Property of:
ConnectionFactory

The prefix used to form the name of the WebSphere MQ dynamic queue that is
created when the application creates an XMS temporary queue.

The rules for forming the prefix are the same as those for forming the contents of
the DynamicQName field in an object descriptor, but the last non blank character
must be an asterisk(*). If the property is not set, the value used is CSQ.* on z/OS
and AMQ.* on the other platforms. By default, the property is not set.

This property is relevant only in the point-to-point domain.

XMSC_WMQ_TEMP_TOPIC_PREFIX
Data type:
String
Property of:
ConnectionFactory, Destination

When creating temporary topics, XMS will generate a topic string of the form
“TEMP/TEMPTOPICPREFIX/unique_id”, or if this property is left with the default
value, just “TEMP/unique_id”. Specifying a non-empty value allows specific
model queues to be defined for creating the managed queues for subscribers to
temporary topics created under this connection.

Any non-null string consisting only of valid characters for a WebSphere MQ topic
string is a valid value for this property.

By default this property is set to “” (empty string).

Note: This property is relevant only in the publish/subscribe domain.

XMSC_WMQ_TEMPORARY_MODEL
Data type:
String
Property of:
ConnectionFactory

The name of the WebSphere MQ model queue from which a dynamic queue is
created when the application creates an XMS temporary queue.

The default value of the property is SYSTEM.DEFAULT.MODEL.QUEUE.

This property is relevant only in the point-to-point domain.

XMSC_WMQ_WILDCARD_FORMAT
Data type:
xmsINT

464 Message Service Client for C/C++

 Property of:
ConnectionFactory, Destination

This property determines which version of wildcard syntax is to be used.

When using Publish/Subscribe with WebSphere MQ ‘*’ and ‘?’ are treated as
wildcards. Whereas ‘#’ and ‘+’ are treated as wildcards when using publish
subscribe with WebSphere Message Broker. This property replaces the
XMSC_WMQ_BROKER_VERSION property.

The valid values for this property are:

XMSC_WMQ_WILDCARD_TOPIC_ONLY
Recognizes the topic level wildcards only i.e. only ‘#’ and ‘+’ are treated as
wildcards. This value is same as XMSC_WMQ_BROKER_V2.
XMSC_WMQ_WILDCARD_CHAR_ONLY
Recognizes the character wildcards only i.e. ‘*’ and ‘?’ are treated as
wildcards. This value is same as XMSC_WMQ_BROKER_V1..

By default this property is set to XMSC_WMQ_WILDCARD_TOPIC_ONLY.

Note: This property is not relevant when doing publish/subscribe using

WebSphere MQ version 6 and below. Instead
XMSC_WMQ_BROKER_VERSION property must be used.

XMSC_WPM_BUS_NAME
Data type:
String
Property of:
ConnectionFactory and Destination
Name used in a URI:
busName

For a connection factory, the name of the service integration bus that the
application connects to or, for a destination, the name of the service integration bus
in which the destination exists.

For a destination that is a topic, this property is the name of the service integration
bus in which the associated topic space exists. This topic space is specified by the
XMSC_WPM_TOPIC_SPACE property.

If the property is not set for a destination, the queue or associated topic space is
assumed to exist in the service integration bus to which the application connects.

By default, the property is not set.

XMSC_WPM_CONNECTION_PROTOCOL
Data type:
xmsINT
Property of:
Connection

Chapter 17. Properties of XMS objects 465

 The communications protocol used for the connection to the messaging engine.
This property is read-only.

The possible values of the property are as follows:

Value Meaning
XMSC_WPM_CP_HTTP The connection uses HTTP over TCP/IP.
XMSC_WPM_CP_TCP The connection uses TCP/IP.

XMSC_WPM_CONNECTION_PROXIMITY
Data type:
xmsINT
Property of:
ConnectionFactory

The connection proximity setting for the connection. This property determines how
close the messaging engine that the application connects to must be to the
bootstrap server.

The valid values of the property are as follows:

Connection
Valid value proximity setting
XMSC_WPM_CONNECTION_PROXIMITY_BUS Bus
XMSC_WPM_CONNECTION_PROXIMITY_CLUSTER Cluster
XMSC_WPM_CONNECTION_PROXIMITY_HOST Host
XMSC_WPM_CONNECTION_PROXIMITY_SERVER Server

The default value is XMSC_WPM_CONNECTION_PROXIMITY_BUS.

For more information about connection proximity, WebSphere Application Server

Information Center.

XMSC_WPM_DUR_SUB_HOME
Data type:
String
Property of:
ConnectionFactory
Name used in a URI:
durableSubscriptionHome

The name of the messaging engine where all durable subscriptions for a
connection or a destination are managed. Messages to be delivered to the durable
subscribers are stored at the publication point of the same messaging engine.

A durable subscription home must be specified for a connection before an

application can create a durable subscriber that uses the connection. Any value
specified for a destination overrides the value specified for the connection.

By default, the property is not set.

This property is relevant only in the publish/subscribe domain.

466 Message Service Client for C/C++

XMSC_WPM_HOST_NAME
Data type:
String
Property of:
Connection

The host name or IP address of the system that contains the messaging engine to
which the application is connected. This property is read-only.

XMSC_WPM_LOCAL_ADDRESS
Data type:
String
Property of:
ConnectionFactory

For a connection to a service integration bus, this property specifies the local
network interface to be used, or the local port or range of local ports to be used, or
both.

The value of the property is a string with the following format:

[host_name][(low_port)[,high_port])]

The meanings of the variables are as follows:

host_name
The host name or IP address of the local network interface to be used for
the connection.
Providing this information is necessary only if the system on which the
application is running has two or more network interfaces and you need to
be able to specify which interface must be used for the connection. If the
system has only one network interface, only that interface can be used. If
the system has two or more network interfaces and you do not specify
which interface must be used, the interface is selected at random.
low_port
The number of the local port to be used for the connection.
If high_port is also specified, low_port is interpreted the lowest port number
in a range of port numbers.
high_port
The highest port number in a range of port numbers. One of the ports in
the specified range must be used for the connection.

Here are some examples of valid values of the property:

JUPITER
9.20.4.98
JUPITER(1000)
9.20.4.98(1000,2000)
(1000)
(1000,2000)
fecc:0:0:a2::2
fecc:0:0:a2::2(1000,2000)
Chapter 17. Properties of XMS objects 467
 By default, the property is not set.
Related reference
“Network stack selection mechanism” on page 58
This section describes the network stack selection mechanism when both IPv4 and
IPv6 network stacks are enabled on a machine.

XMSC_WPM_ME_NAME
Data type:
String
Property of:
Connection

The name of the messaging engine to which the application is connected. This
property is read-only.

XMSC_WPM_NON_PERSISTENT_MAP
Data type:
xmsINT
Property of:
ConnectionFactory

The reliability level of nonpersistent messages that are sent using the connection.

The valid values of the property are as follows:

Valid value Reliability level

XMSC_WPM_MAPPING_AS_DESTINATION Determined by the default
reliability level specified
for the queue or topic
space in the service
integration bus
XMSC_WPM_MAPPING_BEST_EFFORT_NON_ Best effort nonpersistent
PERSISTENT
XMSC_WPM_MAPPING_EXPRESS_NON_ Express nonpersistent
PERSISTENT
XMSC_WPM_MAPPING_RELIABLE_NON_ Reliable nonpersistent
PERSISTENT
XMSC_WPM_MAPPING_RELIABLE_PERSISTENT Reliable persistent
XMSC_WPM_MAPPING_ASSURED_PERSISTENT Assured persistent

The default value is XMSC_WPM_MAPPING_EXPRESS_NON_PERSISTENT.

For more information about message reliability levels, see the WebSphere
Application Server Information Center.

XMSC_WPM_PERSISTENT_MAP
Data type:
xmsINT
Property of:
ConnectionFactory

468 Message Service Client for C/C++

 The reliability level of persistent messages that are sent using the connection.

The valid values of the property are as follows:

Valid value Reliability level

XMSC_WPM_MAPPING_AS_DESTINATION Determined by the default
reliability level specified
for the queue or topic
space in the service
integration bus
XMSC_WPM_MAPPING_BEST_EFFORT_NON_ Best effort nonpersistent
PERSISTENT
XMSC_WPM_MAPPING_EXPRESS_NON_ Express nonpersistent
PERSISTENT
XMSC_WPM_MAPPING_RELIABLE_NON_ Reliable nonpersistent
PERSISTENT
XMSC_WPM_MAPPING_RELIABLE_PERSISTENT Reliable persistent
XMSC_WPM_MAPPING_ASSURED_PERSISTENT Assured persistent

The default value is XMSC_WPM_MAPPING_RELIABLE_PERSISTENT.

For more information about message reliability levels, see the WebSphere
Application Server Information Center.

XMSC_WPM_PORT
Data type:
xmsINT
Property of:
Connection

The number of the port listened on by the messaging engine to which the
application is connected. This property is read-only.

XMSC_WPM_PROVIDER_ENDPOINTS
Data type:
String
Property of:
ConnectionFactory

A sequence of one or more endpoint addresses of bootstrap servers. The endpoint

addresses are separated by commas.

A bootstrap server is an application server that is responsible for selecting the

messaging engine to which the application connects. The endpoint address of a
bootstrap server has the following format:
host_name:port_number:chain_name
The meanings of the components of an endpoint address are as follows:
host_name
The host name or IP address of the system on which the bootstrap server
resides. If no host name or IP address is specified, the default is localhost.

Chapter 17. Properties of XMS objects 469

 port_number
The number of the port on which the bootstrap server listens for incoming
requests. If no port number is specified, the default is 7276.
chain_name
The name of a bootstrap transport chain used by the bootstrap server. The
valid values are as follows:

Valid value Name of the bootstrap transport chain

XMSC_WPM_BOOTSTRAP_HTTP BootstrapTunneledMessaging
XMSC_WPM_BOOTSTRAP_HTTPS BootstrapTunneledSecureMessaging
XMSC_WPM_BOOTSTRAP_SSL BootstrapSecureMessaging
XMSC_WPM_BOOTSTRAP_TCP BootstrapBasicMessaging

If no name is specified, the default value is

XMSC_WPM_BOOTSTRAP_TCP.
For more information about bootstrap transport chains, see the WebSphere
Application Server Information Center.

If no endpoint address is specified, the default is

localhost:7276:BootstrapBasicMessaging.
Related reference
“Network stack selection mechanism” on page 58
This section describes the network stack selection mechanism when both IPv4 and
IPv6 network stacks are enabled on a machine.

XMSC_WPM_SSL_CIPHER_SUITE
Data type:
String
Property of:
ConnectionFactory

The name of the CipherSuite to be used on an SSL or TLS connection to a

WebSphere service integration bus messaging engine. The protocol used in
negotiating the secure connection depends on the specified CipherSuite.
Table 46. CipherSuite options for connection to a WebSphere service integration bus
messaging engine
Cipher suite Protocol used
SSL_RSA_WITH_NULL_MD5 SSLv3
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 SSLv3
SSL_RSA_EXPORT_WITH_RC4_40_MD5 SSLv3
SSL_RSA_WITH_RC4_128_MD5 SSLv3
SSL_RSA_WITH_NULL_SHA SSLv3
SSL_RSA_EXPORT1024_WITH_RC4_56_SHA SSLv3
SSL_RSA_WITH_RC4_128_SHA SSLv3
SSL_RSA_WITH_DES_CBC_SHA SSLv3
SSL_RSA_EXPORT1024_WITH_DES_CBC_SHA SSLv3
SSL_RSA_FIPS_WITH_DES_CBC_SHA SSLv3
SSL_RSA_WITH_3DES_EDE_CBC_SHA SSLv3

470 Message Service Client for C/C++

 Table 46. CipherSuite options for connection to a WebSphere service integration bus
messaging engine (continued)
Cipher suite Protocol used
SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA SSLv3
TLS_RSA_WITH_DES_CBC_SHA TLSv1
TLS_RSA_WITH_3DES_EDE_CBC_SHA TLSv1
TLS_RSA_WITH_AES_128_CBC_SHA TLSv1
TLS_RSA_WITH_AES_256_CBC_SHA TLSv1

Note: TLS_RSA_WITH_AES_128_CBC_SHA and

TLS_RSA_WITH_AES_256_CBC_SHA CipherSuites are supported on
Windows or Solaris only. (This is dictated by GSKit.)

There is no default for this property. If you want to use SSL or TLS, you must
specify a value for this property, otherwise your application will not be able to
connect successfully to the server.

XMSC_WPM_SSL_KEY_REPOSITORY
Data type:
String
Property of:
ConnectionFactory

A path to the file that is the keyring file containing the public or private keys to be
used in the secure connection.

Setting the keyring file property to the special value of

XMSC_WPM_SSL_MS_CERTIFICATE_STORE specifies the use the Microsoft
Windows key database. Using the Microsoft Windows key database, which is
found under Control Panel -> Internet Options -> Content -> Certificates,
removes the need for a separate key file database. Use of this constant on
Windows x64 and other platforms is not permitted.

By default, the property is not set.

XMSC_WPM_SSL_KEYRING_LABEL
Data type:
String
Property of:
ConnectionFactory

The certificate to be used when authenticating with the server. If no value is

specified, the default certificate is used.

By default, the property is not set.

XMSC_WPM_SSL_KEYRING_PW
Data type:
String

Chapter 17. Properties of XMS objects 471

 Property of:
ConnectionFactory

The password for the keyring file.

This property can be used as an alternative to using

XMSC_WPM_SSL_KEYRING_STASH_FILE to configure the password for the
keyring file.

By default, the property is not set.

XMSC_WPM_SSL_KEYRING_STASH_FILE
Data type:
String
Property of:
ConnectionFactory

The name of a binary file containing the password of the key repository file.

This property can be used as an alternative to using

XMSC_WPM_SSL_KEYRING_PW to configure the password for the keyring file.

By default, the property is not set.

XMSC_WPM_SSL_FIPS_REQUIRED
Data type:
Boolean
Property of:
ConnectionFactory

The value of this property determines whether an application can or cannot use
non-FIPS compliant cipher suites. If this property is set to true, only FIPS
algorithms are used for the client-server connection.Setting the value of this
property to TRUE prevents the application from using non-FIPS compliant cipher
suites.

By default, the property is set to FALSE (that is, FIPS mode off).

XMSC_WPM_TARGET_GROUP
Data type:
String
Property of:
ConnectionFactory

The name of a target group of messaging engines. The nature of the target group is
determined by the XMSC_WPM_TARGET_TYPE property.

Set this property if you want to restrict the search for a messaging engine to a
subgroup of the messaging engines in the service integration bus. If you want your
application to be able to connect to any messaging engine in the service integration
bus, do not set this property.

472 Message Service Client for C/C++

 By default, the property is not set.

XMSC_WPM_TARGET_SIGNIFICANCE
Data type:
xmsINT
Property of:
ConnectionFactory

The significance of the target group of messaging engines.

The valid values of the property are as follows:

Valid value Meaning

XMSC_WPM_TARGET_SIGNIFICANCE_ A messaging engine in the target
PREFERRED group is selected if one is available.
Otherwise, a messaging engine outside
the target group is selected, provided
it is in the same service integration
bus.
XMSC_WPM_TARGET_SIGNIFICANCE_ The selected messaging engine must
REQUIRED be in the target group. If a messaging
engine in the target group is not
available, the connection process fails.

The default value of the property is

XMSC_WPM_TARGET_SIGNIFICANCE_PREFERRED.

XMSC_WPM_TARGET_TRANSPORT_CHAIN
Data type:
String
Property of:
ConnectionFactory

The name of the inbound transport chain that the application must use to connect
to a messaging engine.

The value of the property can be the name of any inbound transport chain that is
available in the application server that hosts the messaging engine. The following
named constant is provided for one of the predefined inbound transport chains:

Named constant Name of transport chain

XMSC_WPM_TARGET_TRANSPORT_CHAIN_BASIC InboundBasicMessaging

The default value of the property is

XMSC_WPM_TARGET_TRANSPORT_CHAIN_BASIC.

XMSC_WPM_TARGET_TYPE
Data type:
xmsINT
Property of:
ConnectionFactory

Chapter 17. Properties of XMS objects 473

 The type of the target group of messaging engines. This property determines the
nature of the target group identified by the XMSC_WPM_TARGET_GROUP
property.

The valid values of the property are as follows:

Valid value Meaning

XMSC_WPM_TARGET_TYPE_BUSMEMBER The name of the target group is the
name of a bus member. The target
group is all the messaging engines
in the bus member.
XMSC_WPM_TARGET_TYPE_CUSTOM The name of the target group is the
name of a user defined group of
messaging engines. The target group
is all the messaging engines that are
registered with the user defined
group.
XMSC_WPM_TARGET_TYPE_ME The name of the target group is the
name of a messaging engine. The
target group is the specified
messaging engine.

By default, the property is not set.

XMSC_WPM_TEMP_Q_PREFIX
Data type:
String
Property of:
ConnectionFactory

The prefix used to form the name of the temporary queue that is created in the
service integration bus when the application creates an XMS temporary queue. The
prefix can contain up to 12 characters.

The name of a temporary queue starts with the characters “_Q” followed by the
prefix. The remainder of the name consists of system generated characters.

By default, the property is not set, which means that the name of a temporary
queue does not have a prefix.

This property is relevant only in the point-to-point domain.

XMSC_WPM_TEMP_TOPIC_PREFIX
Data type:
String
Property of:
ConnectionFactory

The prefix used to form the name of a temporary topic that is created by the
application. The prefix can contain up to 12 characters.

The name of a temporary topic starts with the characters “_T” followed by the
prefix. The remainder of the name consists of system generated characters.

474 Message Service Client for C/C++

 By default, the property is not set, which means that the name of a temporary
topic does not have a prefix.

This property is relevant only in the publish/subscribe domain.

XMSC_WPM_TOPIC_SPACE
Data type:
String
Property of:
Destination
Name used in a URI:
topicSpace

The name of the topic space that contains the topic. Only a destination that is a
topic can have this property.

By default, the property is not set, which means that the default topic space is
assumed.

This property is relevant only in the publish/subscribe domain.

Chapter 17. Properties of XMS objects 475

476 Message Service Client for C/C++
Appendix. Notices
This information was developed for products and services offered in the United
States. IBM may not offer the products, services, or features discussed in this
information in other countries. Consult your local IBM representative for
information on the products and services currently available in your area. Any
reference to an IBM product, program, or service is not intended to state or imply
that only that IBM product, program, or service may be used. Any functionally
equivalent product, program, or service that does not infringe any IBM intellectual
property right may be used instead. However, it is the user’s responsibility to
evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter
described in this information. The furnishing of this information does not give you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan, Ltd.
3-2-12, Roppongi, Minato-ku, Tokyo 106–8711, Japan

The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore this statement may not apply
to you.

This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the information. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
information at any time without notice.

Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.

© Copyright IBM Corp. 2005, 2009 477

Notices

Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM United Kingdom Laboratories,
Mail Point 151,
Hursley Park,
Winchester,
Hampshire,
England
SO21 2JN.

Such information may be available, subject to appropriate terms and conditions,

including in some cases, payment of a fee.

The licensed program described in this information and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Programming License Agreement, or any equivalent agreement
between us.

Information concerning non-IBM products was obtained from the suppliers of

those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which

illustrate programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs. The sample
programs are provided ″AS IS″, without warranty of any kind. IBM shall not be
liable for any damages arising out of your use of the sample programs.

Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of
International Business Machines Corporation in the United States, other countries,
or both. If these and other IBM trademarked terms are marked on their first
occurrence in this information with a trademark symbol (® or ™), these symbols
indicate U.S. registered or common law trademarks owned by IBM at the time this
information was published. Such trademarks may also be registered or common
law trademarks in other countries. A current list of IBM trademarks is available on
the Web at "Copyright and trademark information" at www.ibm.com/legal/
copytrade.shtml.

Intel is a trademark of Intel Corporation in the United States, other countries, or

both.

478 Message Service Client for C/C++

 Notices

Linux is a trademark of Linus Torvalds in the United States, other countries, or

both.

Microsoft and Windows are trademarks of Microsoft Corporation in the United

States, other countries, or both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the
United States, other countries, or both.

Other company, product, or service names may be trademarks or service marks of

others.

Appendix. Notices 479

480 Message Service Client for C/C++
Index
A C (continued)
using message listener functions 68
acknowledging messages 39 using the PropertyContext class 64
administered objects 42, 83 writing applications 63
attributes 12 C++
ConnectionFactory properties 84 application, using the C API 80
Destination properties 85 assigning XMS objects 73
retrieval 87 classes 273
AIX compilers 14
compilers 14 getting properties 73
installed directories 19 handling errors 76
uninstalling Message Service Client for C/C++ 22 methods returning a byte array 73
application, unexpected termination 112 sample applications 31
applications setting properties 73
building your own 58 using exception listeners 80
data types for elements in message body 102 using message listeners 78
sample 29 using namespaces 71
description 29 using the PropertyContext class 73
running 30 using the String class 72
writing writing applications 71
general 35 CCSID 56
in C 63 closing a connection 37
in C++ 71 coded character set identifier (CCSID) 56
ASF command line options 17, 18
Handling poison messages 50 communications
assigning XMS objects in C++ 73 securing 91
asynchronous message delivery 41 compiler flag settings 58
attribute, introduction 12 compilers 14
configuring
for an application that connects to a queue manager 25
B for an application that connects to a service integration
body types of messages 101 bus 28
building applications for an application that uses a real-time connection to a
your own 58 broker 27
byte array message server environment 25
C functions returning by reference 66 connecting to a service integration bus 37
C functions returning by value 65 Connection class
C++ methods returning 73 interface definition
bytes message 103 for C 144
BytesMessage class for C++ 284
interface definition object properties 403
for C 132 connection factory
for C++ 275 introduction 36
ConnectionFactory class
interface definition
C for C 149
for C++ 289
C object properties 404
additional functions 271 ConnectionMetaData class
classes 131 interface definition
compilers 14 for C 152
functions accepting a string as input 67 for C++ 292
functions returning a byte array by value 65 object properties 408
functions returning a string by value 64 connections
functions returning a string or byte array by reference 66 closing 37
getting properties 64 handling exceptions 37
handling errors 67 starting 36
object handles stopping 36
data types 63 converting a property value to another data type 52
sample applications 31
setting properties 64
using exception listener functions 69

© Copyright IBM Corp. 2005, 2009 481

D InitialContext class (continued)
interface definition (continued)
data types compatible with Java 52, 101, 102 for C++ 301
deleting objects 51 object properties 410
delivering messages to an application installation wizard 15
asynchronously 41 installed directories
synchronously 41 AIX 19
Destination class Linux 19
interface definition Solaris 19
for C 152 Windows (C/C++) 21
for C++ 293 installing XMS
object properties 409 from command line 17, 18
destinations Linux 15
administered objects silently 18
property mapping 83 Solaris 15
introduction 42 Windows 15
temporary 45 InvalidClientIDException class
durable subscribers 46 interface definition 303
InvalidDestinationException class
interface definition 303
E InvalidSelectorException class
environment variables 113 interface definition 304
ErrorBlock class Iterator class
interface definition 157 interface definition
errors for C 163
codes 58 for C++ 304
handling in C 67 iterators 55
handling in C++ 76
Exception class
interface definition J
for C++ 297 Java compatible data types 52, 101, 102
exception codes 58 JMS_IBM_ArmCorrelator property 417
exception listener functions, using in C 69 JMS_IBM_CHARACTER_SET property 418
exception listeners, using in C++ 80 JMS_IBM_ENCODING property 418
ExceptionListener class JMS_IBM_EXCEPTIONMESSAGE property 419
interface definition JMS_IBM_EXCEPTIONPROBLEMDESTINATION
for C 161 property 419
for C++ 300 JMS_IBM_EXCEPTIONREASON property 419
JMS_IBM_EXCEPTIONTIMESTAMP property 420
JMS_IBM_FEEDBACK property 420
F JMS_IBM_FORMAT property 420
First Failure Data Capture (FFDC) 112 JMS_IBM_LAST_MSG_IN_GROUP property 420
C and C++ applications 113 JMS_IBM_MSGTYPE property 421
JMS_IBM_PUTAPPLTYPE property 421
JMS_IBM_PUTDATE property 422
G JMS_IBM_PUTTIME property 422
JMS_IBM_REPORT_COA property 422
getting properties JMS_IBM_REPORT_COD property 423
in C 64 JMS_IBM_REPORT_DISCARD_MSG property 423
in C++ 73 JMS_IBM_REPORT_EXCEPTION property 424
JMS_IBM_REPORT_EXPIRATION property 424
JMS_IBM_REPORT_NAN property 425
H JMS_IBM_REPORT_PAN property 425
handles, object JMS_IBM_REPORT_PASS_CORREL_ID property 426
data types 63 JMS_IBM_REPORT_PASS_MSG_ID property 426
handling exceptions on a connection 37 JMS_IBM_RETAIN property 426
HTTP tunnelling 37 JMS_IBM_SYSTEM_MESSAGEID property 427
HTTPS 93 JMS_TOG_ARM_Correlator property 427
JMSX_APPID property 428
JMSX_DELIVERY_COUNT property 428
I JMSX_GROUPID property 428
JMSX_GROUPSEQ property 428
IllegalStateException class JMSX_USERID property 429
interface definition 301 JNDI Lookup web service
InitialContext class problems with accessing 115
interface definition JNDI Lookup Web service 88
for C 161

482 Message Service Client for C/C++

L MessageConsumer class
interface definition
Linux for C 194
compilers 14 for C++ 329
installed directories 19 object properties 415
installing XMS 15 MessageEOFException class
uninstalling Message Service Client for C/C++ 22 interface definition 333
log file creation, Linux or Solaris 17 MessageFormatException class
log file, creating 17 interface definition 333
MessageListener class
interface definition
M for C 198
map message 104 for C++ 333
MapMessage class MessageNotReadableException class
interface definition interface definition 334
for C 165 MessageNotWritableException class
for C++ 306 interface definition 334
mapping XMS messages onto WebSphere MQ messages 107 MessageProducer class
message interface definition
body 97, 101, 102 for C 199
body type for C++ 335
bytes 103 object properties 416
map 104 messages
object 104 acknowledging 39
stream 105 mapping onto WebSphere MQ messages 107
text 105 messaging
bytes 103 asynchronous delivery 41
delivery point-to-point 10
asynchronous 41 publish/subscribe 10
synchronous 41 styles 10
delivery mode 41 MQMD header
header fields 97 mapping XMS messages onto WebSphere MQ
map 104 messages 107
object 104 MQRFH2 header
properties 97 mapping XMS messages onto WebSphere MQ
application defined 101 messages 107
IBM-defined 100 XMSC_WMQ_TARGET_CLIENT property 463
JMS-defined 99 multithreaded
selectors 106 applications 35
stream 105 runtime libraries 58
text 105
Message class
interface definition N
for C 179 namespaces, using in C++ 71
for C++ 317 non-durable subscribers
object properties 411 cleanup of queues 48
Message consumers 46 nonpersistent messages 41
asynchronous 48
synchronous 48
message listener functions, using in C 68
message listeners, using in C++ 78 O
message model, XMS 13 object handles
Message object data types 63
body 97 object message 104
header fields 97 object model, XMS 10
properties 97 object properties 403
application defined 101 ObjectMessage class
IBM-defined 100 interface definition
JMS-defined 99 for C 207
Message producers 46 for C++ 343
associated destination 46 objects 12
no associated destination 46 administered 83
message server environment 25 attributes 12
Message Service Client for C/C++ deleting 51
installing 15 operating environments 14

Index 483
P property (continued)
JMSX_USERID 429
persistent messages 41 XMSC_ASYNC_EXCEPTIONS 429
point-to-point messaging 10 XMSC_CLIENT_CCSID 430
Poison messages 48 use in code page conversion 56
primitive types 52 XMSC_CLIENT_ID 430
problem determination XMSC_CONNECTION_TYPE 430
errors that cannot be handled at run time 112 XMSC_DELIVERY_MODE 431
FFDC and trace 113 XMSC_IC_PROVIDER_URL 432
introduction 111 XMSC_IC_SECURITY_AUTHENTICATION 432
runtime errors 111 XMSC_IC_SECURITY_CREDENTIALS 432
process CCSID 56 XMSC_IC_SECURITY_PRINCIPAL 433
process CCSID functions 271 XMSC_IC_SECURITY_PROTOCOL 433
properties XMSC_IC_URL 433
Connection object 403 XMSC_IS_SUBSCRIPTION_MULTICAST 433
ConnectionFactory object 404 XMSC_IS_SUBSCRIPTION_RELIABLE_MULTICAST 433
ConnectionMetaData object 408 XMSC_JMS_MAJOR_VERSION 434
Destination object 409 XMSC_JMS_MINOR_VERSION 434
getting XMSC_JMS_VERSION 434
in C 64 XMSC_MAJOR_VERSION 434
in C++ 73 XMSC_MINOR_VERSION 435
InitialContext object 410 XMSC_PASSWORD 435
introduction 403 XMSC_PRIORITY 435
Message object XMSC_PROVIDER_NAME 436
application defined 101 XMSC_RTT_CONNECTION_PROTOCOL 436
IBM-defined 100 XMSC_RTT_HOST_NAME 436
JMS-defined 99 XMSC_RTT_LOCAL_ADDRESS 437
list of properties 411 XMSC_RTT_MULTICAST 437
MessageConsumer object 415 XMSC_RTT_PORT 438
MessageProducer object 416 XMSC_TIME_TO_LIVE 439
Session object 416 XMSC_USERID 439
setting XMSC_VERSION 440
in C 64 XMSC_WMQ_BROKER_CONTROLQ 440
in C++ 73 XMSC_WMQ_BROKER_PUBQ 440
properties of objects 403 XMSC_WMQ_BROKER_QMGR 440
property XMSC_WMQ_BROKER_SUBQ 440
definitions 416 XMSC_WMQ_BROKER_VERSION 441
introduction 12 XMSC_WMQ_CCSID 442
JMS_IBM_ArmCorrelator 417 XMSC_WMQ_CHANNEL 442
JMS_IBM_CHARACTER_SET 418 XMSC_WMQ_CONNECTION_MODE 442
JMS_IBM_ENCODING 418 XMSC_WMQ_DUR_SUBQ 443
JMS_IBM_EXCEPTIONMESSAGE 419 XMSC_WMQ_ENCODING 443
JMS_IBM_EXCEPTIONPROBLEMDESTINATION 419 XMSC_WMQ_FAIL_IF_QUIESCE 444
JMS_IBM_EXCEPTIONREASON 419 XMSC_WMQ_HOST_NAME 450
JMS_IBM_EXCEPTIONTIMESTAMP 420 XMSC_WMQ_LOCAL_ADDRESS 450
JMS_IBM_FEEDBACK 420 XMSC_WMQ_MESSAGE_BODY 445
JMS_IBM_FORMAT 420 XMSC_WMQ_MESSAGE_SELECTION 451
JMS_IBM_LAST_MSG_IN_GROUP 420 XMSC_WMQ_MQMD_MESSAGE_CONTEXT 445
JMS_IBM_MSGTYPE 421 XMSC_WMQ_MQMD_READ_ENABLED 446
JMS_IBM_PUTAPPLTYPE 421 XMSC_WMQ_MQMD_WRITE_ENABLED 447
JMS_IBM_PUTDATE 422 XMSC_WMQ_MSG_BATCH_SIZE 452
JMS_IBM_PUTTIME 422 XMSC_WMQ_POLLING_INTERVAL 452
JMS_IBM_REPORT_COA 422 XMSC_WMQ_PORT 452
JMS_IBM_REPORT_COD 423 XMSC_WMQ_PROVIDER_VERSION 453
JMS_IBM_REPORT_DISCARD_MSG 423 XMSC_WMQ_PUB_ACK_INTERVAL 454
JMS_IBM_REPORT_EXCEPTION 424 XMSC_WMQ_PUT_ASYNC_ALLOWED 447
JMS_IBM_REPORT_EXPIRATION 424 XMSC_WMQ_QMGR_CCSID 454
JMS_IBM_REPORT_NAN 425 XMSC_WMQ_QUEUE_MANGER 455
JMS_IBM_REPORT_PAN 425 XMSC_WMQ_READ_AHEAD_ALLOWED 448
JMS_IBM_REPORT_PASS_CORREL_ID 426 XMSC_WMQ_READ_AHEAD_CLOSE_POLICY 449
JMS_IBM_REPORT_PASS_MSG_ID 426 XMSC_WMQ_RECEIVE_EXIT 455
JMS_IBM_RETAIN 426 XMSC_WMQ_RECEIVE_EXIT_INIT 455
JMS_IBM_SYSTEM_MESSAGEID 427 XMSC_WMQ_SECURITY_EXIT 456
JMS_TOG_ARM_Correlator 427 XMSC_WMQ_SECURITY_EXIT_INIT 456
JMSX_APPID 428 XMSC_WMQ_SEND_CHECK_COUNT 457
JMSX_DELIVERY_COUNT 428 XMSC_WMQ_SEND_EXIT 456
JMSX_GROUPID 428 XMSC_WMQ_SEND_EXIT_INIT 457
JMSX_GROUPSEQ 428

484 Message Service Client for C/C++

property (continued) receiving messages (continued)
XMSC_WMQ_SHARE_CONV_ALLOWED 457 synchronously 41
XMSC_WMQ_SSL_CERT_STORES 458 removing Message Service Client for C/C++
XMSC_WMQ_SSL_CIPHER_SPEC 459 AIX 22
XMSC_WMQ_SSL_CIPHER_SUITE 459 Linux 22
XMSC_WMQ_SSL_CRYPTO_HW 460 Windows
XMSC_WMQ_SSL_FIPS_REQUIRED 461 by running the uninstaller program 22
XMSC_WMQ_SSL_KEY_REPOSITORY 461 using Add/Remove Programs 22
XMSC_WMQ_SSL_KEY_RESETCOUNT 462 repository of administered objects
XMSC_WMQ_SSL_PEER_NAME 462 introduction 12
XMSC_WMQ_SYNCPOINT_ALL_GETS 463 supported types 83
XMSC_WMQ_TARGET_CLIENT 463 Requestor class
XMSC_WMQ_TEMP_Q_PREFIX 464 interface definition
XMSC_WMQ_TEMP_TOPIC_PREFIX 464 for C 242
XMSC_WMQ_TEMPORARY_MODEL 464 for C++ 370
XMSC_WMQ_WILDCARD_FORMAT 464 requestors, using 51
XMSC_WPM_BUS_NAME 465 ResourceAllocationException class
XMSC_WPM_CONNECTION_PROTOCOL 465 interface definition 373
XMSC_WPM_CONNECTION_PROXIMITY 466 response files, for samples 29
XMSC_WPM_DUR_SUB_HOME 466 return codes 67
XMSC_WPM_HOST_NAME 467 running the sample applications 30
XMSC_WPM_LOCAL_ADDRESS 467 runtime libraries 58
XMSC_WPM_ME_NAME 468
XMSC_WPM_NON_PERSISTENT_MAP 468
XMSC_WPM_PERSISTENT_MAP 468
XMSC_WPM_PORT 469
S
sample applications
XMSC_WPM_PROVIDER_ENDPOINTS 469
building C or C++ 31
XMSC_WPM_SSL_CIPHER_SUITE 470
description 29
XMSC_WPM_SSL_FIPS_REQUIRED 472
running 30
XMSC_WPM_SSL_KEY_REPOSITORY 471
using 29
XMSC_WPM_SSL_KEYRING_LABEL 471
securing communications 91
XMSC_WPM_SSL_KEYRING_PW 471
SecurityException class
XMSC_WPM_SSL_KEYRING_STASH_FILE 472
interface definition 373
XMSC_WPM_TARGET_GROUP 472
selectors, message 106
XMSC_WPM_TARGET_SIGNIFICANCE 473
service integration bus, connecting to 37
XMSC_WPM_TARGET_TRANSPORT_CHAIN 473
Session class
XMSC_WPM_TARGET_TYPE 473
interface definition
XMSC_WPM_TEMP_Q_PREFIX 474
for C 243
XMSC_WPM_TEMP_TOPIC_PREFIX 474
for C++ 373
XMSC_WPM_TOPIC_SPACE 475
object properties 416
Property class
sessions
interface definition
asynchronous message delivery 41
for C 209
introduction 38
for C++ 345
synchronous message delivery 41
Property value, converting form one datatype to another 52
transacted 38
PropertyContext class
setting properties
interface definition
in C 64
for C 223
in C++ 73
for C++ 357
setup
using in C 64
for an application that connects to a queue manager 25
using in C++ 73
for an application that connects to a service integration
publish/subscribe messaging 10, 48
bus 28
for an application that uses a real-time connection to a
broker 27
Q message server environment 25
queue browser, using 50 silent installation 17, 18
queue uniform resource identifiers (URIs) 44 Solaris
QueueBrowser class compilers 14
interface definition installed directories 19
for C 239 installing XMS 15
for C++ 368 SSL 91, 93
starting a connection 36
stopping a connection 36
R stream message 105
StreamMessage class
receiving messages
interface definition
asynchronously 41
for C 256

Index 485
StreamMessage class (continued)
interface definition (continued)
X
for C++ 385 XMS
string compilers 14
C functions accepting as input 67 message model 13
C functions returning by reference 66 object model 10
C functions returning by value 64 operating environments 14
String class threading model 35
interface definition 395 XMSC_ASYNC_EXCEPTIONS property 429
using in C++ 72 XMSC_CLIENT_CCSID property 430
styles of messaging 10 use in code page conversion 56
subscriber queue 46 XMSC_CLIENT_ID property 430
synchronous message delivery 41 XMSC_CONNECTION_TYPE property 430
XMSC_DELIVERY_MODE property 431
XMSC_IC_PROVIDER_URL property 432
XMSC_IC_SECURITY_AUTHENTICATION property 432
T XMSC_IC_SECURITY_CREDENTIALS property 432
temporary destinations 45 XMSC_IC_SECURITY_PRINCIPAL property 433
text message 105 XMSC_IC_SECURITY_PROTOCOL property 433
TextMessage class XMSC_IC_URL property 433
interface definition XMSC_IS_SUBSCRIPTION_MULTICAST property 433
for C 268 XMSC_IS_SUBSCRIPTION_RELIABLE_MULTICAST
for C++ 399 property 433
threading model 35 XMSC_JMS_MAJOR_VERSION property 434
topic uniform resource identifiers (URIs) 42 XMSC_JMS_MINOR_VERSION property 434
trace, configuration 113 XMSC_JMS_VERSION property 434
trademarks 478 XMSC_MAJOR_VERSION property 434
transacted sessions 38 XMSC_MINOR_VERSION property 435
TransactionInProgressException class XMSC_PASSWORD property 435
interface definition 400 XMSC_PRIORITY property 435
TransactionRolledBackException class XMSC_PROVIDER_NAME property 436
interface definition 400 XMSC_RTT_CONNECTION_PROTOCOL property 436
troubleshooting 111 XMSC_RTT_HOST_NAME property 436
tips 115 XMSC_RTT_LOCAL_ADDRESS property 437
XMSC_RTT_MULTICAST property 437
XMSC_RTT_PORT property 438
U XMSC_TIME_TO_LIVE property 439
uniform resource identifiers (URIs) XMSC_USERID property 439
introduction 42 XMSC_VERSION property 440
queue 44 XMSC_WMQ_BROKER_CONTROLQ property 440
topic 42 XMSC_WMQ_BROKER_PUBQ property 440
uninstalling Message Service Client for C/C++ XMSC_WMQ_BROKER_QMGR property 440
AIX 22 XMSC_WMQ_BROKER_SUBQ property 440
Linux 22 XMSC_WMQ_BROKER_VERSION property 441
Windows XMSC_WMQ_CCSID property 442
by running the uninstaller program 22 XMSC_WMQ_CHANNEL property 442
using Add/Remove Programs 22 XMSC_WMQ_CONNECTION_MODE property 442
URI 42 XMSC_WMQ_DUR_SUBQ property 443
XMSC_WMQ_ENCODING property 443
XMSC_WMQ_FAIL_IF_QUIESCE property 444
XMSC_WMQ_HOST_NAME property 450
W XMSC_WMQ_LOCAL_ADDRESS property 450
wildcard characters XMSC_WMQ_MESSAGE_BODY property 445
in topic URIs 42 XMSC_WMQ_MESSAGE_SELECTION property 451
Windows XMSC_WMQ_MQMD_MESSAGE_CONTEXT property 445
AIX XMSC_WMQ_MQMD_READ_ENABLED property 446
installing XMS 15 XMSC_WMQ_MQMD_WRITE_ENABLED property 447
compilers 14 XMSC_WMQ_MSG_BATCH_SIZE property 452
installed directories (C/C++) 21 XMSC_WMQ_POLLING_INTERVAL property 452
installing XMS 15 XMSC_WMQ_PORT property 452
uninstalling Message Service Client for C/C++ XMSC_WMQ_PROVIDER_VERSION property 453
by running the uninstaller program 22 XMSC_WMQ_PUB_ACK_INTERVAL property 454
using Add/Remove Programs 22 XMSC_WMQ_PUT_ASYNC_ALLOWED property 447
writing applications XMSC_WMQ_QMGR_CCSID property 454
general 35 XMSC_WMQ_QUEUE_MANGER property 455
in C 63 XMSC_WMQ_READ_AHEAD_ALLOWED property 448
in C++ 71 XMSC_WMQ_READ_AHEAD_CLOSE_POLICY property 449
XMSC_WMQ_RECEIVE_EXIT property 455

486 Message Service Client for C/C++

XMSC_WMQ_RECEIVE_EXIT_INIT property 455
XMSC_WMQ_SECURITY_EXIT property 456
XMSC_WMQ_SECURITY_EXIT_INIT property 456
XMSC_WMQ_SEND_CHECK_COUNT property 457
XMSC_WMQ_SEND_EXIT property 456
XMSC_WMQ_SEND_EXIT_INIT property 457
XMSC_WMQ_SHARE_CONV_ALLOWED property 457
XMSC_WMQ_SSL_CERT_STORES property 458
XMSC_WMQ_SSL_CIPHER_SPEC property 459
XMSC_WMQ_SSL_CIPHER_SUITE property 459
XMSC_WMQ_SSL_CRYPTO_HW property 460
XMSC_WMQ_SSL_FIPS_REQUIRED property 461
XMSC_WMQ_SSL_KEY_REPOSITORY property 461
XMSC_WMQ_SSL_KEY_RESETCOUNT property 462
XMSC_WMQ_SSL_PEER_NAME property 462
XMSC_WMQ_SYNCPOINT_ALL_GETS property 463
XMSC_WMQ_TARGET_CLIENT property 463
XMSC_WMQ_TEMP_Q_PREFIX property 464
XMSC_WMQ_TEMP_TOPIC_PREFIX property 464
XMSC_WMQ_TEMPORARY_MODEL property 464
XMSC_WMQ_WILDCARD_FORMAT property 464
XMSC_WPM_BUS_NAME property 465
XMSC_WPM_CONNECTION_PROTOCOL property 465
XMSC_WPM_CONNECTION_PROXIMITY property 466
XMSC_WPM_DUR_SUB_HOME property 466
XMSC_WPM_HOST_NAME property 467
XMSC_WPM_LOCAL_ADDRESS property 467
XMSC_WPM_ME_NAME property 468
XMSC_WPM_NON_PERSISTENT_MAP property 468
XMSC_WPM_PERSISTENT_MAP property 468
XMSC_WPM_PORT property 469
XMSC_WPM_PROVIDER_ENDPOINTS property 469
XMSC_WPM_SSL_CIPHER_SUITE property 470
XMSC_WPM_SSL_FIPS_REQUIRED property 472
XMSC_WPM_SSL_KEY_REPOSITORY property 471
XMSC_WPM_SSL_KEYRING_LABEL property 471
XMSC_WPM_SSL_KEYRING_PW property 471
XMSC_WPM_SSL_KEYRING_STASH_FILE property 472
XMSC_WPM_SSL_MS_CERTIFICATE_STORE 471
XMSC_WPM_TARGET_GROUP property 472
XMSC_WPM_TARGET_SIGNIFICANCE property 473
XMSC_WPM_TARGET_TRANSPORT_CHAIN property 473
XMSC_WPM_TARGET_TYPE property 473
XMSC_WPM_TEMP_Q_PREFIX property 474
XMSC_WPM_TEMP_TOPIC_PREFIX property 474
XMSC_WPM_TOPIC_SPACE property 475

Index 487
488 Message Service Client for C/C++
Sending your comments to IBM
If you especially like or dislike anything about this book, please use one of the
methods listed below to send your comments to IBM.

Feel free to comment on what you regard as specific errors or omissions, and on
the accuracy, organization, subject matter, or completeness of this book.

Please limit your comments to the information in this book and the way in which
the information is presented.

To make comments about the functions of IBM products or systems, talk to your
IBM representative or to your IBM authorized remarketer.

When you send comments to IBM, you grant IBM a nonexclusive right to use or
distribute your comments in any way it believes appropriate, without incurring
any obligation to you.

You can send your comments to IBM in any of the following ways:
v By mail, to this address:
User Technologies Department (MP095)
IBM United Kingdom Laboratories
Hursley Park
WINCHESTER,
Hampshire
SO21 2JN
United Kingdom
v By fax:
– From outside the U.K., after your international access code use
44–1962–816151
– From within the U.K., use 01962–816151
v Electronically, use the appropriate network ID:
– IBM Mail Exchange: GBIBM2Q9 at IBMMAIL
– IBMLink™: HURSLEY(IDRCF)
– Internet: [email protected]

Whichever method you use, ensure that you include:

v The publication title and order number
v The topic to which your comment applies
v Your name and address/telephone number/fax number/network ID.

© Copyright IBM Corp. 2005, 2009 489

490 Message Service Client for C/C++



SC34-6984-01
Spine information:

IBM WebSphere Business Integration Version 2.0.1 Message Service Client for C/C++