Message Service Clients for C/C++ and .NET

WebSphere WebSphere Business Integration
®
Version 1.1
Message Service Clients for C/C++ and .NET
SC34-6658-00
Note!
Before using this information and the product it supports, be sure to read the general information under “Notices,” on page
575.
1.1 edition (September 2005)
This edition applies to IBM Message Service Client for C/C++, Version 1.1, and to IBM Message Service Client for
.NET, Version 1.1 Beta, and to any subsequent releases and modifications until otherwise indicated in new editions.
Parts of the specification of the API provided by Message Service Clients for C/C++ and .NET 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. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
About this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Who this book is for . . . . . . . .
What you need to know to understand this
Terms used in this book . . . . . .
How to use this book . . . . . . .
. .
book
. .
. .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. xvii
. xvii
. xviii
. xviii
.
.
Summary of changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
Changes for this edition (SC34-6658-00) .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. xxi
Part 1. Getting started with Message Service Clients for C/C++ and .NET. . . . . 1
Chapter 1. Introducing Message Service Clients for C/C++ and .NET
What are Message Service Clients for C/C++ and .NET?
Styles of messaging . . . . . . . . . . . . .
The XMS object model . . . . . . . . . . . .
Attributes and properties of objects . . . . . . .
Administered objects . . . . . . . . . . .
The XMS message model . . . . . . . . . . .
Operating environments . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . . . . . . . . 3
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3
4
4
6
7
8
8
Chapter 2. Installing Message Service Clients for C/C++ and .NET . . . . . . . . . . 11
Installing Message Service Client for C/C++ . . . . . . . . . . .
Installing Message Service Client for C/C++ using the installation wizard
Installing from the command line . . . . . . . . . . . . . .
What is installed on Linux and Solaris . . . . . . . . . . . .
What is installed on Windows (C/C++) . . . . . . . . . . . .
Uninstalling Message Service Client for C/C++ . . . . . . . . .
Installing Message Service Client for .NET . . . . . . . . . . . .
Installing Message Service Client for .NET using the installation wizard .
What is installed on Windows (.NET). . . . . . . . . . . . .
Uninstalling Message Service Client for .NET . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
11
11
13
13
15
16
17
17
18
19
Chapter 3. Using XMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Setting up the messaging server environment . . . . . . . . . . . . . . . . . . . . . .
Configuring the queue manager and broker for an application that connects to a WebSphere MQ queue
manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring the broker for an application that uses a real-time connection to a broker . . . . . . .
Configuring the service integration bus for an application that connects to a WebSphere service integration
Using the sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . .
Running the sample applications . . . . . . . . . . . . . . . . . . . . . . . . .
Building the C or C++ sample applications . . . . . . . . . . . . . . . . . . . . . .
Building the .NET sample applications . . . . . . . . . . . . . . . . . . . . . . .
Building your own applications . . . . . . . . . . . . . . . . . . . . . . . . . .
.
. 21
. .
. .
bus
. .
. .
. .
. .
. .
21
22
23
24
26
26
27
27
Chapter 4. Problem determination . . . . . . . . . . . . . . . . . . . . . . . . 29
Problem determination for C/C++ applications . . .
Error conditions that can be handled at run time . .
Error conditions that cannot be handled at run time .
Repeatable failures . . . . . . . . . . . .
© Copyright IBM Corp. 2005
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
29
29
30
31
iii
Working with FFDC and trace for C/C++ applications
Configuring trace for .NET applications . . . . . .
Trace configuration using an application configuration
Trace configuration using XMS environment variables
Configuring FFDC for .NET applications . . . . .
. .
. .
file.
. .
. .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
31
33
34
35
36
Part 2. Programming with XMS . . . . . . . . . . . . . . . . . . . . . . . . 37
Chapter 5. Writing XMS applications . . . . . . . . . . . . . . . . . . . . . . . 39
The threading model . . . . . . . . . . . . .
Connections . . . . . . . . . . . . . . . .
Starting and stopping a connection . . . . . . .
Closing a connection . . . . . . . . . . . .
Handling exceptions . . . . . . . . . . . .
Connecting to a WebSphere service integration bus . .
Sessions . . . . . . . . . . . . . . . . .
Transacted sessions . . . . . . . . . . . . .
Acknowledging the receipt of messages in a session . .
Asynchronous message delivery . . . . . . . .
Synchronous message delivery . . . . . . . . .
Message delivery mode . . . . . . . . . . .
Destinations . . . . . . . . . . . . . . . .
Topic uniform resource identifiers (URIs) . . . . .
Queue uniform resource identifiers (URIs) . . . . .
Temporary destinations . . . . . . . . . . .
Message producers with no associated destination . . .
Durable subscribers. . . . . . . . . . . . . .
Non-durable subscribers . . . . . . . . . . . .
Queue browsers . . . . . . . . . . . . . . .
Requestors. . . . . . . . . . . . . . . . .
Deleting objects . . . . . . . . . . . . . . .
Implicit conversion of a property value from one data type
Iterators . . . . . . . . . . . . . . . . .
Coded character set identifiers (CCSIDs). . . . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
to another
. . . .
. . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
39
40
40
40
41
41
42
42
43
44
45
45
45
46
48
48
49
49
51
51
52
52
53
55
56
Chapter 6. Writing XMS applications in C . . . . . . . . . . . . . . . . . . . . . 59
Object handles in C . . . . . . . . . . . . . .
Getting and setting properties in C . . . . . . . .
Using message and exception listener functions in C . .
Using message listener functions in C . . . . . .
Using exception listener functions in C . . . . . .
C functions that return a string by value . . . . . .
C functions that return a byte array by value . . . . .
C functions that return a string or byte array by reference .
C functions that accept a string as input . . . . . . .
Handling errors in C . . . . . . . . . . . . .
Return codes . . . . . . . . . . . . . . .
The error block . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
59
60
60
60
61
62
62
63
64
64
64
65
Chapter 7. Writing XMS applications in C++ . . . . . . . . . . . . . . . . . . . . 67
Using namespaces in C++ . . . .
Using the String class in C++ . . .
C++ methods that return a byte array
Getting and setting properties in C++
Handling errors in C++ . . . . .
Using message and exception listeners
Using message listeners in C++ . .
Using exception listeners in C++ .
Assigning XMS objects in C++ . . .
Using the C API in a C++ application
iv
. . .
. . .
. . .
. . .
. . .
in C++ .
. . .
. . .
. . .
. . .
Message Service Clients for C/C++ and .NET
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
67
68
68
69
69
71
72
73
74
76
Chapter 8. Writing .NET applications . . . . . . . . . . . . . . . . . . . . . . . 79
Destinations in .NET . . . . . . . . .
Getting and setting properties in .NET . . .
Handling of non-existent properties in .NET .
Handling errors in .NET . . . . . . . .
Using message and exception listeners in .NET
Using message listeners in .NET . . . .
Using exception listeners in .NET . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
79
79
80
81
81
81
81
Chapter 9. XMS messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Header fields in an XMS message . . . . . . . .
Properties of an XMS message . . . . . . . . .
JMS defined properties of a message . . . . . .
IBM defined properties of a message . . . . . .
Application defined properties of a message . . .
The body of an XMS message . . . . . . . . .
Bytes messages . . . . . . . . . . . . .
Map messages . . . . . . . . . . . . .
Object messages . . . . . . . . . . . . .
Stream messages . . . . . . . . . . . .
Text messages . . . . . . . . . . . . .
Message selectors . . . . . . . . . . . . .
Mapping XMS messages onto WebSphere MQ messages
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
85
86
87
87
89
89
91
91
92
92
93
93
94
Chapter 10. Working with administered objects . . . . . . . . . . . . . . . . . . 97
Supported types of administered object repository
Property mapping for administered objects . . .
Required connection factory properties . . . .
Required destination properties . . . . . . .
Creating administered objects . . . . . . .
Creating an InitialContext . . . . . . . .
InitialContext properties . . . . . . . . .
URI format for XMS initial contexts . . . . .
Retrieval of administered objects . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 97
. 97
. 98
. 98
. 99
. 99
. 100
. 100
. 101
Part 3. XMS API reference . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Chapter 11. C classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
BytesMessage . .
Functions . . .
Connection . . .
Functions . . .
ConnectionFactory.
Functions . . .
ConnectionMetaData
Functions . . .
Destination . . .
Functions . . .
ErrorBlock . . .
Functions . . .
ExceptionListener .
Functions . . .
InitialContext . .
Functions . . .
Iterator . . . .
Functions . . .
MapMessage . .
Functions . . .
Message . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
123
123
136
136
141
141
144
144
145
145
150
150
154
154
155
155
157
157
159
159
174
Contents
v
Functions . . .
MessageConsumer
Functions . . .
MessageListener .
Functions . . .
MessageProducer .
Functions . . .
ObjectMessage . .
Functions . . .
Property . . . .
Functions . . .
PropertyContext .
Functions . . .
QueueBrowser . .
Functions . . .
Requestor . . .
Functions . . .
Session . . . .
Functions . . .
StreamMessage . .
Functions . . .
TextMessage . . .
Functions . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
174
189
189
193
193
194
194
203
203
205
205
220
220
236
236
239
239
241
241
254
254
267
267
Chapter 12. Additional C functions . . . . . . . . . . . . . . . . . . . . . . . 269
Process CCSID functions
Functions . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 270
. 270
Chapter 13. C++ classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
BytesMessage . . . . .
Methods . . . . . .
Inherited methods . . .
Connection . . . . . .
Methods . . . . . .
Inherited methods . . .
ConnectionFactory. . . .
Constructors . . . . .
Methods . . . . . .
Inherited methods . . .
ConnectionMetaData . . .
Methods . . . . . .
Inherited methods . . .
Destination . . . . . .
Constructors . . . . .
Methods . . . . . .
Inherited methods . . .
Exception. . . . . . .
Methods . . . . . .
ExceptionListener . . . .
Methods . . . . . .
IllegalStateException . . .
Inherited methods . . .
InitialContext . . . . .
Constructors . . . . .
Methods . . . . . .
Inherited methods . . .
InvalidClientIDException .
Inherited methods . . .
InvalidDestinationException
Inherited methods . . .
vi
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Message Service Clients for C/C++ and .NET
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
275
275
283
285
285
289
290
290
290
292
293
293
294
295
295
296
298
299
299
303
303
304
304
305
305
305
306
308
308
309
309
InvalidSelectorException . . .
Inherited methods . . . .
Iterator . . . . . . . .
Methods . . . . . . .
MapMessage . . . . . .
Methods . . . . . . .
Inherited methods . . . .
Message . . . . . . . .
Methods . . . . . . .
Inherited methods . . . .
MessageConsumer . . . .
Methods . . . . . . .
Inherited methods . . . .
MessageEOFException . . .
Inherited methods . . . .
MessageFormatException . .
Inherited methods . . . .
MessageListener . . . . .
Methods . . . . . . .
MessageNotReadableException
Inherited methods . . . .
MessageNotWritableException .
Inherited methods . . . .
MessageProducer . . . . .
Methods . . . . . . .
Inherited methods . . . .
ObjectMessage . . . . . .
Methods . . . . . . .
Inherited methods . . . .
Property . . . . . . . .
Constructors . . . . . .
Methods . . . . . . .
PropertyContext . . . . .
Methods . . . . . . .
QueueBrowser . . . . . .
Methods . . . . . . .
Inherited methods . . . .
Requestor . . . . . . .
Constructors . . . . . .
Methods . . . . . . .
Inherited methods . . . .
ResourceAllocationException .
Inherited methods . . . .
SecurityException . . . . .
Inherited methods . . . .
Session . . . . . . . .
Methods . . . . . . .
Inherited methods . . . .
StreamMessage . . . . . .
Methods . . . . . . .
Inherited methods . . . .
String . . . . . . . . .
Constructors . . . . . .
Methods . . . . . . .
TextMessage . . . . . . .
Methods . . . . . . .
Inherited methods . . . .
TransactionInProgressException
Inherited methods . . . .
TransactionRolledBackException
Inherited methods . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Contents
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
310
310
311
311
314
314
324
325
325
336
337
337
340
341
341
342
342
343
343
344
344
345
345
346
346
354
355
355
356
357
357
359
369
369
381
381
383
384
384
384
386
387
387
388
388
389
389
400
402
402
411
412
412
413
416
416
416
418
418
419
419
vii
Chapter 14. .NET interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . 421
IBytesMessage . . . . . . . .
.NET properties . . . . . .
Methods . . . . . . . . .
Inherited properties and methods
IConnection . . . . . . . . .
.NET properties . . . . . .
Methods . . . . . . . . .
Inherited properties and methods
IConnectionFactory . . . . . .
Methods . . . . . . . . .
Inherited properties and methods
IConnectionMetaData . . . . .
.NET properties . . . . . .
Inherited properties and methods
IDestination . . . . . . . . .
.NET properties . . . . . .
Inherited properties and methods
ExceptionListener . . . . . . .
Delegate . . . . . . . . .
IllegalStateException . . . . . .
Inherited properties and methods
InitialContext . . . . . . . .
.NET properties . . . . . .
Constructors . . . . . . . .
Methods . . . . . . . . .
InvalidClientIDException . . . .
Inherited properties and methods
InvalidDestinationException . . .
Inherited properties and methods
InvalidSelectorException . . . . .
Inherited properties and methods
IMapMessage . . . . . . . .
.NET properties . . . . . .
Methods . . . . . . . . .
Inherited properties and methods
IMessage . . . . . . . . . .
.NET properties . . . . . .
Methods . . . . . . . . .
Inherited properties and methods
IMessageConsumer . . . . . .
.NET properties . . . . . .
Methods . . . . . . . . .
Inherited properties and methods
MessageEOFException . . . . .
Inherited properties and methods
MessageFormatException . . . .
Inherited properties and methods
IMessageListener (delegate) . . .
Delegate . . . . . . . . .
MessageNotReadableException . .
Inherited properties and methods
MessageNotWritableException . . .
Inherited properties and methods
IMessageProducer . . . . . . .
.NET properties . . . . . .
Methods . . . . . . . . .
Inherited properties and methods
IObjectMessage . . . . . . . .
.NET properties . . . . . .
Inherited properties and methods
viii
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Message Service Clients for C/C++ and .NET
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
424
424
424
433
434
434
435
437
438
438
439
440
440
440
441
441
441
442
442
443
443
444
444
444
444
446
446
447
447
448
448
449
449
449
458
459
459
464
465
467
467
468
469
470
470
471
471
472
472
473
473
474
474
475
475
477
480
482
482
482
IPropertyContext . . . . . . .
Methods . . . . . . . . .
IQueueBrowser . . . . . . . .
.NET Properties . . . . . .
Methods . . . . . . . . .
Inherited properties and methods
Requestor . . . . . . . . .
Constructors . . . . . . . .
Methods . . . . . . . . .
ResourceAllocationException . . .
Inherited properties and methods
SecurityException . . . . . . .
Inherited properties and methods
ISession . . . . . . . . . .
.NET properties . . . . . .
Methods . . . . . . . . .
Inherited properties and methods
IStreamMessage . . . . . . .
Methods . . . . . . . . .
Inherited properties and methods
ITextMessage . . . . . . . .
.NET properties . . . . . .
Inherited properties and methods
TransactionInProgressException . .
Inherited properties and methods
TransactionRolledBackException . .
Inherited properties and methods
XMSException . . . . . . . .
.NET properties . . . . . .
XMSFactoryFactory . . . . . .
.NET properties . . . . . .
Methods . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
483
483
493
493
493
494
495
495
495
497
497
498
498
499
499
500
510
511
511
520
521
521
521
522
522
523
523
524
524
525
525
525
Chapter 15. Properties of XMS objects . . . . . . . . . . . . . . . . . . . . . 527
Properties of Connection . . . . . . . . . .
Properties of ConnectionFactory . . . . . . . .
Properties of ConnectionMetaData . . . . . . .
Properties of Destination . . . . . . . . . .
Properties of InitialContext . . . . . . . . . .
Properties of Message . . . . . . . . . . .
Properties of MessageConsumer . . . . . . . .
Properties of MessageProducer . . . . . . . .
Properties of Session . . . . . . . . . . . .
Property definitions . . . . . . . . . . . .
JMS_IBM_CHARACTER_SET . . . . . . . .
JMS_IBM_ENCODING . . . . . . . . . .
JMS_IBM_EXCEPTION_MESSAGE . . . . . .
JMS_IBM_EXCEPTION_PROBLEM_DESTINATION
JMS_IBM_EXCEPTION_REASON . . . . . .
JMS_IBM_EXCEPTION_TIMESTAMP . . . . .
JMS_IBM_FEEDBACK . . . . . . . . . .
JMS_IBM_FORMAT . . . . . . . . . . .
JMS_IBM_LAST_MSG_IN_GROUP . . . . . .
JMS_IBM_MSGTYPE . . . . . . . . . . .
JMS_IBM_PUTAPPLTYPE . . . . . . . . .
JMS_IBM_PUTDATE . . . . . . . . . . .
JMS_IBM_PUTTIME . . . . . . . . . . .
JMS_IBM_REPORT_COA . . . . . . . . .
JMS_IBM_REPORT_COD . . . . . . . . .
JMS_IBM_REPORT_DISCARD_MSG. . . . . .
JMS_IBM_REPORT_EXCEPTION . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Contents
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
527
528
530
530
531
531
533
533
533
533
534
534
535
535
536
536
536
537
537
537
538
538
538
539
539
540
540
ix
JMS_IBM_REPORT_EXPIRATION . . . . . .
JMS_IBM_REPORT_NAN . . . . . . . . .
JMS_IBM_REPORT_PAN . . . . . . . . .
JMS_IBM_REPORT_PASS_CORREL_ID . . . . .
JMS_IBM_REPORT_PASS_MSG_ID . . . . . .
JMS_IBM_SYSTEM_MESSAGEID . . . . . . .
JMSX_APPID . . . . . . . . . . . . .
JMSX_DELIVERY_COUNT . . . . . . . . .
JMSX_GROUPID . . . . . . . . . . . .
JMSX_GROUPSEQ . . . . . . . . . . .
JMSX_USERID . . . . . . . . . . . . .
XMSC_CLIENT_CCSID . . . . . . . . . .
XMSC_CLIENT_ID . . . . . . . . . . .
XMSC_CONNECTION_TYPE . . . . . . . .
XMSC_DELIVERY_MODE . . . . . . . . .
XMSC_IC_SECURITY_CREDENTIALS . . . . .
XMSC_IC_URL . . . . . . . . . . . . .
XMSC_IS_SUBSCRIPTION_MULTICAST . . . .
XMSC_IS_SUBSCRIPTION_RELIABLE_MULTICAST
XMSC_JMS_MAJOR_VERSION . . . . . . .
XMSC_JMS_MINOR_VERSION . . . . . . .
XMSC_JMS_VERSION . . . . . . . . . .
XMSC_MAJOR_VERSION . . . . . . . . .
XMSC_MINOR_VERSION . . . . . . . . .
XMSC_PASSWORD . . . . . . . . . . .
XMSC_PRIORITY . . . . . . . . . . . .
XMSC_PROVIDER_NAME . . . . . . . . .
XMSC_RTT_CONNECTION_PROTOCOL . . . .
XMSC_RTT_HOST_NAME . . . . . . . . .
XMSC_RTT_LOCAL_ADDRESS . . . . . . .
XMSC_RTT_MULTICAST . . . . . . . . .
XMSC_RTT_PORT . . . . . . . . . . . .
XMSC_TIME_TO_LIVE . . . . . . . . . .
XMSC_USERID . . . . . . . . . . . . .
XMSC_VERSION . . . . . . . . . . . .
XMSC_WMQ_BROKER_CONTROLQ . . . . .
XMSC_WMQ_BROKER_PUBQ . . . . . . .
XMSC_WMQ_BROKER_QMGR . . . . . . .
XMSC_WMQ_BROKER_SUBQ . . . . . . .
XMSC_WMQ_BROKER_VERSION . . . . . .
XMSC_WMQ_CCSID . . . . . . . . . . .
XMSC_WMQ_CHANNEL . . . . . . . . .
XMSC_WMQ_CONNECTION_MODE . . . . .
XMSC_WMQ_DUR_SUBQ . . . . . . . . .
XMSC_WMQ_ENCODING . . . . . . . . .
XMSC_WMQ_FAIL_IF_QUIESCE . . . . . . .
XMSC_WMQ_HOST_NAME . . . . . . . .
XMSC_WMQ_LOCAL_ADDRESS . . . . . .
XMSC_WMQ_MESSAGE_SELECTION . . . . .
XMSC_WMQ_MSG_BATCH_SIZE . . . . . .
XMSC_WMQ_POLLING_INTERVAL . . . . .
XMSC_WMQ_PORT . . . . . . . . . . .
XMSC_WMQ_PUB_ACK_INTERVAL . . . . .
XMSC_WMQ_QMGR_CCSID . . . . . . . .
XMSC_WMQ_QUEUE_MANAGER . . . . . .
XMSC_WMQ_RECEIVE_EXIT . . . . . . . .
XMSC_WMQ_RECEIVE_EXIT_INIT . . . . . .
XMSC_WMQ_SECURITY_EXIT . . . . . . .
XMSC_WMQ_SECURITY_EXIT_INIT . . . . .
XMSC_WMQ_SEND_EXIT . . . . . . . . .
XMSC_WMQ_SEND_EXIT_INIT . . . . . . .
x
Message Service Clients for C/C++ and .NET
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
541
542
542
542
543
543
543
544
544
544
545
545
546
546
546
547
547
548
548
548
548
549
549
549
549
549
550
550
551
551
551
552
553
553
553
554
554
554
554
555
555
556
556
556
557
558
558
559
560
560
561
561
561
561
562
562
563
563
563
564
564
XMSC_WMQ_SYNCPOINT_ALL_GETS . .
XMSC_WMQ_TARGET_CLIENT . . . . .
XMSC_WMQ_TEMP_Q_PREFIX . . . . .
XMSC_WMQ_TEMPORARY_MODEL . . .
XMSC_WPM_BUS_NAME . . . . . . .
XMSC_WPM_CONNECTION_PROTOCOL .
XMSC_WPM_CONNECTION_PROXIMITY .
XMSC_WPM_DUR_SUB_HOME . . . . .
XMSC_WPM_HOST_NAME . . . . . .
XMSC_WPM_LOCAL_ADDRESS . . . . .
XMSC_WPM_ME_NAME . . . . . . .
XMSC_WPM_NON_PERSISTENT_MAP . .
XMSC_WPM_PERSISTENT_MAP . . . .
XMSC_WPM_PORT . . . . . . . . .
XMSC_WPM_PROVIDER_ENDPOINTS . .
XMSC_WPM_TARGET_GROUP . . . . .
XMSC_WPM_TARGET_SIGNIFICANCE . .
XMSC_WPM_TARGET_TRANSPORT_CHAIN
XMSC_WPM_TARGET_TYPE . . . . . .
XMSC_WPM_TEMP_Q_PREFIX . . . . .
XMSC_WPM_TEMP_TOPIC_PREFIX . . .
XMSC_WPM_TOPIC_SPACE . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
565
565
566
566
566
567
567
567
568
568
569
569
569
570
570
571
571
572
572
573
573
574
Appendix. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
Trademarks .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 576
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579
Sending your comments to IBM . . . . . . . . . . . . . . . . . . . . . . . . 587
Contents
xi
xii
Message Service Clients for C/C++ and .NET
Figures
1.
2.
XMS objects and their relationships . . . . . 6
Typical use of administered objects by an XMS
application . . . . . . . . . . . . . 8
© Copyright IBM Corp. 2005
xiii
xiv
Message Service Clients for C/C++ and .NET
Tables
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
Message Service Client for C/C++ platforms
and compilers . . . . . . . . . . . . 9
Message Service Client for .NET platforms and
compilers . . . . . . . . . . . . . 9
Installed directories on Linux and Solaris, and
their contents . . . . . . . . . . . . 14
Installed directories on Windows and their
contents . . . . . . . . . . . . . . 15
Installed directories on Windows and their
contents . . . . . . . . . . . . . . 19
XMS sample applications . . . . . . . . 24
Environment variable settings . . . . . . 32
Environment variable settings . . . . . . 35
Wildcard scheme for WebSphere MQ queue
manager with broker v1 . . . . . . . . 46
Example URIs using wildcard scheme for
WebSphere MQ queue manager with broker v1 46
Wildcard scheme for WebSphere MQ with, or
real-time connection to, a broker v2 . . . . 47
Example URIs using wildcard scheme for
WebSphere MQ with, or real-time connection
to, a broker v2 . . . . . . . . . . . 47
Wildcard scheme for WebSphere service
integration bus . . . . . . . . . . . 47
Example URIs using wildcard scheme for
WebSphere service integration bus . . . . . 47
Objects that are deleted automatically . . . . 53
Supported conversions from a property type to
other data types . . . . . . . . . . . 53
Object handle data types . . . . . . . . 59
© Copyright IBM Corp. 2005
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
Return codes from C function calls . . . . . 64
The XMS classes on which the assignment
operator is overloaded . . . . . . . . . 74
JMS message header fields . . . . . . . 86
JMS defined properties of a message . . . . 87
IBM defined properties of a message . . . . 87
XMS data types that are compatible with Java
data types . . . . . . . . . . . . . 90
Name mapping examples for connection
factory and destination properties . . . . . 98
Property settings for administered
ConnectionFactory objects for connections to a
WebSphere MQ queue manager . . . . . . 98
Property settings for administered
ConnectionFactory objects for real-time
connections to a broker . . . . . . . . 98
WebSphere MQ JMS property settings for
administered Destination objects . . . . . 99
Summary of the C classes . . . . . . . 121
Summary of the C++ classes . . . . . . 273
Summary of the .NET class interfaces
421
Properties of Connection . . . . . . . . 527
Properties of ConnectionFactory . . . . . 528
Properties of ConnectionMetaData . . . . 530
Properties of Destination . . . . . . . . 530
Properties of InitialContext . . . . . . . 531
Properties of Message . . . . . . . . . 531
Properties of MessageConsumer . . . . . 533
Properties of MessageProducer . . . . . . 533
Properties of Session . . . . . . . . . 533
xv
xvi
Message Service Clients for C/C++ and .NET
About this book
This book is about IBM® Message Service Clients for C/C++ and .NET, Version 1.1.
The book describes and documents the API provided by Message Service Clients
for C/C++ and .NET. This API is referred to as XMS.
The book has the following parts:
v Part 1, “Getting started with Message Service Clients for C/C++ and .NET,” on
page 1, which describes what Message Service Clients for C/C++ and .NET are,
and how to install and use Message Service Clients for C/C++ and .NET
v Part 2, “Programming with XMS,” on page 37, which describes how to write
XMS applications
v Part 3, “XMS API reference,” on page 103, which documents the XMS classes
and their methods, and the properties of XMS objects
For the latest information about Message Service Clients for C/C++ and .NET, see
the product readme.txt file, which is supplied with Message Service Clients for
C/C++ and .NET.
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 application development skills should also use this
information to enable them to utilize the XMS API. 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 you need to know to understand this book
To understand this book, you need the following skills, knowledge, and
experience:
v C, C++ or .NET application programming skills. If you are not a C++
programmer, you need some knowledge of object oriented concepts and
terminology.
v For those using .NET, a working knowledge of the Microsoft .NET Framework,
together with application programming skills in the .NET language of your
choice.
v A working knowledge of the operating system that you are using.
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 are intending to use.
v 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.
© Copyright IBM Corp. 2005
xvii
About this book
Terms used in this book
The term XMS refers to the API provided by Message Service Clients for C/C++
and .NET.
The term XMS client means an installed instance of Message Service Client for
C/C++ that is supporting an application.
The term JMS means Java Message Service.
The term WebSphere MQ JMS means 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 term 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
How to use 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/ .
xviii
Message Service Clients for C/C++ and .NET
About this book
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/ .
You can access the latest version of the information center for WebSphere
Application Server at http://publib.boulder.ibm.com/infocenter/ws60help/ .
About this book
xix
xx
Message Service Clients for C/C++ and .NET
Summary of changes
This section describes changes in this edition of Message Service Clients for C/C++
and .NET.
Changes for this edition (SC34-6658-00)
This edition provides the following new information:
v .NET API reference
v Clarification of LDAP URI format
v Solaris platform for Message Service Client for C/C++
This edition also contains various editorial improvements, clarifications, and
corrections.
© Copyright IBM Corp. 2005
xxi
xxii
Message Service Clients for C/C++ and .NET
Part 1. Getting started with Message Service Clients for C/C++
and .NET
Chapter 1. Introducing Message Service Clients for C/C++
What are Message Service Clients for C/C++ and .NET? .
Styles of messaging . . . . . . . . . . . . . .
The XMS object model . . . . . . . . . . . . .
Attributes and properties of objects . . . . . . . .
Administered objects . . . . . . . . . . . .
The XMS message model . . . . . . . . . . . .
Operating environments . . . . . . . . . . . .
and
. .
. .
. .
. .
. .
. .
. .
.NET
. .
. .
. .
. .
. .
. .
. .
. . . . . . . . . . . . . . . 3
. . . . . . . . . . . . . . . 3
. . . . . . . . . . . . . . . 4
. . . . . . . . . . . . . . . 4
. . . . . . . . . . . . . . . 6
. . . . . . . . . . . . . . . 7
. . . . . . . . . . . . . . . 8
. . . . . . . . . . . . . . . 8
Chapter 2. Installing Message Service Clients for C/C++ and .NET . . . . . . . . . . . . . . . . 11
Installing Message Service Client for C/C++ . . . . . . . . . . . . . . . . . . . . . . . . 11
Installing Message Service Client for C/C++ using the installation wizard . . . . . . . . . . . . . 11
Installing from the command line . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
What is installed on Linux and Solaris . . . . . . . . . . . . . . . . . . . . . . . . . 13
What is installed on Windows (C/C++) . . . . . . . . . . . . . . . . . . . . . . . . . 15
Uninstalling Message Service Client for C/C++ . . . . . . . . . . . . . . . . . . . . . . 16
Uninstalling on Windows using Add/Remove Programs . . . . . . . . . . . . . . . . . . 16
Installing Message Service Client for .NET . . . . . . . . . . . . . . . . . . . . . . . . . 17
Installing Message Service Client for .NET using the installation wizard . . . . . . . . . . . . . . 17
What is installed on Windows (.NET). . . . . . . . . . . . . . . . . . . . . . . . . . 18
Uninstalling Message Service Client for .NET . . . . . . . . . . . . . . . . . . . . . . . 19
Chapter 3. Using XMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting up the messaging server environment . . . . . . . . . . . . . . . . . . . . . .
Configuring the queue manager and broker for an application that connects to a WebSphere MQ queue
manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring the broker for an application that uses a real-time connection to a broker . . . . . . .
Configuring the service integration bus for an application that connects to a WebSphere service integration
Using the sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . .
Running the sample applications . . . . . . . . . . . . . . . . . . . . . . . . .
Building the C or C++ sample applications . . . . . . . . . . . . . . . . . . . . . .
Building the .NET sample applications . . . . . . . . . . . . . . . . . . . . . . .
Building your own applications . . . . . . . . . . . . . . . . . . . . . . . . . .
. . 21
. . 21
. .
. .
bus
. .
. .
. .
. .
. .
21
22
23
24
26
26
27
27
Chapter 4. Problem determination . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Problem determination for C/C++ applications . . . . . . . . . . . . . . . . . . . . . . . 29
Error conditions that can be handled at run time . . . . . . . . . . . . . . . . . . . . . . 29
Error conditions that cannot be handled at run time . . . . . . . . . . . . . . . . . . . . . 30
Repeatable failures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Working with FFDC and trace for C/C++ applications . . . . . . . . . . . . . . . . . . . . 31
Configuring trace for .NET applications . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Trace configuration using an application configuration file. . . . . . . . . . . . . . . . . . . 34
Trace configuration using XMS environment variables . . . . . . . . . . . . . . . . . . . . 35
Configuring FFDC for .NET applications . . . . . . . . . . . . . . . . . . . . . . . . . 36
© Copyright IBM Corp. 2005
1
2
Message Service Clients for C/C++ and .NET
Chapter 1. Introducing Message Service Clients for C/C++ and
.NET
This chapter introduces Message Service Client for C/C++ and Message Service
Client for .NET.
This chapter contains the following sections:
v “What are Message Service Clients for C/C++ and .NET?”
v “Styles of messaging” on page 4
v “The XMS object model” on page 4
v “The XMS message model” on page 8
v “Operating environments” on page 8
What are Message Service Clients for C/C++ and .NET?
Message Service Clients for C/C++ and .NET provide 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. Message Service Client for
.NET contains a fully managed implementation of XMS, which can be used by any
.NET compliant language.
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 Business Integration Event Broker or WebSphere
Business Integration 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
Business Integration Event Broker or WebSphere Business Integration 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
© Copyright IBM Corp. 2005
3
v A native WebSphere MQ application
v A JMS application that is using the WebSphere default messaging provider
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
routes published messages to subscribers. A subscriber receives messages
on all topics, and 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:
4
Message Service Clients for C/C++ and .NET
ConnectionFactory
A ConnectionFactory object encapsulates a set of configuration parameters
for a connection. An application uses a connection factory to create a
connection. An application can create a ConnectionFactory object at run
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
A destination is where an application sends messages, or it is a source
from which an application receives messages, or both. 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 or
receives.
MessageProducer
An application uses a message producer to send messages to a destination.
MessageConsumer
An application uses a message consumer to receive messages sent to a
destination.
Figure 1 on page 6 shows these objects and their relationships.
Chapter 1. Introducing Message Service Clients for C/C++ and .NET
5
ConnectionFactory
Creates
Connection
Creates
Creates
MessageProducer
Creates
Session
Sends to
Destination
Creates
Message
MessageConsumer
Receives from
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
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 connection factory, XMS returns a handle for
the connection factory to the application. In general, for each C++ method in the
C++ interface, there is an equivalent C function in the C interface.
In .NET, the XMS classes are defined as a set of .NET interfaces. Each object is
implemented by a concrete implementation of its interface. When you are coding
XMS .NET applications, you only need to use the declared interfaces.
The XMS object model is based upon the domain independent interfaces that are
described in the 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. Attributes and properties, however, are implemented in different ways.
Attributes
An attribute of an object is always present and occupies storage, even if
the attribute does not have a value. In this respect, an attribute is similar in
concept to a field in a fixed length data structure. Another distinguishing
feature 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, and the storage recovered,
after its value has been set, although you can change its value. Each
6
Message Service Clients for C/C++ and .NET
individual property does not have its own methods for setting and getting
its value. Instead, XMS provides a set of generic methods for setting and
getting the values of properties.
Administered objects
Administered objects allow the connection settings used by client applications to
be administered from a central repository. An application can retrieve object
definitions from the central repository, and use 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 is used by applications to make the initial
connection to the server.
v A Destination object 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 that an application
connects to.
The WebSphere MQ JMS administration tool (JMSAdmin) available with
WebSphere MQ can be used to create and manage administered objects for
WebSphere MQ, WebSphere Business Integration Message Broker, or WebSphere
Business Integration 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 connection factories and
destinations for WebSphere MQ queue manager, or for a real time 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.
Chapter 1. Introducing Message Service Clients for C/C++ and .NET
7
Administration console
Administers
XMS application
Produces/consumes
messages
Looks up
Destination
Administered
objects repository
Messaging server
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.
An XMS client is supplied for each of the operating systems listed in Table 1 on
page 9 and Table 2 on page 9. The tables also list the compiler for each client
platform.
8
Message Service Clients for C/C++ and .NET
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 2003, Version 7.1
Windows 2000, Windows Server 2003
Red Hat Enterprise Linux 3.0 (Intel™ only)
gcc 3.2.2 (supplied with the operating
system)
Sun Solaris version 9
C compiler: Forte Developer 6 Update 2
C++ compiler: Forte Developer 6 Update 2
Note: XMS on Solaris has been built and tested using the Forte Developer 6
Update 2 C and C++ compilers. The version of the C compiler itself (run ″cc
-V″ to find this) is 5.3. The version of the C++ compiler itself (run ″CC -V″
to find this) is 5.3.
The XMS C libraries should be readily usable with objects built with earlier
or later versions of the Sun Studio C compilers.
The XMS C++ libraries should be 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 prior to 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.
Table 2. Message Service Client for .NET platforms and compilers
Operating system
Compiler
Microsoft Windows XP with Service Pack 1
.NET Framework v1.14322
Chapter 1. Introducing Message Service Clients for C/C++ and .NET
9
10
Message Service Clients for C/C++ and .NET
Chapter 2. Installing Message Service Clients for C/C++ and
.NET
This chapter describes how to installMessage Service Clients for C/C++ and .NET
(XMS).
This chapter contains the following sections:
v “Installing Message Service Client for C/C++”
v “Installing Message Service Client for .NET” on page 17
Installing Message Service Client for C/C++
Follow these instructions to install or uninstall Message Service Client for C/C++.
Message Service Client for C/C++ is installed using an InstallShield MultiPlatform
5 installer. You can either use the installer in the form of a wizard with a graphical
user interface, or you can invoke it from a command prompt. For general
information about MultiPlatform 5, see the InstallShield Web site at
http://www.installshield.com/. For the latest information about installing the
product, see the product readme.txt file supplied with Message Service Client for
C/C++.
The following sections describe how to install and uninstall Message Service Client
for C/C++ in more detail:
v “Installing Message Service Client for C/C++ using the installation wizard”
v “Installing from the command line” on page 13
v “What is installed on Linux and Solaris” on page 13
v “What is installed on Windows (C/C++)” on page 15
v “Uninstalling Message Service Client for C/C++” on page 16
Installing Message Service Client for C/C++ using the
installation wizard
The installation for Message Service Client for C/C++ uses an InstallShield
MultiPlatform 5 installer. Two setup options are available, so that you can choose
either a complete or a custom installation.
The installed client requires 100 MB of disk space on Linux, Solaris and Windows.
To install Message Service Client for C/C++ client on 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. On Linux, log in as root. On Solaris, log in as root. On Windows, log on as an
administrator.
Note: On Linux or Solaris, you can install as a non-root user to any directory
that the user has write access to. If you want to do this, though, you
must run the installer with the -log !<directory> flag as described in
“Installing from the command line” on page 13.
© Copyright IBM Corp. 2005
11
2. 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.
3. Run the setup file:
v On Linux, run the file called setuplinuxia32 that is in the gxixms_install
directory.
v On Solaris, run the file called setupsolaris that is in the gxixms_install
directory.
v On Windows, run the file setup.exe that is in the gxixms_install directory.
Messages in the command prompt window inform you that the installer is
searching for, and preparing, a Java Virtual Machine (JVM). Message Service
Client for C/C++ provides a JVM for the installer; you do not need to provide
one. The installation wizard opens and asks you to select a language to be
used for this wizard.
4. Select the appropriate language and click OK.
The installation wizard displays the following message:
Welcome to the IBM Message Service Client for C/C++ installation wizard
5. Click Next.
The installation wizard asks you to read the licence agreement.
6. If you accept the terms of the licence agreement, click I accept the terms in
the licence agreement, and then click Next. The installation wizard asks you
where you want to install Message Service Client for C/C++.
7. To install Message Service Client for C/C++ in the directory suggested, click
Next. If you do not want to install Message Service Client for C/C++ in the
directory suggested, 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.
8. Select the type of setup that you require:
v To install all program features, click Complete.
v To choose which features you want to install, click Custom.
9. 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 11. If you select the custom install option, the installation
wizard asks you which features you want to install.
10. 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.
11. When you are happy with your selected installation options, click Next to
start the installation. Note that Cancel becomes unavailable when the
installation has started.
12
Message Service Clients for C/C++ and .NET
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 the following message:
The installation wizard has successfully installed IBM Message Service Client
for C/C++. Choose Finish to exit the wizard.
12. Click Next . If you want to view the readme file for Message Service Client
for C/C++, select View Readme before clicking Next.
13. Click Finish to close the installation wizard.
You have now successfully installed Message Service Client for C/C++, which is
ready to use.
Installing from the command line
Running the installer from a command prompt allows you to finely control the
installation.
Command line options
If you invoke the installer from a command prompt using the runtime command
line option -silent, you can perform an unattended, or silent, installation, which
requires no interaction with the wizard. If you run the installer in silent mode, the
default setup options are used. Other runtime command line options allow you to
have more control over the installation.
For specific information about the runtime command line options, see the
InstallShield MultiPlatform 5 User’s Guide, which you can download from
http://www.installshield.com/.
Creating a log file on Linux or Solaris when you are not logged
in as root
On Linux or Solaris, you can install as a non-root user to any directory that the
user has access to. However, when you run the installer from the command line,
the installer tries, by default, to create a log file in the /var/log/ directory, which
is not accessible to a non-root user. Therefore, if you are carrying out the
installation when you are not logged in as root, you must run the installer with the
-log !<directory> flag:
v On Linux, type the following command:
./setuplinuxia32 -log ’!<directory>’
For example:
./setuplinuxia32 -log ’!/home/myuser/install.log’
v On Solaris, type the following command:
./setupsolaris -log ’!<directory>’
For example:
./setupsolaris -log ’!/home/myuser/install.log’
What is installed on Linux and Solaris
On 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 3 on page 14 lists the installed directories, relative to the installation
directory, and describes their contents.
Chapter 2. Installing Message Service Clients for C/C++ and .NET
13
Table 3. Installed directories on Linux and Solaris, and their contents
Installed feature
Installed directory
Runtime
Development
Tools
Documentation
and Samples
14
Contents
The readme.txt file for the
product and the licence
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.2
directory
lib/3.2
On Linux only, the shared
object library required to
compile XMS applications
written in C++ using the
gcc 3.2 compiler, and to run
the applications
tools/c/include
The XMS header files for C
tools/cpp/include
The XMS header files for
C++
doc
This documentation as a
PDF file
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/SampleConsumerC
The source and makefile for
the C message consumer
sample application
tools/samples/SampleProducerC
The source and makefile for
the C message producer
sample application
tools/samples/SampleConsumerCPP
The source and makefile for
the C++ message consumer
sample application
tools/samples/SampleProducerCPP
The source and makefile for
the C++ message producer
sample application
tools/samples/SampleConfigC
The sampleconfig tool
Message Service Clients for C/C++ and .NET
What is installed on Windows (C/C++)
On Windows, XMS is installed in the C:\Program Files\IBM\XMS directory unless
you choose to install it in a different directory.
Table 4 lists the installed directories, relative to the installation directory, and
describes their contents.
Table 4. Installed directories on Windows and their contents
Installed feature Installed directory
Contents
Runtime
The licence agreement for
the product and the
readme.txt file
Development
Tools
Documentation
and Samples
_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
tools\c\include
The XMS header files for C
tools\cpp\include
The XMS header files for
C++
tools\lib
The XMS link libraries for C
and C++
doc
This documentation as a
PDF file
tools\samples\bin
The compiled sample
applications and the
command file to run them
tools\samples\SampleConsumerC
The source and makefile for
the C message consumer
sample application
tools\samples\SampleProducerC
The source and makefile for
the C message producer
sample application
tools\samples\SampleConsumerCPP
The source and makefile for
the C++ message consumer
sample application
tools\samples\SampleProducerCPP
The source and makefile for
the C++ message producer
sample application
tools\samples\c\sampleconfig
The sampleconfig tool
tools\samples\readme.txt
The readme.txt file for the
sample applications
Chapter 2. Installing Message Service Clients for C/C++ and .NET
15
Note: The files MSVCR71.dll, MSVCR71.pdb, MSVCP71.dll, and MSVCP71.pdb in
the bin directory are redistributed Microsoft runtime libraries. They are
needed to run all XMS applications because they provide the C and C++
system runtime implementations used by all applications or libraries linked
with Microsoft Visual C++ .NET 2003. 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.
To remove Message Service Client for C/C++ from your Linux or Windows
system, follow this procedure:
1. On Linux, log in as root. On Solaris, log in as root. On Windows, log on as an
administrator.
2. Run the uninstaller:
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:
Welcome to the IBM Message Service Client for C/C++ installation wizard
3. Click Next.
The Uninstaller window displays details of what is about to be uninstalled.
4. Click Next to start the removal of the XMS.
The Uninstaller window confirms that XMS is being uninstalled. When XMS
has been removed successfully, the window displays the following message:
The InstallShield Wizard has successfully uninstalled IBM Message Service Client
for C/C++. Choose Finish to exit the wizard.
5. Click Finish to close the installation wizard.
You have now successfully removed the XMS client from your system.
Uninstalling on Windows 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.
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++.”
To remove Message Service Client for C/C++ using Add/Remove Programs,
follow this procedure:
1. Log on to Windows as an administrator.
16
Message Service Clients for C/C++ and .NET
2. From the Windows task bar, click Start —> Settings —> Control Panel.
The Control Panel window opens.
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:
Welcome to the IBM Message Service Client for C/C++ installation wizard
6. Click Next.
The Uninstaller window provides information about what is about to be
uninstalled.
7. Click Next to start the removal of the XMS.
The Uninstaller window confirms that Message Service Client for C/C++ is
being uninstalled. When Message Service Client for C/C++ has been removed
successfully, the window displays the following message:
The InstallShield Wizard has successfully uninstalled IBM Message Service Client
for C/C++. Choose Finish to exit the wizard.
8. Click Finish to close the Uninstaller window.
You have now successfully removed Message Service Client for C/C++ from your
system.
Installing Message Service Client for .NET
Follow these instructions to install or uninstall Message Service Client for .NET.
Message Service Client for .NET is installed using an InstallShield X/Windows MSI
installer. You can either use the installer in the form of a wizard with a graphical
user interface, or you can invoke it from a command prompt. For further
information about InstallShield, see the InstallShield Web site at
http://www.installshield.com/. For the latest information about installing the
product, see the product readme.txt file supplied with Message Service Client for
.NET.
The following sections describe how to install and uninstall Message Service Client
for .NET in more detail:
v “Installing Message Service Client for .NET using the installation wizard”
v “What is installed on Windows (.NET)” on page 18
v “Uninstalling Message Service Client for .NET” on page 19
Installing Message Service Client for .NET using the
installation wizard
The installation uses an InstallShield X/Windows MSI installer. Two setup options
are available, so that you can choose either a complete or a custom installation .
To install Message Service Client for .NET on Windows, follow this procedure.
1. On Windows, log on as an administrator.
2. Run the dotNETClientsetup.exe installer. The installation wizard opens and
asks you to select a language to be used for this wizard.
3. Select the appropriate language and click OK.
Chapter 2. Installing Message Service Clients for C/C++ and .NET
17
The installation wizard displays the following message:
Welcome to IBM Message Service Client for .NET installation wizard
4. Click Next.
The installation wizard asks you to read the licence agreement.
5. If you accept the terms of the licence agreement, click I accept the terms in
the licence agreement, and then click Next.
The installation wizard asks you to choose the setup type that best suits your
needs.
6. Select the type of setup you require:
v To install all program features, and install them in the default installation
directory, click Complete.
v To choose which features you want to install, and specify where they will
be installed, click Custom.
7. Click Next.
If you select the complete install option, the installation wizard tells you that
it is ready to begin installation, as described in step 9. If you select the custom
install option, the installation wizard asks you to select the features that you
want to install.
8. For a custom install only, click an icon in the list of features to specify any
changes to how you want the Message Service Client for .NET features to be
installed. If you do not want to install Message Service Client for .NET in the
directory suggested, choose another directory.
If you choose to install Message Service Client for .NET in a directory that
does not currently exist, the installation wizard creates the directory for you.
If you want to develop XMS applications, ensure that the Development Tools
and Samples feature is selected. This feature provides the sample applications,
and the libraries and any other files needed to compile .NET applications. If
you do not select this feature, only the files needed to run XMS applications
are installed.
9. If you are using the custom install option, click Next after selecting the
options you require as described in step 8.
The installation wizard tells you that it is ready to begin installation.
10. Click Install to start the installation.
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 window displays the following message:
The installation wizard has successfully installed IBM Message Service Client
for .NET. Click Finish to exit the wizard.
11. Click Finish to close the installation wizard.
You have now successfully installed Message Service Client for .NET, which is
ready to use.
What is installed on Windows (.NET)
On Windows, XMS is installed in the C:\Program Files\IBM\.NET Message
Service Client directory unless you choose to install it in a different directory.
Table 5 on page 19 lists the installed directories, relative to the installation
directory, and describes their contents.
18
Message Service Clients for C/C++ and .NET
Table 5. Installed directories on Windows and their contents
Installed directory
Contents
readme.txt
The readme.txt file for the product
docs
This documentation as a PDF file
tools/lib
The files required to run XMS applications
tools/samples/readme/readme.txt
The readme.txt file for the sample applications
tools/samples/bin
The compiled sample applications and the
command file to run them
tools/samples/src/SampleCommon
The common source files for the sample
applications
tools/samples/src/SampleConsumer
The source files for the message consumer
sample application
tools/samples/src/SampleProducer
The source files for the message producer
sample application
Uninstalling Message Service Client for .NET
You can remove Message Service Client for .NET from your Windows system
using Add/Remove Programs.
To remove Message Service Client for .NET using Add/Remove Programs, follow
this procedure:
1. Log on to Windows as an administrator.
2. From the Windows task bar, click Start —> Settings —> Control Panel.
The Control Panel window opens.
3. Double-click Add/Remove Programs.
The Add/Remove Programs window opens.
4. Click IBM Message Service Client for .NET to select it.
5. Click Change/Remove the follow the instructions that appear.
You have now successfully removed Message Service Client for .NET from your
system.
Chapter 2. Installing Message Service Clients for C/C++ and .NET
19
20
Message Service Clients for C/C++ and .NET
Chapter 3. Using XMS
This chapter provides information about how to configure and use XMS after you
have installed it. The chapter describes how to set up the messaging server
environment prior to running XMS applications and describes how to use the
sample applications provided with XMS.
This chapter contains the following sections:
v “Setting up the messaging server environment”
v “Using the sample applications” on page 24
v “Building your own applications” on page 27
v Chapter 10, “Working with administered objects,” on page 97
Setting up the messaging server environment
To allow XMS applications to connect to a server, you must set up the messaging
server environment before running any applications.
Configuring the queue manager and broker for an application
that connects to a WebSphere MQ queue manager
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.
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, make sure that it also has
access to a broker that is running.
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
properties are set for using the broker. For more information about the
properties of a connection factory, see “Properties of ConnectionFactory” on
page 528.
You configure the queue manager and broker to run XMS applications in the same
way that you configure the queue manager and broker 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 that needs access to
WebSphere MQ JMS system queues, wait until Step 4a on page 22 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.
© Copyright IBM Corp. 2005
21
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, perform the following
steps.
The steps assume that your application and the broker connect to the same
queue manager. If your application and the broker connect to different queue
managers, see WebSphere MQ Using Java for the additional configuration that is
required.
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 and
use the broker.
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 Business Integration Event Broker or WebSphere
Business Integration 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 create and deploy a message flow, see the
WebSphere Business Integration Event Broker or WebSphere Business
Integration Message Broker Information Center.
You do not need to perform this step if a suitable message flow is already
deployed at the broker.
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 starting this task, you must do the following:
v Make sure that your application has access to a broker that is running.
22
Message Service Clients for C/C++ and .NET
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 528.
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 Business
Integration Event Broker or WebSphere Business Integration 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 is 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.
You can now start your application.
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 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 Any queue or topic spaces you require must be defined. By default a topic space
called Default.Topic.Space will already have been pre-defined during the server
installation but, if you require further topic spaces, you must create these
yourself. You do not need to pre-define individual topics within a topic space,
since the server instantiates these dynamically as required.
Chapter 3. Using XMS
23
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 pre-defined 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 528.
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.
You can now start your application.
Using the sample applications
A number of sample applications are supplied with XMS. The samples provide an
overview of the common features of each API. You can use these sample
applications to verify your installation and messaging server setup, and also for
guidance in building your own applications.
These samples are not intended to exercise the whole of the API, but rather to
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
which key steps you need to perform to create each object that you need for your
application (connection factory, connection, session, destination, and either 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 5, “Writing XMS applications,” on page 39.
Table 6 shows the three sets of sample applications that are supplied with XMS.
There is one set for each API.
Table 6. XMS sample applications
Name of sample
Description
SampleConsumerC
A message consumer application that consumes messages on to
a queue or topic.
SampleConsumerCPP
SampleConsumerCS
24
Message Service Clients for C/C++ and .NET
Table 6. XMS sample applications (continued)
Name of sample
Description
SampleProducerC
A message producer application that produces messages from a
queue or topic.
SampleProducerCPP
SampleProducerCS
SampleConfigC
SampleConfigCS
A configuration application that allows you 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 corresponding samples for the different APIs support the same functionality,
but have some syntactical differences.
v The consumer and producer sample applications both support:
– Connections to WebSphere MQ, WebSphere Business Integration Event Broker
and WebSphere Business Integration 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) .
– The types of message that XMS supports: base, bytes, map, object, stream and
text messages.
v The consumer sample application supports:
– Synchronous and asynchronous receive modes.
– SQL Selector statements.
v The producer sample 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 allows you to run the samples with the minimum user input.
v Advanced mode allows you to customize more finely the way the samples
operate.
All the samples are compatible and can therefore inter-operate across languages.
For example, the SampleConsumerCPP application can inter-operate with the
Sample ProducerCS application.
Where to find the samples
To find out where the sample applications for Message Service Client for C/C++
are installed:
v For Linux, see Table 3 on page 14.
v For Solaris, see Table 3 on page 14.
v For Windows, see Table 4 on page 15.
Chapter 3. Using XMS
25
To find out where the sample applications for Message Service Client for .NET are
installed, see “What is installed on Windows (.NET)” on page 18.
Running the sample applications
You can run the C, C++ and .NET sample applications interactively in either
simple or advanced mode, or non-interactively using auto-generated or custom
response files.
In the case of the C or C++ sample applications, you must have set up one of the
following environment variables, as appropriate:
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.
The operation of the C and C++ sample applications is identical for all platforms.
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, C++ and .NET
sample applications.
1. Choose which mode you want to run the sample application in. Type either
Advanced or Simple.
2. Answer the questions that then appear. An example question is as follows:
Enter connection type [wpm]:
Pressing Enter selects the default value, as shown in the square brackets at the
end of the question.
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 re-run the sample application with the same
options, without having to re-enter these options manually.
Building the C or C++ sample applications
When you build a sample C or C++ application, an executable version of your
chosen sample is created.
To build the C or C++ samples, you must have the appropriate compiler installed
as described in “Operating environments” on page 8.
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:
v On Linux, type make.
v On Solaris, type make.
v On 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
26
Message Service Clients for C/C++ and .NET
are building the C version of the message producer sample 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:
v On Linux and Solaris, the <install_dir>/lib directory must be in the path
specified by the LD_LIBRARY_PATH environment variable.
v On Windows, the <install_dir>\bin directory must be in the path specified by
the PATH environment variable.
Building the .NET sample applications
When you build a sample .NET application, an executable version of your chosen
sample is created.
To build the .NET samples, you must have the appropriate compiler installed as
described in “Operating environments” on page 8. The task described below
assumes that you have Visual Studio 2003 installed, and that you are familiar with
using Visual Studio 2003.
This section provides the information that you need to build the .NET applications
using Visual Studio 2003. To build a .NET sample application, carry out the
following steps.
v Click the Samples.sln solution file provided with the .NET samples.
v Right click the Solution ’Samples’ in the Solution Explorer window and select
Build Solution.
An executable program is created in the appropriate sample folder’s bin/Debug or
bin/Release, depending on the configuration that you have chosen. This program
has the same name as the folder, with a suffix of CS. For example, if you are
building the C# version of the message producer sample application,
SampleProducerCS.exe is created in the SampleProducer folder.
Building your own applications
You build your own applications in a similar way to building the sample
applications.
This section summarizes the steps that you need carry out to build your own C,
C++ or .NET applications. For additional guidance on how to build your own
applications, use the makefiles provided for each sample application.
1. 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).
2. Build your application:
v For C or C++, build the application as described in “Building the C or C++
sample applications” on page 26.
v For .NET, build the application as described in “Building the .NET sample
applications.”
Chapter 3. Using XMS
27
28
Message Service Clients for C/C++ and .NET
Chapter 4. Problem determination
This chapter provides information to help you to detect and deal with problems.
This chapter contains the following sections:
v “Problem determination for C/C++ applications”
v “Configuring FFDC for .NET applications” on page 36
v “Configuring trace for .NET applications” on page 33
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 30
v “Repeatable failures” on page 31
v “Working with FFDC and trace for C/C++ applications” on page 31
Error conditions that can be handled at run time
Return codes from API calls are error conditions that can be handled a 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 64 and “ErrorBlock” on page 150.
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 “Using message and
exception listener functions in C” on page 60 and “Using message and exception
listeners in C++” on page 71.
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 retry the function every second 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.
© Copyright IBM Corp. 2005
29
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 being used. For further details, see “Handling errors in
C” on page 64.
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 “Handling errors in C++” on page 69.
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 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 39.
Error conditions that cannot be handled at run time
If you experience behavior that is inconsistent with the documented behavior of
XMS, you can use the First Failure Data Capture (FFDC) records generated as a
result of the failure to help determine the cause of the problem.
After detecting an error, look in the application’s current working directory for files
with an .FDC extension, and then use the textual information that these records
contain to investigate the failure and determine whether you can resolve the
problem yourself or whether you need to call your IBM Support Center for
assistance.
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.
It is likely that IBM Support representatives will ask for details of the FFDC
records that were written from the application process. If additional information is
required to help diagnose the problem, the IBM representative may direct you to
provide product trace. It may be necessary for you to capture product trace over
an extended period of time, during which the behavior that you noted must be
demonstrated to allow the problem to be diagnosed. If you are asked to provide
trace, the representative will advise you on which trace options to use and on the
diagnostics that you need to send to IBM.
Tip: To assist with problem diagnosis in the event of a failure, you might find it
helpful to compile applications with symbols included.
30
Message Service Clients for C/C++ and .NET
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 “Working with FFDC and trace
for C/C++ applications.”
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:
alter trace(enabled) tracesize(xxxx)
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 created in a machine readable form. You can format the trace
files using the gxitrcfmt tool. The formatted trace contains a sequence of lines,
where each line contains:
v a time stamp
v a thread identifier
v a component identifier
v a trace record
If you are experiencing problems where you do not have access to the information
provided in the error block, you may wish 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.
Working with FFDC and trace for C/C++ applications
First Failure Data Capture (FFDC) records provide information to help diagnose
problems that you may experience with XMS. If additional information is required
to help find the cause of the error, your IBM Support Center might ask you to
produce a trace.
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. 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.
Configuring trace before running an application
To configure trace for an XMS C or C++ application, set the following XMS
environment variables before running the application:
Chapter 4. Problem determination
31
Table 7. Environment variable settings
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.
Current
working
directory
/dirpath/
The directory path that trace and
FFDC records are written to.
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).
XMS_TRACE_FILE_PATH
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.
Configuring trace dynamically
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
display all
alter trace(enabled) tracesize(100)
help
alter trace(disabled)
alter
32
Message Service Clients for C/C++ and .NET
<enter>
<enter>
<enter>
<enter>
<enter>
<enter>
end
gxisc
alter pid(1234) trace(enabled)
end
<enter>
<enter>
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.
Formatting trace files
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
Each line of the trace contains a date and time, a thread identifier, a component
identifier, function entry/exit or data trace information. The trace record is a
function entry point (indicated by ’{’), a function exit point (indicated by ’}’) or a
function data point.
Configuring trace for .NET applications
For XMS .NET applications, you can configure trace from an application
configuration file as well as from the XMS environment variables. You can select
the components that you want to trace. Trace is normally used under the guidance
of IBM Support.
Tracing for the .NET implementation of XMS is based on the standard .NET trace
infrastructure.
All tracing except for error tracing is disabled by default, and you can turn it on in
either of the following ways:
v By using an application configuration file with a name that consists of the name
of the executable program to which the file relates, with the suffix .config. For
example, the application configuration file for text.exe would have the name
text.exe.config. Using an application configuration file is the preferred way of
enabling trace for XMS .NET applications.
v By using XMS environment variables as for XMS C or C++ applications
Chapter 4. Problem determination
33
Trace files have a name of the form xmsTraceLog<processID>.trc, where <processID>
represents the processID of the application. Trace files are human readable, in a
WebSphere Application Server format. Trace entries contain the following
information:
v The date and time that the trace was logged
v The class name
v The trace type
v The trace message
The following example shows an extract from some trace:
[05/11/2005 09:13:14:332] Crypt
[05/11/2005 09:13:14:332] Crypt
[05/11/2005 09:13:14:332] Crypt
>
d
<
GetClientCredentials
AcquireCredentialsHandleW returned 0
GetClientCredentials
Trace configuration using an application configuration file
The preferred way of configuring trace for XMS .NET applications is to modify the
trace specification in the Trace section of the application configuration file. To turn
trace on using this file, you simply place the file in the same directory as the
executable file for your application.
The following example shows a trace specification that enables all trace and stores
it in a named directory (in this case, c:\somepath).
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<configSections>
<sectionGroup name="IBM.XMS">
<section name="Trace"
type="System.Configuration.SingleTagSectionHandler" />
</sectionGroup>
</configSections>
<IBM.XMS>
<Trace traceSpecification="*=all=enabled" traceFilePath="c:\somepath" />
</IBM.XMS>
</configuration>
If you do not specify a traceFilePath, or if the traceFilePath is present but contains
an empty string, the trace file is placed in the current directory.
You can turn trace on for components in a hierarchy either individually or
collectively. The types of trace available include:
v Method entry and exit trace
v Debug trace
v Exception trace
v Warnings, informational messages and error messages.
Trace can be enabled both by component and trace type. It is also possible to turn
trace on for an entire trace group. The general trace specification is of the following
form:
<ComponentName>=<type>=<state>
where:
34
Message Service Clients for C/C++ and .NET
v ComponentName is the name of the class that you want to trace. You can use a *
wildcard character in this name. For example, *=all=enabled specifies that you
want to trace all classes, and IBM.XMS.impl.*=all=enabled specifies that you
require API trace only.
v type can be any of the following trace types:
– all
– debug
– event
– EntryExit
v state can be either enabled or disabled.
You can string multiple trace elements together by using a ’:’ (colon) delimiter.
Trace configuration using XMS environment variables
You can turn trace on usingXMS environment variables. These environment
variables are only used if there is no trace specification in the application
configuration file.
To configure trace for an XMS .NET application, set the following environment
variables before running the application:
Table 8. Environment variable settings
Environment variables
Default
Settings
Meaning
XMS_TRACE_ON
Not
applicable
Not
applicable:
the value of
this variable
is ignored
If XMS_TRACE_ON is set, all
trace is enabled by default.
XMS_TRACE_FILE_PATH
Current
working
directory
/dirpath/
The directory path that trace and
FFDC records are written to.
XMS_TRACE_SPECIFICATION
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.
Overrides the trace specification,
which follows the format
specified in ..
Chapter 4. Problem determination
35
Configuring FFDC for .NET applications
For the .NET implementation of XMS, one FFDC file is produced for each FFDC.
FFDC files are stored in human readable text files and have names of the form
xmsffdc<processID>_<DateTime>.txt. Files start with the date and time that the
exception occurred, followed by the exception type, and include a unique short
probeId, which can be used to locate where this FFDC occurred.
You do not need to carry out any configuration to turn FFDC on. By default, all
FFDC files are written to the current directory, but you can, if required, specify a
different directory by changing ffdcDirectory in the Trace section of the application
configuration file. In the following example, all trace files are logged to the
directory c:client\ffdc:
<IBM.XMS>
<Trace ffdc=true ffdcDirectory="c:\client\ffdc"/>
</IBM.XMS>
You can disable trace by setting ffdc to false in the Trace section of the application
configuration file.
If you are not using an application configuration file, FFDC is on and trace is off.
36
Message Service Clients for C/C++ and .NET
Part 2. Programming with XMS
Chapter 5. Writing XMS applications . . . . . . .
The threading model . . . . . . . . . . . . .
Connections . . . . . . . . . . . . . . . .
Starting and stopping a connection . . . . . . .
Closing a connection . . . . . . . . . . . .
Handling exceptions . . . . . . . . . . . .
Connecting to a WebSphere service integration bus . .
Sessions . . . . . . . . . . . . . . . . .
Transacted sessions . . . . . . . . . . . . .
Acknowledging the receipt of messages in a session . .
Asynchronous message delivery . . . . . . . .
Synchronous message delivery . . . . . . . . .
Message delivery mode . . . . . . . . . . .
Destinations . . . . . . . . . . . . . . . .
Topic uniform resource identifiers (URIs) . . . . .
Queue uniform resource identifiers (URIs) . . . . .
Temporary destinations . . . . . . . . . . .
Message producers with no associated destination . . .
Durable subscribers. . . . . . . . . . . . . .
Non-durable subscribers . . . . . . . . . . . .
Queue browsers . . . . . . . . . . . . . . .
Requestors. . . . . . . . . . . . . . . . .
Deleting objects . . . . . . . . . . . . . . .
Implicit conversion of a property value from one data type
Iterators . . . . . . . . . . . . . . . . .
Coded character set identifiers (CCSIDs). . . . . . .
. . . . . . . . . . . . . . . . . . . 39
. . . . . . . . . . . . . . . . . . . 39
. . . . . . . . . . . . . . . . . . . 40
. . . . . . . . . . . . . . . . . . . 40
. . . . . . . . . . . . . . . . . . . 40
. . . . . . . . . . . . . . . . . . . 41
. . . . . . . . . . . . . . . . . . . 41
. . . . . . . . . . . . . . . . . . . 42
. . . . . . . . . . . . . . . . . . . 42
. . . . . . . . . . . . . . . . . . . 43
. . . . . . . . . . . . . . . . . . . 44
. . . . . . . . . . . . . . . . . . . 45
. . . . . . . . . . . . . . . . . . . 45
. . . . . . . . . . . . . . . . . . . 45
. . . . . . . . . . . . . . . . . . . 46
. . . . . . . . . . . . . . . . . . . 48
. . . . . . . . . . . . . . . . . . . 48
. . . . . . . . . . . . . . . . . . . 49
. . . . . . . . . . . . . . . . . . . 49
. . . . . . . . . . . . . . . . . . . 51
. . . . . . . . . . . . . . . . . . . 51
. . . . . . . . . . . . . . . . . . . 52
. . . . . . . . . . . . . . . . . . . 52
to another . . . . . . . . . . . . . . . 53
. . . . . . . . . . . . . . . . . . . 55
. . . . . . . . . . . . . . . . . . . 56
Chapter 6. Writing XMS applications in C . . . . . . . . . . . . . . . . . . . . . . . . 59
Object handles in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Getting and setting properties in C . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Using message and exception listener functions in C . . . . . . . . . . . . . . . . . . . . . 60
Using message listener functions in C . . . . . . . . . . . . . . . . . . . . . . . . . 60
Using exception listener functions in C . . . . . . . . . . . . . . . . . . . . . . . . . 61
C functions that return a string by value . . . . . . . . . . . . . . . . . . . . . . . . . 62
C functions that return a byte array by value . . . . . . . . . . . . . . . . . . . . . . . . 62
C functions that return a string or byte array by reference . . . . . . . . . . . . . . . . . . . . 63
C functions that accept a string as input . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Handling errors in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
The error block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Chapter 7. Writing XMS applications in C++ . . . . . . . . . . . . . . . . . . . . . . . 67
Using namespaces in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Using the String class in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
C++ methods that return a byte array . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Getting and setting properties in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Handling errors in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Using message and exception listeners in C++ . . . . . . . . . . . . . . . . . . . . . . . . 71
Using message listeners in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Using exception listeners in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Assigning XMS objects in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Using the C API in a C++ application . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Chapter 8. Writing .NET applications . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Destinations in .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Getting and setting properties in .NET . . . . . . . . . . . . . . . . . . . . . . . . . . 79
© Copyright IBM Corp. 2005
37
Handling of non-existent properties in .NET .
Handling errors in .NET . . . . . . . .
Using message and exception listeners in .NET
Using message listeners in .NET . . . .
Using exception listeners in .NET . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 9. XMS messages . . . . . . . . . .
Header fields in an XMS message . . . . . . . .
Properties of an XMS message . . . . . . . . .
JMS defined properties of a message . . . . . .
IBM defined properties of a message . . . . . .
Application defined properties of a message . . .
The body of an XMS message . . . . . . . . .
Bytes messages . . . . . . . . . . . . .
Map messages . . . . . . . . . . . . .
Object messages . . . . . . . . . . . . .
Stream messages . . . . . . . . . . . .
Text messages . . . . . . . . . . . . .
Message selectors . . . . . . . . . . . . .
Mapping XMS messages onto WebSphere MQ messages
Chapter 10. Working with administered objects
Supported types of administered object repository
Property mapping for administered objects . . .
Required connection factory properties . . . .
Required destination properties . . . . . . .
Creating administered objects . . . . . . .
Creating an InitialContext . . . . . . . .
InitialContext properties . . . . . . . . .
URI format for XMS initial contexts . . . . .
Retrieval of administered objects . . . . . .
38
Message Service Clients for C/C++ and .NET
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
80
81
81
81
81
. . . . . . . . . . . . . . . . . . . . 85
. . . . . . . . . . . . . . . . . . . . 85
. . . . . . . . . . . . . . . . . . . . 86
. . . . . . . . . . . . . . . . . . . . 87
. . . . . . . . . . . . . . . . . . . . 87
. . . . . . . . . . . . . . . . . . . . 89
. . . . . . . . . . . . . . . . . . . . 89
. . . . . . . . . . . . . . . . . . . . 91
. . . . . . . . . . . . . . . . . . . . 91
. . . . . . . . . . . . . . . . . . . . 92
. . . . . . . . . . . . . . . . . . . . 92
. . . . . . . . . . . . . . . . . . . . 93
. . . . . . . . . . . . . . . . . . . . 93
. . . . . . . . . . . . . . . . . . . . 94
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. . 97
. . 97
. . 97
. . 98
. . 98
. . 99
. . 99
. . 100
. . 100
. . 101
Chapter 5. Writing XMS applications
This chapter provides information that you might find useful when writing XMS
applications. The information in this section applies to C, C++ and .NET
applications.
If you are writing applications in C, see also Chapter 6, “Writing XMS applications
in C,” on page 59. If you are writing applications in C++, see also Chapter 7,
“Writing XMS applications in C++,” on page 67. If you are writing .NET
applications, see also Chapter 8, “Writing .NET applications,” on page 79.
The chapter contains the following sections:
v
v
v
v
v
v
v
v
v
v
“The threading model”
“Connections” on page 40
“Sessions” on page 42
“Destinations” on page 45
“Temporary destinations” on page 48
“Durable subscribers” on page 49
“Queue browsers” on page 51
“Requestors” on page 52
“Deleting objects” on page 52
“Implicit conversion of a property value from one data type to another” on page
53
v “Iterators” on page 55
v “Coded character set identifiers (CCSIDs)” on page 56
The threading model
A set of general rules govern how a multithreaded application can use XMS
objects.
These rules are as follows:
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.
v Any object created by a session cannot be used on one thread at the same time
that the session, or any object created by the session, is being used on another
thread.
Exceptions to these rules are indicated by entries labelled “Thread context” in the
interface definitions of the methods in the reference section.
© Copyright IBM Corp. 2005
39
Connections
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++, there is a single type of ConnectionFactory which has a property
that enables you to select which type of protocol you want to use for a connection.
For .NET, an XMS application first uses an XMSFactoryFactory object to get a
reference to a ConnectionFactory object that is appropriate to the required type of
protocol. This ConnectionFactory object can then only produce connections for that
protocol type.
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.
An XMS application can create multiple connections, and a multithreaded
application can use a single Connection object concurrently on multiple threads.
A connection serves several purposes:
v A Connection object encapsulates a communications connection between an
application and a messaging server.
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.
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.
Starting and stopping a connection
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 send messages but
not receive messages, either synchronously or asynchronously. The application can
use the time while the connection is in stopped mode to initialize sessions.
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.
Closing a connection
An application closes a connection by calling the Close Connection method.
When an application closes a connection, XMS takes the following actions:
v XMS closes all the sessions associated with the connection and deletes certain
objects associated with these sessions. For more information about which objects
40
Message Service Clients for C/C++ and .NET
are deleted, see “Deleting objects” on page 52. At the same time, XMS rolls back
any transactions currently in progress within the sessions.
v XMS ends the communications connection with the messaging server.
v XMS releases the memory and other internal resources used by the connection.
If the application is responsible for acknowledging the receipt of messages in a
session, closing the connection does not force XMS to acknowledge the receipt of
any messages that the application has failed to acknowledge. For more information
about acknowledging the receipt of messages, see “Acknowledging the receipt of
messages in a session” on page 43.
Handling exceptions
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 if 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, 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.
For more information about using exception listener functions in a C application,
see “Using exception listener functions in C” on page 61. If you are using C++, see
“Using exception listeners in C++” on page 73 instead.
XMS .NET exceptions are all derived from System.Exception. For more
information, see “Handling errors in .NET” on page 81.
Connecting 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 property is not set explicitly. If the connection is created
successfully, the XMSC_WPM_CONNECTION_PROTOCOL property of the
connection is set to XMSC_WPM_CP_TCP.
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
Chapter 5. Writing XMS applications
41
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, they
each receive 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 needs to 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.
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
42
Message Service Clients for C/C++ and .NET
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 rollback
all these actions as a single transaction.
Acknowledging the receipt of messages in a session
Every session that is not transacted has an acknowledgement mode that
determines how messages received by the application are acknowledged. There are
three possible acknowledgement modes, 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. There
are three acknowledgement modes:
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. And 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.
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.
Chapter 5. Writing XMS applications
43
XMSC_DUPS_OK_ACKNOWLEDGE
The session automatically acknowledges the messages received by the
application, but at times chosen by the session.
Using this acknowledgement mode reduces the amount of work the
session needs to do, but a failure that prevents acknowledgement from
occurring might mean that more than one message becomes available for
delivery again. The application must therefore be able to handle any
messages that are re-delivered.
XMSC_CLIENT_ACKNOWLEDGE
The application has responsibility for acknowledging the messages it
receives by calling the Acknowledge method of the Message class.
The application can acknowledge the receipt of each message individually.
Alternatively, the application can receive a batch of messages and call the
Acknowledge method only for the last message it receives. Calling the
Acknowledge method causes acknowledgement of all messages received
since the last time the method was called.
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. Those messages whose receipt was previously unacknowledged
are re-delivered. However, these messages might not be delivered in the same
sequence that they were previously delivered. In the meantime, higher priority
messages might have arrived, and some of the original messages might have
expired. And, 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.
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 needs concurrent delivery of messages, it must create more than
one session, so that XMS uses more than one thread to handle asynchronous
44
Message Service Clients for C/C++ and .NET
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 “Using message listener functions in C” on page 60. If you are using C++, see
“Using message listeners in C++” on page 72 instead.
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 at most 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.
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 runtime, or obtain a
predefined destination from the repository of administered objects.
As with a connection factory, the most flexible way for an XMS application to
specify a destination is to define it as an administered object. This approach allows
applications written in C, C++ and .NET languages, as well as Java, to 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 uniform resource identifier (URI), which is a string that identifies a
destination and, optionally, specifies 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 145 for C or “Destination” on
page 295 for C++.
Chapter 5. Writing XMS applications
45
For further information about creating a URI, see “Topic uniform resource
identifiers (URIs)” and “Queue uniform resource identifiers (URIs)” on page 48
For .NET applications, you create a destination by using the CreateTopic or
CreateQueue method. These two methods are available in both the ISession and
XMSFactoryFactory objects in the .NET API.
For further information, see “Destinations in .NET” on page 79 and “IDestination”
on page 441 for .NET.
Topic uniform resource identifiers (URIs)
The topic uniform resource identifier (URI) for a topic specifies the name of the
topic, and, optionally, one or more properties of the topic.
The URI for a topic begins with the sequence topic://, followed by the name of
the topic and, optionally, 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 530.
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
schemes are:
v WebSphere MQ queue manager with broker v1 (WebSphere MQ
Publish/Subscribe)
v WebSphere MQ with, or real-time connection to, broker v2 (WebSphere Business
Integration Event Broker or WebSphere Business Integration Message Broker)
v WebSphere service integration bus
WebSphere MQ queue manager with broker v1
Table 9. Wildcard scheme for WebSphere MQ queue manager with broker v1
Wildcard character
Description
*
0 or more characters
?
1 character
%
Escape character
Table 10 gives some examples of how to use this wildcard scheme.
Table 10. Example URIs using wildcard scheme for WebSphere MQ queue manager with broker v1
URI
Matches
″topic://Sport*Results″
All topics starting with ″Sport″ and ending in ″Results″ such as
″topic://SportsResults″ and
″topic://Sport/Hockey/National/Div3/Results″
″topic://Sport?Results″
All topics starting with ″Sport″ followed by a single character,
followed by ″Results″ such as ″topic://SportsResults″ and
″topic://SportXResults″
46
Message Service Clients for C/C++ and .NET
Table 10. Example URIs using wildcard scheme for WebSphere MQ queue manager with broker v1 (continued)
URI
Matches
″topic://Sport/*ball*/Div?/Results/*/???″
Topics such as ″topic://Sport/Football/Div1/Results/2002/Nov″ and
″topic://Sport/Netball/National/Div3/Results/02/Jan″
WebSphere MQ with, or real-time connection to, a broker v2
Table 11. Wildcard scheme for WebSphere MQ with, or real-time connection to, a broker v2
Wildcard character
Description
#
Match multiple levels
+
Match a single level
Table 12 gives some examples of how to use this wildcard scheme.
Table 12. Example URIs using wildcard scheme for WebSphere MQ with, or real-time connection to, a broker v2
URI
Matches
″topic://Sport/+/Results″
All topics with a single hierarchical level name between Sport and
Results, such as ″topic://Sport/Football/Results″ and
″topic://Sport/Ju-Jitsu/Results″
″topic://Sport/#/Results″
All topics starting with ″Sport/″ and ending in ″/Results″ such as
″topic://Sport/Football/Results″ and
″topic://Sport/Hockey/National/Div3/Results″
″topic://Sport/Football/#″
All topics starting with ″Sport/Football/″ such as
″topic://Sport/Football/Results″ and
″topic://Sport/Football/TeamNews/Signings/Managerial″
WebSphere service integration bus
Table 13. Wildcard scheme for WebSphere service integration bus
Wildcard character
Description
*
Match any characters at one level in the hierarchy
//
Match 0 or more levels
//.
Match 0 or more levels (at the end of a Topic
expression)
Table 14 gives some examples of how to use this wildcard scheme.
Table 14. Example URIs using wildcard scheme for WebSphere service integration bus
URI
Matches
″topic://Sport/*ball/Results″
All topics with a single hierarchical level name ending in ″ball″
between Sport and Results, such as ″topic://Sport/Football/Results″
and ″topic://Sport/Netball/Results″
″topic://Sport//Results″
All topics starting with ″Sport/″ and ending in ″/Results″ such as
″topic://Sport/Football/Results″ and
″topic://Sport/Hockey/National/Div3/Results″
″topic://Sport/Football//.″
All topics starting with ″Sport/Football/″ such as
″topic://Sport/Football/Results″ and
″topic://Sport/Football/TeamNews/Signings/Managerial″
Chapter 5. Writing XMS applications
47
Table 14. Example URIs using wildcard scheme for WebSphere service integration bus (continued)
URI
Matches
″topic://Sport/*ball//Results//.″
Topics such as ″topic://Sport/Football/Results″ and
″topic://Sport/Netball/National/Div3/Results/2002/November″
Queue uniform resource identifiers (URIs)
The URI for a queue specifies the name of the queue, and, optionally, one or more
properties of the queue.
The URI for a queue begins with the sequence queue://, followed by the name of
the queue, and optionally, 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
optionally 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 it.
Remote queue managers are only supported for retrieving messages from 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 example is 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 C example connects to queue Q1 on queue manager HOST1.QM1,
and causes all messages to be sent as nonpersistent and priority 5:
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.
48
Message Service Clients for C/C++ and .NET
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 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 is the
sooner.
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,
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 with no associated destination
In the C and C++ API, a message producer can be created with a null destination.
The C API allows NULL to 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, see “Session” on page 241 for C.
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, see “Session” on page 389 for C++.
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
Chapter 5. Writing XMS applications
49
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 can specify whether the durable subscriber is to receive messages published
by its own connection.
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, and is specified by setting the XMSC_CLIENT_ID
property of the connection factory that is used to create the connection.
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 until 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 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 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. If
you do need to change the subscriber queue, the only way is to delete the
subscription and create a new one.
50
Message Service Clients for C/C++ and .NET
For an application that connects to a service integration bus, each durable
subscriber must have a designated durable subscription home. To specify the
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. Any 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.
If message consumer applications are not shut down gracefully, with the consumer
objects being deleted prior to or during the closing of the connection, then
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. Full 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 you find
large numbers of messages left on this queue as a result of this issue.
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. If the iterator ever indicates that there are no more messages on the
queue, the iterator stops returning messages from that point onwards, 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.
Chapter 5. Writing XMS applications
51
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
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 85.
Requestors
An application uses a requestor to send a request message and then wait for, and
receive, the reply.
Many messaging applications are based around 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 then 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 blocks until the
reply is received or until the session ends, whichever is the sooner. The requestor
expects only one reply to each request message.
When the application closes the requestor, the temporary queue or topic is deleted.
The associated session, however, does not close. In this respect, XMS behaves
differently compared to JMS.
Deleting objects
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 depend for their
existence upon the connection or session. These objects are shown in Table 15 on
page 53. 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.
52
Message Service Clients for C/C++ and .NET
Table 15. 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
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. There are a number of rules that govern which
conversions are supported and how XMS performs the conversions.
A property of an object has a name and a value, where the value has an associated
data type. The data type of 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
normally calls the method that is appropriate for the property type. For example,
to get the value of an integer property, an application normally 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 16.
Table 16. 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
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 general rules governing the supported conversions are as follows:
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 cannot be converted into a value with data type xmsSHORT.
v A property value of any data type can be converted into a string.
Chapter 5. Writing XMS applications
53
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 returns error
code XMS_E_NUMBER_FORMAT_ERROR.
v If an application attempts a conversion that is not supported, XMS returns error
code XMS_E_TYPE_CONVERSION_FAILED.
The specific rules for converting a property value from one data type to another
are as follows:
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. Any other string 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 meanings of the components of the string are 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.
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 returns error code XMS_E_NUMBER_FORMAT_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[e_char[e_sign]e_digits]
The meanings of the components of the string are 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.
e_char An exponent character, which is either E or e.
e_sign An 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.
54
Message Service Clients for C/C++ and .NET
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 returns error code XMS_E_NUMBER_FORMAT_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 returns error code XMS_E_TYPE_CONVERSION_FAILED.
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.
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. XMS .NET is
similar to Java and uses an IEnumerator interface.
An application can use an iterator to perform any of 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)
{
Chapter 5. Writing XMS applications
55
rc = xmsIteratorHasNext(it, &more, xmsError);
while (more)
{
rc = xmsIteratorGetNextProperty(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");
xmsIteratorDispose(&it, xmsError);
}
/********************************************************/
Coded character set identifiers (CCSIDs)
For C or C++, strings of character data 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, if necessary, XMS converts the character data in the string from the
code page used by the object into the code page that XMS needs the data to be in.
Similarly, when an object receives a string of character data from XMS across the
API, if necessary, XMS converts 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 needs to know 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 property is a coded character set
identifier (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.
56
Message Service Clients for C/C++ and .NET
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 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. And 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.
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 a CCSID that is not valid, or specifies a CCSID for
which the platform does not support code page conversion, the call fails
and XMS returns error code XMS_E_ILLEGAL_PROPERTY_VALUE.
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
needs to determine which code page the object is using.
This is a special value of the property and is not an actual CCSID.
Chapter 5. Writing XMS applications
57
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 85)
v Properties (see “Properties of an XMS message” on page 86)
v The body (see “The body of an XMS message” on page 89)
When XMS needs to convert the strings in an outgoing message, XMS uses the
code page associated with the session that created the message. When XMS needs
to convert the strings in an incoming message, XMS 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 how much data needs to be converted and how frequently it is done. If you are
designing applications to maximize the throughput of messages, you might want
to consider ways of reducing the amount of data conversion that is required. Here
are two examples of how this can be done:
v In some situations, you might know that the strings in incoming messages are in
a certain code page, the UTF-8 representation of Unicode data, for example. 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. Since this
class has a fixed encoding, no further information is required to interpret it.
58
Message Service Clients for C/C++ and .NET
Chapter 6. Writing XMS applications in C
This chapter provides information that you might find useful when writing XMS
applications in C.
The chapter contains the following sections:
v “Object handles in C”
v “Using message and exception listener functions in C” on page 60
v “C functions that return a string by value” on page 62
v “C functions that return a byte array by value” on page 62
v “C functions that return a string or byte array by reference” on page 63
v “C functions that accept a string as input” on page 64
v “Handling errors in C” on page 64
Object handles in C
A C application uses an object handle to access an object. There are two kinds of
object handle. One kind of object handle has a data type that is related to the type
of the object, and the other kind 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 subsequently to access the object.
Every object handle has a data type, which is related to the type of the object.
Table 17 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 89.
Table 17. Object handle data types
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,
StreamMessage, and TextMessage
xmsHMsg
MessageConsumer
xmsHMsgConsumer
MessageProducer
xmsHMsgProducer
Property
xmsHProperty
QueueBrowser
xmsHQueueBrowser
© Copyright IBM Corp. 2005
59
Table 17. Object handle data types (continued)
Type of object
Object handle data type
Requestor
xmsHRequestor
Session
xmsHSess
Certain functions return a generic object handle, which is not related to the type of
the 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 object handle data type that is related to the type of the
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.
Getting and setting 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 59.
All objects can have properties except ErrorBlock, Iterator, and Property objects.
If an application sets the value of a property, the new value replaces any previous
value the property had.
Using 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.
Using 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.
60
Message Service Clients for C/C++ and .NET
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.
Note that it is the responsibility of the application to 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, this
time 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
normally, 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 193.
Using 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
needs to refer to when processing an error block. In all other respects, the way that
context data is used with an exception listener function is the same as the way it is
used with a message listener function.
For more information about the exception listener function, including its signature,
see “MessageListener” on page 343.
Note that it is the responsibility of the application to release the resources used by
an error block received in this way. XMS does not release these resources.
Chapter 6. Writing XMS applications in C
61
To stop the asynchronous reporting of problems with a connection, the application
can call the xmsConnSetExceptionListener() function again, this time passing a null
pointer as a parameter instead of a pointer to an exception listener function.
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. Here is an example of one
of these functions, xmsGetStringProperty() in the PropertyContext class:
xmsRC xmsGetStringProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsCHAR *propertyValue,
xmsINT length,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);
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.
Note that, 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. You cannot use the standard C string manipulation
functions to process strings containing embedded nulls because these functions
assume that the first null character in a string marks 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.
62
Message Service Clients for C/C++ and .NET
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. Here is an example of
one of these functions, 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.
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 error code XMS_E_DATA_TRUNCATED.
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, tells the application 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 62 or “C functions that return a byte array by
value” on page 62, 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 have an impact on performance.
To deliver better performance in this situation, the C API provides another set of
functions. 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().
Chapter 6. Writing XMS applications in C
63
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.
Because these functions return a pointer to memory owned by XMS, the
application must not attempt to free or modify the contents of this memory.
Attempting to do so might cause unpredictable results.
The pointer returned to the application remains valid until the XMS object, with
which the string or byte array is associated, is deleted. The application must copy
the string or byte array if it needs the data after the object is deleted.
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. Here is an example
of one of these functions, 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
This parameter is a pointer to a character array that contains the string to
be passed to XMS.
length This parameter is 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.
Handling errors 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 respective 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 18 shows the possible return codes
and their meaning.
Table 18. Return codes from C function calls
64
Return code
Meaning
XMS_OK
The call completed successfully.
Message Service Clients for C/C++ and .NET
Table 18. Return codes from C function calls (continued)
Return code
Meaning
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 from the error block.
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 does not indicate precisely
which error has occurred. The header file xmsc.h defines a named constant
for each exception code.
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. If XMS needs 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
150.
Chapter 6. Writing XMS applications in C
65
66
Message Service Clients for C/C++ and .NET
Chapter 7. Writing XMS applications in C++
This chapter provides information that you might find useful when writing XMS
applications in C++.
The chapter contains the following sections:
v “Using namespaces in C++”
v “Using the String class in C++” on page 68
v “C++ methods that return a byte array” on page 68
v “Getting and setting properties in C++” on page 69
v “Handling errors in C++” on page 69
v “Using message and exception listeners in C++” on page 71
v “Assigning XMS objects in C++” on page 74
v “Using the C API in a C++ application” on page 76
Using 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. See the following fragment of code, for example:
#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. See the following fragment of code,
for example:
#include <xms.hpp>
using namespace std;
using namespace xms;
int main(int argc, char *argv[])
© Copyright IBM Corp. 2005
67
{
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);
}
Using the String class 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 simply 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 412.
C++ methods that return a byte array
This section describes the interface used by C++ methods that return a byte array.
68
Message Service Clients for C/C++ and .NET
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. Here is an example of
one of these methods, PropertyContext.getBytesProperty():
xmsINT getBytesProperty(const String & propertyName,
xmsSBYTE *propertyValue,
const xmsINT length,
xmsINT *actualLength) const;
The way that the parameters propertyValue, length, and actualLength control the
retrieval of the byte array is exactly the same as the way described in “C functions
that return a byte array by value” on page 62.
Other examples of these methods are MapMessage.getBytes(),
MapMessage.getObject(), Property.getByteArray(), and String.get().
Getting and setting 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.
Handling errors in C++
If XMS detects an error while processing a call to a method, XMS throws an
exception.
An XMS exception is an object of one of the following types:
v Exception
v IllegalStateException
Chapter 7. Writing XMS applications in C++
69
v
v
v
v
v
v
v
InvalidClientIDException
InvalidDestinationException
InvalidSelectorException
MessageEOFException
MessageFormatException
MessageNotReadableException
MessageNotWritableException
v
v
v
v
ResourceAllocationException
SecurityException
TransactionInProgressException
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 simply 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
nRC = -1;
}
return(nRC);
}
Note that, if an application uses this technique to catch XMS exceptions, the
application must catch an exception by reference, and not by value. This ensures
that an exception is not sliced and 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 simply specify the std::exception class in the exception declaration
of the catch construct. The following code fragment illustrates this point:
70
Message Service Clients for C/C++ and .NET
#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, the application 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 299. 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 65.
If XMS detects more than one error during a call, XMS can create an exception for
each error and link the exceptions to form a chain. After an application has caught
the first exception, the application 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.
Note that, because the getLinkedException() method returns a pointer to a linked
exception, it is the responsibility of the application to release the object using the
C++ delete operator.
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.
Using message and exception listeners in C++
A C++ application uses a message listener to receive messages asynchronously, and
uses an exception listener to be notified asynchronously of a problem with a
connection.
Chapter 7. Writing XMS applications in C++
71
Using 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 the message listener, and so the
application must ensure that the message listener is still available when XMS calls
the onMessage() method.
Note that, 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 needs
concurrent delivery of messages, see “Asynchronous message delivery” on page
44.
To stop the asynchronous delivery of messages to a message consumer, the
application can call the setMessageListener() method again, this time 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 how to implement a message
listener class with an onMessage() method:
#include <xms.hpp>
using namespace std;
class MyMsgListener : public xms::MessageListener
{
public:
virtual xmsVOID onMessage(const xms::Message * pMsg);
};
-------–-------------------------------------------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;
72
Message Service Clients for C/C++ and .NET
}
delete pMsg;
}
}
Note that, because XMS delivers a pointer to a message when it calls the
onMessage() method, it is the responsibility of the application to 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
sess
dest
msgConn
=
=
=
=
cf.createConnection();
conn.createSession();
xms::Destination(XMS_DESTINATION_TYPE_TOPIC, "test");
sess.createConsumer(dest);
msgConn.setMessageListener(&msgLst);
conn.start();
while(xmsTRUE)
{
Sleep(1000);
cout << "Waiting..." << endl;
}
}
catch(exception & ex)
{
nRC = -1;
}
return(nRC);
}
Using 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
Chapter 7. Writing XMS applications in C++
73
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 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, this time 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.
Note that, because XMS passes a pointer to an exception when it calls the
onException() method, it is the responsibility of the application to release the
exception by using the C++ delete operator.
Assigning XMS objects 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 19. 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:
v For some types of object, 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 object, 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 19 indicates, for each type of object, whether the overloaded assignment
operator makes a shallow or a deep copy of an object.
Table 19. The XMS classes on which the assignment operator is overloaded
Class
BytesMessage
U
Connection
U
ConnectionFactory
U
ConnectionMetaData
U
Destination
U
Deep copy
Exception
U
IllegalStateException
U
InitialContext
74
Shallow copy
U
InvalidClientIDException
U
InvalidDestinationException
U
Message Service Clients for C/C++ and .NET
Table 19. The XMS classes on which the assignment operator is overloaded (continued)
Class
Shallow copy
InvalidSelectorException
Deep copy
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
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 points:
#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();
Chapter 7. Writing XMS applications in C++
75
// 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.
if (sess2.isNull() == xmsTRUE)
{
cout << "invalid session" << endl;
}
return(0);
}
Using the C API 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();
76
Message Service Clients for C/C++ and .NET
// Retrieve the handle for the connection.
hConn = conn.getHandle();
// Using the retrieved handle, call a C API function.
xmsConnStart(hConn, NULL);
// 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 closes or
deletes an object in this way, the application can no longer use the object using the
C++ API.
Being able to use the C API is useful if a C++ application needs to use function
that is available only in the C API. The function described in “C functions that
return a string or byte array by reference” on page 63 is an example of such
function.
Chapter 7. Writing XMS applications in C++
77
78
Message Service Clients for C/C++ and .NET
Chapter 8. Writing .NET applications
This chapter provides information that you might find useful when writing XMS
.NET applications.
The chapter contains the following sections:
v “Destinations in .NET”
v “Getting and setting properties in .NET”
v “Handling of non-existent properties in .NET” on page 80
v “Handling errors in .NET” on page 81
v “Using message and exception listeners in .NET” on page 81
Destinations in .NET
In .NET, destinations are created according to protocol type and can only be used
on the protocol type for which they are created.
Two functions are provided for creating destinations, one for topics and one for
queues:
v IDestination CreateTopic(String topic);
v IDestination CreateQueue(String queue);
These functions are available on the following two objects in the API:
v ISession
v XMSFactoryFactory
In both cases these methods can accept a URI style string, which can include
parameters, in the following format:
"topic://some/topic/name?priority=5"
Alternatively, these methods can accept just a destination name, that, is, a name
without a topic:// or queue:// prefix and without parameters.
So, the following URI style string:
CreateTopic("topic://some/topic/name");
would produce the same result as the following destination name:
CreateTopic("some/topic/name");
As for WebSphere service integration bus JMS, topics can also be specified in a
shorthand form which includes both the topicname and topicspace but cannot
include parameters:
CreateTopic("topicspace:topicname");
Getting and setting properties in .NET
A .NET application uses the methods in the PropertyContext interface to get and
set the properties of objects.
© Copyright IBM Corp. 2005
79
The PropertyContext interface encapsulates methods that get and set properties.
These methods are inherited, directly or indirectly, by the following classes:
v BytesMessage
v Connection
v
v
v
v
v
v
v
v
v
v
v
v
ConnectionFactory
ConnectionMetaData
Destination
MapMessage
Message
MessageConsumer
MessageProducer
ObjectMessage
QueueBrowser
Session
StreamMessage
TextMessage
If an application sets the value of a property, the new value replaces any previous
value the property had.
For further information about XMS properties, see Chapter 15, “Properties of XMS
objects,” on page 527.
For ease of use, in .NET XMS property names and values are predefined as public
constants in a class called XMSC. The names of these constants are in the form
XMSC.USERID. Alternatively, you can use the XMS property names used in C or
C++, which are in the form ″XMSC_USERID″. In this case, the property name must
be provided as a string.
Handling of non-existent properties in .NET
The handling of non-existent properties in the XMS .NET is broadly consistent
with the JMS specification, whilst also maintaining some consistency with the C
and C++ implementations of XMS.
In JMS, accessing a non-existent property can result in a Java system exception
when a method tries to convert the non-existent (null) value to the required type.
If a property does not exist:
v getStringProperty and getObjectProperty return null
v getBooleanProperty returns false since Boolean.valueOf(null) returns false
v getIntProperty etc.throw java.lang.NumberFormatException since
Integer.valueOf(null) throws the exception
If a property does not exist in XMS .NET:
v GetStringProperty and GetObjectProperty (and GetBytesProperty) return null
(which is the same as Java)
v GetBooleanProperty throws System.NullReferenceException
v GetIntProperty etc, throws System.NullReferenceException
This implementation is different from Java, but it is broadly consistent with the
JMS specification, whilst also maintaining some consistency with the XMS C and
80
Message Service Clients for C/C++ and .NET
C++ interfaces. Like the Java implementation, XMS .NET propagates any
exceptions from the System.Convert call to the caller. The difference is that XMS
explicitly throws NullReferenceExceptions rather than just using the native
behavior of the .NET framework through passing null to system conversion
routines. If your application sets a property to a String like “abc” and calls
GetIntProperty, the System.FormatException thrown by Convert.ToInt32(″abc″) is
propagated to the caller, which is consistent with Java. MessageFormatException is
thrown only if the types used for setProperty and getProperty are incompatible.
This behavior is also consistent with Java.
Handling errors in .NET
XMS .NET exceptions are all derived from System.Exception. XMS method calls
can throw specific XMS exceptions such as MessageFormatException, general
XMSExceptions, or system exceptions such as NullReferenceException.
Applications should ideally be written to catch any of these, either in specific catch
blocks or in general System.Exception catch blocks, as appropriate to the
application’s requirements.
Using message and exception listeners in .NET
A .NET application uses a message listener to receive messages asynchronously,
and uses an exception listener to be notified asynchronously of a problem with a
connection.
The functionality of both the message and exception listeners is exactly the same
for .NET as it is for C++. However there are some small implementation
differences.
Using message listeners in .NET
To receive messages asynchronously you must:
1. Define a method which matches the signature of the message listener delegate.
The method that you define can be either a static or an instance method and
can be defined in any accessible class. The delegate signature is as follows:
public delegate void MessageListener(IMessage msg);
and so you could define the method as:
void SomeMethodName(IMessage msg);
2. Instantiate this method as a delegate using something similar to:
MessageListener OnMsgMethod = new MessageListener(SomeMethodName)
3. Register the delegate with one or more consumers by setting it to the
MessageListener property of the consumer as follows:
consumer.MessageListener = OnMsgMethod;
Remove the delegate by setting the MessageListener back to null:
consumer.MessageListener = null;
Using exception listeners in .NET
The exception listener works in much the same way as the message listener, but
has a different delegate definition and is assigned to the connection rather then the
message consumer. This is the same as for C++.
1. Define the method. The delegate signature is as follows:
public delegate void ExceptionListener(Exception ex);
Chapter 8. Writing .NET applications
81
and so the method defined could be:
void SomeMethodName(Exception ex);
2. Instantiate this method as a delegate using something similar to:
ExceptionListener OnExMethod = new ExceptionListener(SomeMethodName)
3. Register the delegate with the connection by setting its ExceptionListener
property:
connection.ExceptionListener = OnExMethod ;
and remove the delegate by setting the ExceptionListener back to:
null:
connection.ExceptionListener = null;
It is not necessary to delete exceptions or messages as this is taken care of
automatically by the garbage collector when no references to them remain.
A sample code for using the above would be:
using System;
using System.Threading;
using IBM.XMS;
public class Sample
{
public static void Main()
{
XMSFactoryFactory factoryFactory = XMSFactoryFactory.GetInstance(XMSC.CT_RTT);
IConnectionFactory connectionFactory = factoryFactory.CreateConnectionFactory();
connectionFactory.SetStringProperty(XMSC.RTT_HOST_NAME, "localhost");
connectionFactory.SetStringProperty(XMSC.RTT_PORT, "1506");
//
// Create the connection and register an exception listener
//
IConnection connection = connectionFactory.CreateConnection();
connection.ExceptionListener = new ExceptionListener(Sample.OnException);
ISession session = connection.CreateSession(false, AcknowledgeMode.AutoAcknowledge);
IDestination topic = session.CreateTopic("topic://xms/sample");
//
// Create the consumer and register an async message listener
//
IMessageConsumer consumer = session.CreateConsumer(topic);
consumer.MessageListener = new MessageListener(Sample.OnMessage);
connection.Start();
while (true)
{
Console.WriteLine("Waiting for messages....");
Thread.Sleep(1000);
}
}
static void OnMessage(IMessage msg)
{
Console.WriteLine(msg);
}
static void OnException(Exception ex)
82
Message Service Clients for C/C++ and .NET
{
Console.WriteLine(ex);
}
}
Chapter 8. Writing .NET applications
83
84
Message Service Clients for C/C++ and .NET
Chapter 9. XMS messages
This chapter describes the structure and content of XMS messages and how
applications process XMS messages.
An XMS message has the following parts:
A 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”
A 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 about
the properties of a message, see “Properties of an XMS message” on page
86.
A body
The body of a message contains application data. For more information
about the body of a message, see “The body of an XMS message” on page
89.
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 93.
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 174 for C, or “Message” on
page 325 for C++, or “IMessage” on page 459 for .NET. A header field is always
readable and writable.
Table 20 on page 86 lists the JMS message header fields and indicates how the
value of each field is set for a transmitted message. Note that 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.
© Copyright IBM Corp. 2005
85
Table 20. JMS message header fields
Name of the JMS message
header field
How the value is set for a transmitted message (in the
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
This section describes the properties of an XMS message and introduces the three
kinds of property supported by XMS: JMS defined properties, IBM defined
properties, and application defined properties.
To allow an XMS application to exchange messages with a WebSphere JMS
application, 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 commence with the prefix JMSX.
v The same IBM defined properties that WebSphere JMS supports. The names of
these properties commence 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
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.
An XMS application uses this 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 “Getting
and setting properties in C” on page 60 or “Getting and setting properties in C++”
on page 69.
86
Message Service Clients for C/C++ and .NET
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.
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 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 55.
JMS defined properties of a message
Table 21 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 the
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. Note that 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 21. JMS defined properties of a message
XMS name of the JMS
defined property
JMS name
How the value is set for a transmitted
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]
IBM defined properties of a message
Table 22 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. Note that some of the properties are
set automatically by XMS when an application sends a message.
Table 22. IBM defined properties of a message
XMS name of the IBM defined
property
WebSphere JMS name
Data type
JMS_IBM_CHARACTER_SET
JMS_IBM_Character_Set
xmsINT
How the value is set
for a transmitted
message (in the
format method [class])
Set Integer Property
[PropertyContext]
Chapter 9. XMS messages
87
Table 22. IBM defined properties of a message (continued)
How the value is set
for a transmitted
message (in the
format method [class])
XMS name of the IBM defined
property
WebSphere JMS name
Data type
JMS_IBM_ENCODING
JMS_IBM_Encoding
xmsINT
Set Integer Property
[PropertyContext]
JMS_IBM_EXCEPTION_MESSAGE
JMS_IBM_Exception_Message
String
Receive
[MessageConsumer]
JMS_IBM_EXCEPTION_REASON
JMS_IBM_Exception_Reason
xmsINT
Receive
[MessageConsumer]
JMS_IBM_EXCEPTION_TIMESTAMP
JMS_IBM_Exception_Timestamp
xmsLONG Receive
[MessageConsumer]
JMS_IBM_EXCEPTION_PROBLEM_
DESTINATION
JMS_IBM_ExceptionProblemDestination
String
Receive
[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]
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_
ID
JMS_IBM_Report_Pass_Correl_ID
xmsINT
Set Integer Property
[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]
88
Message Service Clients for C/C++ and .NET
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 contains the methods to
process the body of a bytes message. For more information about bytes
messages, see “Bytes messages” on page 91.
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 contains the methods to process the body
of a map message. For more information about map messages, see “Map
messages” on page 91.
Object
The body contains a serialized Java or .NET object. A message with this
type of body is called a object message. The ObjectMessage class contains
the methods to process the body of an object message. For more
information about object messages, see “Object messages” on page 92.
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 contains the methods to process the body of a stream
message. For more information about stream messages, see “Stream
messages” on page 92.
Text
The body contains a string. A message with this type of body is called a
text message. The TextMessage class contains the methods to process the
body of a text message. For more information about text messages, see
“Text messages” on page 93.
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 error code XMS_E_BAD_PARAMETER.
Chapter 9. XMS messages
89
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
See the following fragment of C code, for example:
xmsMESSAGE_TYPE msgtype;
xmsMsgConsumerReceive(messageConsumer, &msg, errorBlock);
xmsMsgGetTypeId(msg, &msgtype, errorBlock);
if (msgtype == XMS_MESSAGE_TYPE_BYTES)
{
xmsBytesMsgGetBodyLength(msg, &length, errorBlock);
}
In the C++ interface, BytesMessage, MapMessage, ObjectMessage, StreamMessage,
and TextMessage are subclasses of the Message class.
In .NET, the IMessage interface is the parent of all message objects, and can be
used in messaging functions to represent any of the XMS message types.
To ensure that XMS applications can exchange messages with WebSphere MQ JMS
applications, an XMS application and a WebSphere MQ JMS application 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 23. For each
XMS data type, the table shows the compatible Java data type. XMS provides the
methods to write elements of application data with these data types, and only
these data types.
Table 23. XMS data types that are compatible with Java data types
90
XMS data type Represents
Size
Compatible
Java data type
xmsBOOL
The boolean value xmsTRUE or xmsFALSE
32 bits
boolean
xmsCHAR16
Double byte character
16 bits
char
xmsSBYTE
Signed 8-bit integer
8 bits
byte
xmsSHORT
Signed 16-bit integer
16 bits
short
xmsINT
Signed 32-bit integer
32 bits
int
xmsLONG
Signed 64-bit integer
64 bits
long
xmsFLOAT
Signed floating point number
32 bits
float
xmsDOUBLE
Signed double precision floating point number
64 bits
double
String
String of characters
Message Service Clients for C/C++ and .NET
-
String
Bytes messages
The body of a bytes message contains a stream of bytes. The body contains no data
names or data type information, only the actual data, and it is entirely 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 multiple times.
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.
Using the C interface only, an application can skip over bytes without reading
them by calling a read function with a null pointer for the value parameter, or for
the buffer parameter if the application calls xmsBytesMsgReadBytes(). For
information about how to skip over a string, see “xmsBytesMsgReadUTF – Read
UTF String” on page 129.
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.
If an application calls the Clear Body method of the Message class 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 23 on page 90. 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, the 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
Chapter 9. XMS messages
91
then use the methods of the Iterator class to retrieve each Property object in turn,
and 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.
When an application gets the value of 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,
therefore, see “Implicit conversion of a property value from one data type to
another” on page 53.
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 when the body of an object message is read-only, the body becomes readable
and writable. The method also clears the body.
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 23 on page
90.
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. Each time the
application writes a value to the message stream, the value and its data type is
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.
92
Message Service Clients for C/C++ and .NET
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 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 for the
buffer parameter if the application calls xmsStreamMsgReadBytes() or
xmsStreamMsgReadObject(). For information about how to skip over a value that
is a string, see “xmsStreamMsgReadString – Read String” on page 260.
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 of the
StreamMessage 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, therefore, see “Implicit conversion of a property value from
one data type to another” on page 53.
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 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 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 an text 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 text 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 an 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 which messages it wants to
receive.
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. 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 satisfy the selection
criteria, XMS does not deliver the message and, in the point-to-point domain, the
message remains on the queue.
Chapter 9. XMS messages
93
An application can create more than one message consumer, each with its own
message selector expression. If an incoming message satisfies 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
v
v
v
v
v
v
can also reference the following message header fields:
JMSCorrelationID
JMSDeliveryMode
JMSMessageID
JMSPriority
JMSTimestamp
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
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 therefore, see WebSphere MQ Using Java. Note, in particular,
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
This section describes how 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
exactly 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_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
94
Message Service Clients for C/C++ and .NET
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_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 exactly 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 9. XMS messages
95
96
Message Service Clients for C/C++ and .NET
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.
The chapter contains the following sections:
v “Supported types of administered object repository”
v “Property mapping for administered objects”
v “Required connection factory properties” on page 98
v “Required destination properties” on page 98
v
v
v
v
v
“Creating administered objects” on page 99
“Creating an InitialContext” on page 99
“InitialContext properties” on page 100
“URI format for XMS initial contexts” on page 100
“Retrieval of administered objects” on page 101
Supported types of administered object repository
XMS supports two types of administered object directory: File System and
Lightweight Directory Access Protocol (LDAP). File System object directories take
the form of serialized Java and Naming Directory Interface (JNDI) objects. LDAP
object directories are any 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
automatically update themselves to reflect changes to connection settings made in
the central repository.
Note: It is necessary to restart application connections for changes to the object
directory to take effect.
Property mapping for administered objects
To enable applications to use WebSphere MQ JMS 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
© Copyright IBM Corp. 2005
97
in this table are just a small set of examples, and not all properties shown are
relevant to all connection types and servers.
Table 24. Name mapping examples for connection factory and destination properties
WebSphere MQ JMS
property short name
XMS property name
PER
XMSC_DELIVERY_MODE
EXP
XMSC_TIME_TO_LIVE
PRI
XMSC_PRIORITY
Required connection factory properties
When an application creates a connection factory, there are a number of properties
that must be defined to create a connection to a messaging server.
The properties listed below are the minimum properties that an application needs
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 528.
Connection to a WebSphere MQ queue manager
Table 25. Property settings for administered ConnectionFactory objects for connections to a
WebSphere MQ queue manager
XMS properties that must be set
Equivalent WebSphere MQ JMS properties that
must be set
XMSC_CONNECTION_TYPE
XMS works this out from the connection factory class
and TRAN property
XMSC_WMQ_HOST_NAME
HOST
XMSC_WMQ_PORT
PORT
Real-time connection to a broker
Table 26. Property settings for administered ConnectionFactory objects for real-time
connections to a broker
XMS properties that must be set
Equivalent WebSphere MQ JMS properties that
must be set
XMSC_CONNECTION_TYPE
XMS works this out from the connection factory class
and TRAN property
XMSC_RTT_HOST_NAME
HOST
XMSC_RTT_PORT
PORT
Required destination properties
When an application is creating a destination, there are a number of WebSphere
MQ JMS properties that an application must set on an administered Destination
object.
98
Message Service Clients for C/C++ and .NET
Table 27. WebSphere MQ JMS property settings for administered Destination objects
Type of connection
Property
Description
WebSphere MQ queue
manager
QU
The queue that you wish to connect to
QMGR
The queue manager that owns the queue
(optional)
TOP
The topic that the application uses as a
destination
Real-time connection to a
broker
TOP
The topic that the application uses as a
destination
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.
For further details about the different types of administered object repository that
XMS supports, see “Supported types of administered object repository” on page 97.
To create the administered objects for WebSphere MQ, WebSphere Business
Integration Event Broker, or WebSphere Business Integration Message Broker, use
the WebSphere MQ JMS administration (JMSAdmin) tool.
The following steps summarize what you need to do.
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
connection factory properties” on page 98.
2. Create the required destination on the messaging server that your application
will connect to:
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.
The minimum properties that XMS requires to make a connection are defined
in “Required destination properties” on page 98
Creating an InitialContext
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.
An InitialContext object encapsulates a connection to the repository. The XMS API
provides methods to:
v Create an InitialContext object
v Delete the InitialContext object when it is no longer required (applies to C and
C++ only).
v Lookup an administered object in the administered object repository.
For further details about creating an InitialContext object, see “InitialContext” on
page 155 for C, or “InitialContext” on page 305 for C++, or “InitialContext” on
page 444 for.NET, and “Properties of InitialContext” on page 531.
Chapter 10. Working with administered objects
99
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 and in the .NET implementation of XMS, the additional information is
provided in an environment Hashtable to the constructor.
In the C/C++ implementation of XMS, the information is provided by setting
properties on the InitialContext object after it has been constructed. For C/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.
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. Note that if you use ’\’, then each separator needs to be escaped by
using an additional ’\’. This prevents the C runtime or .NET framework from
trying to interpret the separator as an escape character for what follows. Further, if
the URI is coded as literal C strings in source code, the compiler also requires each
’\’ character to be escaped.
Examples of this syntax include:
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"
100
Message Service Clients for C/C++ and .NET
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 as follows:
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
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.
The name of the object to be retrieved can be:
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
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
101
102
Message Service Clients for C/C++ and .NET
Part 3. XMS API reference
Chapter 11. C classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
BytesMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
xmsBytesMsgGetBodyLength – Get Body Length . . . . . . . . . . . . . . . . . . . . 123
xmsBytesMsgReadBoolean – Read Boolean Value . . . . . . . . . . . . . . . . . . . . 123
xmsBytesMsgReadByte – Read Byte . . . . . . . . . . . . . . . . . . . . . . . . . 124
xmsBytesMsgReadBytes – Read Bytes . . . . . . . . . . . . . . . . . . . . . . . . 124
xmsBytesMsgReadBytesByRef – Read Bytes by Reference . . . . . . . . . . . . . . . . . . 125
xmsBytesMsgReadChar – Read Character . . . . . . . . . . . . . . . . . . . . . . . 126
xmsBytesMsgReadDouble – Read Double Precision Floating Point Number . . . . . . . . . . . 126
xmsBytesMsgReadFloat – Read Floating Point Number . . . . . . . . . . . . . . . . . . 127
xmsBytesMsgReadInt – Read Integer . . . . . . . . . . . . . . . . . . . . . . . . 127
xmsBytesMsgReadLong – Read Long Integer . . . . . . . . . . . . . . . . . . . . . . 127
xmsBytesMsgReadShort – Read Short Integer. . . . . . . . . . . . . . . . . . . . . . 128
xmsBytesMsgReadUnsignedByte – Read Unsigned Byte . . . . . . . . . . . . . . . . . . 128
xmsBytesMsgReadUnsignedShort – Read Unsigned Short Integer . . . . . . . . . . . . . . . 129
xmsBytesMsgReadUTF – Read UTF String. . . . . . . . . . . . . . . . . . . . . . . 129
xmsBytesMsgReset – Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
xmsBytesMsgWriteBoolean – Write Boolean Value . . . . . . . . . . . . . . . . . . . . 131
xmsBytesMsgWriteByte – Write Byte . . . . . . . . . . . . . . . . . . . . . . . . 131
xmsBytesMsgWriteBytes – Write Bytes . . . . . . . . . . . . . . . . . . . . . . . . 131
xmsBytesMsgWriteChar – Write Character . . . . . . . . . . . . . . . . . . . . . . . 132
xmsBytesMsgWriteDouble – Write Double Precision Floating Point Number . . . . . . . . . . . 132
xmsBytesMsgWriteFloat – Write Floating Point Number . . . . . . . . . . . . . . . . . . 133
xmsBytesMsgWriteInt – Write Integer . . . . . . . . . . . . . . . . . . . . . . . . 133
xmsBytesMsgWriteLong – Write Long Integer . . . . . . . . . . . . . . . . . . . . . 134
xmsBytesMsgWriteShort – Write Short Integer . . . . . . . . . . . . . . . . . . . . . 134
xmsBytesMsgWriteUTF – Write UTF String . . . . . . . . . . . . . . . . . . . . . . 134
Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
xmsConnClose – Close Connection . . . . . . . . . . . . . . . . . . . . . . . . . 136
xmsConnCreateSession – Create Session . . . . . . . . . . . . . . . . . . . . . . . 136
xmsConnGetClientID – Get Client ID . . . . . . . . . . . . . . . . . . . . . . . . 137
xmsConnGetExceptionListener – Get Exception Listener . . . . . . . . . . . . . . . . . . 138
xmsConnGetMetaData – Get Metadata . . . . . . . . . . . . . . . . . . . . . . . . 138
xmsConnSetClientID – Set Client ID . . . . . . . . . . . . . . . . . . . . . . . . . 139
xmsConnSetExceptionListener – Set Exception Listener . . . . . . . . . . . . . . . . . . 139
xmsConnStart – Start Connection . . . . . . . . . . . . . . . . . . . . . . . . . . 140
xmsConnStop – Stop Connection . . . . . . . . . . . . . . . . . . . . . . . . . . 140
ConnectionFactory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
xmsConnFactCreate – Create Connection Factory . . . . . . . . . . . . . . . . . . . . 141
xmsConnFactCreateConnection – Create Connection (using the default user identity) . . . . . . . . 141
xmsConnFactCreateConnectionForUser – Create Connection (using a specified user identity) . . . . . . 142
xmsConnFactDispose – Delete Connection Factory . . . . . . . . . . . . . . . . . . . . 142
ConnectionMetaData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
xmsConnMetaDataGetJMSXProperties – Get JMS Defined Message Properties . . . . . . . . . . . 144
Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
xmsDestCreate – Create Destination (using a URI) . . . . . . . . . . . . . . . . . . . . 145
xmsDestCreateByType – Create Destination (specifying a type and name) . . . . . . . . . . . . 145
xmsDestCreateTemporaryByType – Create Temporary Destination . . . . . . . . . . . . . . . 146
xmsDestDispose – Delete Destination . . . . . . . . . . . . . . . . . . . . . . . . 147
xmsDestGetName – Get Destination Name . . . . . . . . . . . . . . . . . . . . . . 147
xmsDestGetTypeId – Get Destination Type . . . . . . . . . . . . . . . . . . . . . . 148
© Copyright IBM Corp. 2005
103
xmsDestToString – Get Destination Name as URI . . . . . . .
ErrorBlock . . . . . . . . . . . . . . . . . . . . . .
Functions . . . . . . . . . . . . . . . . . . . . . .
xmsErrorClear – Clear Error Block . . . . . . . . . . . .
xmsErrorCreate – Create Error Block . . . . . . . . . . .
xmsErrorDispose – Delete Error Block . . . . . . . . . . .
xmsErrorGetErrorCode – Get Error Code . . . . . . . . . .
xmsErrorGetErrorData – Get Error Data . . . . . . . . . .
xmsErrorGetErrorString – Get Error String . . . . . . . . .
xmsErrorGetJMSException – Get Exception Code . . . . . . .
xmsErrorGetLinkedError – Get Linked Error . . . . . . . . .
ExceptionListener . . . . . . . . . . . . . . . . . . . .
Functions . . . . . . . . . . . . . . . . . . . . . .
onException – On Exception . . . . . . . . . . . . . .
InitialContext . . . . . . . . . . . . . . . . . . . . .
Functions . . . . . . . . . . . . . . . . . . . . . .
xmsInitialContextCreate – Create Initial Context . . . . . . . .
xmsInitialContextDispose – Delete Initial Context . . . . . . .
xmsInitialContextLookup – Look Up Object in Initial Context . . .
Iterator . . . . . . . . . . . . . . . . . . . . . . .
Functions . . . . . . . . . . . . . . . . . . . . . .
xmsIteratorDispose – Delete Iterator . . . . . . . . . . . .
xmsIteratorGetNext – Get Next Object . . . . . . . . . . .
xmsIteratorHasNext – Check for More Objects . . . . . . . .
xmsIteratorReset – Reset Iterator . . . . . . . . . . . . .
MapMessage . . . . . . . . . . . . . . . . . . . . .
Functions . . . . . . . . . . . . . . . . . . . . . .
xmsMapMsgGetBoolean – Get Boolean Value . . . . . . . . .
xmsMapMsgGetByte – Get Byte . . . . . . . . . . . . .
xmsMapMsgGetBytes – Get Bytes . . . . . . . . . . . .
xmsMapMsgGetBytesByRef – Get Bytes by Reference . . . . . .
xmsMapMsgGetChar – Get Character . . . . . . . . . . .
xmsMapMsgGetDouble – Get Double Precision Floating Point Number
xmsMapMsgGetFloat – Get Floating Point Number . . . . . . .
xmsMapMsgGetInt – Get Integer . . . . . . . . . . . . .
xmsMapMsgGetLong – Get Long Integer . . . . . . . . . .
xmsMapMsgGetMap – Get Name-Value Pairs . . . . . . . .
xmsMapMsgGetObject – Get Object . . . . . . . . . . . .
xmsMapMsgGetShort – Get Short Integer . . . . . . . . . .
xmsMapMsgGetString – Get String . . . . . . . . . . . .
xmsMapMsgGetStringByRef – Get String by Reference . . . . .
xmsMapMsgItemExists – Check Name-Value Pair Exists . . . . .
xmsMapMsgSetBoolean – Set Boolean Value . . . . . . . . .
xmsMapMsgSetByte – Set Byte . . . . . . . . . . . . .
xmsMapMsgSetBytes – Set Bytes . . . . . . . . . . . . .
xmsMapMsgSetChar – Set Character . . . . . . . . . . .
xmsMapMsgSetDouble – Set Double Precision Floating Point Number
xmsMapMsgSetFloat – Set Floating Point Number . . . . . . .
xmsMapMsgSetInt – Set Integer . . . . . . . . . . . . .
xmsMapMsgSetLong – Set Long Integer . . . . . . . . . .
xmsMapMsgSetObject – Set Object . . . . . . . . . . . .
xmsMapMsgSetShort – Set Short Integer . . . . . . . . . .
xmsMapMsgSetString – Set String . . . . . . . . . . . .
Message . . . . . . . . . . . . . . . . . . . . . . .
Functions . . . . . . . . . . . . . . . . . . . . . .
xmsMsgAcknowledge – Acknowledge . . . . . . . . . . .
xmsMsgClearBody – Clear Body . . . . . . . . . . . . .
xmsMsgClearProperties – Clear Properties . . . . . . . . . .
xmsMsgDispose – Delete Message . . . . . . . . . . . .
xmsMsgGetJMSCorrelationID – Get JMSCorrelationID . . . . . .
xmsMsgGetJMSDeliveryMode – Get JMSDeliveryMode . . . . .
104
Message Service Clients for C/C++ and .NET
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
148
150
150
150
150
151
151
151
152
152
153
154
154
154
155
155
155
155
156
157
157
157
157
158
158
159
159
159
159
160
161
161
162
162
163
163
164
164
165
166
166
167
167
168
168
169
169
170
170
171
171
172
173
174
174
174
174
175
175
176
176
xmsMsgGetJMSDestination – Get JMSDestination . . . . . . . . . . . . . . . . . . . .
xmsMsgGetJMSExpiration – Get JMSExpiration . . . . . . . . . . . . . . . . . . . . .
xmsMsgGetJMSMessageID – Get JMSMessageID . . . . . . . . . . . . . . . . . . . .
xmsMsgGetJMSPriority – Get JMSPriority . . . . . . . . . . . . . . . . . . . . . . .
xmsMsgGetJMSRedelivered – Get JMSRedelivered . . . . . . . . . . . . . . . . . . . .
xmsMsgGetJMSReplyTo – Get JMSReplyTo . . . . . . . . . . . . . . . . . . . . . .
xmsMsgGetJMSTimestamp – Get JMSTimestamp . . . . . . . . . . . . . . . . . . . .
xmsMsgGetJMSType – Get JMSType . . . . . . . . . . . . . . . . . . . . . . . . .
xmsMsgGetProperties – Get Properties . . . . . . . . . . . . . . . . . . . . . . . .
xmsMsgGetTypeId – Get Type . . . . . . . . . . . . . . . . . . . . . . . . . . .
xmsMsgPropertyExists – Check Property Exists . . . . . . . . . . . . . . . . . . . . .
xmsMsgSetJMSCorrelationID – Set JMSCorrelationID . . . . . . . . . . . . . . . . . . .
xmsMsgSetJMSDeliveryMode – Set JMSDeliveryMode . . . . . . . . . . . . . . . . . . .
xmsMsgSetJMSDestination – Set JMSDestination. . . . . . . . . . . . . . . . . . . . .
xmsMsgSetJMSExpiration – Set JMSExpiration . . . . . . . . . . . . . . . . . . . . .
xmsMsgSetJMSMessageID – Set JMSMessageID . . . . . . . . . . . . . . . . . . . . .
xmsMsgSetJMSPriority – Set JMSPriority . . . . . . . . . . . . . . . . . . . . . . .
xmsMsgSetJMSRedelivered – Set JMSRedelivered . . . . . . . . . . . . . . . . . . . .
xmsMsgSetJMSReplyTo – Set JMSReplyTo . . . . . . . . . . . . . . . . . . . . . . .
xmsMsgSetJMSTimestamp – Set JMSTimestamp . . . . . . . . . . . . . . . . . . . . .
xmsMsgSetJMSType – Set JMSType . . . . . . . . . . . . . . . . . . . . . . . . .
MessageConsumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xmsMsgConsumerClose – Close Message Consumer . . . . . . . . . . . . . . . . . . .
xmsMsgConsumerGetMessageListener – Get Message Listener . . . . . . . . . . . . . . . .
xmsMsgConsumerGetMessageSelector – Get Message Selector . . . . . . . . . . . . . . . .
xmsMsgConsumerReceive – Receive . . . . . . . . . . . . . . . . . . . . . . . . .
xmsMsgConsumerReceiveNoWait – Receive with No Wait . . . . . . . . . . . . . . . . .
xmsMsgConsumerReceiveWithWait – Receive (with a wait interval) . . . . . . . . . . . . . .
xmsMsgConsumerSetMessageListener – Set Message Listener . . . . . . . . . . . . . . . .
MessageListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
onMessage – On Message . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MessageProducer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xmsMsgProducerClose – Close Message Producer . . . . . . . . . . . . . . . . . . . .
xmsMsgProducerGetDeliveryMode – Get Default Delivery Mode . . . . . . . . . . . . . . .
xmsMsgProducerGetDestination – Get Destination . . . . . . . . . . . . . . . . . . . .
xmsMsgProducerGetDisableMsgID – Get Disable Message ID Flag . . . . . . . . . . . . . .
xmsMsgProducerGetDisableMsgTS – Get Disable Time Stamp Flag . . . . . . . . . . . . . .
xmsMsgProducerGetPriority – Get Default Priority . . . . . . . . . . . . . . . . . . . .
xmsMsgProducerGetTimeToLive – Get Default Time to Live . . . . . . . . . . . . . . . . .
xmsMsgProducerSend – Send . . . . . . . . . . . . . . . . . . . . . . . . . . .
xmsMsgProducerSendDest – Send (to a specified destination) . . . . . . . . . . . . . . . .
xmsMsgProducerSendDestWithAttr – Send (to a specified destination, specifying a delivery mode, priority,
and time to live) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xmsMsgProducerSendWithAttr – Send (specifying a delivery mode, priority, and time to live) . . . . .
xmsMsgProducerSetDeliveryMode – Set Default Delivery Mode . . . . . . . . . . . . . . .
xmsMsgProducerSetDisableMsgID – Set Disable Message ID Flag . . . . . . . . . . . . . . .
xmsMsgProducerSetDisableMsgTS – Set Disable Time Stamp Flag . . . . . . . . . . . . . . .
xmsMsgProducerSetPriority – Set Default Priority . . . . . . . . . . . . . . . . . . . .
xmsMsgProducerSetTimeToLive – Set Default Time to Live . . . . . . . . . . . . . . . . .
ObjectMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xmsObjectMsgGetObjectAsBytes – Get Object as Bytes . . . . . . . . . . . . . . . . . .
xmsObjectMsgSetObjectAsBytes – Set Object as Bytes . . . . . . . . . . . . . . . . . . .
Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xmsPropertyCreate – Create Property (with no property value or property type) . . . . . . . . . .
xmsPropertyDispose – Delete Property . . . . . . . . . . . . . . . . . . . . . . . .
xmsPropertyDuplicate – Copy Property . . . . . . . . . . . . . . . . . . . . . . .
Part 3. XMS API reference
177
178
178
179
180
180
181
181
182
182
183
183
184
184
185
185
186
186
187
187
188
189
189
189
189
190
190
191
191
192
193
193
193
194
194
194
194
195
195
196
196
196
197
197
198
199
200
200
201
202
202
203
203
203
204
205
205
205
205
206
105
xmsPropertyGetBoolean – Get Boolean Property Value . . . . . . . .
xmsPropertyGetByte – Get Byte Property Value . . . . . . . . . . .
xmsPropertyGetByteArray – Get Byte Array Property Value . . . . . . .
xmsPropertyGetByteArrayByRef – Get Byte Array Property Value by Reference
xmsPropertyGetChar – Get Character Property Value . . . . . . . . .
xmsPropertyGetDouble – Get Double Precision Floating Point Property Value .
xmsPropertyGetFloat – Get Floating Point Property Value . . . . . . .
xmsPropertyGetInt – Get Integer Property Value . . . . . . . . . .
xmsPropertyGetLong – Get Long Integer Property Value . . . . . . . .
xmsPropertyGetName – Get Property Name . . . . . . . . . . . .
xmsPropertyGetShort – Get Short Integer Property Value . . . . . . . .
xmsPropertyGetString – Get String Property Value . . . . . . . . . .
xmsPropertyGetStringByRef – Get String Property Value by Reference . . .
xmsPropertyGetTypeId – Get Property Type . . . . . . . . . . . .
xmsPropertyIsTypeId – Check Property Type . . . . . . . . . . . .
xmsPropertySetBoolean – Set Boolean Property Value . . . . . . . . .
xmsPropertySetByte – Set Byte Property Value . . . . . . . . . . .
xmsPropertySetByteArray – Set Byte Array Property Value . . . . . . .
xmsPropertySetChar – Set Character Property Value . . . . . . . . .
xmsPropertySetDouble – Set Double Precision Floating Point Property Value .
xmsPropertySetFloat – Set Floating Point Property Value . . . . . . . .
xmsPropertySetInt – Set Integer Property Value . . . . . . . . . . .
xmsPropertySetLong – Set Long Integer Property Value . . . . . . . .
xmsPropertySetShort – Set Short Integer Property Value . . . . . . . .
xmsPropertySetString – Set String Property Value . . . . . . . . . .
PropertyContext . . . . . . . . . . . . . . . . . . . . . . .
Functions . . . . . . . . . . . . . . . . . . . . . . . . .
xmsGetBooleanProperty – Get Boolean Property . . . . . . . . . . .
xmsGetByteArrayProperty – Get Byte Array Property . . . . . . . . .
xmsGetByteArrayPropertyByRef – Get Byte Array Property by Reference . .
xmsGetByteProperty – Get Byte Property . . . . . . . . . . . . .
xmsGetCharProperty – Get Character Property . . . . . . . . . . .
xmsGetDoubleProperty – Get Double Precision Floating Point Property . . .
xmsGetFloatProperty – Get Floating Point Property . . . . . . . . .
xmsGetHandleTypeId – Get Handle Type . . . . . . . . . . . . .
xmsGetIntProperty – Get Integer Property . . . . . . . . . . . . .
xmsGetLongProperty – Get Long Integer Property . . . . . . . . . .
xmsGetObjectProperty – Get Object Property . . . . . . . . . . . .
xmsGetProperty – Get Property . . . . . . . . . . . . . . . .
xmsGetShortProperty – Get Short Integer Property . . . . . . . . . .
xmsGetStringProperty – Get String Property . . . . . . . . . . . .
xmsGetStringPropertyByRef – Get String Property by Reference . . . . .
xmsSetBooleanProperty – Set Boolean Property . . . . . . . . . . .
xmsSetByteProperty – Set Byte Property . . . . . . . . . . . . .
xmsSetByteArrayProperty – Set Byte Array Property . . . . . . . . .
xmsSetCharProperty – Set Character Property . . . . . . . . . . .
xmsSetDoubleProperty – Set Double Precision Floating Point Property . . .
xmsSetFloatProperty – Set Floating Point Property . . . . . . . . . .
xmsSetIntProperty – Set Integer Property . . . . . . . . . . . . .
xmsSetLongProperty – Set Long Integer Property . . . . . . . . . .
xmsSetObjectProperty – Set Object Property . . . . . . . . . . . .
xmsSetProperty – Set Property. . . . . . . . . . . . . . . . .
xmsSetShortProperty – Set Short Integer Property . . . . . . . . . .
xmsSetStringProperty – Set String Property . . . . . . . . . . . .
QueueBrowser . . . . . . . . . . . . . . . . . . . . . . . .
Functions . . . . . . . . . . . . . . . . . . . . . . . . .
xmsQueueBrowserClose – Close Queue Browser . . . . . . . . . .
xmsQueueBrowserGetEnumeration – Get Messages . . . . . . . . .
xmsQueueBrowserGetMessageSelector – Get Message Selector . . . . . .
xmsQueueBrowserGetQueue – Get Queue . . . . . . . . . . . . .
Requestor . . . . . . . . . . . . . . . . . . . . . . . . .
106
Message Service Clients for C/C++ and .NET
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
206
207
207
208
208
209
209
210
210
211
211
212
212
213
214
214
215
215
216
216
217
217
218
218
218
220
220
220
220
221
222
222
223
223
224
224
225
225
226
227
227
228
229
229
230
231
231
232
232
233
233
234
234
235
236
236
236
236
237
237
239
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xmsRequestorClose – Close Requestor . . . . . . . . . . . . . . . . . . . . . . .
xmsRequestorCreate – Create Requestor . . . . . . . . . . . . . . . . . . . . . .
xmsRequestorRequest – Request . . . . . . . . . . . . . . . . . . . . . . . . .
Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xmsSessClose – Close Session . . . . . . . . . . . . . . . . . . . . . . . . . .
xmsSessCommit – Commit . . . . . . . . . . . . . . . . . . . . . . . . . . .
xmsSessCreateBrowser – Create Queue Browser . . . . . . . . . . . . . . . . . . . .
xmsSessCreateBrowserSelector – Create Queue Browser (with message selector) . . . . . . . . .
xmsSessCreateBytesMessage – Create Bytes Message . . . . . . . . . . . . . . . . . .
xmsSessCreateConsumer – Create Consumer . . . . . . . . . . . . . . . . . . . . .
xmsSessCreateConsumerSelector – Create Consumer (with message selector) . . . . . . . . . .
xmsSessCreateConsumerSelectorLocal – Create Consumer (with message selector and local message flag)
xmsSessCreateDurableSubscriber – Create Durable Subscriber . . . . . . . . . . . . . . .
xmsSessCreateDurableSubscriberSelector – Create Durable Subscriber (with message selector and local
message flag) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xmsSessCreateMapMessage – Create Map Message . . . . . . . . . . . . . . . . . . .
xmsSessCreateMessage – Create Message . . . . . . . . . . . . . . . . . . . . . .
xmsSessCreateObjectMessage – Create Object Message . . . . . . . . . . . . . . . . .
xmsSessCreateProducer – Create Producer . . . . . . . . . . . . . . . . . . . . . .
xmsSessCreateStreamMessage – Create Stream Message . . . . . . . . . . . . . . . . .
xmsSessCreateTextMessage – Create Text Message . . . . . . . . . . . . . . . . . . .
xmsSessCreateTextMessageInit – Create Text Message (initialized) . . . . . . . . . . . . . .
xmsSessGetAcknowledgeMode – Get Acknowledgement Mode . . . . . . . . . . . . . . .
xmsSessGetTransacted – Determine Whether Transacted . . . . . . . . . . . . . . . . .
xmsSessRecover – Recover . . . . . . . . . . . . . . . . . . . . . . . . . . .
xmsSessRollback – Rollback . . . . . . . . . . . . . . . . . . . . . . . . . .
xmsSessUnsubscribe – Unsubscribe . . . . . . . . . . . . . . . . . . . . . . . .
StreamMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xmsStreamMsgReadBoolean – Read Boolean Value . . . . . . . . . . . . . . . . . . .
xmsStreamMsgReadByte – Read Byte . . . . . . . . . . . . . . . . . . . . . . .
xmsStreamMsgReadBytes – Read Bytes . . . . . . . . . . . . . . . . . . . . . . .
xmsStreamMsgReadBytesByRef – Read Bytes by Reference . . . . . . . . . . . . . . . .
xmsStreamMsgReadChar – Read Character . . . . . . . . . . . . . . . . . . . . .
xmsStreamMsgReadDouble – Read Double Precision Floating Point Number . . . . . . . . . .
xmsStreamMsgReadFloat – Read Floating Point Number . . . . . . . . . . . . . . . . .
xmsStreamMsgReadInt – Read Integer . . . . . . . . . . . . . . . . . . . . . . .
xmsStreamMsgReadLong – Read Long Integer . . . . . . . . . . . . . . . . . . . .
xmsStreamMsgReadObject – Read Object . . . . . . . . . . . . . . . . . . . . . .
xmsStreamMsgReadShort – Read Short Integer . . . . . . . . . . . . . . . . . . . .
xmsStreamMsgReadString – Read String . . . . . . . . . . . . . . . . . . . . . .
xmsStreamMsgReset – Reset . . . . . . . . . . . . . . . . . . . . . . . . . .
xmsStreamMsgWriteBoolean – Write Boolean Value . . . . . . . . . . . . . . . . . .
xmsStreamMsgWriteByte – Write Byte . . . . . . . . . . . . . . . . . . . . . . .
xmsStreamMsgWriteBytes – Write Bytes . . . . . . . . . . . . . . . . . . . . . .
xmsStreamMsgWriteChar – Write Character . . . . . . . . . . . . . . . . . . . . .
xmsStreamMsgWriteDouble – Write Double Precision Floating Point Number . . . . . . . . . .
xmsStreamMsgWriteFloat – Write Floating Point Number . . . . . . . . . . . . . . . .
xmsStreamMsgWriteInt – Write Integer . . . . . . . . . . . . . . . . . . . . . . .
xmsStreamMsgWriteLong – Write Long Integer . . . . . . . . . . . . . . . . . . . .
xmsStreamMsgWriteObject – Write Object . . . . . . . . . . . . . . . . . . . . . .
xmsStreamMsgWriteShort – Write Short Integer . . . . . . . . . . . . . . . . . . . .
xmsStreamMsgWriteString – Write String . . . . . . . . . . . . . . . . . . . . . .
TextMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xmsTextMsgGetText – Get Text . . . . . . . . . . . . . . . . . . . . . . . . .
xmsTextMsgSetText – Set Text . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 12. Additional C functions .
. 269
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Part 3. XMS API reference
.
.
.
.
.
.
.
.
.
.
.
.
.
239
239
239
240
241
241
241
241
242
242
243
243
244
245
. 246
246
247
248
248
249
249
250
250
251
251
252
252
252
254
254
254
254
255
256
256
257
257
258
258
258
260
260
261
261
262
262
263
263
264
264
264
265
266
266
267
267
267
268
107
Process CCSID functions . . . . . . . .
Functions . . . . . . . . . . . . .
xmsGetClientCCSID – Get Process CCSID .
xmsSetClientCCSID – Set Process CCSID .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 13. C++ classes . . . . . . . . . . . . . . . . .
BytesMessage . . . . . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . . .
getBodyLength – Get Body Length . . . . . . . . . . . .
readBoolean – Read Boolean Value . . . . . . . . . . . .
readByte – Read Byte . . . . . . . . . . . . . . . . .
readBytes – Read Bytes . . . . . . . . . . . . . . . .
readChar – Read Character . . . . . . . . . . . . . . .
readDouble – Read Double Precision Floating Point Number . . .
readFloat – Read Floating Point Number . . . . . . . . . .
readInt – Read Integer . . . . . . . . . . . . . . . .
readLong – Read Long Integer . . . . . . . . . . . . .
readShort – Read Short Integer . . . . . . . . . . . . .
readUnsignedByte – Read Unsigned Byte . . . . . . . . . .
readUnsignedShort – Read Unsigned Short Integer . . . . . . .
readUTF – Read UTF String . . . . . . . . . . . . . .
reset – Reset . . . . . . . . . . . . . . . . . . . .
writeBoolean – Write Boolean Value . . . . . . . . . . . .
writeByte – Write Byte . . . . . . . . . . . . . . . .
writeBytes – Write Bytes . . . . . . . . . . . . . . . .
writeChar – Write Character . . . . . . . . . . . . . .
writeDouble – Write Double Precision Floating Point Number . . .
writeFloat – Write Floating Point Number . . . . . . . . . .
writeInt – Write Integer . . . . . . . . . . . . . . . .
writeLong – Write Long Integer . . . . . . . . . . . . .
writeShort – Write Short Integer . . . . . . . . . . . . .
writeUTF – Write UTF String . . . . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . . . . . .
Connection . . . . . . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . . .
close – Close Connection . . . . . . . . . . . . . . .
createSession – Create Session . . . . . . . . . . . . . .
getClientID – Get Client ID . . . . . . . . . . . . . . .
getExceptionListener – Get Exception Listener . . . . . . . .
getHandle – Get Handle . . . . . . . . . . . . . . . .
getMetaData – Get Metadata . . . . . . . . . . . . . .
isNull – Check Whether Null . . . . . . . . . . . . . .
setClientID – Set Client ID . . . . . . . . . . . . . . .
setExceptionListener – Set Exception Listener . . . . . . . . .
start – Start Connection . . . . . . . . . . . . . . . .
stop – Stop Connection . . . . . . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . . . . . .
ConnectionFactory. . . . . . . . . . . . . . . . . . . .
Constructors . . . . . . . . . . . . . . . . . . . . .
ConnectionFactory – Create Connection Factory . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . . .
~ConnectionFactory – Delete Connection Factory . . . . . . .
createConnection – Create Connection (using the default user identity)
createConnection – Create Connection (using a specified user identity)
getHandle – Get Handle . . . . . . . . . . . . . . . .
isNull – Check Whether Null . . . . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . . . . . .
ConnectionMetaData . . . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . . .
getHandle – Get Handle . . . . . . . . . . . . . . . .
getJMSXProperties – Get JMS Defined Message Properties . . . .
108
Message Service Clients for C/C++ and .NET
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
270
270
270
270
. . . . . . . . . . . . . 273
. . . . . . . . . . . . . 275
. . . . . . . . . . . . . 275
. . . . . . . . . . . . . 275
. . . . . . . . . . . . . 275
. . . . . . . . . . . . . 275
. . . . . . . . . . . . . 276
. . . . . . . . . . . . . 277
. . . . . . . . . . . . . 277
. . . . . . . . . . . . . 277
. . . . . . . . . . . . . 278
. . . . . . . . . . . . . 278
. . . . . . . . . . . . . 278
. . . . . . . . . . . . . 279
. . . . . . . . . . . . . 279
. . . . . . . . . . . . . 279
. . . . . . . . . . . . . 280
. . . . . . . . . . . . . 280
. . . . . . . . . . . . . 280
. . . . . . . . . . . . . 281
. . . . . . . . . . . . . 281
. . . . . . . . . . . . . 281
. . . . . . . . . . . . . 282
. . . . . . . . . . . . . 282
. . . . . . . . . . . . . 282
. . . . . . . . . . . . . 283
. . . . . . . . . . . . . 283
. . . . . . . . . . . . . 283
. . . . . . . . . . . . . 285
. . . . . . . . . . . . . 285
. . . . . . . . . . . . . 285
. . . . . . . . . . . . . 285
. . . . . . . . . . . . . 286
. . . . . . . . . . . . . 286
. . . . . . . . . . . . . 286
. . . . . . . . . . . . . 287
. . . . . . . . . . . . . 287
. . . . . . . . . . . . . 287
. . . . . . . . . . . . . 288
. . . . . . . . . . . . . 288
. . . . . . . . . . . . . 289
. . . . . . . . . . . . . 289
. . . . . . . . . . . . . 290
. . . . . . . . . . . . . 290
. . . . . . . . . . . . . 290
. . . . . . . . . . . . . 290
. . . . . . . . . . . . . 290
. . . . . . . . . . . . . 290
. . . . . . . . . . . . . 291
. . . . . . . . . . . . . 291
. . . . . . . . . . . . . 292
. . . . . . . . . . . . . 292
. . . . . . . . . . . . . 293
. . . . . . . . . . . . . 293
. . . . . . . . . . . . . 293
. . . . . . . . . . . . . 293
isNull – Check Whether Null . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . . .
Destination . . . . . . . . . . . . . . . . . . .
Constructors . . . . . . . . . . . . . . . . . .
Destination – Create Destination (specifying a type and name)
Destination – Create Destination (using a URI) . . . . .
Methods . . . . . . . . . . . . . . . . . . .
~Destination – Delete Destination . . . . . . . . .
getHandle – Get Handle . . . . . . . . . . . . .
getName – Get Destination Name . . . . . . . . .
getTypeId – Get Destination Type . . . . . . . . .
isNull – Check Whether Null . . . . . . . . . . .
toString – Get Destination Name as URI . . . . . . .
Inherited methods . . . . . . . . . . . . . . . .
Exception. . . . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . .
~Exception – Delete Exception . . . . . . . . . . .
dump – Dump Exception . . . . . . . . . . . .
getErrorCode – Get Error Code . . . . . . . . . .
getErrorData – Get Error Data . . . . . . . . . . .
getErrorString – Get Error String . . . . . . . . . .
getHandle – Get Handle . . . . . . . . . . . . .
getJMSException – Get Exception Code . . . . . . . .
getLinkedException – Get Linked Exception . . . . . .
isNull – Check Whether Null . . . . . . . . . . .
ExceptionListener . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . .
onException – On Exception . . . . . . . . . . .
IllegalStateException . . . . . . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . . .
InitialContext . . . . . . . . . . . . . . . . . .
Constructors . . . . . . . . . . . . . . . . . .
InitialContext – Create Initial Context . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . .
~InitialContext – Delete Initial Context . . . . . . . .
getHandle – Get Handle . . . . . . . . . . . . .
isNull – Check Whether Null . . . . . . . . . . .
lookup – Look Up Object in Initial Context . . . . . .
Inherited methods . . . . . . . . . . . . . . . .
InvalidClientIDException . . . . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . . .
InvalidDestinationException . . . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . . .
InvalidSelectorException . . . . . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . . .
Iterator . . . . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . .
~Iterator – Delete Iterator . . . . . . . . . . . .
getHandle – Get Handle . . . . . . . . . . . . .
getNext – Get Next Object . . . . . . . . . . . .
hasNext – Check for More Objects . . . . . . . . .
isNull – Check Whether Null . . . . . . . . . . .
reset – Reset Iterator . . . . . . . . . . . . . .
MapMessage . . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . .
getBoolean – Get Boolean Value . . . . . . . . . .
getByte – Get Byte . . . . . . . . . . . . . . .
getBytes – Get Bytes . . . . . . . . . . . . . .
getChar – Get Character . . . . . . . . . . . . .
getDouble – Get Double Precision Floating Point Number .
getFloat – Get Floating Point Number . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Part 3. XMS API reference
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
294
294
295
295
295
296
296
296
296
297
297
297
297
298
299
299
299
299
299
300
300
300
301
301
301
303
303
303
304
304
305
305
305
305
305
306
306
306
306
308
308
309
309
310
310
311
311
311
311
312
312
312
313
314
314
314
314
315
315
315
316
109
getInt – Get Integer . . . . . . . . . . . . .
getLong – Get Long Integer . . . . . . . . . .
getMap – Get Name-Value Pairs . . . . . . . . .
getObject – Get Object . . . . . . . . . . . .
getShort – Get Short Integer . . . . . . . . . .
getString – Get String . . . . . . . . . . . .
itemExists – Check Name-Value Pair Exists . . . . .
setBoolean – Set Boolean Value . . . . . . . . .
setByte – Set Byte . . . . . . . . . . . . . .
setBytes – Set Bytes . . . . . . . . . . . . .
setChar – Set Character . . . . . . . . . . . .
setDouble – Set Double Precision Floating Point Number .
setFloat – Set Floating Point Number . . . . . . .
setInt – Set Integer . . . . . . . . . . . . .
setLong – Set Long Integer . . . . . . . . . . .
setObject – Set Object . . . . . . . . . . . . .
setShort – Set Short Integer . . . . . . . . . . .
setString – Set String . . . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . .
Message . . . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . .
~Message – Delete Message . . . . . . . . . .
acknowledge – Acknowledge . . . . . . . . . .
clearBody – Clear Body . . . . . . . . . . . .
clearProperties – Clear Properties . . . . . . . . .
getHandle – Get Handle . . . . . . . . . . . .
getJMSCorrelationID – Get JMSCorrelationID . . . . .
getJMSDeliveryMode – Get JMSDeliveryMode . . . .
getJMSDestination – Get JMSDestination . . . . . .
getJMSExpiration – Get JMSExpiration . . . . . . .
getJMSMessageID – Get JMSMessageID . . . . . .
getJMSPriority – Get JMSPriority . . . . . . . . .
getJMSRedelivered – Get JMSRedelivered . . . . . .
getJMSReplyTo – Get JMSReplyTo . . . . . . . .
getJMSTimestamp – Get JMSTimestamp . . . . . .
getJMSType – Get JMSType . . . . . . . . . . .
getProperties – Get Properties . . . . . . . . . .
isNull – Check Whether Null . . . . . . . . . .
propertyExists – Check Property Exists . . . . . . .
setJMSCorrelationID – Set JMSCorrelationID . . . . .
setJMSDeliveryMode – Set JMSDeliveryMode . . . .
setJMSDestination – Set JMSDestination . . . . . .
setJMSExpiration – Set JMSExpiration . . . . . . .
setJMSMessageID – Set JMSMessageID . . . . . . .
setJMSPriority – Set JMSPriority . . . . . . . . .
setJMSRedelivered – Set JMSRedelivered . . . . . .
setJMSReplyTo – Set JMSReplyTo . . . . . . . . .
setJMSTimestamp – Set JMSTimestamp . . . . . . .
setJMSType – Set JMSType . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . .
MessageConsumer . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . .
close – Close Message Consumer . . . . . . . . .
getHandle – Get Handle . . . . . . . . . . . .
getMessageListener – Get Message Listener . . . . .
getMessageSelector – Get Message Selector . . . . .
isNull – Check Whether Null . . . . . . . . . .
receive – Receive . . . . . . . . . . . . . .
receive – Receive (with a wait interval) . . . . . . .
receiveNoWait – Receive with No Wait . . . . . . .
setMessageListener – Set Message Listener . . . . .
110
Message Service Clients for C/C++ and .NET
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
316
316
317
317
318
318
319
319
320
320
320
321
321
322
322
322
323
323
324
325
325
325
325
326
326
327
327
327
328
328
329
329
330
330
330
331
331
331
332
332
332
333
333
334
334
334
335
335
336
336
337
337
337
337
337
338
338
339
339
339
340
Inherited methods . . . . . . . . . . . . . . . . . . . . .
MessageEOFException . . . . . . . . . . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . . . . . . . .
MessageFormatException . . . . . . . . . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . . . . . . . .
MessageListener . . . . . . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . . . . .
onMessage – On Message . . . . . . . . . . . . . . . . .
MessageNotReadableException . . . . . . . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . . . . . . . .
MessageNotWritableException . . . . . . . . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . . . . . . . .
MessageProducer . . . . . . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . . . . .
close – Close Message Producer . . . . . . . . . . . . . . .
getDeliveryMode – Get Default Delivery Mode . . . . . . . . . .
getDestination – Get Destination . . . . . . . . . . . . . . .
getDisableMsgID – Get Disable Message ID Flag . . . . . . . . .
getDisableMsgTS – Get Disable Time Stamp Flag . . . . . . . . .
getHandle – Get Handle . . . . . . . . . . . . . . . . . .
getPriority – Get Default Priority . . . . . . . . . . . . . . .
getTimeToLive – Get Default Time to Live . . . . . . . . . . . .
isNull – Check Whether Null . . . . . . . . . . . . . . . .
send – Send . . . . . . . . . . . . . . . . . . . . . .
send – Send (specifying a delivery mode, priority, and time to live) . . .
send – Send (to a specified destination). . . . . . . . . . . . .
send – Send (to a specified destination, specifying a delivery mode, priority,
setDeliveryMode – Set Default Delivery Mode . . . . . . . . . .
setDisableMsgID – Set Disable Message ID Flag . . . . . . . . . .
setDisableMsgTS – Set Disable Time Stamp Flag . . . . . . . . . .
setPriority – Set Default Priority . . . . . . . . . . . . . . .
setTimeToLive – Set Default Time to Live . . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . . . . . . . .
ObjectMessage . . . . . . . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . . . . .
getObject – Get Object as Bytes . . . . . . . . . . . . . . .
setObject – Set Object as Bytes . . . . . . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . . . . . . . .
Property . . . . . . . . . . . . . . . . . . . . . . . . .
Constructors . . . . . . . . . . . . . . . . . . . . . . .
Property – Copy Property . . . . . . . . . . . . . . . . .
Property – Create Property . . . . . . . . . . . . . . . . .
Property – Create Property (with no property value or property type) . .
Methods . . . . . . . . . . . . . . . . . . . . . . . .
~Property – Delete Property . . . . . . . . . . . . . . . .
getBoolean – Get Boolean Property Value . . . . . . . . . . . .
getByte – Get Byte Property Value . . . . . . . . . . . . . .
getByteArray – Get Byte Array Property Value . . . . . . . . . .
getChar – Get Character Property Value . . . . . . . . . . . .
getDouble – Get Double Precision Floating Point Property Value . . . .
getFloat – Get Floating Point Property Value . . . . . . . . . . .
getHandle – Get Handle . . . . . . . . . . . . . . . . . .
getInt – Get Integer Property Value . . . . . . . . . . . . . .
getLong – Get Long Integer Property Value . . . . . . . . . . .
getShort – Get Short Integer Property Value . . . . . . . . . . .
getString – Get String Property Value . . . . . . . . . . . . .
getTypeId – Get Property Type . . . . . . . . . . . . . . .
isNull – Check Whether Null . . . . . . . . . . . . . . . .
isTypeId – Check Property Type . . . . . . . . . . . . . . .
name – Get Property Name . . . . . . . . . . . . . . . .
setBoolean – Set Boolean Property Value . . . . . . . . . . . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
and time
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
to
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
live)
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Part 3. XMS API reference
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
340
341
341
342
342
343
343
343
344
344
345
345
346
346
346
346
347
347
347
348
348
348
349
349
349
350
351
352
352
352
353
353
354
355
355
355
356
356
357
357
357
357
358
359
359
359
359
360
360
361
361
361
361
362
362
362
363
363
364
364
365
111
setByte – Set Byte Property Value . . . . . . . . . . . .
setByteArray – Set Byte Array Property Value . . . . . . .
setChar – Set Character Property Value . . . . . . . . . .
setDouble – Set Double Precision Floating Point Property Value .
setFloat – Set Floating Point Property Value . . . . . . . .
setInt – Set Integer Property Value . . . . . . . . . . .
setLong – Set Long Integer Property Value . . . . . . . .
setShort – Set Short Integer Property Value . . . . . . . .
setString – Set String Property Value . . . . . . . . . .
PropertyContext . . . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . .
getBooleanProperty – Get Boolean Property . . . . . . . .
getByteProperty – Get Byte Property . . . . . . . . . .
getBytesProperty – Get Byte Array Property . . . . . . . .
getCharProperty – Get Character Property . . . . . . . . .
getDoubleProperty – Get Double Precision Floating Point Property
getFloatProperty – Get Floating Point Property . . . . . . .
getIntProperty – Get Integer Property . . . . . . . . . .
getLongProperty – Get Long Integer Property . . . . . . .
getObjectProperty – Get Object Property . . . . . . . . .
getProperty – Get Property . . . . . . . . . . . . . .
getShortProperty – Get Short Integer Property . . . . . . .
getStringProperty – Get String Property . . . . . . . . .
setBooleanProperty – Set Boolean Property . . . . . . . .
setByteProperty – Set Byte Property . . . . . . . . . . .
setBytesProperty – Set Byte Array Property . . . . . . . .
setCharProperty – Set Character Property . . . . . . . . .
setDoubleProperty – Set Double Precision Floating Point Property .
setFloatProperty – Set Floating Point Property . . . . . . .
setIntProperty – Set Integer Property . . . . . . . . . .
setLongProperty – Set Long Integer Property . . . . . . . .
setObjectProperty – Set Object Property . . . . . . . . .
setProperty – Set Property . . . . . . . . . . . . . .
setShortProperty – Set Short Integer Property . . . . . . . .
setStringProperty – Set String Property . . . . . . . . . .
QueueBrowser . . . . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . .
close – Close Queue Browser . . . . . . . . . . . . .
getEnumeration – Get Messages . . . . . . . . . . . .
getHandle – Get Handle . . . . . . . . . . . . . . .
getMessageSelector – Get Message Selector . . . . . . . .
getQueue – Get Queue . . . . . . . . . . . . . . .
isNull – Check Whether Null . . . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . . . . .
Requestor . . . . . . . . . . . . . . . . . . . . .
Constructors . . . . . . . . . . . . . . . . . . . .
Requestor – Create Requestor . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . .
close – Close Requestor . . . . . . . . . . . . . . .
getHandle – Get Handle . . . . . . . . . . . . . . .
isNull – Check Whether Null . . . . . . . . . . . . .
request – Request . . . . . . . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . . . . .
ResourceAllocationException . . . . . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . . . . .
SecurityException . . . . . . . . . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . . . . .
Session . . . . . . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . .
close – Close Session . . . . . . . . . . . . . . . .
commit – Commit . . . . . . . . . . . . . . . . .
112
Message Service Clients for C/C++ and .NET
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
365
365
366
366
367
367
367
368
368
369
369
369
369
369
370
370
371
371
372
372
373
373
374
374
374
375
375
376
376
377
377
378
378
379
379
381
381
381
381
382
382
382
383
383
384
384
384
384
384
385
385
385
386
387
387
388
388
389
389
389
389
createBrowser – Create Queue Browser . . . . . . . . . . . . . . . .
createBrowser – Create Queue Browser (with message selector). . . . . . . .
createBytesMessage – Create Bytes Message . . . . . . . . . . . . . .
createConsumer – Create Consumer . . . . . . . . . . . . . . . . .
createConsumer – Create Consumer (with message selector) . . . . . . . . .
createConsumer – Create Consumer (with message selector and local message flag) .
createDurableSubscriber – Create Durable Subscriber . . . . . . . . . . .
createDurableSubscriber – Create Durable Subscriber (with message selector and local
createMapMessage – Create Map Message . . . . . . . . . . . . . . .
createMessage – Create Message . . . . . . . . . . . . . . . . . .
createObjectMessage – Create Object Message . . . . . . . . . . . . .
createProducer – Create Producer . . . . . . . . . . . . . . . . .
createQueue – Create Queue . . . . . . . . . . . . . . . . . . .
createStreamMessage – Create Stream Message . . . . . . . . . . . . .
createTemporaryQueue – Create Temporary Queue . . . . . . . . . . . .
createTemporaryTopic – Create Temporary Topic . . . . . . . . . . . .
createTextMessage – Create Text Message . . . . . . . . . . . . . . .
createTextMessage – Create Text Message (initialized) . . . . . . . . . . .
createTopic – Create Topic . . . . . . . . . . . . . . . . . . . .
getAcknowledgeMode – Get Acknowledgement Mode . . . . . . . . . .
getHandle – Get Handle . . . . . . . . . . . . . . . . . . . . .
getTransacted – Determine Whether Transacted . . . . . . . . . . . . .
isNull – Check Whether Null . . . . . . . . . . . . . . . . . . .
recover – Recover . . . . . . . . . . . . . . . . . . . . . . .
rollback – Rollback . . . . . . . . . . . . . . . . . . . . . .
unsubscribe – Unsubscribe . . . . . . . . . . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . .
StreamMessage . . . . . . . . . . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . .
readBoolean – Read Boolean Value . . . . . . . . . . . . . . . . .
readByte – Read Byte . . . . . . . . . . . . . . . . . . . . . .
readBytes – Read Bytes . . . . . . . . . . . . . . . . . . . . .
readChar – Read Character . . . . . . . . . . . . . . . . . . . .
readDouble – Read Double Precision Floating Point Number . . . . . . . .
readFloat – Read Floating Point Number . . . . . . . . . . . . . . .
readInt – Read Integer . . . . . . . . . . . . . . . . . . . . .
readLong – Read Long Integer . . . . . . . . . . . . . . . . . .
readObject – Read Object . . . . . . . . . . . . . . . . . . . .
readShort – Read Short Integer . . . . . . . . . . . . . . . . . .
readString – Read String. . . . . . . . . . . . . . . . . . . . .
reset – Reset . . . . . . . . . . . . . . . . . . . . . . . . .
writeBoolean – Write Boolean Value . . . . . . . . . . . . . . . . .
writeByte – Write Byte . . . . . . . . . . . . . . . . . . . . .
writeBytes – Write Bytes . . . . . . . . . . . . . . . . . . . . .
writeChar – Write Character . . . . . . . . . . . . . . . . . . .
writeDouble – Write Double Precision Floating Point Number . . . . . . . .
writeFloat – Write Floating Point Number . . . . . . . . . . . . . . .
writeInt – Write Integer . . . . . . . . . . . . . . . . . . . . .
writeLong – Write Long Integer . . . . . . . . . . . . . . . . . .
writeObject – Write Object . . . . . . . . . . . . . . . . . . . .
writeShort – Write Short Integer . . . . . . . . . . . . . . . . . .
writeString – Write String . . . . . . . . . . . . . . . . . . . .
Inherited methods . . . . . . . . . . . . . . . . . . . . . . . .
String . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . .
String – Create String . . . . . . . . . . . . . . . . . . . . . .
String – Create String (from a byte array) . . . . . . . . . . . . . . .
String – Create String (from a character array) . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . .
~String – Delete String . . . . . . . . . . . . . . . . . . . . .
c_str – Get Pointer to String . . . . . . . . . . . . . . . . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
message flag)
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Part 3. XMS API reference
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
390
390
390
391
391
392
392
393
394
394
394
395
395
395
396
396
397
397
397
398
398
398
399
399
400
400
400
402
402
402
402
403
403
404
404
404
405
405
406
406
406
407
407
408
408
408
409
409
409
410
410
411
411
412
412
412
412
412
413
413
413
113
concatenate – Concatenate Strings
equalTo – Compare Strings . . .
get – Get String . . . . . .
isNull – Check Whether Null . .
TextMessage . . . . . . . . . .
Methods . . . . . . . . . .
getText – get Text . . . . . .
setText – Set Text . . . . . .
Inherited methods . . . . . . .
TransactionInProgressException . . .
Inherited methods . . . . . . .
TransactionRolledBackException . . .
Inherited methods . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 14. .NET interfaces . . . . . . . . . . . . . . . . . . .
IBytesMessage . . . . . . . . . . . . . . . . . . . . . . . .
.NET properties . . . . . . . . . . . . . . . . . . . . . .
BodyLength – Get Body Length . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . . . . . .
ReadBoolean – Read Boolean Value . . . . . . . . . . . . . . .
ReadSignedByte – Read Byte . . . . . . . . . . . . . . . . .
ReadBytes – Read Bytes . . . . . . . . . . . . . . . . . . .
ReadChar – Read Character . . . . . . . . . . . . . . . . .
ReadDouble – Read Double Precision Floating Point Number . . . . . .
ReadFloat – Read Floating Point Number . . . . . . . . . . . . .
ReadInt – Read Integer . . . . . . . . . . . . . . . . . . .
ReadLong – Read Long Integer . . . . . . . . . . . . . . . .
ReadShort – Read Short Integer . . . . . . . . . . . . . . . .
ReadByte – Read Unsigned Byte . . . . . . . . . . . . . . . .
ReadUnsignedShort – Read Unsigned Short Integer . . . . . . . . .
ReadUTF – Read UTF String . . . . . . . . . . . . . . . . .
Reset – Reset . . . . . . . . . . . . . . . . . . . . . .
WriteBoolean – Write Boolean Value . . . . . . . . . . . . . . .
WriteByte – Write Byte . . . . . . . . . . . . . . . . . . .
WriteBytes – Write Bytes . . . . . . . . . . . . . . . . . .
WriteBytes – Write Partial Bytes Array . . . . . . . . . . . . . .
WriteChar – Write Character . . . . . . . . . . . . . . . . .
WriteDouble – Write Double Precision Floating Point Number . . . . . .
WriteFloat – Write Floating Point Number . . . . . . . . . . . . .
WriteInt – Write Integer . . . . . . . . . . . . . . . . . . .
WriteLong – Write Long Integer . . . . . . . . . . . . . . . .
WriteObject – Write Object . . . . . . . . . . . . . . . . . .
WriteShort – Write Short Integer . . . . . . . . . . . . . . . .
WriteUTF – Write UTF String . . . . . . . . . . . . . . . . .
Inherited properties and methods . . . . . . . . . . . . . . . .
IConnection . . . . . . . . . . . . . . . . . . . . . . . . .
.NET properties . . . . . . . . . . . . . . . . . . . . . .
ClientID – Get and Set Client ID . . . . . . . . . . . . . . . .
ExceptionListener – Get and Set Exception Listener . . . . . . . . . .
MetaData – Get Metadata . . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . . . . . .
Close – Close Connection . . . . . . . . . . . . . . . . . .
CreateSession – Create Session . . . . . . . . . . . . . . . .
Start – Start Connection . . . . . . . . . . . . . . . . . . .
Stop – Stop Connection . . . . . . . . . . . . . . . . . . .
Inherited properties and methods . . . . . . . . . . . . . . . .
IConnectionFactory . . . . . . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . . . . . .
CreateConnection – Create Connection Factory (using the default user identity)
CreateConnection – Create Connection (using a specified user identity) . . .
Inherited properties and methods . . . . . . . . . . . . . . . .
114
Message Service Clients for C/C++ and .NET
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
413
414
414
415
416
416
416
416
416
418
418
419
419
. . . . . . . . . . 421
. . . . . . . . . . 424
. . . . . . . . . . 424
. . . . . . . . . . 424
. . . . . . . . . . 424
. . . . . . . . . . 424
. . . . . . . . . . 424
. . . . . . . . . . 425
. . . . . . . . . . 426
. . . . . . . . . . 426
. . . . . . . . . . 426
. . . . . . . . . . 427
. . . . . . . . . . 427
. . . . . . . . . . 427
. . . . . . . . . . 428
. . . . . . . . . . 428
. . . . . . . . . . 428
. . . . . . . . . . 429
. . . . . . . . . . 429
. . . . . . . . . . 429
. . . . . . . . . . 430
. . . . . . . . . . 430
. . . . . . . . . . 430
. . . . . . . . . . 431
. . . . . . . . . . 431
. . . . . . . . . . 431
. . . . . . . . . . 432
. . . . . . . . . . 432
. . . . . . . . . . 432
. . . . . . . . . . 433
. . . . . . . . . . 433
. . . . . . . . . . 434
. . . . . . . . . . 434
. . . . . . . . . . 434
. . . . . . . . . . 434
. . . . . . . . . . 435
. . . . . . . . . . 435
. . . . . . . . . . 435
. . . . . . . . . . 435
. . . . . . . . . . 436
. . . . . . . . . . 436
. . . . . . . . . . 437
. . . . . . . . . . 438
. . . . . . . . . . 438
. . . . . . . . . . 438
. . . . . . . . . . 438
. . . . . . . . . . 439
IConnectionMetaData . . . . . . . . . . . . . . . . . .
.NET properties . . . . . . . . . . . . . . . . . . .
JMSXPropertyNames – Get JMS Defined Message Properties . . .
Inherited properties and methods . . . . . . . . . . . . .
IDestination . . . . . . . . . . . . . . . . . . . . . .
.NET properties . . . . . . . . . . . . . . . . . . .
Name – Get Destination Name . . . . . . . . . . . . .
TypeId – Get Destination Type . . . . . . . . . . . . .
Inherited properties and methods . . . . . . . . . . . . .
ExceptionListener . . . . . . . . . . . . . . . . . . . .
Delegate . . . . . . . . . . . . . . . . . . . . . .
ExceptionListener – Exception Listener . . . . . . . . . . .
IllegalStateException . . . . . . . . . . . . . . . . . . .
Inherited properties and methods . . . . . . . . . . . . .
InitialContext . . . . . . . . . . . . . . . . . . . . .
.NET properties . . . . . . . . . . . . . . . . . . .
Environment - Get the environment . . . . . . . . . . . .
Constructors . . . . . . . . . . . . . . . . . . . . .
InitialContext – Create Initial Context . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . . .
AddToEnvironment - Add a New Property to the Environment . .
Close - Close this context . . . . . . . . . . . . . . .
Lookup – Look Up Object in Initial Context . . . . . . . . .
RemoveFromEnvironment - Remove a Property from the Environment
InvalidClientIDException . . . . . . . . . . . . . . . . .
Inherited properties and methods . . . . . . . . . . . . .
InvalidDestinationException . . . . . . . . . . . . . . . .
Inherited properties and methods . . . . . . . . . . . . .
InvalidSelectorException . . . . . . . . . . . . . . . . . .
Inherited properties and methods . . . . . . . . . . . . .
IMapMessage . . . . . . . . . . . . . . . . . . . . .
.NET properties . . . . . . . . . . . . . . . . . . .
MapNames – Get Map Names. . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . . .
GetBoolean – Get Boolean Value . . . . . . . . . . . . .
GetByte – Get Byte . . . . . . . . . . . . . . . . .
GetBytes – Get Bytes . . . . . . . . . . . . . . . . .
GetChar – Get Character . . . . . . . . . . . . . . .
GetDouble – Get Double Precision Floating Point Number . . . .
GetFloat – Get Floating Point Number . . . . . . . . . . .
GetInt – Get Integer . . . . . . . . . . . . . . . . .
GetLong – Get Long Integer . . . . . . . . . . . . . .
GetObject – Get Object . . . . . . . . . . . . . . . .
GetShort – Get Short Integer . . . . . . . . . . . . . .
GetString – Get String . . . . . . . . . . . . . . . .
ItemExists – Check Name-Value Pair Exists . . . . . . . . .
SetBoolean – Set Boolean Value . . . . . . . . . . . . .
SetByte – Set Byte . . . . . . . . . . . . . . . . . .
SetBytes – Set Bytes . . . . . . . . . . . . . . . . .
SetChar – Set Character . . . . . . . . . . . . . . . .
SetDouble – Set Double Precision Floating Point Number . . . .
SetFloat – Set Floating Point Number . . . . . . . . . . .
SetInt – Set Integer . . . . . . . . . . . . . . . . .
SetLong – Set Long Integer . . . . . . . . . . . . . . .
SetObject – Set Object . . . . . . . . . . . . . . . .
SetShort – Set Short Integer. . . . . . . . . . . . . . .
SetString – Set String . . . . . . . . . . . . . . . . .
Inherited properties and methods . . . . . . . . . . . . .
IMessage . . . . . . . . . . . . . . . . . . . . . . .
.NET properties . . . . . . . . . . . . . . . . . . .
GetJMSCorrelationID – Get and Set JMSCorrelationID . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Part 3. XMS API reference
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
440
440
440
440
441
441
441
441
441
442
442
442
443
443
444
444
444
444
444
444
444
445
445
445
446
446
447
447
448
448
449
449
449
449
449
449
450
450
450
451
451
451
452
452
453
453
453
454
454
455
455
455
456
456
456
457
457
458
459
459
459
115
JMSDeliveryMode – Get and Set JMSDeliveryMode . . . . .
JMSDestination – Get and Set JMSDestination . . . . . . .
JMSExpiration – Get and Set JMSExpiration . . . . . . . .
JMSMessageID – Get and Set JMSMessageID . . . . . . . .
JMSPriority – Get and Set JMSPriority . . . . . . . . . .
JMSRedelivered – Get and Set JMSRedelivered . . . . . . .
JMSReplyTo – Get and Set JMSReplyTo . . . . . . . . . .
JMSTimestamp – Get and Set JMSTimestamp . . . . . . . .
JMSType – Get and Set JMSType . . . . . . . . . . . .
PropertyNames – Get Properties . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . .
Acknowledge – Acknowledge . . . . . . . . . . . . .
ClearBody – Clear Body . . . . . . . . . . . . . . .
ClearProperties – Clear Properties . . . . . . . . . . .
PropertyExists – Check Property Exists . . . . . . . . . .
Inherited properties and methods . . . . . . . . . . . .
IMessageConsumer . . . . . . . . . . . . . . . . . .
.NET properties . . . . . . . . . . . . . . . . . .
MessageListener – Get and Set Message Listener . . . . . .
MessageSelector – Get Message Selector . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . .
Close – Close Message Consumer . . . . . . . . . . .
Receive – Receive . . . . . . . . . . . . . . . . .
Receive – Receive (with a wait interval) . . . . . . . . .
ReceiveNoWait – Receive with No Wait . . . . . . . . .
Inherited properties and methods . . . . . . . . . . . .
MessageEOFException . . . . . . . . . . . . . . . . .
Inherited properties and methods . . . . . . . . . . . .
MessageFormatException . . . . . . . . . . . . . . . .
Inherited properties and methods . . . . . . . . . . . .
IMessageListener (delegate) . . . . . . . . . . . . . . .
Delegate . . . . . . . . . . . . . . . . . . . . .
MessageListener - Message Listener . . . . . . . . . . .
MessageNotReadableException . . . . . . . . . . . . . .
Inherited properties and methods . . . . . . . . . . . .
MessageNotWritableException . . . . . . . . . . . . . . .
Inherited properties and methods . . . . . . . . . . . .
IMessageProducer . . . . . . . . . . . . . . . . . . .
.NET properties . . . . . . . . . . . . . . . . . .
DeliveryMode – Get and Set Default Delivery Mode . . . . .
Destination – Get Destination . . . . . . . . . . . . .
DisableMsgID – Get and Set Disable Message ID Flag . . . . .
DisableMsgTS – Get and Set Disable Time Stamp Flag . . . . .
Priority – Get and Set Default Priority . . . . . . . . . .
TimeToLive – Get and Set Default Time to Live . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . .
Close – Close Message Producer . . . . . . . . . . . .
Send – Send . . . . . . . . . . . . . . . . . . .
Send – Send (specifying a delivery mode, priority, and time to live)
Send – Send (to a specified destination) . . . . . . . . .
Send – Send (to a specified destination, specifying a delivery mode,
Inherited properties and methods . . . . . . . . . . . .
IObjectMessage . . . . . . . . . . . . . . . . . . . .
.NET properties . . . . . . . . . . . . . . . . . .
Object – Get and Set Object as Bytes . . . . . . . . . . .
Inherited properties and methods . . . . . . . . . . . .
IPropertyContext . . . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . .
GetBooleanProperty – Get Boolean Property . . . . . . . .
GetByteProperty – Get Byte Property . . . . . . . . . .
GetBytesProperty – Get Byte Array Property . . . . . . . .
116
Message Service Clients for C/C++ and .NET
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
priority,
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
and time to
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
live)
. .
. .
. .
. .
. .
. .
. .
. .
. .
. .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
459
460
460
461
461
462
462
463
463
463
464
464
464
465
465
465
467
467
467
467
468
468
468
468
469
469
470
470
471
471
472
472
472
473
473
474
474
475
475
475
475
476
476
477
477
477
477
478
478
479
480
480
482
482
482
482
483
483
483
483
483
GetCharProperty – Get Character Property . . . . . . . . . . . . . . . . . . .
GetDoubleProperty – Get Double Precision Floating Point Property . . . . . . . . . . .
GetFloatProperty – Get Floating Point Property . . . . . . . . . . . . . . . . . .
GetIntProperty – Get Integer Property . . . . . . . . . . . . . . . . . . . . .
GetLongProperty – Get Long Integer Property . . . . . . . . . . . . . . . . . .
GetObjectProperty – Get Object Property . . . . . . . . . . . . . . . . . . . .
GetShortProperty – Get Short Integer Property . . . . . . . . . . . . . . . . . .
GetStringProperty – Get String Property . . . . . . . . . . . . . . . . . . . .
SetBooleanProperty – Set Boolean Property . . . . . . . . . . . . . . . . . . .
SetByteProperty – Set Byte Property . . . . . . . . . . . . . . . . . . . . . .
SetBytesProperty – Set Byte Array Property . . . . . . . . . . . . . . . . . . .
SetCharProperty – Set Character Property . . . . . . . . . . . . . . . . . . . .
SetDoubleProperty – Set Double Precision Floating Point Property . . . . . . . . . . .
SetFloatProperty – Set Floating Point Property . . . . . . . . . . . . . . . . . .
SetIntProperty – Set Integer Property . . . . . . . . . . . . . . . . . . . . .
SetLongProperty – Set Long Integer Property . . . . . . . . . . . . . . . . . . .
SetObjectProperty – Set Object Property . . . . . . . . . . . . . . . . . . . .
SetShortProperty – Set Short Integer Property . . . . . . . . . . . . . . . . . .
SetStringProperty – Set String Property . . . . . . . . . . . . . . . . . . . . .
IQueueBrowser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.NET Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MessageSelector – Get Message Selector . . . . . . . . . . . . . . . . . . . .
Queue – Get Queue . . . . . . . . . . . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Close – Close Queue Browser . . . . . . . . . . . . . . . . . . . . . . . .
GetEnumerator – Get Messages . . . . . . . . . . . . . . . . . . . . . . .
Inherited properties and methods . . . . . . . . . . . . . . . . . . . . . . .
Requestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Requestor – Create Requestor . . . . . . . . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Close – Close Requestor . . . . . . . . . . . . . . . . . . . . . . . . . .
Request – Request Response . . . . . . . . . . . . . . . . . . . . . . . .
ResourceAllocationException . . . . . . . . . . . . . . . . . . . . . . . . . .
Inherited properties and methods . . . . . . . . . . . . . . . . . . . . . . .
SecurityException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Inherited properties and methods . . . . . . . . . . . . . . . . . . . . . . .
ISession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.NET properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AcknowledgeMode – Get Acknowledgement Mode . . . . . . . . . . . . . . . .
Transacted – Determine Whether Transacted . . . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Close – Close Session . . . . . . . . . . . . . . . . . . . . . . . . . . .
Commit – Commit . . . . . . . . . . . . . . . . . . . . . . . . . . .
CreateBrowser – Create Queue Browser . . . . . . . . . . . . . . . . . . . .
CreateBrowser – Create Queue Browser (with message selector) . . . . . . . . . . . .
CreateBytesMessage – Create Bytes Message . . . . . . . . . . . . . . . . . . .
CreateConsumer – Create Consumer . . . . . . . . . . . . . . . . . . . . .
CreateConsumer – Create Consumer (with message selector) . . . . . . . . . . . . .
CreateConsumer – Create Consumer (with message selector and local message flag) . . . . .
CreateDurableSubscriber – Create Durable Subscriber . . . . . . . . . . . . . . . .
CreateDurableSubscriber – Create Durable Subscriber (with message selector and local message flag)
CreateMapMessage – Create Map Message . . . . . . . . . . . . . . . . . . .
CreateMessage – Create Message . . . . . . . . . . . . . . . . . . . . . . .
CreateObjectMessage – Create Object Message . . . . . . . . . . . . . . . . . .
CreateProducer – Create Producer . . . . . . . . . . . . . . . . . . . . . .
CreateQueue – Create Queue . . . . . . . . . . . . . . . . . . . . . . . .
CreateStreamMessage – Create Stream Message . . . . . . . . . . . . . . . . . .
CreateTemporaryQueue – Create Temporary Queue . . . . . . . . . . . . . . . .
CreateTemporaryTopic – Create Temporary Topic . . . . . . . . . . . . . . . . .
CreateTextMessage – Create Text Message . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Part 3. XMS API reference
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
484
484
485
485
485
486
486
487
487
487
488
488
489
489
490
490
490
491
492
493
493
493
493
493
493
494
494
495
495
495
495
495
496
497
497
498
498
499
499
499
499
500
500
500
500
501
501
502
502
502
503
504
504
505
505
505
506
506
507
507
507
117
CreateTextMessage – Create Text Message (initialized) . . .
CreateTopic – Create Topic . . . . . . . . . . . .
Recover – Recover . . . . . . . . . . . . . . .
Rollback – Rollback . . . . . . . . . . . . . .
Unsubscribe – Unsubscribe . . . . . . . . . . . .
Inherited properties and methods . . . . . . . . . .
IStreamMessage . . . . . . . . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . .
ReadBoolean – Read Boolean Value . . . . . . . . .
ReadByte – Read Byte . . . . . . . . . . . . .
ReadBytes – Read Bytes . . . . . . . . . . . . .
ReadChar – Read Character . . . . . . . . . . .
ReadDouble – Read Double Precision Floating Point Number
ReadFloat – Read Floating Point Number . . . . . . .
ReadInt – Read Integer . . . . . . . . . . . . .
ReadLong – Read Long Integer . . . . . . . . . .
ReadObject – Read Object . . . . . . . . . . . .
ReadShort – Read Short Integer . . . . . . . . . .
ReadString – Read String . . . . . . . . . . . .
Reset – Reset . . . . . . . . . . . . . . . .
WriteBoolean – Write Boolean Value . . . . . . . . .
WriteByte – Write Byte . . . . . . . . . . . . .
WriteBytes – Write Bytes . . . . . . . . . . . .
WriteChar – Write Character . . . . . . . . . . .
WriteDouble – Write Double Precision Floating Point Number
WriteFloat – Write Floating Point Number . . . . . . .
WriteInt – Write Integer . . . . . . . . . . . . .
WriteLong – Write Long Integer . . . . . . . . . .
WriteObject – Write Object . . . . . . . . . . . .
WriteShort – Write Short Integer . . . . . . . . . .
WriteString – Write String . . . . . . . . . . . .
Inherited properties and methods . . . . . . . . . .
ITextMessage . . . . . . . . . . . . . . . . . .
.NET properties . . . . . . . . . . . . . . . .
Text – Get Text . . . . . . . . . . . . . . . .
Inherited properties and methods . . . . . . . . . .
TransactionInProgressException . . . . . . . . . . . .
Inherited properties and methods . . . . . . . . . .
TransactionRolledBackException . . . . . . . . . . . .
Inherited properties and methods . . . . . . . . . .
XMSException . . . . . . . . . . . . . . . . . .
.NET properties . . . . . . . . . . . . . . . .
GetErrorCode – Get Error Code . . . . . . . . . .
GetLinkedException – Get Linked Exception . . . . . .
XMSFactoryFactory . . . . . . . . . . . . . . . .
.NET properties . . . . . . . . . . . . . . . .
MetaData – Retrieve MetaData . . . . . . . . . .
Methods . . . . . . . . . . . . . . . . . . .
CreateConnectionFactory - Create Connection Factory . . .
CreateQueue – Create Queue . . . . . . . . . . .
CreateTopic – Create Topic . . . . . . . . . . . .
GetInstance - Get an instance of XMSFactoryFactory . . .
Chapter 15. Properties of XMS objects
Properties of Connection . . . . .
Properties of ConnectionFactory . . .
Properties of ConnectionMetaData . .
Properties of Destination . . . . .
Properties of InitialContext . . . . .
Properties of Message . . . . . .
Properties of MessageConsumer . . .
118
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
508
508
508
509
509
510
511
511
511
511
512
512
513
513
513
514
514
514
515
515
515
516
516
517
517
517
518
518
518
519
519
520
521
521
521
521
522
522
523
523
524
524
524
524
525
525
525
525
525
525
526
526
. . . . . . . . . . . . . . . . . . . . . . . . . 527
. . . . . . . . . . . . . . . . . . . . . . . . . 527
. . . . . . . . . . . . . . . . . . . . . . . . . 528
. . . . . . . . . . . . . . . . . . . . . . . . . 530
. . . . . . . . . . . . . . . . . . . . . . . . . 530
. . . . . . . . . . . . . . . . . . . . . . . . . 531
. . . . . . . . . . . . . . . . . . . . . . . . . 531
. . . . . . . . . . . . . . . . . . . . . . . . . 533
Message Service Clients for C/C++ and .NET
Properties of MessageProducer . . . . . . . .
Properties of Session . . . . . . . . . . . .
Property definitions . . . . . . . . . . . .
JMS_IBM_CHARACTER_SET . . . . . . . .
JMS_IBM_ENCODING . . . . . . . . . .
JMS_IBM_EXCEPTION_MESSAGE . . . . . .
JMS_IBM_EXCEPTION_PROBLEM_DESTINATION
JMS_IBM_EXCEPTION_REASON . . . . . .
JMS_IBM_EXCEPTION_TIMESTAMP . . . . .
JMS_IBM_FEEDBACK . . . . . . . . . .
JMS_IBM_FORMAT . . . . . . . . . . .
JMS_IBM_LAST_MSG_IN_GROUP . . . . . .
JMS_IBM_MSGTYPE . . . . . . . . . . .
JMS_IBM_PUTAPPLTYPE . . . . . . . . .
JMS_IBM_PUTDATE . . . . . . . . . . .
JMS_IBM_PUTTIME . . . . . . . . . . .
JMS_IBM_REPORT_COA . . . . . . . . .
JMS_IBM_REPORT_COD . . . . . . . . .
JMS_IBM_REPORT_DISCARD_MSG. . . . . .
JMS_IBM_REPORT_EXCEPTION . . . . . . .
JMS_IBM_REPORT_EXPIRATION . . . . . .
JMS_IBM_REPORT_NAN . . . . . . . . .
JMS_IBM_REPORT_PAN . . . . . . . . .
JMS_IBM_REPORT_PASS_CORREL_ID . . . . .
JMS_IBM_REPORT_PASS_MSG_ID . . . . . .
JMS_IBM_SYSTEM_MESSAGEID . . . . . . .
JMSX_APPID . . . . . . . . . . . . .
JMSX_DELIVERY_COUNT . . . . . . . . .
JMSX_GROUPID . . . . . . . . . . . .
JMSX_GROUPSEQ . . . . . . . . . . .
JMSX_USERID . . . . . . . . . . . . .
XMSC_CLIENT_CCSID . . . . . . . . . .
XMSC_CLIENT_ID . . . . . . . . . . .
XMSC_CONNECTION_TYPE . . . . . . . .
XMSC_DELIVERY_MODE . . . . . . . . .
XMSC_IC_SECURITY_CREDENTIALS . . . . .
XMSC_IC_URL . . . . . . . . . . . . .
XMSC_IS_SUBSCRIPTION_MULTICAST . . . .
XMSC_IS_SUBSCRIPTION_RELIABLE_MULTICAST
XMSC_JMS_MAJOR_VERSION . . . . . . .
XMSC_JMS_MINOR_VERSION . . . . . . .
XMSC_JMS_VERSION . . . . . . . . . .
XMSC_MAJOR_VERSION . . . . . . . . .
XMSC_MINOR_VERSION . . . . . . . . .
XMSC_PASSWORD . . . . . . . . . . .
XMSC_PRIORITY . . . . . . . . . . . .
XMSC_PROVIDER_NAME . . . . . . . . .
XMSC_RTT_CONNECTION_PROTOCOL . . . .
XMSC_RTT_HOST_NAME . . . . . . . . .
XMSC_RTT_LOCAL_ADDRESS . . . . . . .
XMSC_RTT_MULTICAST . . . . . . . . .
XMSC_RTT_PORT . . . . . . . . . . . .
XMSC_TIME_TO_LIVE . . . . . . . . . .
XMSC_USERID . . . . . . . . . . . . .
XMSC_VERSION . . . . . . . . . . . .
XMSC_WMQ_BROKER_CONTROLQ . . . . .
XMSC_WMQ_BROKER_PUBQ . . . . . . .
XMSC_WMQ_BROKER_QMGR . . . . . . .
XMSC_WMQ_BROKER_SUBQ . . . . . . .
XMSC_WMQ_BROKER_VERSION . . . . . .
XMSC_WMQ_CCSID . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Part 3. XMS API reference
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
533
533
533
534
534
535
535
536
536
536
537
537
537
538
538
538
539
539
540
540
541
542
542
542
543
543
543
544
544
544
545
545
546
546
546
547
547
548
548
548
548
549
549
549
549
549
550
550
551
551
551
552
553
553
553
554
554
554
554
555
555
119
XMSC_WMQ_CHANNEL . . . . . . .
XMSC_WMQ_CONNECTION_MODE . . .
XMSC_WMQ_DUR_SUBQ . . . . . . .
XMSC_WMQ_ENCODING . . . . . . .
XMSC_WMQ_FAIL_IF_QUIESCE . . . . .
XMSC_WMQ_HOST_NAME . . . . . .
XMSC_WMQ_LOCAL_ADDRESS . . . .
XMSC_WMQ_MESSAGE_SELECTION . . .
XMSC_WMQ_MSG_BATCH_SIZE . . . .
XMSC_WMQ_POLLING_INTERVAL . . .
XMSC_WMQ_PORT . . . . . . . . .
XMSC_WMQ_PUB_ACK_INTERVAL . . .
XMSC_WMQ_QMGR_CCSID . . . . . .
XMSC_WMQ_QUEUE_MANAGER . . . .
XMSC_WMQ_RECEIVE_EXIT . . . . . .
XMSC_WMQ_RECEIVE_EXIT_INIT . . . .
XMSC_WMQ_SECURITY_EXIT . . . . .
XMSC_WMQ_SECURITY_EXIT_INIT . . .
XMSC_WMQ_SEND_EXIT . . . . . . .
XMSC_WMQ_SEND_EXIT_INIT . . . . .
XMSC_WMQ_SYNCPOINT_ALL_GETS . .
XMSC_WMQ_TARGET_CLIENT . . . . .
XMSC_WMQ_TEMP_Q_PREFIX . . . . .
XMSC_WMQ_TEMPORARY_MODEL . . .
XMSC_WPM_BUS_NAME . . . . . . .
XMSC_WPM_CONNECTION_PROTOCOL .
XMSC_WPM_CONNECTION_PROXIMITY .
XMSC_WPM_DUR_SUB_HOME . . . . .
XMSC_WPM_HOST_NAME . . . . . .
XMSC_WPM_LOCAL_ADDRESS . . . . .
XMSC_WPM_ME_NAME . . . . . . .
XMSC_WPM_NON_PERSISTENT_MAP . .
XMSC_WPM_PERSISTENT_MAP . . . .
XMSC_WPM_PORT . . . . . . . . .
XMSC_WPM_PROVIDER_ENDPOINTS . .
XMSC_WPM_TARGET_GROUP . . . . .
XMSC_WPM_TARGET_SIGNIFICANCE . .
XMSC_WPM_TARGET_TRANSPORT_CHAIN
XMSC_WPM_TARGET_TYPE . . . . . .
XMSC_WPM_TEMP_Q_PREFIX . . . . .
XMSC_WPM_TEMP_TOPIC_PREFIX . . .
XMSC_WPM_TOPIC_SPACE . . . . . .
120
Message Service Clients for C/C++ and .NET
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
556
556
556
557
558
558
559
560
560
561
561
561
561
562
562
563
563
563
564
564
565
565
566
566
566
567
567
567
568
568
569
569
569
570
570
571
571
572
572
573
573
574
Chapter 11. C classes
This chapter documents the C classes and their functions. Table 28 summarizes all
the classes.
Table 28. Summary of the C classes
Class
Description
BytesMessage
A bytes message is a message whose body comprises a
stream of bytes.
Connection
A Connection object represents an application’s active
connection to a broker.
ConnectionFactory
An application uses a connection factory to create a
connection.
ConnectionMetaData
A ConnectionMetaData object provides information
about a connection.
Destination
A destination is where an application sends messages,
or it is a source from which an application receives
messages, or both.
ErrorBlock
If a C function call fails, XMS can store information in
an error block about why the call failed.
ExceptionListener
An application uses an exception listener to be notified
asynchronously of a problem with a connection.
InitialContext
An application uses an InitialContext object to create
objects from object definitions that are retrieved from a
repository of administered objects.
Iterator
An iterator encapsulates a list of objects. An application
uses an iterator to access each object in turn.
MapMessage
A map message is a message whose body comprises a
set of name-value pairs, where each value has an
associated data type.
Message
A Message object represents a message that an
application sends or receives.
MessageConsumer
An application uses a message consumer to receive
messages sent to a destination.
MessageListener
An application uses a message listener to receive
messages asynchronously.
MessageProducer
An application uses a message producer to send
messages to a destination.
ObjectMessage
An object message is a message whose body comprises
a serialized Java or .NET object.
Property
A Property object represents a property of an object.
PropertyContext
The PropertyContext class contains functions that get
and set properties. These functions can operate on any
type of object that can have properties.
QueueBrowser
An application uses a queue browser to browse
messages on a queue without removing them.
Requestor
An application uses a requestor to send a request
message and then wait for, and receive, the reply.
© Copyright IBM Corp. 2005
121
C classes
Table 28. Summary of the C classes (continued)
Class
Description
Session
A session is a single threaded context for sending and
receiving messages.
StreamMessage
A stream message is a message whose body comprises
a stream of values, where each value has an associated
data type.
TextMessage
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.
122
Message Service Clients for C/C++ and .NET
C classes
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
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
Chapter 11. C classes
123
C classes
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:
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
124
Message Service Clients for C/C++ and .NET
C classes
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
v XMS_X_MESSAGE_EOF_EXCEPTION
xmsBytesMsgReadBytesByRef – Read Bytes by Reference
Interface:
xmsRC xmsBytesMsgReadBytesByRef(xmsHMsg message,
xmsSBYTE **stream,
xmsINT *length,
xmsHErrorBlock errorBlock);
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 63.
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
v XMS_X_MESSAGE_EOF_EXCEPTION
Chapter 11. C classes
125
C classes
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);
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
126
Message Service Clients for C/C++ and .NET
C classes
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:
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);
Chapter 11. C classes
127
C classes
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.
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.
128
Message Service Clients for C/C++ and .NET
C classes
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
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 62.
Parameters:
message (input)
The handle for the message.
Chapter 11. C classes
129
C classes
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 error code
XMS_E_DATA_TRUNCATED. 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.
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
130
Message Service Clients for C/C++ and .NET
C classes
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:
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.
Chapter 11. C classes
131
C classes
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.
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.
132
Message Service Clients for C/C++ and .NET
C classes
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
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
Chapter 11. C classes
133
C classes
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.
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:
134
Message Service Clients for C/C++ and .NET
C classes
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
Chapter 11. C classes
135
C classes
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 527.
Functions
xmsConnClose – Close Connection
Interface:
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
136
Message Service Clients for C/C++ and .NET
C classes
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 “Acknowledging
the receipt of messages in a session” on page 43.
session (output)
The handle for the session.
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 62.
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
Chapter 11. C classes
137
C classes
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.
For more information about using exception listener functions, see “Using
exception listener functions in C” on page 61.
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
138
Message Service Clients for C/C++ and .NET
C classes
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.
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 “Using
exception listener functions in C” on page 61.
Parameters:
connection (input)
The handle for the connection.
Chapter 11. C classes
139
C classes
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:
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
140
Message Service Clients for C/C++ and .NET
C classes
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 528.
Functions
xmsConnFactCreate – Create Connection Factory
Interface:
xmsRC xmsConnFactCreate(xmsHConnFact *factory,
xmsHErrorBlock errorBlock);
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.
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 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.
Chapter 11. C classes
141
C classes
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);
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 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);
142
Message Service Clients for C/C++ and .NET
C classes
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.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
Chapter 11. C classes
143
C classes
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 530.
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
144
Message Service Clients for C/C++ and .NET
C classes
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 530.
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:
Chapter 11. C classes
145
C classes
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.
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 48.
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.
146
Message Service Clients for C/C++ and .NET
C classes
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
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 62.
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.
Chapter 11. C classes
147
C classes
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.
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 62.
Parameters:
destination (input)
The handle for the destination.
148
Message Service Clients for C/C++ and .NET
C classes
destinationName (output)
The buffer to contain the URI. The URI is either a queue URI or a
topic URI.
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
Chapter 11. C classes
149
C classes
ErrorBlock
If a C function call fails, XMS can store information in an error block about why
the call failed. For more information about the error block and its contents, see
“The error block” on page 65.
Functions in this class return the following return codes:
Return code
XMS_OK
XMS_E_INVALID_ERROR_BLOCK
Any other value
Meaning
The call completed successfully.
The call failed because the error block that
was passed to the function was not valid.
The call failed for some other reason.
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);
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
150
Message Service Clients for C/C++ and .NET
C classes
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 65.
Parameters:
errorBlock (input)
The handle for the error block.
errorCode (output)
The error code.
Thread context:
Any
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 65.
For more information about how to use this function, see “C functions that return
a string by value” on page 62.
Chapter 11. C classes
151
C classes
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 65.
For more information about how to use this function, see “C functions that return
a string by value” on page 62.
Parameters:
errorBlock (input)
The handle for the error block.
buffer (output)
The buffer to contain the error string.
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);
152
Message Service Clients for C/C++ and .NET
C classes
Get the exception code.
For more information about the exception code, see “The error block” on page 65.
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
Chapter 11. C classes
153
C classes
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 “Using
exception listener functions in C” on page 61.
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.
154
Message Service Clients for C/C++ and .NET
C classes
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 531.
Functions
xmsInitialContextCreate – Create Initial Context
Interface:
xmsRC xmsInitialContextCreate(xmsCHAR *address,
xmsHInitialContect *hContext,
xmsHErrorBlock errorBlock);
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 100.
Parameters:
contextAddress (input)
A URI that identifies the location of a repository containing
administered objects. The exact syntax of the URI depends on the
context type. For further details see “URI format for XMS initial
contexts” on page 100.
hContext (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. 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:
initialContext (input/output)
On input, the handle for the InitialContext object. On output, the
function returns a null handle.
Chapter 11. C classes
155
C classes
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 hInitialContext,
xmsCHAR *name,
xmsHObj *returnedObject,
xmsHANDLE_TYPE *type,
xmsHErrorBlock errorBlock);
Create an object from an object definition that is retrieved from the repository of
administered objects.
Parameters:
hInitialContext (input)
The handle for the InitialContext object.
name (input)
The name of the administered object in the format of a null
terminated string. The name can be either a simple name or a
complex name. For further details, see “Retrieval of administered
objects” on page 101.
returnedObject (output)
The handle for the object that is created.
type (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
156
Message Service Clients for C/C++ and .NET
C classes
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:
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.
Chapter 11. C classes
157
C classes
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.
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
158
Message Service Clients for C/C++ and .NET
C classes
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 91.
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);
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.
Chapter 11. C classes
159
C classes
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 62.
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:
v XMS_X_GENERAL_EXCEPTION
160
Message Service Clients for C/C++ and .NET
C classes
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 63.
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.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
Chapter 11. C classes
161
C classes
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.
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
162
Message Service Clients for C/C++ and .NET
C classes
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.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
Chapter 11. C classes
163
C classes
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 62.
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.
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.
164
Message Service Clients for C/C++ and .NET
C classes
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.
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
Chapter 11. C classes
165
C classes
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 62.
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:
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 63.
Parameters:
166
Message Service Clients for C/C++ and .NET
C classes
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.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
xmsMapMsgSetBoolean – Set Boolean Value
Interface:
xmsRC xmsMapMsgSetBoolean(xmsHMsg message,
xmsCHAR *name,
xmsBOOL value,
xmsHErrorBlock errorBlock);
Chapter 11. C classes
167
C classes
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
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:
168
Message Service Clients for C/C++ and .NET
C classes
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
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:
Chapter 11. C classes
169
C classes
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
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.
170
Message Service Clients for C/C++ and .NET
C classes
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:
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.
Chapter 11. C classes
171
C classes
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.
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
172
Message Service Clients for C/C++ and .NET
C classes
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
Chapter 11. C classes
173
C classes
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 85. For a list of the JMS defined properties of a
Message object, see “JMS defined properties of a message” on page 87. For a list of
the IBM defined properties of a Message object, see “IBM defined properties of a
message” on page 87.
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 “Acknowledging the
receipt of messages in a session” on page 43.
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 89.
174
Message Service Clients for C/C++ and .NET
C classes
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:
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:
Chapter 11. C classes
175
C classes
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:
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 62.
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:
176
Message Service Clients for C/C++ and .NET
C classes
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_NON_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_NON_PERSISTENT. For a message that has been
received, the function returns the delivery mode that was set by
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 error code XMS_E_NOT_SET 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
Chapter 11. C classes
177
C classes
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.
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 62.
Parameters:
message (input)
The handle for the message.
178
Message Service Clients for C/C++ and .NET
C classes
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.
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 error code XMS_E_NOT_SET.
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:
Chapter 11. C classes
179
C classes
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.
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
180
Message Service Clients for C/C++ and .NET
C classes
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.
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 62.
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.
Chapter 11. C classes
181
C classes
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
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 89.
182
Message Service Clients for C/C++ and .NET
C classes
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
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);
Chapter 11. C classes
183
C classes
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.
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_NON_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);
184
Message Service Clients for C/C++ and .NET
C classes
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.
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.
Chapter 11. C classes
185
C classes
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.
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);
186
Message Service Clients for C/C++ and .NET
C classes
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.
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.
Chapter 11. C classes
187
C classes
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.
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
188
Message Service Clients for C/C++ and .NET
C classes
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 533.
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.
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 “Using message
listener functions in C” on page 60.
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.
Chapter 11. C classes
189
C classes
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.
For more information about how to use this function, see “C functions that return
a string by value” on page 62.
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:
190
Message Service Clients for C/C++ and .NET
C classes
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:
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.
Chapter 11. C classes
191
C classes
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:
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 “Using message
listener functions in C” on page 60.
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
192
Message Service Clients for C/C++ and .NET
C classes
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 “Using message
listener functions in C” on page 60.
Parameters:
context (input)
A pointer to the context data that is registered with the message
consumer.
message (input)
The handle for the message.
Chapter 11. C classes
193
C classes
MessageProducer
An application uses a message producer to send messages to a destination.
For a list of the XMS defined properties of a MessageProducer object, see
“Properties of MessageProducer” on page 533.
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_NON_PERSISTENT
For a real-time connection to a broker, the value is always
XMSC_DELIVERY_NON_PERSISTENT.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
194
Message Service Clients for C/C++ and .NET
C classes
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
Chapter 11. C classes
195
C classes
xmsMsgProducerGetDisableMsgTS – Get Disable Time Stamp
Flag
Interface:
xmsRC xmsMsgProducerGetDisableMsgTS(xmsHMsgProducer producer,
xmsBOOL *timeStampDisabled,
xmsHErrorBlock errorBlock);
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);
196
Message Service Clients for C/C++ and .NET
C classes
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.
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.
Chapter 11. C classes
197
C classes
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.
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_NON_PERSISTENT
For a real-time connection to a broker, the value must be
XMSC_DELIVERY_NON_PERSISTENT.
198
Message Service Clients for C/C++ and .NET
C classes
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.
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_NON_PERSISTENT
For a real-time connection to a broker, the value must be
XMSC_DELIVERY_NON_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 11. C classes
199
C classes
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
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_NON_PERSISTENT
For a real-time connection to a broker, the value must be
XMSC_DELIVERY_NON_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_NON_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.
200
Message Service Clients for C/C++ and .NET
C classes
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.
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
Chapter 11. C classes
201
C classes
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.
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
202
Message Service Clients for C/C++ and .NET
C classes
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.
For more information about how to use this function, see “C functions that return
a byte array by value” on page 62.
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 error code
XMS_E_DATA_TRUNCATED.
2. If any other error occurs while attempting to get the object, XMS reports
the error but does not set the actualLength parameter.
Chapter 11. C classes
203
C classes
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.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION
204
Message Service Clients for C/C++ and .NET
C classes
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);
Delete the Property object.
If an application tries to delete a Property object that is already deleted, the call is
ignored.
Parameters:
Chapter 11. C classes
205
C classes
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.
propertyValue (output)
The boolean property value.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
206
Message Service Clients for C/C++ and .NET
C classes
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 62.
Parameters:
property (input)
The handle for the Property object.
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.
Chapter 11. C classes
207
C classes
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 63.
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);
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.
208
Message Service Clients for C/C++ and .NET
C classes
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.
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
Chapter 11. C classes
209
C classes
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
Exceptions:
v XMS_X_GENERAL_EXCEPTION
210
Message Service Clients for C/C++ and .NET
C classes
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 62.
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.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Chapter 11. C classes
211
C classes
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 62.
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);
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 63.
212
Message Service Clients for C/C++ and .NET
C classes
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 error code
XMS_E_TYPE_CONVERSION_FAILED.
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
XMS_PROPERTY_TYPE_DOUBLE
errorBlock (input)
The handle for an error block or a null handle.
Chapter 11. C classes
213
C classes
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
xmsPropertySetBoolean – Set Boolean Property Value
Interface:
xmsRC xmsPropertySetBoolean(xmsHProperty property,
xmsBOOL propertyValue,
xmsHErrorBlock errorBlock);
214
Message Service Clients for C/C++ and .NET
C classes
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);
Set a byte array property value in the Property object and set the property type.
Parameters:
property (input)
The handle for the Property object.
Chapter 11. C classes
215
C classes
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.
Parameters:
property (input)
The handle for the Property object.
propertyValue (input)
The double precision floating point property value.
216
Message Service Clients for C/C++ and .NET
C classes
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.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION
Chapter 11. C classes
217
C classes
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
xmsPropertySetString – Set String Property Value
Interface:
xmsRC xmsPropertySetString(xmsHProperty property,
xmsCHAR *propertyValue,
xmsINT length,
xmsHErrorBlock errorBlock);
218
Message Service Clients for C/C++ and .NET
C classes
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
Chapter 11. C classes
219
C classes
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.
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 62.
Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
220
Message Service Clients for C/C++ and .NET
C classes
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
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 63.
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
Chapter 11. C classes
221
C classes
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.
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
222
Message Service Clients for C/C++ and .NET
C classes
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.
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
Chapter 11. C classes
223
C classes
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
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.
224
Message Service Clients for C/C++ and .NET
C classes
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);
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 62.
Chapter 11. C classes
225
C classes
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.
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:
226
Message Service Clients for C/C++ and .NET
C classes
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:
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.
Chapter 11. C classes
227
C classes
For more information about how to use this function, see “C functions that return
a string by value” on page 62.
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
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 63.
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
228
Message Service Clients for C/C++ and .NET
C classes
string. If an application calls this function to get a pointer to a
value that is not a string, XMS returns error code
XMS_E_TYPE_CONVERSION_FAILED.
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:
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:
Chapter 11. C classes
229
C classes
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
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
230
Message Service Clients for C/C++ and .NET
C classes
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:
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
Chapter 11. C classes
231
C classes
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.
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
232
Message Service Clients for C/C++ and .NET
C classes
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.
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
Chapter 11. C classes
233
C classes
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
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.
234
Message Service Clients for C/C++ and .NET
C classes
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
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
Chapter 11. C classes
235
C classes
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:
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.
236
Message Service Clients for C/C++ and .NET
C classes
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);
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 62.
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.
Chapter 11. C classes
237
C classes
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
238
Message Service Clients for C/C++ and .NET
C classes
Requestor
An application uses a requestor to send a request message and then wait for, and
receive, the reply.
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.
Chapter 11. C classes
239
C classes
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
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
240
Message Service Clients for C/C++ and .NET
C classes
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 533.
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 “Deleting objects” on page 52.
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
Chapter 11. C classes
241
C classes
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.
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.
242
Message Service Clients for C/C++ and .NET
C classes
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:
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.
Chapter 11. C classes
243
C classes
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.
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
244
Message Service Clients for C/C++ and .NET
C classes
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.
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
Chapter 11. C classes
245
C classes
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
49.
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.
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.
246
Message Service Clients for C/C++ and .NET
C classes
For more information about durable subscribers, see “Durable subscribers” on page
49.
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.
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:
Chapter 11. C classes
247
C classes
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.
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
248
Message Service Clients for C/C++ and .NET
C classes
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
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
Chapter 11. C classes
249
C classes
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);
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
250
Message Service Clients for C/C++ and .NET
C classes
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 “Acknowledging the
receipt of messages in a session” on page 43.
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.
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.
Chapter 11. C classes
251
C classes
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 “Acknowledging the receipt
of messages in a session” on page 43.
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
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);
252
Message Service Clients for C/C++ and .NET
C classes
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 11. C classes
253
C classes
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 92.
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.
Exceptions:
254
Message Service Clients for C/C++ and .NET
C classes
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 11. C classes
255
C classes
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 63.
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
256
Message Service Clients for C/C++ and .NET
C classes
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
Chapter 11. C classes
257
C classes
xmsStreamMsgReadInt – Read Integer
Interface:
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,
258
Message Service Clients for C/C++ and .NET
C classes
xmsINT *actualLength,
xmsOBJECT_TYPE *objectType,
xmsHErrorBlock errorBlock);
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 62.
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
Chapter 11. C classes
259
C classes
xmsStreamMsgReadShort – Read Short Integer
Interface:
xmsRC xmsStreamMsgReadShort(xmsHMsg message,
xmsSHORT *value,
xmsHErrorBlock errorBlock);
Read a signed 16-bit integer from the message stream.
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 62.
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,
260
Message Service Clients for C/C++ and .NET
C classes
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 error code
XMS_E_DATA_TRUNCATED. 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.
Chapter 11. C classes
261
C classes
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
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
262
Message Service Clients for C/C++ and .NET
C classes
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION
xmsStreamMsgWriteChar – Write Character
Interface:
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
Chapter 11. C classes
263
C classes
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:
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:
264
Message Service Clients for C/C++ and .NET
C classes
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
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
Chapter 11. C classes
265
C classes
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:
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
266
Message Service Clients for C/C++ and .NET
C classes
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);
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 62.
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 error code
XMS_E_DATA_TRUNCATED.
2. If any other error occurs while attempting to get the string, XMS reports
the error but does not set the actualLength parameter.
Chapter 11. C classes
267
C classes
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.
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
268
Message Service Clients for C/C++ and .NET
Chapter 12. Additional C functions
This chapter documents the C functions that do not belong to any class. The
chapter contains the following section:
v Process CCSID functions
© Copyright IBM Corp. 2005
269
Additional C 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 (CCSIDs)” 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:
Named constant
XMSC_CCSID_UTF8
XMSC_CCSID_UTF16
XMSC_CCSID_UTF32
CCSID
The UTF-8 representation of Unicode data
The UTF-16 representation of Unicode data
The UTF-32 representation of Unicode data
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
270
Message Service Clients for C/C++ and .NET
Additional C functions
Exceptions:
v XMS_X_GENERAL_EXCEPTION
Chapter 12. Additional C functions
271
Additional C functions
272
Message Service Clients for C/C++ and .NET
Chapter 13. C++ classes
This chapter documents the C++ classes and their methods. Table 29 summarizes
all the classes.
Table 29. Summary of the C++ classes
Class
Description
BytesMessage
A bytes message is a message whose body comprises a
stream of bytes.
Connection
A Connection object represents an application’s active
connection to a broker.
ConnectionFactory
An application uses a connection factory to create a
connection.
ConnectionMetaData
A ConnectionMetaData object provides information
about a connection.
Destination
A destination is where an application sends messages,
or it is a source from which an application receives
messages, or both.
Exception
If XMS detects an error while processing a call to a C++
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
An application uses an exception listener to be notified
asynchronously of a problem with a connection.
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.
InitialContext
An application uses an InitialContext object to create
objects from object definitions that are retrieved from a
repository of administered objects.
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.
InvalidDestinationException
XMS throws this exception if an application specifies a
destination that is not valid.
InvalidSelectorException
XMS throws this exception if an application provides a
message selector expression whose syntax is not valid.
Iterator
An iterator encapsulates a list of objects. An application
uses an iterator to access each object in turn.
MapMessage
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
273
C++ classes
Table 29. Summary of the C++ classes (continued)
274
Class
Description
Message
A Message object represents a message that an
application sends or receives.
MessageConsumer
An application uses a message consumer to receive
messages sent to a destination.
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.
MessageFormatException
XMS throws this exception if XMS encounters a
message with a format that is not valid.
MessageListener
An application uses a message listener to receive
messages asynchronously.
MessageNotReadableException
XMS throws this exception if an application attempts to
read the body of a message that is write-only.
MessageNotWritableException
XMS throws this exception if an application attempts to
write to the body of a message that is read-only.
MessageProducer
An application uses a message producer to send
messages to a destination.
ObjectMessage
An object message is a message whose body comprises
a serialized Java or .NET object.
Property
A Property object represents a property of an object.
PropertyContext
PropertyContext is an abstract superclass that
encapsulates methods that get and set properties. These
methods are inherited by other classes.
QueueBrowser
An application uses a queue browser to browse
messages on a queue without removing them.
Requestor
An application uses a requestor to send a request
message and then wait for, and receive, the reply.
ResourceAllocationException
XMS throws this exception if XMS cannot allocate the
resources required by a method.
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.
Session
A session is a single threaded context for sending and
receiving messages.
StreamMessage
A stream message is a message whose body comprises
a stream of values, where each value has an associated
data type.
String
A String object encapsulates a string.
TextMessage
A text message is a message whose body comprises a
string.
TransactionInProgressException
XMS throws this exception if an application requests an
operation that is not valid because a transaction is in
progress.
TransactionRolledBackException
XMS throws this exception if an application calls
Session.commit() to commit the current transaction, but
the transaction is subsequently rolled back.
Message Service Clients for C/C++ and .NET
C++ classes
BytesMessage
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::Message
|
+----xms::BytesMessage
A bytes message is a message whose body comprises a stream of bytes.
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
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;
Chapter 13. C++ classes
275
C++ classes
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.
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
276
Message Service Clients for C/C++ and .NET
C++ classes
v XMS_X_MESSAGE_NOT_READABLE_EXCEPTION
v XMS_X_MESSAGE_EOF_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.
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
Chapter 13. C++ classes
277
C++ classes
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.
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
278
Message Service Clients for C/C++ and .NET
C++ classes
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.
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
Chapter 13. C++ classes
279
C++ classes
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);
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:
280
Message Service Clients for C/C++ and .NET
C++ classes
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
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.
Chapter 13. C++ classes
281
C++ classes
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
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:
282
Message Service Clients for C/C++ and .NET
C++ classes
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
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,
Chapter 13. C++ classes
283
C++ classes
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
284
Message Service Clients for C/C++ and .NET
C++ classes
Connection
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::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 527.
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
Chapter 13. C++ classes
285
C++ classes
This parameter is ignored if the session is transacted. For more
information about acknowledgement modes, see “Acknowledging
the receipt of messages in a session” on page 43.
Returns:
The Session object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
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 “Using exception
listeners in C++” on page 73.
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.
286
Message Service Clients for C/C++ and .NET
C++ classes
Parameters:
None
Returns:
The handle for the connection.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
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
Chapter 13. C++ classes
287
C++ classes
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
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 “Using exception
listeners in C++” on page 73.
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:
288
Message Service Clients for C/C++ and .NET
C++ classes
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.
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
Chapter 13. C++ classes
289
C++ classes
ConnectionFactory
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::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 528.
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.
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
290
Message Service Clients for C/C++ and .NET
C++ classes
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
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;
Chapter 13. C++ classes
291
C++ classes
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,
setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty,
setObjectProperty, setProperty, setShortProperty, setStringProperty
292
Message Service Clients for C/C++ and .NET
C++ classes
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 530.
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
Returns:
The Iterator object.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
Chapter 13. C++ classes
293
C++ classes
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
294
Message Service Clients for C/C++ and .NET
C++ classes
Destination
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::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 530.
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.
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
Chapter 13. C++ classes
295
C++ classes
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();
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
296
Message Service Clients for C/C++ and .NET
C++ classes
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.
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;
Chapter 13. C++ classes
297
C++ classes
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
298
Message Service Clients for C/C++ and .NET
C++ classes
Exception
Inheritance hierarchy:
std::exception
|
+----xms::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.
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
getErrorCode – Get Error Code
Interface:
xmsINT getErrorCode() const;
Chapter 13. C++ classes
299
C++ classes
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
getHandle – Get Handle
Interface:
xmsHErrorBlock getHandle() const;
300
Message Service Clients for C/C++ and .NET
C++ classes
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
isNull – Check Whether Null
Interface:
xmsBOOL isNull() const;
Determine whether the Exception object is a null object.
Chapter 13. C++ classes
301
C++ classes
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
302
Message Service Clients for C/C++ and .NET
C++ classes
ExceptionListener
Inheritance hierarchy:
None
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.
Methods
onException – On Exception
Interface:
virtual xmsVOID onException(const 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 “Using exception
listeners in C++” on page 73.
Parameters:
exception (input)
A pointer to an exception created by XMS.
Returns:
Void
Chapter 13. C++ classes
303
C++ classes
IllegalStateException
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::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.
Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull
304
Message Service Clients for C/C++ and .NET
C++ classes
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 531.
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 100.
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
100.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
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
Chapter 13. C++ classes
305
C++ classes
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
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 101.
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:
306
Message Service Clients for C/C++ and .NET
C++ classes
getBooleanProperty, getByteProperty, getBytesProperty, getCharProperty,
getDoubleProperty, getFloatProperty, getIntProperty, getLongProperty,
getObjectProperty, getProperty, getShortProperty, getStringProperty,
setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty,
setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty,
setObjectProperty, setProperty, setShortProperty, setStringProperty
Chapter 13. C++ classes
307
C++ classes
InvalidClientIDException
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::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.
Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull
308
Message Service Clients for C/C++ and .NET
C++ classes
InvalidDestinationException
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::InvalidDestinationException
XMS throws this exception if an application specifies a destination that is not valid.
Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull
Chapter 13. C++ classes
309
C++ classes
InvalidSelectorException
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::InvalidSelectorException
XMS throws this exception if an application provides a message selector expression
whose syntax is not valid.
Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull
310
Message Service Clients for C/C++ and .NET
C++ classes
Iterator
Inheritance hierarchy:
None
An iterator encapsulates a list of objects. An application uses an iterator to access
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 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
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
Chapter 13. C++ classes
311
C++ classes
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
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.
312
Message Service Clients for C/C++ and .NET
C++ classes
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
Chapter 13. C++ classes
313
C++ classes
MapMessage
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::Message
|
+----xms::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 91.
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
314
Message Service Clients for C/C++ and .NET
C++ classes
getBytes – Get Bytes
Interface:
xmsINT getBytes(const String & name,
xmsSBYTE *buffer,
const xmsINT bufferLength,
xmsINT *actualLength) const;
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 68.
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;
Chapter 13. C++ classes
315
C++ classes
Get the double precision 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 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;
316
Message Service Clients for C/C++ and .NET
C++ classes
Get the long integer identified by name from the body of the map message.
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 68.
Parameters:
name (input)
A String object encapsulating the name of the name-value pair.
Chapter 13. C++ classes
317
C++ classes
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;
318
Message Service Clients for C/C++ and .NET
C++ classes
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
Chapter 13. C++ classes
319
C++ classes
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.
Parameters:
320
Message Service Clients for C/C++ and .NET
C++ classes
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
Chapter 13. C++ classes
321
C++ classes
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
const
const
const
String & name,
xmsOBJECT_TYPE objectType,
xmsSBYTE *value,
xmsINT length);
Set a value, with a specified data type, in the body of the map message.
Parameters:
name (input)
A String object encapsulating the name to identify the value in the
body of the map message.
322
Message Service Clients for C/C++ and .NET
C++ classes
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
setString – Set String
Interface:
xmsVOID setString(const String & name,
const String value);
Chapter 13. C++ classes
323
C++ classes
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
324
Message Service Clients for C/C++ and .NET
C++ classes
Message
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::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 85. For a list of the JMS defined properties of a
Message object, see “JMS defined properties of a message” on page 87. For a list of
the IBM defined properties of a Message object, see “IBM defined properties of a
message” on page 87.
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 “Acknowledging the
receipt of messages in a session” on page 43.
Parameters:
None
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
Chapter 13. C++ classes
325
C++ classes
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
created message depends on the type of message body. For more information, see
“The body of an XMS message” on page 89.
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
326
Message Service Clients for C/C++ and .NET
C++ classes
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:
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_NON_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_NON_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().
Chapter 13. C++ classes
327
C++ classes
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
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 with error code
XMS_E_NOT_SET 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
328
Message Service Clients for C/C++ and .NET
C++ classes
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.
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
with error code XMS_E_NOT_SET.
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
Chapter 13. C++ classes
329
C++ classes
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.
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
330
Message Service Clients for C/C++ and .NET
C++ classes
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.
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;
Chapter 13. C++ classes
331
C++ classes
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
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.
332
Message Service Clients for C/C++ and .NET
C++ classes
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:
XMSC_DELIVERY_PERSISTENT
XMSC_DELIVERY_NON_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.
Chapter 13. C++ classes
333
C++ classes
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
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);
334
Message Service Clients for C/C++ and .NET
C++ classes
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
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.
Chapter 13. C++ classes
335
C++ classes
Returns:
Void
Exceptions:
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
336
Message Service Clients for C/C++ and .NET
C++ classes
MessageConsumer
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::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 533.
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
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;
Chapter 13. C++ classes
337
C++ classes
Get a pointer to the message listener that is registered with the message consumer.
For more information about using message listeners, see “Using message listeners
in C++” on page 72.
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
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
338
Message Service Clients for C/C++ and .NET
C++ classes
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;
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:
Chapter 13. C++ classes
339
C++ classes
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 “Using message listeners
in C++” on page 72.
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:
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
340
Message Service Clients for C/C++ and .NET
C++ classes
MessageEOFException
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::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.
Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull
Chapter 13. C++ classes
341
C++ classes
MessageFormatException
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::MessageFormatException
XMS throws this exception if XMS encounters a message with a format that is not
valid.
Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull
342
Message Service Clients for C/C++ and .NET
C++ classes
MessageListener
Inheritance hierarchy:
None
An application uses a message listener to receive messages asynchronously.
Methods
onMessage – On Message
Interface:
virtual xmsVOID onMessage(const 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 “Using message listeners
in C++” on page 72.
Parameters:
message (input)
A pointer to the Message object.
Returns:
Void
Chapter 13. C++ classes
343
C++ classes
MessageNotReadableException
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::MessageNotReadableException
XMS throws this exception if an application attempts to read the body of a
message that is write-only.
Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull
344
Message Service Clients for C/C++ and .NET
C++ classes
MessageNotWritableException
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::MessageNotWritableException
XMS throws this exception if an application attempts to write to the body of a
message that is read-only.
Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull
Chapter 13. C++ classes
345
C++ classes
MessageProducer
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::MessageProducer
An application uses a message producer to send messages to a destination.
For a list of the XMS defined properties of a MessageProducer object, see
“Properties of MessageProducer” on page 533.
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_NON_PERSISTENT
For a real-time connection to a broker, the method always returns
XMSC_DELIVERY_NON_PERSISTENT.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
346
Message Service Clients for C/C++ and .NET
C++ classes
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
Chapter 13. C++ classes
347
C++ classes
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
348
Message Service Clients for C/C++ and .NET
C++ classes
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
const
const
const
Message & message,
xmsINT deliveryMode,
xmsINT priority,
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.
Parameters:
Chapter 13. C++ classes
349
C++ classes
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_NON_PERSISTENT
For a real-time connection to a broker, the value must be
XMSC_DELIVERY_NON_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:
v XMS_X_GENERAL_EXCEPTION
350
Message Service Clients for C/C++ and .NET
C++ classes
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
const
const
const
const
Destination & destination,
Message & message,
xmsINT deliveryMode,
xmsINT priority,
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_NON_PERSISTENT
For a real-time connection to a broker, the value must be
XMSC_DELIVERY_NON_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
Chapter 13. C++ classes
351
C++ classes
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_NON_PERSISTENT
For a real-time connection to a broker, the value must be
XMSC_DELIVERY_NON_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_NON_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
setDisableMsgTS – Set Disable Time Stamp Flag
Interface:
xmsVOID setDisableMsgTS(const xmsBOOL timeStampDisabled);
352
Message Service Clients for C/C++ and .NET
C++ classes
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.
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.
Chapter 13. C++ classes
353
C++ classes
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
354
Message Service Clients for C/C++ and .NET
C++ classes
ObjectMessage
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::Message
|
+----xms::ObjectMessage
An object message is a message whose body comprises a serialized Java or .NET
object.
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 68.
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.
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 error code
XMS_E_DATA_TRUNCATED.
2. If any other error occurs while attempting to get the object, XMS reports
the error but does not set the actualLength parameter.
Chapter 13. C++ classes
355
C++ classes
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,
getObjectProperty, getProperty, getShortProperty, getStringProperty,
setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty,
setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty,
setObjectProperty, setProperty, setShortProperty, setStringProperty
356
Message Service Clients for C/C++ and .NET
C++ classes
Property
Inheritance hierarchy:
None
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.
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);
Property(const String & propertyName,
const xmsSBYTE propertyValue);
Property(const String & propertyName,
const xmsCHAR16 propertyValue);
Property(const String & propertyName,
Chapter 13. C++ classes
357
C++ classes
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
Exceptions:
v XMS_X_GENERAL_EXCEPTION
358
Message Service Clients for C/C++ and .NET
C++ classes
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
Exceptions:
v XMS_X_GENERAL_EXCEPTION
Chapter 13. C++ classes
359
C++ classes
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 68.
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
360
Message Service Clients for C/C++ and .NET
C++ classes
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
getInt – Get Integer Property Value
Interface:
xmsINT getInt() const;
Chapter 13. C++ classes
361
C++ classes
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
getString – Get String Property Value
Interface:
String getString() const;
Get the string property value from the Property object.
362
Message Service Clients for C/C++ and .NET
C++ classes
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;
Determine whether the Property object is a null object.
Parameters:
None
Returns:
v xmsTRUE, if the Property object is a null object.
Chapter 13. C++ classes
363
C++ classes
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;
Get the property name from the Property object.
Parameters:
None
Returns:
A String object encapsulating the property name.
364
Message Service Clients for C/C++ and .NET
C++ classes
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
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:
Chapter 13. C++ classes
365
C++ classes
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.
Returns:
Void
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION
366
Message Service Clients for C/C++ and .NET
C++ classes
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.
Parameters:
propertyValue (input)
The long integer property value.
Returns:
Void
Thread context:
Any
Exceptions:
Chapter 13. C++ classes
367
C++ classes
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
368
Message Service Clients for C/C++ and .NET
C++ classes
PropertyContext
Inheritance hierarchy:
None
PropertyContext is an abstract superclass that contains methods that get and set
properties. These methods are inherited by other classes.
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 13. C++ classes
369
C++ classes
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 68.
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;
Get the value of the double precision floating point property identified by name.
370
Message Service Clients for C/C++ and .NET
C++ classes
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 13. C++ classes
371
C++ classes
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 68.
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
372
Message Service Clients for C/C++ and .NET
C++ classes
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 13. C++ classes
373
C++ classes
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:
374
Message Service Clients for C/C++ and .NET
C++ classes
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 13. C++ classes
375
C++ classes
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
376
Message Service Clients for C/C++ and .NET
C++ classes
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 13. C++ classes
377
C++ classes
setObjectProperty – Set Object Property
Interface:
xmsVOID setObjectProperty(const
const
const
const
String & propertyName,
xmsOBJECT_TYPE objectType,
xmsSBYTE *propertyValue,
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.
378
Message Service Clients for C/C++ and .NET
C++ classes
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 13. C++ classes
379
C++ classes
v XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION
380
Message Service Clients for C/C++ and .NET
C++ classes
QueueBrowser
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::QueueBrowser
An application uses a queue browser to browse messages on a queue without
removing them.
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
Returns:
The Iterator object.
Chapter 13. C++ classes
381
C++ classes
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.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
382
Message Service Clients for C/C++ and .NET
C++ classes
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
Chapter 13. C++ classes
383
C++ classes
Requestor
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::Requestor
An application uses a requestor to send a request message and then wait for, and
receive, the reply.
Constructors
Requestor – Create Requestor
Interface:
Requestor(const Session & session,
const Destination & destination);
Create a requestor.
Parameters:
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
384
Message Service Clients for C/C++ and .NET
C++ classes
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:
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:
Chapter 13. C++ classes
385
C++ classes
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
386
Message Service Clients for C/C++ and .NET
C++ classes
ResourceAllocationException
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::ResourceAllocationException
XMS throws this exception if XMS cannot allocate the resources required by a
method.
Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull
Chapter 13. C++ classes
387
C++ classes
SecurityException
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::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.
Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull
388
Message Service Clients for C/C++ and .NET
C++ classes
Session
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::Session
A session is a single threaded context for sending and receiving messages.
For a list of the XMS defined properties of a Session object, see “Properties of
Session” on page 533.
Methods
close – Close Session
Interface:
xmsVOID close();
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 “Deleting objects” on page 52.
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
Chapter 13. C++ classes
389
C++ classes
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
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
390
Message Service Clients for C/C++ and .NET
C++ classes
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:
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
Chapter 13. C++ classes
391
C++ classes
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
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
49.
Parameters:
topic (input)
A Destination object representing the topic. The topic must not be a
temporary topic.
392
Message Service Clients for C/C++ and .NET
C++ classes
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:
MessageConsumer createDurableSubscriber(const
const
const
const
Destination & topic,
String & subscriptionName;
String & messageSelector,
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
49.
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:
Chapter 13. C++ classes
393
C++ classes
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
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
394
Message Service Clients for C/C++ and .NET
C++ classes
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.
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.
Chapter 13. C++ classes
395
C++ classes
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.
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 48.
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 48.
Parameters:
None
Returns:
The Destination object representing the temporary topic.
Exceptions:
v XMS_X_GENERAL_EXCEPTION
396
Message Service Clients for C/C++ and .NET
C++ classes
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
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
Chapter 13. C++ classes
397
C++ classes
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 “Acknowledging the
receipt of messages in a session” on page 43.
Parameters:
None
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
398
Message Service Clients for C/C++ and .NET
C++ classes
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
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 “Acknowledging the receipt
of messages in a session” on page 43.
Parameters:
None
Returns:
Void
Exceptions:
v XMS_X_GENERAL_EXCEPTION
v XMS_X_ILLEGAL_STATE_EXCEPTION
Chapter 13. C++ classes
399
C++ classes
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
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,
400
Message Service Clients for C/C++ and .NET
C++ classes
setBooleanProperty, setByteProperty, setBytesProperty, setCharProperty,
setDoubleProperty, setFloatProperty, setIntProperty, setLongProperty,
setObjectProperty, setProperty, setShortProperty, setStringProperty
Chapter 13. C++ classes
401
C++ classes
StreamMessage
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::Message
|
+----xms::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 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 92.
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
402
Message Service Clients for C/C++ and .NET
C++ classes
readBytes – Read Bytes
Interface:
xmsINT readBytes(xmsSBYTE *buffer,
const xmsINT bufferLength,
xmsINT *returnedLength) const;
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
Chapter 13. C++ classes
403
C++ classes
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 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
404
Message Service Clients for C/C++ and .NET
C++ classes
v XMS_X_MESSAGE_EOF_EXCEPTION
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 68.
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
Chapter 13. C++ classes
405
C++ classes
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
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;
406
Message Service Clients for C/C++ and .NET
C++ classes
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
Chapter 13. C++ classes
407
C++ classes
writeBytes – Write Bytes
Interface:
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
408
Message Service Clients for C/C++ and .NET
C++ classes
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 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:
Chapter 13. C++ classes
409
C++ classes
v XMS_X_GENERAL_EXCEPTION
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:
410
Message Service Clients for C/C++ and .NET
C++ classes
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
Chapter 13. C++ classes
411
C++ classes
String
Inheritance hierarchy:
None
A String object encapsulates a string.
This class is a helper class.
Constructors
String – Create String
Interface:
String();
Create a String object that encapsulates a null string.
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:
412
Message Service Clients for C/C++ and .NET
C++ classes
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();
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.
Chapter 13. C++ classes
413
C++ classes
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;
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 68.
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.
414
Message Service Clients for C/C++ and .NET
C++ classes
Returns:
Void
Thread context:
Any
Exceptions:
v XMS_X_GENERAL_EXCEPTION
isNull – Check Whether Null
Interface:
xmsBOOL isNull() const;
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
Chapter 13. C++ classes
415
C++ classes
TextMessage
Inheritance hierarchy:
xms::PropertyContext
|
+----xms::Message
|
+----xms::TextMessage
A text message is a message whose body comprises a string.
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.
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,
416
Message Service Clients for C/C++ and .NET
C++ classes
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
Chapter 13. C++ classes
417
C++ classes
TransactionInProgressException
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::TransactionInProgressException
XMS throws this exception if an application requests an operation that is not valid
because a transaction is in progress.
Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull
418
Message Service Clients for C/C++ and .NET
C++ classes
TransactionRolledBackException
Inheritance hierarchy:
std::exception
|
+----xms::Exception
|
+----xms::TransactionRolledBackException
XMS throws this exception if an application calls Session.commit() to commit the
current transaction, but the transaction is subsequently rolled back.
Inherited methods
The following methods are inherited from the Exception class:
dump, getErrorCode, getErrorData, getErrorString, getHandle, getJMSException,
getLinkedException, isNull
Chapter 13. C++ classes
419
C++ classes
420
Message Service Clients for C/C++ and .NET
Chapter 14. .NET interfaces
This chapter documents the .NET class interfaces and their properties and
methods. Table 30 summarizes all the interfaces, which are defined within the
IBM.XMS namespace.
Table 30. Summary of the .NET class interfaces
Interface
Description
IBytesMessage
A bytes message is a message whose body comprises a
stream of bytes.
IConnection
A Connection object represents an application’s active
connection to a broker.
IConnectionFactory
An application uses a connection factory to create a
connection.
IConnectionMetaData
A ConnectionMetaData object provides information
about a connection.
IDestination
A destination is where an application sends messages,
or it is a source from which an application receives
messages, or both.
ExceptionListener (delegate)
An application uses an exception listener to be notified
asynchronously of a problem with a connection.
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.
InitialContext
An application uses an InitialContext object to create
objects from object definitions that are retrieved from a
repository of administered objects.
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.
InvalidDestinationException
XMS throws this exception if an application specifies a
destination that is not valid.
InvalidSelectorException
XMS throws this exception if an application provides a
message selector expression whose syntax is not valid.
IMapMessage
A map message is a message whose body comprises a
set of name-value pairs, where each value has an
associated data type.
IMessage
A Message object represents a message that an
application sends or receives. IMessage is a superclass
for the message classes such as IMapMessage
IMessageConsumer
An application uses a message consumer to receive
messages sent to a destination.
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.
MessageFormatException
XMS throws this exception if XMS encounters a
message with a format that is not valid.
© Copyright IBM Corp. 2005
421
.NET interfaces
Table 30. Summary of the .NET class interfaces (continued)
Interface
Description
MessageListener (delegate)
An application uses a message listener to receive
messages asynchronously.
MessageNotReadableException
XMS throws this exception if an application attempts to
read the body of a message that is write-only.
MessageNotWritableException
XMS throws this exception if an application attempts to
write to the body of a message that is read-only.
IMessageProducer
An application uses a message producer to send
messages to a destination.
IObjectMessage
An object message is a message whose body comprises
a serialized Java or .NET object.
IPropertyContext
PropertyContext is an abstract superclass that
encapsulates methods that get and set properties. These
methods are inherited by other classes.
IQueueBrowser
An application uses a queue browser to browse
messages on a queue without removing them.
Requestor
An application uses a requestor to send a request
message and then wait for, and receive, the reply.
ResourceAllocationException
XMS throws this exception if XMS cannot allocate the
resources required by a method.
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.
ISession
A session is a single threaded context for sending and
receiving messages.
IStreamMessage
A stream message is a message whose body comprises
a stream of values, where each value has an associated
data type.
ITextMessage
A text message is a message whose body comprises a
string.
TransactionInProgressException
XMS throws this exception if an application requests an
operation that is not valid because a transaction is in
progress.
TransactionRolledBackException
XMS throws this exception if an application calls
Session.commit() to commit the current transaction, but
the transaction is subsequently rolled back.
XMSC
For .NET, XMS property names and values are defined
in this class as public constants. For further details, see
the reference information relating to XMS properties.
XMSException
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
XMSException object is just one type of exception.
However, the XMSException class is a superclass of the
other XMS exception classes. XMS throws an
XMSException object in situations where none of the
other types of exception are appropriate.
422
Message Service Clients for C/C++ and .NET
.NET interfaces
Table 30. Summary of the .NET class interfaces (continued)
Interface
Description
XMSFactoryFactory
If an application is not using administered objects, use
this class to create connection factories, queues and
topics.
Chapter 14. .NET interfaces
423
.NET interfaces
IBytesMessage
A bytes message is a message whose body comprises a stream of bytes.
Inheritance hierarchy:
IBM.XMS.IPropertyContext
|
+----IBM.XMS.IMessage
|
+----IBM.XMS.IBytesMessage
.NET properties
BodyLength – Get Body Length
Interface:
Int64 BodyLength
{
get;
}
Get the length of the body of the message in bytes when the body of the message
is read-only.
The value returned is the length of the whole body regardless of where the cursor
for reading the message is currently positioned.
Exceptions:
v XMSException
v MessageNotReadableException
Methods
ReadBoolean – Read Boolean Value
Interface:
Boolean ReadBoolean();
Read a boolean value from the bytes message stream.
Parameters:
None
Returns:
The boolean value that is read.
Exceptions:
v XMSException
v MessageNotReadableException
v MessageEOFException
ReadSignedByte – Read Byte
Interface:
Int16
424
ReadSignedByte();
Message Service Clients for C/C++ and .NET
.NET interfaces
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 XMSException
v MessageNotReadableException
v MessageEOFException
ReadBytes – Read Bytes
Interface:
Int32
ReadBytes(Byte[] array);
Int32
ReadBytes(Byte[] array, Int32 length);
Read an array of bytes from the bytes message stream starting from the current
position of the cursor.
Parameters:
array (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 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.
length (input)
The length of the buffer in bytes
Returns:
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.
Exceptions:
v XMSException
v MessageNotReadableException
v MessageEOFException
Chapter 14. .NET interfaces
425
.NET interfaces
ReadChar – Read Character
Interface:
Char
ReadChar();
Read the next 2 bytes from the bytes message stream as a character.
Parameters:
None
Returns:
The character that is read.
Exceptions:
v XMSException
v MessageNotReadableException
v MessageEOFException
ReadDouble – Read Double Precision Floating Point Number
Interface:
Double
ReadDouble();
Read the next 8 bytes from the bytes message stream as a double precision floating
point number.
Parameters:
None
Returns:
The double precision floating point number that is read.
Exceptions:
v XMSException
v MessageNotReadableException
v MessageEOFException
ReadFloat – Read Floating Point Number
Interface:
Single
ReadFloat();
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 XMSException
v MessageNotReadableException
v MessageEOFException
426
Message Service Clients for C/C++ and .NET
.NET interfaces
ReadInt – Read Integer
Interface:
Int32
ReadInt();
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 XMSException
v MessageNotReadableException
v MessageEOFException
ReadLong – Read Long Integer
Interface:
Int64
ReadLong();
Read the next 8 bytes from the bytes message stream as a signed 64-bit integer.
Parameters:
None
Returns:
The long integer that is read.
Exceptions:
v XMSException
v MessageNotReadableException
v MessageEOFException
ReadShort – Read Short Integer
Interface:
Int16
ReadShort();
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 XMSException
v MessageNotReadableException
v MessageEOFException
Chapter 14. .NET interfaces
427
.NET interfaces
ReadByte – Read Unsigned Byte
Interface:
Byte
ReadByte();
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 XMSException
v MessageNotReadableException
v MessageEOFException
ReadUnsignedShort – Read Unsigned Short Integer
Interface:
Int32
ReadUnsignedShort();
Read the next 2 bytes from the bytes message stream as an unsigned 16-bit integer.
Parameters:
None
Returns:
The unsigned short integer that is read.
Exceptions:
v XMSException
v MessageNotReadableException
v MessageEOFException
ReadUTF – Read UTF String
Interface:
String
ReadUTF();
Read a string, encoded in UTF-8, from the bytes message stream.
Parameters:
None
Returns:
A String object encapsulating the string that is read.
Exceptions:
v XMSException
v MessageNotReadableException
v MessageEOFException
428
Message Service Clients for C/C++ and .NET
.NET interfaces
Reset – Reset
Interface:
void Reset();
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 XMSException
v MessageNotReadableException
WriteBoolean – Write Boolean Value
Interface:
void
WriteBoolean(Boolean value);
Write a boolean value to the bytes message stream.
Parameters:
value (input)
The boolean value to be written.
Returns:
Void
Exceptions:
v XMSException
v MessageNotWritableException
WriteByte – Write Byte
Interface:
void WriteByte(Byte value);
void WriteSignedByte(Int16 value);
Write a byte to the bytes message stream.
Parameters:
value (input)
The byte to be written.
Returns:
Void
Exceptions:
v XMSException
v MessageNotWritableException
Chapter 14. .NET interfaces
429
.NET interfaces
WriteBytes – Write Bytes
Interface:
void
WriteBytes(Byte[] value);
Write an array of bytes to the bytes message stream.
Parameters:
value (input)
The array of bytes to be written.
Returns:
Void
Exceptions:
v XMSException
v MessageNotWritableException
WriteBytes – Write Partial Bytes Array
Interface:
void
WriteBytes(Byte[] value, int offset, int length);
Write a partial array of bytes to the bytes message stream, as defined by the
specified length.
Parameters:
value (input)
The array of bytes to be written.
offset (input)
The starting point for the array of bytes to be written.
length (input)
The number of bytes to write.
Returns:
Void
Exceptions:
v XMSException
v MessageNotWritableException
WriteChar – Write Character
Interface:
void
WriteChar(Char 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
430
Message Service Clients for C/C++ and .NET
.NET interfaces
Exceptions:
v XMSException
v MessageNotWritableException
WriteDouble – Write Double Precision Floating Point Number
Interface:
void
WriteDouble(Double 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 XMSException
v MessageNotWritableException
WriteFloat – Write Floating Point Number
Interface:
void
WriteFloat(Single 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 XMSException
v MessageNotWritableException
WriteInt – Write Integer
Interface:
void
WriteInt(Int32 value);
Write an integer to the bytes message stream as 4 bytes, high order byte first.
Parameters:
value (input)
The integer to be written.
Chapter 14. .NET interfaces
431
.NET interfaces
Returns:
Void
Exceptions:
v XMSException
v MessageNotWritableException
WriteLong – Write Long Integer
Interface:
void
WriteLong(Int64 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 XMSException
v MessageNotWritableException
WriteObject – Write Object
Interface:
void
WriteObject(Object value);
Write the specified object into the byte message stream.
Parameters:
value (input)
The object to be written, which must be a reference to a primitive
type.
Returns:
Void
Exceptions:
v XMSException
v MessageNotWritableException
WriteShort – Write Short Integer
Interface:
void
WriteShort(Int16 value);
Write a short integer to the bytes message stream as 2 bytes, high order byte first.
Parameters:
432
Message Service Clients for C/C++ and .NET
.NET interfaces
value (input)
The short integer to be written.
Returns:
Void
Exceptions:
v XMSException
v MessageNotWritableException
WriteUTF – Write UTF String
Interface:
void
WriteUTF(String value);
Write a string, encoded in UTF-8, to the bytes message stream.
Parameters:
value (input)
A String object encapsulating the string to be written.
Returns:
Void
Exceptions:
v XMSException
v MessageNotWritableException
Inherited properties and methods
The following properties are inherited from the IMessage interface:
JMSCorrelationID, JMSDeliveryMode, JMSDestination, JMSExpiration,
JMSMessageID, JMSPriority, JMSRedelivered, JMSReplyTo, JMSTimestamp,
JMSType, Properties
The following methods are inherited from the IMessage interface:
clearBody, clearProperties, PropertyExists
The following methods are inherited from the IPropertyContext interface:
GetBooleanProperty, GetByteProperty, GetBytesProperty, GetCharProperty,
GetDoubleProperty, GetFloatProperty, GetIntProperty, GetLongProperty,
GetObjectProperty, GetShortProperty, GetStringProperty, SetBooleanProperty,
SetByteProperty, SetBytesProperty, SetCharProperty, SetDoubleProperty,
SetFloatProperty, SetIntProperty, SetLongProperty, SetObjectProperty,
SetShortProperty, SetStringProperty
Chapter 14. .NET interfaces
433
.NET interfaces
IConnection
A Connection object represents an application’s active connection to a broker.
Inheritance hierarchy:
IBM.XMS.IPropertyContext
|
+----IBM.XMS.IConnection
For a list of the XMS defined properties of a Connection object, see “Properties of
Connection” on page 527.
.NET properties
ClientID – Get and Set Client ID
Interface:
String ClientID
{
get;
set;
}
Get the client identifier for the connection.
Set the client identifier for the connection.
The client identifier can either be preconfigured by the administrator in a
ConnectionFactory, or assigned by setting ClientID.
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 sets 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 set a client identifier after
this point, the call throws exception IllegalStateException.
This property is not valid for a real-time connection to a broker.
Exceptions:
v XMSException
v IllegalStateException
v InvalidClientIDException
ExceptionListener – Get and Set Exception Listener
Interface:
ExceptionListener ExceptionListener
{
get;
set;
}
Get the exception listener that is registered with the connection.
Register an exception listener with the connection.
434
Message Service Clients for C/C++ and .NET
.NET interfaces
If no exception listener is registered with the connection, the method returns null.
If an exception listener is already registered with the connection, you can cancel
the registration by specifying a null instead of the exception listener.
For more information about using exception listeners, see “Using message and
exception listeners in .NET” on page 81.
Exceptions:
v XMSException
MetaData – Get Metadata
Interface:
IConnectionMetaData MetaData
{
get;
}
Get the metadata for the connection.
Exceptions:
v XMSException
Methods
Close – Close Connection
Interface:
void
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 XMSException
CreateSession – Create Session
Interface:
ISession CreateSession(Boolean transacted,
AcknowledgeMode acknowledgeMode);
Create a session.
Parameters:
Chapter 14. .NET interfaces
435
.NET interfaces
transacted (input)
The value True means that the session is transacted. The value
False means that the session is not transacted.
For a real-time connection to a broker, the value must be False.
acknowledgeMode (input)
Indicates how messages received by an application are
acknowledged. The value must be one of the following from the
AcknowledgeMode enumerator:
AcknowledgeMode.AutoAcknowledge
AcknowledgeMode.ClientAcknowledge
AcknowledgeMode.DupsOkAcknowledge
For a real-time connection to a broker, the value must be
AcknowledgeMode.AutoAcknowledge or
AcknowledgeMode.DupsOkAcknowledge
This parameter is ignored if the session is transacted. For more
information about acknowledgement modes, see “Acknowledging
the receipt of messages in a session” on page 43.
Returns:
The Session object.
Exceptions:
v XMSException
Start – Start Connection
Interface:
void
Start();
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 XMSException
Stop – Stop Connection
Interface:
void
Stop();
Stop the delivery of incoming messages for the connection. The call is ignored if
the connection is already stopped.
Parameters:
None
436
Message Service Clients for C/C++ and .NET
.NET interfaces
Returns:
Void
Exceptions:
v XMSException
Inherited properties and methods
The following methods are inherited from the IPropertyContext interface:
GetBooleanProperty, GetByteProperty, GetBytesProperty, GetCharProperty,
GetDoubleProperty, GetFloatProperty, GetIntProperty, GetLongProperty,
GetObjectProperty, GetShortProperty, GetStringProperty, SetBooleanProperty,
SetByteProperty, SetBytesProperty, SetCharProperty, SetDoubleProperty,
SetFloatProperty, SetIntProperty, SetLongProperty, SetObjectProperty,
SetShortProperty, SetStringProperty
Chapter 14. .NET interfaces
437
.NET interfaces
IConnectionFactory
An application uses a connection factory to create a connection.
Inheritance hierarchy:
IBM.XMS.IPropertyContext
|
+----IBM.XMS.IConnectionFactory
For a list of the XMS defined properties of a ConnectionFactory object, see
“Properties of ConnectionFactory” on page 528.
Methods
CreateConnection – Create Connection Factory (using the default
user identity)
Interface:
IConnection CreateConnection();
Create a connection factory with the default properties.
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.
Parameters:
None
Exceptions:
v XMSException
CreateConnection – Create Connection (using a specified user
identity)
Interface:
IConnection CreateConnection(String userId, 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
authenticate the application. If you provide a null, an attempt is
made to create the connection without authentication.
438
Message Service Clients for C/C++ and .NET
.NET interfaces
password (input)
A String object encapsulating the password to be used to
authenticate the application. If you provide a null, an attempt is
made to create the connection without authentication.
Returns:
The Connection object.
Exceptions:
v XMSException
v XMS_X_SECURITY_EXCEPTION
Inherited properties and methods
The following methods are inherited from the IPropertyContext interface:
GetBooleanProperty, GetByteProperty, GetBytesProperty, GetCharProperty,
GetDoubleProperty, GetFloatProperty, GetIntProperty, GetLongProperty,
GetObjectProperty, GetShortProperty, GetStringProperty, SetBooleanProperty,
SetByteProperty, SetBytesProperty, SetCharProperty, SetDoubleProperty,
SetFloatProperty, SetIntProperty, SetLongProperty, SetObjectProperty,
SetShortProperty, SetStringProperty
Chapter 14. .NET interfaces
439
.NET interfaces
IConnectionMetaData
A ConnectionMetaData object provides information about a connection.
Inheritance hierarchy:
IBM.XMS.IPropertyContext
|
+----IBM.XMS.IConnectionMetaData
For a list of the XMS defined properties of a ConnectionMetaData object, see
“Properties of ConnectionMetaData” on page 530.
.NET properties
JMSXPropertyNames – Get JMS Defined Message Properties
Interface:
System.Collections.IEnumerator JMSXPropertyNames
{
get;
}
Return an enumeration of the names of the JMS defined message properties
supported by the connection.
JMS defined message properties are not supported by a real-time connection to a
broker.
Exceptions:
v XMSException
Inherited properties and methods
The following methods are inherited from the IPropertyContext interface:
GetBooleanProperty, GetByteProperty, GetBytesProperty, GetCharProperty,
GetDoubleProperty, GetFloatProperty, GetIntProperty, GetLongProperty,
GetObjectProperty, GetShortProperty, GetStringProperty, SetBooleanProperty,
SetByteProperty, SetBytesProperty, SetCharProperty, SetDoubleProperty,
SetFloatProperty, SetIntProperty, SetLongProperty, SetObjectProperty,
SetShortProperty, SetStringProperty
440
Message Service Clients for C/C++ and .NET
.NET interfaces
IDestination
A destination is where an application sends messages, or it is a source from which
an application receives messages, or both.
Inheritance hierarchy:
IBM.XMS.IPropertyContext
|
+----IBM.XMS.IDestination
For a list of the XMS defined properties of a Destination object, see “Properties of
Destination” on page 530.
.NET properties
Name – Get Destination Name
Interface:
String Name
{
get;
}
Get the name of the destination. The name is a string encapsulating either the
name of a queue or the name of a topic.
Exceptions:
v XMSException
TypeId – Get Destination Type
Interface:
DestinationType TypeId
{
get;
}
Get the type of the destination. The type of the destination is one of the following
values:
DestinationType.Queue
DestinationType.Topic
Exceptions:
v XMSException
Inherited properties and methods
The following methods are inherited from the IPropertyContext interface:
GetBooleanProperty, GetByteProperty, GetBytesProperty, GetCharProperty,
GetDoubleProperty, GetFloatProperty, GetIntProperty, GetLongProperty,
GetObjectProperty, GetShortProperty, GetStringProperty, SetBooleanProperty,
SetByteProperty, SetBytesProperty, SetCharProperty, SetDoubleProperty,
SetFloatProperty, SetIntProperty, SetLongProperty, SetObjectProperty,
SetShortProperty, SetStringProperty
Chapter 14. .NET interfaces
441
.NET interfaces
ExceptionListener
Inheritance hierarchy:
None
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.
Delegate
ExceptionListener – Exception Listener
Interface:
public delegate void ExceptionListener(Exception ex)
Notify the application of a problem with a connection.
Methods that implement this delegate can be registered with the connection.
For more information about using exception listeners, see “Using message and
exception listeners in .NET” on page 81.
Parameters:
exception (input)
A pointer to an exception created by XMS.
Returns:
Void
442
Message Service Clients for C/C++ and .NET
.NET interfaces
IllegalStateException
Inheritance hierarchy:
IBM.XMS.XMSException
|
+----IBM.XMS.Exception
|
+----IBM.XMS.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.
Inherited properties and methods
The following methods are inherited from the XMSException interface:
GetErrorCode, GetLinkedException
Chapter 14. .NET interfaces
443
.NET interfaces
InitialContext
An application uses an InitialContext object to create objects from object definitions
that are retrieved from a repository of administered objects.
Inheritance hierarchy:
None
.NET properties
Environment - Get the environment
Interface:
Hashtable Environment
{
get;
}
Get the environment.
Exceptions:
v Exceptions are specific to the directory service being used.
Constructors
InitialContext – Create Initial Context
Interface:
InitialContext(Hashtable env);
Create an InitialContext object.
Parameters:
The information required to establish a connection to the repository of
administered objects is provided to the constructor in an environment
Hashtable.
Exceptions:
v XMSException
Methods
AddToEnvironment - Add a New Property to the Environment
Interface:
Object AddToEnvironment(String propName, Object propVal);
Add a new property to the environment.
Parameters:
propName (input)
A String object encapsulating the name of the property to be
added.
propVal (input)
The value of the property to be added.
Returns:
The old value of the property.
444
Message Service Clients for C/C++ and .NET
.NET interfaces
Exceptions:
v Exceptions are specific to the directory service being used.
Close - Close this context
Interface:
void Close()
Close this context.
Parameters:
None
Returns:
None
Exceptions:
v Exceptions are specific to the directory service being used.
Lookup – Look Up Object in Initial Context
Interface:
Object Lookup(String name);
Create an object from an object definition that is retrieved from the repository of
administered objects.
Parameters:
name (input)
A String object encapsulating the name of the administered object
to be retrieved. The name can be either a simple name or a
complex name. For further details, see “Retrieval of administered
objects” on page 101.
Returns:
Either an IConnectionFactory or an IDestination, depending on the type of
object being retrieved. If the function can access the directory, but cannot
find the required object, a null is returned.
Exceptions:
v Exceptions are specific to the directory service being used.
RemoveFromEnvironment - Remove a Property from the
Environment
Interface:
Object RemoveFromEnvironment(String propName);
Remove a property from the environment.
Parameters:
propName (input)
A String object encapsulating the name of the property to be
removed.
Returns:
The object that has been removed.
Exceptions:
v Exceptions are specific to the directory service being used.
Chapter 14. .NET interfaces
445
.NET interfaces
InvalidClientIDException
Inheritance hierarchy:
IBM.XMS.XMSException
|
+----IBM.XMS.XMSException
|
+----IBM.XMS.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.
Inherited properties and methods
The following methods are inherited from the XMSException interface:
GetErrorCode, GetLinkedException
446
Message Service Clients for C/C++ and .NET
.NET interfaces
InvalidDestinationException
Inheritance hierarchy:
IBM.XMS.XMSException
|
+----IBM.XMS.XMSException
|
+----IBM.XMS.InvalidDestinationException
XMS throws this exception if an application specifies a destination that is not valid.
Inherited properties and methods
The following methods are inherited from the XMSException interface:
GetErrorCode, GetLinkedException
Chapter 14. .NET interfaces
447
.NET interfaces
InvalidSelectorException
Inheritance hierarchy:
IBM.XMS.XMSException
|
+----IBM.XMS.XMSException
|
+----IBM.XMS.InvalidSelectorException
XMS throws this exception if an application provides a message selector expression
whose syntax is not valid.
Inherited properties and methods
The following methods are inherited from the XMSException interface:
GetErrorCode, GetLinkedException
448
Message Service Clients for C/C++ and .NET
.NET interfaces
IMapMessage
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:
IBM.XMS.IPropertyContext
|
+----IBM.XMS.IMessage
|
+----IBM.XMS.IMapMessage
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 91.
.NET properties
MapNames – Get Map Names
Interface:
System.Collections.IEnumerator MapNames
{
get;
}
Get an enumeration of the names in the body of the map message.
Exceptions:
v XMSException
Methods
GetBoolean – Get Boolean Value
Interface:
Boolean GetBoolean(String name);
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 XMSException
GetByte – Get Byte
Interface:
Byte
GetByte(String name);
Int16
GetSignedByte(String name);
Chapter 14. .NET interfaces
449
.NET interfaces
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 XMSException
GetBytes – Get Bytes
Interface:
Byte[]
GetBytes(String name);
Get the array of bytes identified by name from the body of the map message.
Parameters:
name (input)
A String object encapsulating the name that identifies the array of
bytes.
Returns:
The number of bytes in the array.
Exceptions:
v XMSException
GetChar – Get Character
Interface:
Char
GetChar(String name);
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 XMSException
GetDouble – Get Double Precision Floating Point Number
Interface:
Double
GetDouble(String name);
Get the double precision floating point number identified by name from the body
of the map message.
450
Message Service Clients for C/C++ and .NET
.NET interfaces
Parameters:
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 XMSException
GetFloat – Get Floating Point Number
Interface:
Single
GetFloat(String name);
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 XMSException
GetInt – Get Integer
Interface:
Int32
GetInt(String name);
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 XMSException
GetLong – Get Long Integer
Interface:
Int64
GetLong(String name);
Get the long integer identified by name from the body of the map message.
Chapter 14. .NET interfaces
451
.NET interfaces
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 XMSException
GetObject – Get Object
Interface:
Object
GetObject(String name);
Get a reference to the value of a name-value pair, from the body of the map
message. The name-value pair is identified by name.
Parameters:
name (input)
A String object encapsulating the name of the name-value pair.
Returns:
The value, which is one of the following object types:
Boolean
Byte
Byte[]
Char
Double
Single
Int32
Int64
Int16
String
Exceptions:
XMSException
GetShort – Get Short Integer
Interface:
Int16
GetShort(String name);
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.
452
Message Service Clients for C/C++ and .NET
.NET interfaces
Exceptions:
v XMSException
GetString – Get String
Interface:
String
GetString(String name);
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 XMSException
ItemExists – Check Name-Value Pair Exists
Interface:
Boolean ItemExists(String name);
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 True, if the body of the map message contains a name-value pair with
the specified name.
v False, if the body of the map message does not contain a name-value
pair with the specified name.
Exceptions:
v XMSException
SetBoolean – Set Boolean Value
Interface:
void
SetBoolean(String name, Boolean value);
Set a boolean value in the body of the map message.
Parameters:
Chapter 14. .NET interfaces
453
.NET interfaces
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 XMSException
SetByte – Set Byte
Interface:
void
void
SetByte(String name, Byte value);
SetSignedByte(String name, Int16 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 XMSException
SetBytes – Set Bytes
Interface:
void
SetBytes(String name, Byte[] value);
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.
Returns:
Void
Exceptions:
v XMSException
454
Message Service Clients for C/C++ and .NET
.NET interfaces
SetChar – Set Character
Interface:
void
SetChar(String name, Char value);
Set a 2-byte character in the body of the map message.
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 XMSException
SetDouble – Set Double Precision Floating Point Number
Interface:
void
SetDouble(String name, Double 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 XMSException
SetFloat – Set Floating Point Number
Interface:
void
SetFloat(String name, Single 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.
Chapter 14. .NET interfaces
455
.NET interfaces
Returns:
Void
Exceptions:
v XMSException
SetInt – Set Integer
Interface:
void
SetInt(String name, Int32 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 XMSException
SetLong – Set Long Integer
Interface:
void
SetLong(String name, Int64 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 XMSException
SetObject – Set Object
Interface:
void
SetObject(String name, Object value);
Set a value, which must be an XMS primitive type, in the body of the map
message.
456
Message Service Clients for C/C++ and .NET
.NET interfaces
Parameters:
name (input)
A String object encapsulating the name to identify the value in the
body of the map message.
value (input)
An array of bytes containing the value to be set.
Returns:
Void
Exceptions:
v XMSException
SetShort – Set Short Integer
Interface:
void
SetShort(String name, Int16 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 XMSException
SetString – Set String
Interface:
void
SetString(String name, 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 XMSException
Chapter 14. .NET interfaces
457
.NET interfaces
Inherited properties and methods
The following properties are inherited from the IMessage interface:
JMSCorrelationID, JMSDeliveryMode, JMSDestination, JMSExpiration,
JMSMessageID, JMSPriority, JMSRedelivered, JMSReplyTo, JMSTimestamp,
JMSType, Properties
The following methods are inherited from the IMessage interface:
clearBody, clearProperties, PropertyExists
The following methods are inherited from the IPropertyContext interface:
GetBooleanProperty, GetByteProperty, GetBytesProperty, GetCharProperty,
GetDoubleProperty, GetFloatProperty, GetIntProperty, GetLongProperty,
GetObjectProperty, GetShortProperty, GetStringProperty, SetBooleanProperty,
SetByteProperty, SetBytesProperty, SetCharProperty, SetDoubleProperty,
SetFloatProperty, SetIntProperty, SetLongProperty, SetObjectProperty,
SetShortProperty, SetStringProperty
458
Message Service Clients for C/C++ and .NET
.NET interfaces
IMessage
A Message object represents a message that an application sends or receives.
IMessage is a superclass for the message classes such as IMapMessage.
Inheritance hierarchy:
IBM.XMS.IPropertyContext
|
+----IBM.XMS.IMessage
For a list of the JMS message header fields in a Message object, see “Header fields
in an XMS message” on page 85. For a list of the JMS defined properties of a
Message object, see “JMS defined properties of a message” on page 87. For a list of
the IBM defined properties of a Message object, see “IBM defined properties of a
message” on page 87.
Messages are deleted by the garbage collector. When a message is deleted, this
frees the resources it was using.
.NET properties
GetJMSCorrelationID – Get and Set JMSCorrelationID
Interface:
String JMSCorrelationID
{
get;
set;
}
Get the correlation identifier of the message as a String object.
Set the correlation identifier of the message as a String object.
Exceptions:
v XMSException
JMSDeliveryMode – Get and Set JMSDeliveryMode
Interface:
DeliveryMode JMSDeliveryMode
{
get;
set;
}
Get the delivery mode of the message.
Set the delivery mode of the message.
The delivery mode of the message is one of the following values:
DeliveryMode.Persistent
DeliveryMode.NonPersistent
For a newly created message that has not been sent, the delivery mode is
DeliveryMode.Persistent, except for a real-time connection to a broker for which
the delivery mode is DeliveryMode.NonPersistent. For a message that has been
Chapter 14. .NET interfaces
459
.NET interfaces
received, the method returns the delivery mode that was set by the
IMessageProducer.send() call when the message was sent unless the receiving
application changes the delivery mode by setting JMSDeliveryMode.
Exceptions:
v XMSException
JMSDestination – Get and Set JMSDestination
Interface:
IDestination JMSDestination
{
get;
set;
}
Get the destination of the message.
Set the destination of the message.
The destination is set by the IMessageProducer.send() call when the message is
sent. The value of JMSDestination is ignored. However, you can use
JMSDestination to change the destination of a message that has been received.
For a newly created message that has not been sent, the method returns a null
Destination object, unless the sending application sets a destination by setting
JMSDestination. For a message that has been received, the method returns a
Destination object for the destination that was set by the IMessageProducer.send()
call when the message was sent unless the receiving application changes the
destination by setting JMSDestination.
Exceptions:
v XMSException
JMSExpiration – Get and Set JMSExpiration
Interface:
Int64 JMSExpiration
{
get;
set;
}
Get the expiration time of the message.
Set the expiration time of the message.
The expiration time is set by the IMessageProducer.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.
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 setting JMSExpiration.
For a message that has been received, the method returns the expiration time that
460
Message Service Clients for C/C++ and .NET
.NET interfaces
was set by the IMessageProducer.send() call when the message was sent unless the
receiving application changes the expiration time by setting JMSExpiration.
If the time to live is 0, the IMessageProducer.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.
Exceptions:
v XMSException
JMSMessageID – Get and Set JMSMessageID
Interface:
String JMSMessageID
{
get;
set;
}
Get the message identifier of the message as a string object encapsulating the
message identifier.
Set the message identifier of the message as a string object encapsulating the
message identifier.
The message identifier is set by the IMessageProducer.send() call when the
message is sent. For a message that has been received, the method returns the
message identifier that was set by the IMessageProducer.send() call when the
message was sent unless the receiving application changes the message identifier
by setting JMSMessageID.
If the message has no message identifier, the method returns a null.
Exceptions:
v XMSException
JMSPriority – Get and Set JMSPriority
Interface:
Int32 JMSPriority
{
get;
set;
}
Get the priority of the message.
Set the priority of the message.
The priority is set by the IMessageProducer.send() call when the message is sent.
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 setting JMSPriority. For a message
Chapter 14. .NET interfaces
461
.NET interfaces
that has been received, the method returns the priority that was set by the
IMessageProducer.send() call when the message was sent unless the receiving
application changes the priority by setting JMSPriority.
Exceptions:
v XMSException
JMSRedelivered – Get and Set JMSRedelivered
Interface:
Boolean JMSRedelivered
{
get;
set;
}
Get an indication of whether the message is being re-delivered. The indication is
set by the IMessageConsumer.receive() call when the message is received.
Indicate whether the message is being re-delivered.
This property has the following values:
v True, if the message is being re-delivered.
v False, if the message is not being re-delivered.
For a real-time connection to a broker, the value is always False.
An indication of re-delivery set by JMSRedelivered before the message is sent is
ignored by the IMessageProducer.send() call when the message is sent, and is
ignored and replaced by the IMessageConsumer.receive() call when the message is
received. However, you can useJMSRedelivered to change the indication for a
message that has been received.
Exceptions:
v XMSException
JMSReplyTo – Get and Set JMSReplyTo
Interface:
IDestination JMSReplyTo
{
get;
set;
}
Get the destination where a reply to the message is to be sent.
Set the destination where a reply to the message is to be sent.
The value of this property is 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 XMSException
462
Message Service Clients for C/C++ and .NET
.NET interfaces
JMSTimestamp – Get and Set JMSTimestamp
Interface:
Int64 JMSTimestamp
{
get;
set;
}
Get the time when the message was sent.
Set the time when the message is sent.
The time stamp is set by the IMessageProducer.send() call when the message is
sent and is expressed in milliseconds since 00:00:00 GMT on the 1 January 1970.
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 setting JMSTimestamp. For a
message that has been received, the method returns the time stamp that was set by
the IMessageProducer.send() call when the message was sent unless the receiving
application changes the time stamp by setting JMSTimestamp.
Exceptions:
v XMSException
Notes:
1. If the time stamp is undefined, the method returns 0 but throws no
exception.
JMSType – Get and Set JMSType
Interface:
String JMSType
{
get;
set;
}
Get the type of the message.
Set the type of the message.
The value of JMSType is a string encapsulating the type of the message. If data
conversion is required, this is the type after conversion.
Exceptions:
v XMSException
PropertyNames – Get Properties
Interface:
System.Collections.IEnumerator PropertyNames
{
get;
}
Chapter 14. .NET interfaces
463
.NET interfaces
Get an enumeration of the names properties of the message.
Exceptions:
v XMSException
Methods
Acknowledge – Acknowledge
Interface:
void
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
AcknowledgeMode.ClientAcknowledge. 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 “Acknowledging the
receipt of messages in a session” on page 43.
Parameters:
None
Returns:
Void
Exceptions:
v XMSException
v IllegalStateException
ClearBody – Clear Body
Interface:
void
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
created message depends on the type of message body. For more information, see
“The body of an XMS message” on page 89.
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
464
Message Service Clients for C/C++ and .NET
.NET interfaces
Exceptions:
v XMSException
ClearProperties – Clear Properties
Interface:
void
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 XMSException
PropertyExists – Check Property Exists
Interface:
Boolean PropertyExists(String propertyName);
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 True, if the message has a property with the specified name.
v False, if the message does not have a property with the specified name.
Exceptions:
v XMSException
Inherited properties and methods
The following methods are inherited from the IPropertyContext interface:
GetBooleanProperty, GetByteProperty, GetBytesProperty, GetCharProperty,
GetDoubleProperty, GetFloatProperty, GetIntProperty, GetLongProperty,
GetObjectProperty, GetShortProperty, GetStringProperty, SetBooleanProperty,
Chapter 14. .NET interfaces
465
.NET interfaces
SetByteProperty, SetBytesProperty, SetCharProperty, SetDoubleProperty,
SetFloatProperty, SetIntProperty, SetLongProperty, SetObjectProperty,
SetShortProperty, SetStringProperty
466
Message Service Clients for C/C++ and .NET
.NET interfaces
IMessageConsumer
An application uses a message consumer to receive messages sent to a destination.
Inheritance hierarchy:
IBM.XMS.IPropertyContext
|
+----IBM.XMS.IMessageConsumer
For a list of the XMS defined properties of a MessageConsumer object, see
“Properties of MessageConsumer” on page 533.
.NET properties
MessageListener – Get and Set Message Listener
Interface:
MessageListener MessageListener
{
get;
set;
}
Get the message listener that is registered with the message consumer. If no
message listener is registered with the message consumer, MessageListener is null.
Register a message listener with the message consumer. If a message listener is
already registered with the message consumer, you can cancel the registration by
specifying a null instead.
For more information about using message listeners, see “Using message and
exception listeners in .NET” on page 81.
Exceptions:
v XMSException
MessageSelector – Get Message Selector
Interface:
String MessageSelector
{
get;
}
Get the message selector for the message consumer. The return value is 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 value of MessageSelector is a null String
object.
Exceptions:
v XMSException
Chapter 14. .NET interfaces
467
.NET interfaces
Methods
Close – Close Message Consumer
Interface:
void
Close();
Close the message consumer.
If an application tries to close a message consumer that is already closed, the call is
ignored.
Parameters:
None
Returns:
Void
Exceptions:
v XMSException
Receive – Receive
Interface:
IMessage Receive();
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 XMSException
Receive – Receive (with a wait interval)
Interface:
IMessage Receive(Int64 delay);
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:
delay (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
468
Message Service Clients for C/C++ and .NET
.NET interfaces
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 XMSException
ReceiveNoWait – Receive with No Wait
Interface:
IMessage ReceiveNoWait();
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 XMSException
Inherited properties and methods
The following methods are inherited from the IPropertyContext interface:
GetBooleanProperty, GetByteProperty, GetBytesProperty, GetCharProperty,
GetDoubleProperty, GetFloatProperty, GetIntProperty, GetLongProperty,
GetObjectProperty, GetShortProperty, GetStringProperty, SetBooleanProperty,
SetByteProperty, SetBytesProperty, SetCharProperty, SetDoubleProperty,
SetFloatProperty, SetIntProperty, SetLongProperty, SetObjectProperty,
SetShortProperty, SetStringProperty
Chapter 14. .NET interfaces
469
.NET interfaces
MessageEOFException
Inheritance hierarchy:
IBM.XMS.XMSException
|
+----IBM.XMS.XMSException
|
+----IBM.XMS.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.
Inherited properties and methods
The following methods are inherited from the XMSException interface:
GetErrorCode, GetLinkedException
470
Message Service Clients for C/C++ and .NET
.NET interfaces
MessageFormatException
Inheritance hierarchy:
IBM.XMS.XMSException
|
+----IBM.XMS.XMSException
|
+----IBM.XMS.MessageFormatException
XMS throws this exception if XMS encounters a message with a format that is not
valid.
Inherited properties and methods
The following methods are inherited from the XMSException interface:
GetErrorCode, GetLinkedException
Chapter 14. .NET interfaces
471
.NET interfaces
IMessageListener (delegate)
Inheritance hierarchy:
None
An application uses a message listener to receive messages asynchronously.
Delegate
MessageListener - Message Listener
Interface:
public delegate void MessageListener(IMessage msg);
Deliver a message asynchronously to the message consumer.
Methods that implement this delegate can be registered with the connection.
For more information about using message listeners, see “Using message and
exception listeners in .NET” on page 81.
Parameters:
mesg (input)
The Message object.
Returns:
Void
472
Message Service Clients for C/C++ and .NET
.NET interfaces
MessageNotReadableException
Inheritance hierarchy:
IBM.XMS.XMSException
|
+----IBM.XMS.XMSException
|
+----IBM.XMS.MessageNotReadableException
XMS throws this exception if an application attempts to read the body of a
message that is write-only.
Inherited properties and methods
The following methods are inherited from the XMSException interface:
GetErrorCode, GetLinkedException
Chapter 14. .NET interfaces
473
.NET interfaces
MessageNotWritableException
Inheritance hierarchy:
IBM.XMS.XMSException
|
+----IBM.XMS.XMSException
|
+----IBM.XMS.MessageNotWritableException
XMS throws this exception if an application attempts to write to the body of a
message that is read-only.
Inherited properties and methods
The following methods are inherited from the XMSException interface:
GetErrorCode, GetLinkedException
474
Message Service Clients for C/C++ and .NET
.NET interfaces
IMessageProducer
An application uses a message producer to send messages to a destination.
Inheritance hierarchy:
IBM.XMS.IPropertyContext
|
+----IBM.XMS.IMessageProducer
For a list of the XMS defined properties of a MessageProducer object, see
“Properties of MessageProducer” on page 533.
.NET properties
DeliveryMode – Get and Set Default Delivery Mode
Interface:
DeliveryMode DeliveryMode
{
get;
set;
}
Get the default delivery mode for messages sent by the message producer.
Set the default delivery mode for messages sent by the message producer.
The default delivery mode has one of the following values:
DeliveryMode.Persistent
DeliveryMode.NonPersistent
For a real-time connection to a broker, the value must be
DeliveryMode.NonPersistent.
The default value is DeliveryMode.Persistent, except for a real-time connection to
a broker for which the default value is DeliveryMode.NonPersistent.
Exceptions:
v XMSException
Destination – Get Destination
Interface:
IDestination Destination
{
get;
}
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:
Chapter 14. .NET interfaces
475
.NET interfaces
v XMSException
DisableMsgID – Get and Set Disable Message ID Flag
Interface:
Boolean DisableMessageID
{
get;
set;
}
Get an indication of whether a receiving application requires message identifiers to
be included in messages sent by the message producer.
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.
DisabledMsgID has the following values:
v True, if a receiving application does not require message identifiers to be
included in messages sent by the message producer.
v False, if a receiving application does require message identifiers to be included
in messages sent by the message producer.
Exceptions:
v XMSException
DisableMsgTS – Get and Set Disable Time Stamp Flag
Interface:
Boolean DisableMessageTimestamp
{
get;
set;
}
Get an indication of whether a receiving application requires time stamps to be
included in messages sent by the message producer.
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.
DisableMsgTS has the following values:
v True, if a receiving application does not require time stamps to be included in
messages sent by the message producer.
v False, if a receiving application does require time stamps to be included in
messages sent by the message producer.
Returns:
476
Message Service Clients for C/C++ and .NET
.NET interfaces
Exceptions:
v XMSException
Priority – Get and Set Default Priority
Interface:
Int32 Priority
{
get;
set;
}
Get the default priority for messages sent by the message producer.
Set the default priority for messages sent by the message producer.
The value of the default message priority is an integer in the range 0, the lowest
priority, to 9, the highest priority.
On a real-time connection to a broker, the priority of a message is ignored.
Exceptions:
v XMSException
TimeToLive – Get and Set Default Time to Live
Interface:
Int64 TimeToLive
{
get;
set;
}
Get the default length of time that a message exists before it expires.
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 and is
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, this value is always 0.
Exceptions:
v XMSException
Methods
Close – Close Message Producer
Interface:
void
Close();
Close the message producer.
Chapter 14. .NET interfaces
477
.NET interfaces
If an application tries to close a message producer that is already closed, the call is
ignored.
Parameters:
None
Returns:
Void
Exceptions:
v XMSException
Send – Send
Interface:
void Send(IMessage msg) ;
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:
msg (input)
The Message object.
Returns:
Void
Exceptions:
v XMSException
v MessageFormatException
v InvalidDestinationException
Send – Send (specifying a delivery mode, priority, and time to
live)
Interface:
void Send(IMessage msg,
DeliveryMode deliveryMode,
Int32 priority,
Int64 timeToLive);
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:
msg (input)
The Message object.
deliveryMode (input)
The delivery mode for the message, which must be one of the
following values:
DeliveryMode.Persistent
DeliveryMode.NonPersistent
478
Message Service Clients for C/C++ and .NET
.NET interfaces
For a real-time connection to a broker, the value must be
DeliveryMode.NonPersistent.
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
v
v
v
XMSException
MessageFormatException
InvalidDestinationException
IllegalStateException
Send – Send (to a specified destination)
Interface:
void Send(IDestination dest, IMessage msg) ;
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:
dest (input)
The Destination object.
msg (input)
The Message object.
Returns:
Void
Exceptions:
v XMSException
v MessageFormatException
v InvalidDestinationException
Chapter 14. .NET interfaces
479
.NET interfaces
Send – Send (to a specified destination, specifying a delivery
mode, priority, and time to live)
Interface:
void Send(IDestination dest,
IMessage msg,
DeliveryMode deliveryMode,
Int32 priority,
Int64 timeToLive) ;
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:
dest (input)
The Destination object.
msg (input)
The Message object.
deliveryMode (input)
The delivery mode for the message, which must be one of the
following values:
DeliveryMode.Persistent
DeliveryMode.NonPersistent
For a real-time connection to a broker, the value must be
DeliveryMode.NonPersistent.
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 XMSException
v MessageFormatException
v InvalidDestinationException
v IllegalStateException
Inherited properties and methods
The following methods are inherited from the IPropertyContext interface:
GetBooleanProperty, GetByteProperty, GetBytesProperty, GetCharProperty,
GetDoubleProperty, GetFloatProperty, GetIntProperty, GetLongProperty,
480
Message Service Clients for C/C++ and .NET
.NET interfaces
GetObjectProperty, GetShortProperty, GetStringProperty, SetBooleanProperty,
SetByteProperty, SetBytesProperty, SetCharProperty, SetDoubleProperty,
SetFloatProperty, SetIntProperty, SetLongProperty, SetObjectProperty,
SetShortProperty, SetStringProperty
Chapter 14. .NET interfaces
481
.NET interfaces
IObjectMessage
An object message is a message whose body comprises a serialized Java or .NET
object.
Inheritance hierarchy:
IBM.XMS.IPropertyContext
|
+----IBM.XMS.IMessage
|
+----IBM.XMS.IObjectMessage
.NET properties
Object – Get and Set Object as Bytes
Interface:
System.Object Object
{
get;
set;
}
Byte[] GetObject();
Get the object that forms the body of the object message.
Set the string that forms the body of the object message.
Exceptions:
v XMSException
v MessageNotReadableException
v MessageEOFException
v MessageNotWritableException
Inherited properties and methods
The following properties are inherited from the IMessage interface:
JMSCorrelationID, JMSDeliveryMode, JMSDestination, JMSExpiration,
JMSMessageID, JMSPriority, JMSRedelivered, JMSReplyTo, JMSTimestamp,
JMSType, Properties
The following methods are inherited from the IMessage interface:
clearBody, clearProperties, PropertyExists
The following methods are inherited from the IPropertyContext interface:
GetBooleanProperty, GetByteProperty, GetBytesProperty, GetCharProperty,
GetDoubleProperty, GetFloatProperty, GetIntProperty, GetLongProperty,
GetObjectProperty, GetShortProperty, GetStringProperty, SetBooleanProperty,
SetByteProperty, SetBytesProperty, SetCharProperty, SetDoubleProperty,
SetFloatProperty, SetIntProperty, SetLongProperty, SetObjectProperty,
SetShortProperty, SetStringProperty
482
Message Service Clients for C/C++ and .NET
.NET interfaces
IPropertyContext
IPropertyContext 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:
Boolean GetBooleanProperty(String property_name);
Get the value of the boolean property with the specified name.
Parameters:
property_name (input)
A String object encapsulating the name of the property.
Returns:
The value of the property.
Thread context:
Determined by the subclass
Exceptions:
v XMSException
GetByteProperty – Get Byte Property
Interface:
Byte
Int16
GetByteProperty(String property_name) ;
GetSignedByteProperty(String property_name) ;
Get the value of the byte property identified by name.
Parameters:
property_name (input)
A String object encapsulating the name of the property.
Returns:
The value of the property.
Thread context:
Determined by the subclass
Exceptions:
v XMSException
GetBytesProperty – Get Byte Array Property
Interface:
Byte[]
GetBytesProperty(String property_name) ;
Get the value of the byte array property identified by name.
Chapter 14. .NET interfaces
483
.NET interfaces
Parameters:
property_name (input)
A String object encapsulating the name of the property.
Returns:
The number of bytes in the array.
Thread context:
Determined by the subclass
Exceptions:
v XMSException
GetCharProperty – Get Character Property
Interface:
Char
GetCharProperty(String property_name) ;
Get the value of the 2-byte character property identified by name.
Parameters:
property_name (input)
A String object encapsulating the name of the property.
Returns:
The value of the property.
Thread context:
Determined by the subclass
Exceptions:
v XMSException
GetDoubleProperty – Get Double Precision Floating Point
Property
Interface:
Double
GetDoubleProperty(String property_name) ;
Get the value of the double precision floating point property identified by name.
Parameters:
property_name (input)
A String object encapsulating the name of the property.
Returns:
The value of the property.
Thread context:
Determined by the subclass
Exceptions:
v XMSException
484
Message Service Clients for C/C++ and .NET
.NET interfaces
GetFloatProperty – Get Floating Point Property
Interface:
Single
GetFloatProperty(String property_name) ;
Get the value of the floating point property identified by name.
Parameters:
property_name (input)
A String object encapsulating the name of the property.
Returns:
The value of the property.
Thread context:
Determined by the subclass
Exceptions:
v XMSException
GetIntProperty – Get Integer Property
Interface:
Int32
GetIntProperty(String property_name) ;
Get the value of the integer property identified by name.
Parameters:
property_name (input)
A String object encapsulating the name of the property.
Returns:
The value of the property.
Thread context:
Determined by the subclass
Exceptions:
v XMSException
GetLongProperty – Get Long Integer Property
Interface:
Int64
GetLongProperty(String property_name) ;
Get the value of the long integer property identified by name.
Parameters:
property_name (input)
A String object encapsulating the name of the property.
Returns:
The value of the property.
Thread context:
Determined by the subclass
Exceptions:
Chapter 14. .NET interfaces
485
.NET interfaces
v XMSException
GetObjectProperty – Get Object Property
Interface:
Object
GetObjectProperty( String property_name) ;
Get the value and data type of the property identified by name.
Parameters:
property_name (input)
A String object encapsulating the name of the property.
Returns:
The value of the property, which is one of the following object types:
Boolean
Byte
Byte[]
Char
Double
Single
Int32
Int64
Int16
String
Thread context:
Determined by the subclass
Exceptions:
v XMSException
GetShortProperty – Get Short Integer Property
Interface:
Int16
GetShortProperty(String property_name) ;
Get the value of the short integer property identified by name.
Parameters:
property_name (input)
A String object encapsulating the name of the property.
Returns:
The value of the property.
Thread context:
Determined by the subclass
Exceptions:
v XMSException
486
Message Service Clients for C/C++ and .NET
.NET interfaces
GetStringProperty – Get String Property
Interface:
String
GetStringProperty(String property_name) ;
Get the value of the string property identified by name.
Parameters:
property_name (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 XMSException
SetBooleanProperty – Set Boolean Property
Interface:
void SetBooleanProperty( String property_name,
Boolean value) ;
Set the value of the boolean property identified by name.
Parameters:
property_name (input)
A String object encapsulating the name of the property.
value (input)
The value of the property.
Returns:
Void
Thread context:
Determined by the subclass
Exceptions:
v XMSException
v MessageNotWritableException
SetByteProperty – Set Byte Property
Interface:
void SetByteProperty( String property_name, Byte value) ;
void SetSignedByteProperty( String property_name, Int16 value) ;
Set the value of the byte property identified by name.
Parameters:
property_name (input)
A String object encapsulating the name of the property.
Chapter 14. .NET interfaces
487
.NET interfaces
value (input)
The value of the property.
Returns:
Void
Thread context:
Determined by the subclass
Exceptions:
v XMSException
v MessageNotWritableException
SetBytesProperty – Set Byte Array Property
Interface:
void SetBytesProperty( String property_name, Byte[] value ) ;
Set the value of the byte array property identified by name.
Parameters:
property_name (input)
A String object encapsulating the name of the property.
value (input)
The value of the property, which is an array of bytes.
Returns:
Void
Thread context:
Determined by the subclass
Exceptions:
v XMSException
v MessageNotWritableException
SetCharProperty – Set Character Property
Interface:
void SetCharProperty( String property_name,
Char value) ;
Set the value of the 2-byte character property identified by name.
Parameters:
property_name (input)
A String object encapsulating the name of the property.
value (input)
The value of the property.
Returns:
Void
Thread context:
Determined by the subclass
Exceptions:
488
Message Service Clients for C/C++ and .NET
.NET interfaces
v XMSException
v MessageNotWritableException
SetDoubleProperty – Set Double Precision Floating Point
Property
Interface:
void SetDoubleProperty( String property_name,
Double value) ;
Set the value of the double precision floating point property identified by name.
Parameters:
property_name (input)
A String object encapsulating the name of the property.
value (input)
The value of the property.
Returns:
Void
Thread context:
Determined by the subclass
Exceptions:
v XMSException
v MessageNotWritableException
SetFloatProperty – Set Floating Point Property
Interface:
void SetFloatProperty( String property_name,
Single value) ;
Set the value of the floating point property identified by name.
Parameters:
property_name (input)
A String object encapsulating the name of the property.
value (input)
The value of the property.
Returns:
Void
Thread context:
Determined by the subclass
Exceptions:
v XMSException
v MessageNotWritableException
Chapter 14. .NET interfaces
489
.NET interfaces
SetIntProperty – Set Integer Property
Interface:
void SetIntProperty( String property_name,
Int32 value) ;
Set the value of the integer property identified by name.
Parameters:
property_name (input)
A String object encapsulating the name of the property.
value (input)
The value of the property.
Returns:
Void
Thread context:
Determined by the subclass
Exceptions:
v XMSException
v MessageNotWritableException
SetLongProperty – Set Long Integer Property
Interface:
void SetLongProperty( String property_name,
Int64 value) ;
Set the value of the long integer property identified by name.
Parameters:
property_name (input)
A String object encapsulating the name of the property.
value (input)
The value of the property.
Returns:
Void
Thread context:
Determined by the subclass
Exceptions:
v XMSException
v MessageNotWritableException
SetObjectProperty – Set Object Property
Interface:
void SetObjectProperty( String property_name,
Object value) ;
Set the value and data type of a property identified by name.
Parameters:
490
Message Service Clients for C/C++ and .NET
.NET interfaces
property_name (input)
A String object encapsulating the name of the property.
objectType (input)
The value of the property, which must be one of the following
object types:
Boolean
Byte
Byte[]
Char
Double
Single
Int32
Int64
Int16
String
value (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 XMSException
v MessageNotWritableException
SetShortProperty – Set Short Integer Property
Interface:
void SetShortProperty( String property_name,
Int16 value) ;
Set the value of the short integer property identified by name.
Parameters:
property_name (input)
A String object encapsulating the name of the property.
value (input)
The value of the property.
Returns:
Void
Thread context:
Determined by the subclass
Exceptions:
v XMSException
v MessageNotWritableException
Chapter 14. .NET interfaces
491
.NET interfaces
SetStringProperty – Set String Property
Interface:
void SetStringProperty( String property_name,
String value);
Set the value of the string property identified by name.
Parameters:
property_name (input)
A String object encapsulating the name of the property.
value (input)
A String object encapsulating the string that is the value of the
property.
Returns:
Void
Thread context:
Determined by the subclass
Exceptions:
v XMSException
v MessageNotWritableException
492
Message Service Clients for C/C++ and .NET
.NET interfaces
IQueueBrowser
An application uses a queue browser to browse messages on a queue without
removing them.
Inheritance hierarchy:
IBM.XMS.IPropertyContext
System.Collections.IEnumerable
|
+----IBM.XMS.IQueueBrowser
.NET Properties
MessageSelector – Get Message Selector
Interface:
String MessageSelector
{
get;
}
Get the message selector for the queue browser.
The message selector is 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 XMSException
Queue – Get Queue
Interface:
IDestination Queue
{
get;
}
Get the queue associated with the queue browser as a destination object
representing the queue.
Exceptions:
v XMSException
Methods
Close – Close Queue Browser
Interface:
void
Close();
Close the queue browser.
If an application tries to close a queue browser that is already closed, the call is
ignored.
Chapter 14. .NET interfaces
493
.NET interfaces
Parameters:
None
Returns:
Void
Exceptions:
v XMSException
GetEnumerator – Get Messages
Interface:
IEnumerator GetEnumerator();
Get a list of the messages on the queue.
The method returns an enumerator that encapsulates a list of Message objects. The
order of the Message objects is the same as the order in which the messages would
be retrieved from the queue. The application can then use the enumerator to
browse each message in turn.
The enumerator is updated dynamically as messages are put on the queue and
removed from the queue. Each time the application calls IEnumerator.MoveNext()
to browse the next message on the queue, the message 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 enumerator. The application can therefore use more than one
enumerator to browse the messages on a queue and maintain multiple positions
within the queue.
Parameters:
None
Returns:
The Iterator object.
Exceptions:
v XMSException
Inherited properties and methods
The following methods are inherited from the IPropertyContext interface:
GetBooleanProperty, GetByteProperty, GetBytesProperty, GetCharProperty,
GetDoubleProperty, GetFloatProperty, GetIntProperty, GetLongProperty,
GetObjectProperty, GetShortProperty, GetStringProperty, SetBooleanProperty,
SetByteProperty, SetBytesProperty, SetCharProperty, SetDoubleProperty,
SetFloatProperty, SetIntProperty, SetLongProperty, SetObjectProperty,
SetShortProperty, SetStringProperty
494
Message Service Clients for C/C++ and .NET
.NET interfaces
Requestor
An application uses a requestor to send a request message and then wait for, and
receive, the reply.
Inheritance hierarchy:
None
Constructors
Requestor – Create Requestor
Interface:
Requestor(ISession sess, IDestination dest);
Create a requestor.
Parameters:
sess (input)
A Session object. The session must not be transacted and must
have one of the following acknowledgement modes:
AcknowledgeMode.AutoAcknowledge
AcknowledgeMode.DupsOkAcknowledge
dest (input)
A Destination object representing the destination where the
application can send request messages.
Thread context:
The session associated with the requestor
Exceptions:
v XMSException
Methods
Close – Close Requestor
Interface:
void
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 XMSException
Chapter 14. .NET interfaces
495
.NET interfaces
Request – Request Response
Interface:
IMessage Request(IMessage requestMessage);
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 XMSException
496
Message Service Clients for C/C++ and .NET
.NET interfaces
ResourceAllocationException
Inheritance hierarchy:
IBM.XMS.XMSException
|
+----IBM.XMS.XMSException
|
+----IBM.XMS.ResourceAllocationException
XMS throws this exception if XMS cannot allocate the resources required by a
method.
Inherited properties and methods
The following methods are inherited from the XMSException interface:
GetErrorCode, GetLinkedException
Chapter 14. .NET interfaces
497
.NET interfaces
SecurityException
Inheritance hierarchy:
IBM.XMS.XMSException
|
+----IBM.XMS.XMSException
|
+----IBM.XMS.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.
Inherited properties and methods
The following methods are inherited from the XMSException interface:
GetErrorCode, GetLinkedException
498
Message Service Clients for C/C++ and .NET
.NET interfaces
ISession
A session is a single threaded context for sending and receiving messages.
Inheritance hierarchy:
IBM.XMS.IPropertyContext
|
+----IBM.XMS.ISession
For a list of the XMS defined properties of a Session object, see “Properties of
Session” on page 533.
.NET properties
AcknowledgeMode – Get Acknowledgement Mode
Interface:
AcknowledgeMode AcknowledgeMode
{
get;
}
Get the acknowledgement mode for the session.
The acknowledgement mode is specified when the session is created.
Provided the session is not transacted, the acknowledgement mode is one of the
following values:
AcknowledgeMode.AutoAcknowledge
AcknowledgeMode.ClientAcknowledge
AcknowledgeMode.DupsOkAcknowledge
For more information about acknowledgement modes, see “Acknowledging the
receipt of messages in a session” on page 43.
A session that is transacted has no acknowledgement mode. If the session is
transacted, the method returns AcknowledgeMode.SessionTransacted instead.
Exceptions:
v XMSException
Transacted – Determine Whether Transacted
Interface:
Boolean Transacted
{
get;
}
Determine whether the session is transacted.
The transacted stated is:
v True, if the session is transacted.
v False, if the session is not transacted.
For a real-time connection to a broker, the method always returns False.
Chapter 14. .NET interfaces
499
.NET interfaces
Exceptions:
v XMSException
Methods
Close – Close Session
Interface:
void Close();
Close the session. If the session is transacted, any transaction in progress is rolled
back.
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 XMSException
Commit – Commit
Interface:
void Commit();
Commit all messages processed in the current transaction.
The session must be a transacted session.
Parameters:
None
Returns:
Void
Exceptions:
v XMSException
v IllegalStateException
v TransactionRolledBackException
CreateBrowser – Create Queue Browser
Interface:
IQueueBrowser CreateBrowser(IDestination queue) ;
Create a queue browser for the specified queue.
Parameters:
500
Message Service Clients for C/C++ and .NET
.NET interfaces
queue (input)
A Destination object representing the queue.
Returns:
The QueueBrowser object.
Exceptions:
v XMSException
v InvalidDestinationException
CreateBrowser – Create Queue Browser (with message selector)
Interface:
IQueueBrowser CreateBrowser(IDestination queue, String selector) ;
Create a queue browser for the specified queue using a message selector.
Parameters:
queue (input)
A Destination object representing the queue.
selector (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 XMSException
v InvalidDestinationException
v InvalidSelectorException
CreateBytesMessage – Create Bytes Message
Interface:
IBytesMessage CreateBytesMessage();
Create a bytes message.
Parameters:
None
Returns:
The BytesMessage object.
Exceptions:
v XMSException
v IllegalStateException (The session is closed)
Chapter 14. .NET interfaces
501
.NET interfaces
CreateConsumer – Create Consumer
Interface:
IMessageConsumer CreateConsumer(IDestination dest) ;
Create a message consumer for the specified destination.
Parameters:
dest (input)
The Destination object.
Returns:
The MessageConsumer object.
Exceptions:
v XMSException
v InvalidDestinationException
CreateConsumer – Create Consumer (with message selector)
Interface:
IMessageConsumer CreateConsumer(IDestination dest,
String selector) ;
Create a message consumer for the specified destination using a message selector.
Parameters:
dest (input)
The Destination object.
selector (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 XMSException
v InvalidDestinationException
v InvalidSelectorException
CreateConsumer – Create Consumer (with message selector and
local message flag)
Interface:
IMessageConsumer CreateConsumer(IDestination dest,
String selector,
Boolean noLocal) ;
502
Message Service Clients for C/C++ and .NET
.NET interfaces
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:
dest (input)
The Destination object.
selector (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.
noLocal (input)
The value True means that the message consumer does not receive
the messages published by its own connection. The value False
means that the message consumer does receive the messages
published by its own connection. The default value is False.
Returns:
The MessageConsumer object.
Exceptions:
v XMSException
v InvalidDestinationException
v InvalidSelectorException
CreateDurableSubscriber – Create Durable Subscriber
Interface:
IMessageConsumer CreateDurableSubscriber(IDestination dest,
String subscription) ;
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
49.
Parameters:
dest (input)
A Destination object representing the topic. The topic must not be a
temporary topic.
subscription (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 XMSException
Chapter 14. .NET interfaces
503
.NET interfaces
v InvalidDestinationException
CreateDurableSubscriber – Create Durable Subscriber (with
message selector and local message flag)
Interface:
IMessageConsumer CreateDurableSubscriber(IDestination dest,
String subscription,
String selector,
Boolean noLocal) ;
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
49.
Parameters:
dest (input)
A Destination object representing the topic. The topic must not be a
temporary topic.
subscription (input)
A String object encapsulating a name that identifies the durable
subscription. The name must be unique within the client identifier
for the connection.
selector (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 True means that the durable subscriber does not receive
the messages published by its own connection. The value False
means that the durable subscriber does receive the messages
published by its own connection. The default value is False.
Returns:
The MessageConsumer object representing the durable subscriber.
Exceptions:
v XMSException
v InvalidDestinationException
v InvalidSelectorException
CreateMapMessage – Create Map Message
Interface:
IMapMessage CreateMapMessage();
504
Message Service Clients for C/C++ and .NET
.NET interfaces
Create a map message.
Parameters:
None
Returns:
The MapMessage object.
Exceptions:
v XMSException
v IllegalStateException (The session is closed)
CreateMessage – Create Message
Interface:
IMessage CreateMessage();
Create a message that has no body.
Parameters:
None
Returns:
The Message object.
Exceptions:
v XMSException
v IllegalStateException (The session is closed)
CreateObjectMessage – Create Object Message
Interface:
IObjectMessage CreateObjectMessage();
Create an object message.
Parameters:
None
Returns:
The ObjectMessage object.
Exceptions:
v XMSException
v IllegalStateException (The session is closed)
CreateProducer – Create Producer
Interface:
IMessageProducer CreateProducer(IDestination dest) ;
Create a message producer to send messages to the specified destination.
Parameters:
Chapter 14. .NET interfaces
505
.NET interfaces
dest (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.
Returns:
The MessageProducer object.
Exceptions:
v XMSException
v InvalidDestinationException
CreateQueue – Create Queue
Interface:
IDestination CreateQueue(String queue) ;
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:
queue (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 XMSException
CreateStreamMessage – Create Stream Message
Interface:
IStreamMessage CreateStreamMessage();
Create a stream message.
Parameters:
None
Returns:
The StreamMessage object.
Exceptions:
v XMSException
v XMS_ILLEGAL_STATE_EXCEPTION
506
Message Service Clients for C/C++ and .NET
.NET interfaces
CreateTemporaryQueue – Create Temporary Queue
Interface:
IDestination CreateTemporaryQueue() ;
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.
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 48.
Parameters:
None
Returns:
The Destination object representing the temporary queue.
Exceptions:
v XMSException
CreateTemporaryTopic – Create Temporary Topic
Interface:
IDestination CreateTemporaryTopic() ;
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 48.
Parameters:
None
Returns:
The Destination object representing the temporary topic.
Exceptions:
v XMSException
CreateTextMessage – Create Text Message
Interface:
ITextMessage CreateTextMessage();
Create a text message with an empty body.
Chapter 14. .NET interfaces
507
.NET interfaces
Parameters:
None
Returns:
The TextMessage object.
Exceptions:
v XMSException
CreateTextMessage – Create Text Message (initialized)
Interface:
ITextMessage CreateTextMessage(String initialValue);
Create a text message whose body is initialized with the specified text.
Parameters:
initialValue (input)
A String object encapsulating the text to initialize the body of the
text message.
None
Returns:
The TextMessage object.
Exceptions:
v XMSException
CreateTopic – Create Topic
Interface:
IDestination CreateTopic(String topic) ;
Create a Destination object to represent a topic.
Parameters:
topic (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 XMSException
Recover – Recover
Interface:
void Recover();
Recover the session. Message delivery is stopped and then restarted with the
oldest unacknowledged message.
508
Message Service Clients for C/C++ and .NET
.NET interfaces
The session must not be a transacted session.
For more information about recovering a session, see “Acknowledging the receipt
of messages in a session” on page 43.
Parameters:
None
Returns:
Void
Exceptions:
v XMSException
v IllegalStateException
Rollback – Rollback
Interface:
void Rollback();
Rollback all messages processed in the current transaction.
The session must be a transacted session.
Parameters:
None
Returns:
Void
Exceptions:
v XMSException
v IllegalStateException
Unsubscribe – Unsubscribe
Interface:
void Unsubscribe(String subscription);
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:
subscription (input)
A String object encapsulating the name that identifies the durable
subscription.
Chapter 14. .NET interfaces
509
.NET interfaces
Returns:
Void
Exceptions:
v XMSException
v InvalidDestinationException
v IllegalStateException
Inherited properties and methods
The following methods are inherited from the IPropertyContext interface:
GetBooleanProperty, GetByteProperty, GetBytesProperty, GetCharProperty,
GetDoubleProperty, GetFloatProperty, GetIntProperty, GetLongProperty,
GetObjectProperty, GetShortProperty, GetStringProperty, SetBooleanProperty,
SetByteProperty, SetBytesProperty, SetCharProperty, SetDoubleProperty,
SetFloatProperty, SetIntProperty, SetLongProperty, SetObjectProperty,
SetShortProperty, SetStringProperty
510
Message Service Clients for C/C++ and .NET
.NET interfaces
IStreamMessage
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 and
read sequentially.
Inheritance hierarchy:
IBM.XMS.IPropertyContext
|
+----IBM.XMS.IMessage
|
+----IBM.XMS.IStreamMessage
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 92.
Methods
ReadBoolean – Read Boolean Value
Interface:
Boolean ReadBoolean();
Read a boolean value from the message stream.
Parameters:
None
Returns:
The boolean value that is read.
Exceptions:
v XMSException
v MessageNotReadableException
v MessageEOFException
ReadByte – Read Byte
Interface:
Int16
ReadSignedByte();
Byte
ReadByte();
Read a signed 8-bit integer from the message stream.
Parameters:
None
Returns:
The byte that is read.
Exceptions:
v XMSException
v MessageNotReadableException
v MessageEOFException
Chapter 14. .NET interfaces
511
.NET interfaces
ReadBytes – Read Bytes
Interface:
Int32
ReadBytes(Byte[] array);
Read an array of bytes from the message stream.
Parameters:
array (input)
The buffer containing the array of bytes that is read and the length
of the buffer in bytes.
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.
Returns:
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.
Exceptions:
v XMSException
v MessageNotReadableException
v MessageEOFException
ReadChar – Read Character
Interface:
Char
ReadChar();
Read a 2-byte character from the message stream.
Parameters:
None
Returns:
The character that is read.
Exceptions:
v XMSException
v MessageNotReadableException
v MessageEOFException
512
Message Service Clients for C/C++ and .NET
.NET interfaces
ReadDouble – Read Double Precision Floating Point Number
Interface:
Double
ReadDouble();
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 XMSException
v MessageNotReadableException
v MessageEOFException
ReadFloat – Read Floating Point Number
Interface:
Single
ReadFloat();
Read a 4-byte floating point number from the message stream.
Parameters:
None
Returns:
The floating point number that is read.
Exceptions:
v XMSException
v MessageNotReadableException
v MessageEOFException
ReadInt – Read Integer
Interface:
Int32
ReadInt();
Read a signed 32-bit integer from the message stream.
Parameters:
None
Returns:
The integer that is read.
Exceptions:
v XMSException
v MessageNotReadableException
v MessageEOFException
Chapter 14. .NET interfaces
513
.NET interfaces
ReadLong – Read Long Integer
Interface:
Int64
ReadLong();
Read a signed 64-bit integer from the message stream.
Parameters:
None
Returns:
The long integer that is read.
Exceptions:
v XMSException
v MessageNotReadableException
v MessageEOFException
ReadObject – Read Object
Interface:
Object
ReadObject();
Read a value from the message stream, and return its data type.
Parameters:
None
Returns:
The value, which is one of the following object types:
Boolean
Byte
Byte[]
Char
Double
Single
Int32
Int64
Int16
String
Exceptions:
XMSException
ReadShort – Read Short Integer
Interface:
Int16
ReadShort();
Read a signed 16-bit integer from the message stream.
Parameters:
None
514
Message Service Clients for C/C++ and .NET
.NET interfaces
Returns:
The short integer that is read.
Exceptions:
v XMSException
v MessageNotReadableException
v MessageEOFException
ReadString – Read String
Interface:
String
ReadString();
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 XMSException
v MessageNotReadableException
v MessageEOFException
Reset – Reset
Interface:
void
Reset();
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 XMSException
v MessageNotReadableException
v MessageEOFException
WriteBoolean – Write Boolean Value
Interface:
void
WriteBoolean(Boolean value);
Write a boolean value to the message stream.
Chapter 14. .NET interfaces
515
.NET interfaces
Parameters:
value (input)
The boolean value to be written.
Returns:
Void
Exceptions:
v XMSException
v MessageNotWritableException
WriteByte – Write Byte
Interface:
void
void
WriteByte(Byte value);
WriteSignedByte(Int16 value);
Write a byte to the message stream.
Parameters:
value (input)
The byte to be written.
Returns:
Void
Exceptions:
v XMSException
v MessageNotWritableException
WriteBytes – Write Bytes
Interface:
void
WriteBytes(Byte[] value);
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 XMSException
v MessageNotWritableException
516
Message Service Clients for C/C++ and .NET
.NET interfaces
WriteChar – Write Character
Interface:
void
WriteChar(Char 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 XMSException
v MessageNotWritableException
WriteDouble – Write Double Precision Floating Point Number
Interface:
void
WriteDouble(Double 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 XMSException
v MessageNotWritableException
WriteFloat – Write Floating Point Number
Interface:
void
WriteFloat(Single 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 XMSException
v MessageNotWritableException
Chapter 14. .NET interfaces
517
.NET interfaces
WriteInt – Write Integer
Interface:
void
WriteInt(Int32 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 XMSException
v MessageNotWritableException
WriteLong – Write Long Integer
Interface:
void
WriteLong(Int64 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 XMSException
v MessageNotWritableException
WriteObject – Write Object
Interface:
void
WriteObject(Object value);
Write a value, with a specified data type, to the message stream.
Parameters:
objectType (input)
The value, which must be one of the following object types:
Boolean
Byte
Byte[]
Char
Double
Single
518
Message Service Clients for C/C++ and .NET
.NET interfaces
Int32
Int64
Int16
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 XMSException
WriteShort – Write Short Integer
Interface:
void
WriteShort(Int16 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:
v XMSException
v MessageNotWritableException
WriteString – Write String
Interface:
void
WriteString(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 XMSException
v MessageNotWritableException
Chapter 14. .NET interfaces
519
.NET interfaces
Inherited properties and methods
The following properties are inherited from the IMessage interface:
JMSCorrelationID, JMSDeliveryMode, JMSDestination, JMSExpiration,
JMSMessageID, JMSPriority, JMSRedelivered, JMSReplyTo, JMSTimestamp,
JMSType, Properties
The following methods are inherited from the IMessage interface:
clearBody, clearProperties, PropertyExists
The following methods are inherited from the IPropertyContext interface:
GetBooleanProperty, GetByteProperty, GetBytesProperty, GetCharProperty,
GetDoubleProperty, GetFloatProperty, GetIntProperty, GetLongProperty,
GetObjectProperty, GetShortProperty, GetStringProperty, SetBooleanProperty,
SetByteProperty, SetBytesProperty, SetCharProperty, SetDoubleProperty,
SetFloatProperty, SetIntProperty, SetLongProperty, SetObjectProperty,
SetShortProperty, SetStringProperty
520
Message Service Clients for C/C++ and .NET
.NET interfaces
ITextMessage
A text message is a message whose body comprises a string.
Inheritance hierarchy:
IBM.XMS.IPropertyContext
|
+----IBM.XMS.IMessage
|
+----IBM.XMS.ITextMessage
.NET properties
Text – Get Text
Interface:
String Text
{
get;
set;
}
Get the string that forms the body of the text message.
Set the string that forms the body of the text message.
If required, XMS converts the characters in the string into the local code page.
Exceptions:
v XMSException
v MessageNotReadableException
v MessageNotWritableException
v MessageEOFException
Inherited properties and methods
The following properties are inherited from the IMessage interface:
JMSCorrelationID, JMSDeliveryMode, JMSDestination, JMSExpiration,
JMSMessageID, JMSPriority, JMSRedelivered, JMSReplyTo, JMSTimestamp,
JMSType, Properties
The following methods are inherited from the IMessage interface:
clearBody, clearProperties, PropertyExists
The following methods are inherited from the IPropertyContext interface:
GetBooleanProperty, GetByteProperty, GetBytesProperty, GetCharProperty,
GetDoubleProperty, GetFloatProperty, GetIntProperty, GetLongProperty,
GetObjectProperty, GetShortProperty, GetStringProperty, SetBooleanProperty,
SetByteProperty, SetBytesProperty, SetCharProperty, SetDoubleProperty,
SetFloatProperty, SetIntProperty, SetLongProperty, SetObjectProperty,
SetShortProperty, SetStringProperty
Chapter 14. .NET interfaces
521
.NET interfaces
TransactionInProgressException
Inheritance hierarchy:
IBM.XMS.XMSException
|
+----IBM.XMS.XMSException
|
+----IBM.XMS.TransactionInProgressException
XMS throws this exception if an application requests an operation that is not valid
because a transaction is in progress.
Inherited properties and methods
The following methods are inherited from the XMSException interface:
GetErrorCode, GetLinkedException
522
Message Service Clients for C/C++ and .NET
.NET interfaces
TransactionRolledBackException
Inheritance hierarchy:
IBM.XMS.XMSException
|
+----IBM.XMS.XMSException
|
+----IBM.XMS.TransactionRolledBackException
XMS throws this exception if an application calls Session.commit() to commit the
current transaction, but the transaction is subsequently rolled back.
Inherited properties and methods
The following methods are inherited from the XMSException interface:
GetErrorCode, GetLinkedException
Chapter 14. .NET interfaces
523
.NET interfaces
XMSException
If XMS detects an error while processing a call to a .NET method, XMS throws an
exception. An exception is an object that encapsulates information about the error.
Inheritance hierarchy:
System.Exception
|
+----IBM.XMS.XMSException
There are different types of XMS exception, and an XMSException object is just one
type of exception. However, the XMSException class is a superclass of the other
XMS exception classes. XMS throws an XMSException object in situations where
none of the other types of exception are appropriate.
.NET properties
GetErrorCode – Get Error Code
Interface:
public String ErrorCode
{
get {return errorCode_;}
}
Get the error code.
Exceptions:
v XMSException
GetLinkedException – Get Linked Exception
Interface:
public Exception LinkedException
{
get { return linkedException_;}
set { linkedException_ = value;}
}
Get the next exception in the chain of exceptions.
The method returns a null if there are no more exceptions in the chain.
Exceptions:
v XMSException
524
Message Service Clients for C/C++ and .NET
.NET interfaces
XMSFactoryFactory
If an application is not using administered objects, use this class to create
connection factories, queues and topics.
Inheritance hierarchy:
None
.NET properties
MetaData – Retrieve MetaData
Interface:
IConnectionMetaData MetaData
Get the metadata that is appropriate to the connection type of the
XMSFactoryFactory object.
Exceptions:
None
Methods
CreateConnectionFactory - Create Connection Factory
Interface:
IConnectionFactory CreateConnectionFactory();
Create a ConnectionFactory object of the declared type.
Parameters:
None
Returns:
The ConnectionFactory object.
Exceptions:
v XMSException
CreateQueue – Create Queue
Interface:
IDestination CreateQueue(String name);
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:
name (input)
A String object encapsulating the name of the queue, or
encapsulating a uniform resource identifier (URI) that identifies the
queue.
Chapter 14. .NET interfaces
525
.NET interfaces
Returns:
The Destination object representing the queue.
Exceptions:
v XMSException
CreateTopic – Create Topic
Interface:
IDestination CreateTopic(String name);
Create a Destination object to represent a topic.
Parameters:
name (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 XMSException
GetInstance - Get an instance of XMSFactoryFactory
Interface:
static XMSFactoryFactory GetInstance(int connectionType);
Create an instance of XMSFactoryFactory. An XMS application uses an
XMSFactoryFactory object to get a reference to a ConnectionFactory object that is
appropriate to the required type of protocol. This ConnectionFactory object can
then only produce connections for that protocol type
Parameters:
connectionType (input)
The type of connection for which the ConnectionFactory object will
produce connections:
XMS.CT_WPM
XMSC.CT_RTT
XMSC.CT_WMQ
Returns:
The XMSFactoryFactory object dedicated to the declared connection type.
Exceptions:
v NotSupportedException
526
Message Service Clients for C/C++ and .NET
Chapter 15. 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 528
v “Properties of ConnectionMetaData” on page 530
v “Properties of Destination” on page 530
v “Properties of InitialContext” on page 531
v “Properties of Message” on page 531
v “Properties of MessageConsumer” on page 533
v “Properties of MessageProducer” on page 533
v “Properties of Session” on page 533
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 533
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.
Note: The property names that appear in this chapter are in the form used for C
and C++. This form of the property name can also be used in .NET.
However, in .NET property names are also provided as constants in the
XMSC class. If you are using these predefined constants, the property names
are in the form XMSC.<NAME>, so, for example, you would use
XMCS.USERID, rather than XMSC_USERID.
Properties of Connection
Table 31. 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.
© Copyright IBM Corp. 2005
527
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
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
Table 32. Properties of ConnectionFactory
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_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.
XMSC_WMQ_BROKER_PUBQ
The name of the queue monitored by a broker where
applications send messages that they publish.
XMSC_WMQ_BROKER_QMGR
The name of the queue manager to which a broker is
connected.
XMSC_WMQ_BROKER_SUBQ
The name of the subscriber queue for a nondurable message
consumer.
XMSC_WMQ_BROKER_VERSION
The type of broker used by the application for a connection or
for the destination.
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.
528
Message Service Clients for C/C++ and .NET
Table 32. Properties of ConnectionFactory (continued)
Name of property
Description
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.
XMSC_WMQ_MSG_BATCH_SIZE
The maximum number of messages to be retrieved from a
queue in one batch when using asynchronous message
delivery.
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.
XMSC_WMQ_PORT
The number of the port on which a queue manager listens for
incoming requests.
XMSC_WMQ_PUB_ACK_INTERVAL
The number of messages published by a publisher before the
XMS client requests an acknowledgement from the broker.
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_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_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_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.
Chapter 15. Properties of XMS objects
529
Table 32. Properties of ConnectionFactory (continued)
Name of property
Description
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.
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
Table 33. 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.
Properties of Destination
Table 34. 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.
530
Message Service Clients for C/C++ and .NET
Table 34. Properties of Destination (continued)
Name of property
Description
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.
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_TARGET_CLIENT
Whether messages sent to the destination contain an
MQRFH2 header.
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
Table 35. Properties of InitialContext
Name of property
Description
XMSC_IC_URL
For LDAP and FileSystem contexts, the address of the
repository containing administered objects.
Properties of Message
Table 36. Properties of Message
Name of property
Description
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.
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_EXCEPTION_MESSAGE
Text that describes why the message was sent to the exception
destination. This property is read-only.
JMS_IBM_EXCEPTION_PROBLEM_DESTINATION
The name of the destination that the message was at before
the message was sent to the exception destination.
JMS_IBM_EXCEPTION_REASON
A reason code indicating the reason why the message was
sent to the exception destination.
Chapter 15. Properties of XMS objects
531
Table 36. Properties of Message (continued)
Name of property
Description
JMS_IBM_EXCEPTION_TIMESTAMP
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 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.
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_SYSTEM_MESSAGEID
An identifier that identifies the message uniquely within the
service integration bus. This property is read-only.
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.
532
Message Service Clients for C/C++ and .NET
Properties of MessageConsumer
Table 37. 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.
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
Table 38. 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
Table 39. 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. This 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:
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.
Chapter 15. Properties of XMS objects
533
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 86.
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_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. 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.
534
Message Service Clients for C/C++ and .NET
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
MQENC_INTEGER_NORMAL
MQENC_INTEGER_REVERSED
MQENC_DECIMAL_NORMAL
MQENC_DECIMAL_REVERSED
MQENC_FLOAT_IEEE_NORMAL
MQENC_FLOAT_IEEE_REVERSED
MQENC_FLOAT_S390
MQENC_NATIVE
Meaning
Normal integer encoding
Reversed integer encoding
Normal packed decimal encoding
Reversed packed decimal encoding
Normal IEEE floating point encoding
Reversed IEEE floating point encoding
zSeries® (System/390®) architecture floating
point encoding
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.
By default, the property is not set.
This property is not relevant when an application connects to a service integration
bus.
JMS_IBM_EXCEPTION_MESSAGE
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_EXCEPTION_PROBLEM_DESTINATION
Data type:
String
Property of:
Message
Chapter 15. Properties of XMS objects
535
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_EXCEPTION_REASON
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.
JMS_IBM_EXCEPTION_TIMESTAMP
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.
536
Message Service Clients for C/C++ and .NET
JMS_IBM_FORMAT
Data type:
String
Property of:
Message
The nature 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.
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
MQMT_DATAGRAM
MQMT_REQUEST
MQMT_REPLY
MQMT_REPORT
Meaning
The message
The message
The message
The message
is
is
is
is
one that does not require a reply.
one that requires a reply.
a reply message.
a report message.
Chapter 15. Properties of XMS objects
537
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.
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.
538
Message Service Clients for C/C++ and .NET
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
MQRO_COA
Meaning
Request confirm on arrival report messages,
with no application data from the original
message included in a report message.
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.
Chapter 15. Properties of XMS objects
539
The valid values of the property are as follows:
Valid value
MQRO_COD
Meaning
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.
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.
540
Message Service Clients for C/C++ and .NET
The valid values of the property are as follows:
Valid value
MQRO_EXCEPTION
MQRO_EXCEPTION_WITH_DATA
MQRO_EXCEPTION_WITH_FULL_DATA
Meaning
Request exception report messages,
with no application data from the
original message included in a report
message.
Request exception report messages,
with the first 100 bytes of application
data from the original message
included in a report message.
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.
The valid values of the property are as follows:
Valid value
MQRO_EXPIRATION
Meaning
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.
Chapter 15. Properties of XMS objects
541
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.
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
MQRO_PASS_CORREL_ID
MQRO_COPY_MSG_ID_TO_CORREL_ID
542
Message Service Clients for C/C++ and .NET
Meaning
Request that the correlation identifier
of any report or reply message is the
same as that of the original message.
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
MQRO_PASS_MSG_ID
MQRO_NEW_MSG_ID
Meaning
Request that the message identifier of any report or
reply message is the same as that of the original
message.
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_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.
JMSX_APPID
Data type:
String
Property of:
Message
The name of the application that sent the message.
Chapter 15. Properties of XMS objects
543
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
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.
544
Message Service Clients for C/C++ and .NET
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_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 (CCSIDs)” on page 56.
The following named constants are defined for certain Unicode CCSIDs and can be
used when setting the property:
Named constant
XMSC_CCSID_UTF8
XMSC_CCSID_UTF16
XMSC_CCSID_UTF32
CCSID
The UTF-8 representation of Unicode data
The UTF-16 representation of Unicode data
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 (CCSIDs)” on page 56.
Chapter 15. Properties of XMS objects
545
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.
This property is not relevant for a real-time connection to a broker.
XMSC_CONNECTION_TYPE
Data type:
xmsINT
Property of:
ConnectionFactory
The type of messaging server to which an application connects.
The valid values of the property are as follows:
Valid value
XMSC_CT_RTT
XMSC_CT_WMQ
XMSC_CT_WPM
Meaning
A real-time connection to a broker.
A connection to a WebSphere MQ queue
manager.
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.
546
Message Service Clients for C/C++ and .NET
The valid values of the property are as follows:
Valid value
XMSC_DELIVERY_NOT_PERSISTENT
XMSC_DELIVERY_PERSISTENT
XMSC_DELIVERY_AS_APP
XMSC_DELIVERY_AS_DEST
Meaning
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.
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.
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.
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_SECURITY_CREDENTIALS
Data type:
String
Property of:
InitialContext
XMSC_IC_URL
Data type:
String
Property of:
InitialContext
Chapter 15. Properties of XMS objects
547
For LDAP and FileSystem contexts, the address of the repository containing
administered objects.
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
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.
548
Message Service Clients for C/C++ and .NET
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.
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.
XMSC_PRIORITY
Data type:
xmsINT
Property of:
Destination
Name used in a URI:
priority
The priority of messages sent to the destination.
Chapter 15. Properties of XMS objects
549
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.
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.
550
Message Service Clients for C/C++ and .NET
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.
By default, the property is not set.
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.
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 15. Properties of XMS objects
551
The valid values of the property are as follows:
Valid value
XMSC_RTT_MULTICAST_DISABLED
Meaning
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.
552
Message Service Clients for C/C++ and .NET
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
0
A positive integer
Meaning
A message sent to the destination never expires.
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.
XMSC_VERSION
Data type:
String
Property of:
ConnectionMetaData
The version identifier of the XMS client. This property is read-only.
Chapter 15. Properties of XMS objects
553
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
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.
554
Message Service Clients for C/C++ and .NET
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_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
Business Integration Event Broker or WebSphere Business
Integration Message Broker but have not changed the
application.
XMSC_BROKER_V2 The application is using a broker of WebSphere Business
Integration Event Broker or WebSphere Business Integration
Message Broker.
The default value for a connection factory is XMSC_BROKER_V1 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.
This property is relevant only in the publish/subscribe domain.
XMSC_WMQ_CCSID
Data type:
xmsINT
Chapter 15. Properties of XMS objects
555
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
XMSC_WMQ_CM_BINDINGS
XMSC_WMQ_CM_CLIENT
By default, the property is not set.
XMSC_WMQ_DUR_SUBQ
Data type:
String
Property of:
Destination
556
Message Service Clients for C/C++ and .NET
Meaning
A connection to a queue manager in bindings
mode.
A connection to a queue manager in client mode.
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
MQENC_INTEGER_NORMAL
MQENC_INTEGER_REVERSED
MQENC_DECIMAL_NORMAL
MQENC_DECIMAL_REVERSED
MQENC_FLOAT_IEEE_NORMAL
MQENC_FLOAT_IEEE_REVERSED
MQENC_FLOAT_S390
MQENC_NATIVE
Meaning
Normal integer encoding
Reversed integer encoding
Normal packed decimal encoding
Reversed packed decimal encoding
Normal IEEE floating point encoding
Reversed IEEE floating point encoding
zSeries (System/390) architecture floating
point encoding
Native machine encoding
Chapter 15. Properties of XMS objects
557
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_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_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_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.
For information about the different ways in which a queue manager can be
stopped, see the WebSphere MQ System Administration Guide.
XMSC_WMQ_HOST_NAME
Data type:
String
558
Message Service Clients for C/C++ and .NET
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.
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:
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)
Chapter 15. Properties of XMS objects
559
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_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
XMSC_MSEL_CLIENT
XMSC_MSEL_BROKER
Meaning
Message selection is done by the XMS client.
Message selection is done by the broker.
The default value is XMSC_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_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.
560
Message Service Clients for C/C++ and .NET
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
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_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
Chapter 15. Properties of XMS objects
561
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
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.
562
Message Service Clients for C/C++ and .NET
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.
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
Chapter 15. Properties of XMS objects
563
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
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 563.
This property is relevant only when an application connects to a queue manager in
client mode.
564
Message Service Clients for C/C++ and .NET
XMSC_WMQ_SYNCPOINT_ALL_GETS
Data type:
xmsINT
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
XMSC_SYNCP_ALL_GETS_NO
Meaning
When the circumstances are appropriate, the
XMS client can retrieve messages from queues
outside of syncpoint control.
The XMS client must retrieve all messages
from queues within syncpoint control.
XMSC_SYNCP_ALL_GETS_YES
The default value is XMSC_SYNCP_ALL_GETS_NO.
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
XMSC_TARGET_DEST_JMS
XMSC_TARGET_DEST_MQ
Meaning
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.
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_TARGET_DEST_JMS.
Chapter 15. Properties of XMS objects
565
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_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_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.
566
Message Service Clients for C/C++ and .NET
XMSC_WPM_CONNECTION_PROTOCOL
Data type:
xmsINT
Property of:
Connection
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
XMSC_WPM_CP_HTTP
XMSC_WPM_CP_TCP
Meaning
The connection uses HTTP over TCP/IP.
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:
Valid value
XMSC_WPM_CONNECTION_PROXIMITY_BUS
XMSC_WPM_CONNECTION_PROXIMITY_CLUSTER
XMSC_WPM_CONNECTION_PROXIMITY_HOST
XMSC_WPM_CONNECTION_PROXIMITY_SERVER
Connection
proximity setting
Bus
Cluster
Host
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.
Chapter 15. Properties of XMS objects
567
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.
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
568
Message Service Clients for C/C++ and .NET
9.20.4.98
JUPITER(1000)
9.20.4.98(1000,2000)
(1000)
(1000,2000)
By default, the property is not set.
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
XMSC_WPM_MAPPING_AS_DESTINATION
XMSC_WPM_MAPPING_BEST_EFFORT_NON_
PERSISTENT
XMSC_WPM_MAPPING_EXPRESS_NON_
PERSISTENT
XMSC_WPM_MAPPING_RELIABLE_NON_
PERSISTENT
XMSC_WPM_MAPPING_RELIABLE_PERSISTENT
XMSC_WPM_MAPPING_ASSURED_PERSISTENT
Reliability level
Determined by the default
reliability level specified
for the queue or topic
space in the service
integration bus
Best effort nonpersistent
Express nonpersistent
Reliable nonpersistent
Reliable 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
Chapter 15. Properties of XMS objects
569
Property of:
ConnectionFactory
The reliability level of persistent messages that are sent using the connection.
The valid values of the property are as follows:
Valid value
XMSC_WPM_MAPPING_AS_DESTINATION
XMSC_WPM_MAPPING_BEST_EFFORT_NON_
PERSISTENT
XMSC_WPM_MAPPING_EXPRESS_NON_
PERSISTENT
XMSC_WPM_MAPPING_RELIABLE_NON_
PERSISTENT
XMSC_WPM_MAPPING_RELIABLE_PERSISTENT
XMSC_WPM_MAPPING_ASSURED_PERSISTENT
Reliability level
Determined by the default
reliability level specified
for the queue or topic
space in the service
integration bus
Best effort nonpersistent
Express nonpersistent
Reliable nonpersistent
Reliable 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:
570
Message Service Clients for C/C++ and .NET
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.
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
XMSC_WPM_BOOTSTRAP_HTTP
XMSC_WPM_BOOTSTRAP_TCP
Name of the bootstrap transport
chain
BootstrapTunneledMessaging
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.
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.
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.
Chapter 15. Properties of XMS objects
571
The valid values of the property are as follows:
Valid value
XMSC_WPM_TARGET_SIGNIFICANCE_
PREFERRED
XMSC_WPM_TARGET_SIGNIFICANCE_
REQUIRED
Meaning
A messaging engine in the target
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.
The selected messaging engine must
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
XMSC_WPM_TARGET_TRANSPORT_CHAIN_BASIC
Name of transport chain
InboundBasicMessaging
The default value of the property is
XMSC_WPM_TARGET_TRANSPORT_CHAIN_BASIC.
XMSC_WPM_TARGET_TYPE
Data type:
xmsINT
Property of:
ConnectionFactory
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.
572
Message Service Clients for C/C++ and .NET
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.
By default, the property is not set, which means that the name of a temporary
topic does not have a prefix.
Chapter 15. Properties of XMS objects
573
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.
574
Message Service Clients for C/C++ and .NET
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:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, 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
575
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. 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 IBM’s application programming interfaces.
Trademarks
The following terms are trademarks of International Business Machines
Corporation in the United States, other countries, or both:
IBM
zSeries
System/390
WebSphere
Intel is a trademark of Intel Corporation in the United States, other countries, or
both.
Linux is a trademark of Linus Torvalds in the United States, other countries, or
both.
576
Message Service Clients for C/C++ and .NET
Notices
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
577
578
Message Service Clients for C/C++ and .NET
Index
Special characters
.NET
getting properties 80
installing XMS 17
interfaces 421
setting properties 80
using exception listeners 81
using message listeners 81
using the PropertyContext class
writing applications 79
80
A
acknowledging messages 43
administered objects 45
introduction 7
working with 97
application configuration file 33, 34, 36
application, unexpected termination 30
applications
building your own 27
sample
building 26, 27
description 24
running 26
writing
general 39
in C 59
in C# 79
in C++ 67
assigning XMS objects in C++ 74
asynchronous message delivery 44
attribute, introduction 6
B
body types of messages 89
building applications
sample 26, 27
your own 27
byte array
C functions returning by reference 63
C functions returning by value 63
C++ methods returning 69
bytes message 91
BytesMessage class
interface definition
for C 123
for C++ 275
C
C
additional functions
classes 121
compilers 8
functions accepting a
functions returning a
functions returning a
269
string as input 64
byte array by value
string by value 62
© Copyright IBM Corp. 2005
63
C (continued)
functions returning a string or byte array by reference 63
getting properties 60
handling errors 64
object handles
data types 59
introduction 4
setting properties 60
using exception listener functions 61
using message listener functions 60
using the PropertyContext class 60
writing applications 59
C#
writing applications 79
C++
application, using the C API 76
assigning XMS objects 74
classes 273
compilers 8
getting properties 69
handling errors 69
methods returning a byte array 69
setting properties 69
using exception listeners 73
using message listeners 72
using namespaces 67
using the PropertyContext class 69
using the String class 68
writing applications 67
CCSID 56
cleanup, for non-durable subscribers 51
closing a connection 40
coded character set identifier (CCSID) 56
command line options 13
compiler flag settings 27
compilers 8
configuring
for an application that connects to a queue manager 21
for an application that connects to a service integration
bus 23
for an application that uses a real-time connection to a
broker 22
connecting to a service integration bus 41
Connection class
interface definition
for C 136
for C++ 285
introduction 4
object properties 527
connection factories, administered objects
introduction 7
working with 97
ConnectionFactory class
interface definition
for C 141
for C++ 290
introduction 4
object properties 528
ConnectionMetaData class
interface definition
for C 144
579
ConnectionMetaData class (continued)
interface definition (continued)
for C++ 293
object properties 530
connections
closing 40
handling exceptions 41
introduction 40
starting 40
stopping 40
constants, .NET property names 80
converting a property value to another data type
G
getting properties
in .NET 80
in C 60
in C++ 69
H
53
D
data types compatible with Java 89
deleting objects 52
delivering messages to an application
asynchronously 44
synchronously 45
Destination class
interface definition
for C 145
for C++ 295
introduction 4
object properties 530
destinations
administered objects
introduction 7
working with 97
introduction 45
temporary 48
durable subscribers 49
E
environment variables 31, 33, 35
LD_LIBRARY_PATH 26
PATH 26
ErrorBlock class
interface definition 150
errors
handling in C 64
handling in C++ 69
Exception class
interface definition
for C++ 299
exception listener functions, using
exception listeners, using in .NET
exception listeners, using in C++
ExceptionListener class
interface definition
for C 154
for C++ 303
ExceptionListener delegate (.NET)
in C 61
81
73
442
F
First Failure Data Capture (FFDC)
.NET applications 36
C and C++ applications 31
580
33, 34, 35
Message Service Clients for C/C++ and .NET
handles, object
data types 59
introduction 4
handling errors
in C 64
in C++ 69
handling exceptions on a connection
HTTP tunnelling 41
41
I
IBytesMessage interface (.NET) 424
IConnection interface (.NET) 434
IConnectionFactory interface (.NET) 438
IDestination interface (.NET) 441
IIConnectionMetaData interface (.NET) 440
IllegalStateException class
interface definition 304
IllegalStateException interface (.NET) 443
IMapMessage interface (.NET) 449
IMessage interface (.NET) 459
IMessageConsumer interface (.NET) 467
IMessageListener delegate (.NET) 472
IMessageProducer interface (.NET) 475
InitialContext class
interface definition
for C 155
for C++ 305
object properties 531
InitialContext interface (.NET) 444
installation wizard 11, 17
installed directories
Linux 13
Solaris 13
Windows 18
Windows (C/C++) 15
installing silently 13
installing XMS
.NET 17
Linux 11
Solaris 11
Windows 11
InvalidClientIDException
.NET 446
InvalidClientIDException class
interface definition 308
InvalidDestinationException class
interface definition 309
InvalidDestinationException interface
.NET 447
InvalidSelectorException class
interface definition 310
InvalidSelectorException interface
.NET 448
IObjectMessage interface (.NET) 482
IPropertyContext interface (.NET) 483
IQueueBrowser interface (.NET) 493
ISession interface (.NET) 499
IStreamMessage interface (.NET) 511
Iterator class
interface definition
for C 157
for C++ 311
iterators 55
ITextMessage interface (.NET) 521
J
Java compatible data types 89
JMS_IBM_CHARACTER_SET property 534
JMS_IBM_ENCODING property 534
JMS_IBM_EXCEPTION_MESSAGE property 535
JMS_IBM_EXCEPTION_PROBLEM_DESTINATION
property 535
JMS_IBM_EXCEPTION_REASON property 536
JMS_IBM_EXCEPTION_TIMESTAMP property 536
JMS_IBM_FEEDBACK property 536
JMS_IBM_FORMAT property 537
JMS_IBM_LAST_MSG_IN_GROUP property 537
JMS_IBM_MSGTYPE property 537
JMS_IBM_PUTAPPLTYPE property 538
JMS_IBM_PUTDATE property 538
JMS_IBM_PUTTIME property 538
JMS_IBM_REPORT_COA property 539
JMS_IBM_REPORT_COD property 539
JMS_IBM_REPORT_DISCARD_MSG property 540
JMS_IBM_REPORT_EXCEPTION property 540
JMS_IBM_REPORT_EXPIRATION property 541
JMS_IBM_REPORT_NAN property 542
JMS_IBM_REPORT_PAN property 542
JMS_IBM_REPORT_PASS_CORREL_ID property 542
JMS_IBM_REPORT_PASS_MSG_ID property 543
JMS_IBM_SYSTEM_MESSAGEID property 543
JMSX_APPID property 543
JMSX_DELIVERY_COUNT property 544
JMSX_GROUPID property 544
JMSX_GROUPSEQ property 544
JMSX_USERID property 545
L
LD_LIBRARY_PATH environment variable 26
Linux
compilers 8
installed directories 13
installing XMS 11
uninstalling Message Service Client for C/C++
log file creation, Linux or Solaris 13
log file, creating 13
16
M
map message 91
MapMessage class
interface definition
for C 159
for C++ 314
mapping XMS messages onto WebSphere MQ messages
message
body 89
body type
bytes 91
map 91
object 92
94
message (continued)
body type (continued)
stream 92
text 93
bytes 91
delivery
asynchronous 44
synchronous 45
delivery mode 45
header fields 85
map 91
object 92
properties
application defined 89
IBM defined 87
introduction 86
JMS defined 87
selectors 93
stream 92
text 93
Message class
interface definition
for C 174
for C++ 325
introduction 4
object properties 531
message listener functions, using in C 60
message listeners, using in .NET 81
message listeners, using in C++ 72
message model, XMS 8
Message object
header fields 85
properties
application defined 89
IBM defined 87
introduction 86
JMS defined 87
Message producers
no associated destination 49
Message Service Client for .NET
installing 17
Message Service Client for C/C++
installing 11
installing from command line 13
MessageConsumer class
interface definition
for C 189
for C++ 337
introduction 4
object properties 533
MessageEOFException
.NET 470
MessageEOFException class
interface definition 341
MessageFormatException
.NET 471
MessageFormatException class
interface definition 342
MessageListener class
interface definition
for C 193
for C++ 343
MessageNotReadableException
.NET 473
MessageNotReadableException class
interface definition 344
Index
581
MessageNotWritableException
.NET 474
MessageNotWritableException class
interface definition 345
MessageProducer class
interface definition
for C 194
for C++ 346
introduction 4
object properties 533
messages
acknowledging 43
mapping onto WebSphere MQ messages 94
messaging
point-to-point 4
publish/subscribe 4
styles 4
MQMD header
mapping XMS messages onto WebSphere MQ
messages 94
MQRFH2 header
mapping XMS messages onto WebSphere MQ
messages 94
XMSC_WMQ_TARGET_CLIENT property 565
multithreaded
applications 39
runtime libraries 27
N
namespaces, using in C++ 67
non-durable subscribers
cleanup of queues 51
non-existent properties, .NET 80
nonpersistent messages 45
O
object handles
data types 59
introduction 4
object message 92
object model, XMS 4
object properties 527
ObjectMessage class
interface definition
for C 203
for C++ 355
objects
administered
introduction 7
working with 97
deleting 52
operating environments 8
P
PATH environment variable 26
persistent messages 45
point-to-point messaging 4
problem determination
errors that cannot be handled at run time
FFDC 36
FFDC and trace 31, 33, 34, 35
introduction 29
runtime errors 29
582
30
Message Service Clients for C/C++ and .NET
process CCSID 57
process CCSID functions 270
properties
Connection object 527
ConnectionFactory object 528
ConnectionMetaData object 530
Destination object 530
getting
in .NET 80
in C 60
in C++ 69
InitialContext object 531
introduction 527
Message object
application defined 89
IBM defined 87
introduction 86
JMS defined 87
list of properties 531
MessageConsumer object 533
MessageProducer object 533
Session object 533
setting
in .NET 80
in C 60
in C++ 69
properties of objects 527
property
definitions 533
introduction 6
JMS_IBM_CHARACTER_SET 534
JMS_IBM_ENCODING 534
JMS_IBM_EXCEPTION_MESSAGE 535
JMS_IBM_EXCEPTION_PROBLEM_DESTINATION
JMS_IBM_EXCEPTION_REASON 536
JMS_IBM_EXCEPTION_TIMESTAMP 536
JMS_IBM_FEEDBACK 536
JMS_IBM_FORMAT 537
JMS_IBM_LAST_MSG_IN_GROUP 537
JMS_IBM_MSGTYPE 537
JMS_IBM_PUTAPPLTYPE 538
JMS_IBM_PUTDATE 538
JMS_IBM_PUTTIME 538
JMS_IBM_REPORT_COA 539
JMS_IBM_REPORT_COD 539
JMS_IBM_REPORT_DISCARD_MSG 540
JMS_IBM_REPORT_EXCEPTION 540
JMS_IBM_REPORT_EXPIRATION 541
JMS_IBM_REPORT_NAN 542
JMS_IBM_REPORT_PAN 542
JMS_IBM_REPORT_PASS_CORREL_ID 542
JMS_IBM_REPORT_PASS_MSG_ID 543
JMS_IBM_SYSTEM_MESSAGEID 543
JMSX_APPID 543
JMSX_DELIVERY_COUNT 544
JMSX_GROUPID 544
JMSX_GROUPSEQ 544
JMSX_USERID 545
XMSC_CLIENT_CCSID
definition 545
use in code page conversion 56
XMSC_CLIENT_ID 546
XMSC_CONNECTION_TYPE 546
XMSC_DELIVERY_MODE 546
XMSC_IC_SECURITY_CREDENTIALS 547
XMSC_IC_URL 547
XMSC_IS_SUBSCRIPTION_MULTICAST 548
535
property (continued)
XMSC_IS_SUBSCRIPTION_RELIABLE_MULTICAST
XMSC_JMS_MAJOR_VERSION 548
XMSC_JMS_MINOR_VERSION 548
XMSC_JMS_VERSION 549
XMSC_MAJOR_VERSION 549
XMSC_MINOR_VERSION 549
XMSC_PASSWORD 549
XMSC_PRIORITY 549
XMSC_PROVIDER_NAME 550
XMSC_RTT_CONNECTION_PROTOCOL 550
XMSC_RTT_HOST_NAME 551
XMSC_RTT_LOCAL_ADDRESS 551
XMSC_RTT_MULTICAST 551
XMSC_RTT_PORT 552
XMSC_TIME_TO_LIVE 553
XMSC_USERID 553
XMSC_VERSION 553
XMSC_WMQ_BROKER_CONTROLQ 554
XMSC_WMQ_BROKER_PUBQ 554
XMSC_WMQ_BROKER_QMGR 554
XMSC_WMQ_BROKER_SUBQ 554
XMSC_WMQ_BROKER_VERSION 555
XMSC_WMQ_CCSID 555
XMSC_WMQ_CHANNEL 556
XMSC_WMQ_CONNECTION_MODE 556
XMSC_WMQ_DUR_SUBQ 556
XMSC_WMQ_ENCODING 557
XMSC_WMQ_FAIL_IF_QUIESCE 558
XMSC_WMQ_HOST_NAME 558
XMSC_WMQ_LOCAL_ADDRESS 559
XMSC_WMQ_MESSAGE_SELECTION 560
XMSC_WMQ_MSG_BATCH_SIZE 560
XMSC_WMQ_POLLING_INTERVAL 561
XMSC_WMQ_PORT 561
XMSC_WMQ_PUB_ACK_INTERVAL 561
XMSC_WMQ_QMGR_CCSID 561
XMSC_WMQ_QUEUE_MANGER 562
XMSC_WMQ_RECEIVE_EXIT 562
XMSC_WMQ_RECEIVE_EXIT_INIT 563
XMSC_WMQ_SECURITY_EXIT 563
XMSC_WMQ_SECURITY_EXIT_INIT 563
XMSC_WMQ_SEND_EXIT 564
XMSC_WMQ_SEND_EXIT_INIT 564
XMSC_WMQ_SYNCPOINT_ALL_GETS 565
XMSC_WMQ_TARGET_CLIENT 565
XMSC_WMQ_TEMP_Q_PREFIX 566
XMSC_WMQ_TEMPORARY_MODEL 566
XMSC_WPM_BUS_NAME 566
XMSC_WPM_CONNECTION_PROTOCOL 567
XMSC_WPM_CONNECTION_PROXIMITY 567
XMSC_WPM_DUR_SUB_HOME 567
XMSC_WPM_HOST_NAME 568
XMSC_WPM_LOCAL_ADDRESS 568
XMSC_WPM_ME_NAME 569
XMSC_WPM_NON_PERSISTENT_MAP 569
XMSC_WPM_PERSISTENT_MAP 569
XMSC_WPM_PORT 570
XMSC_WPM_PROVIDER_ENDPOINTS 570
XMSC_WPM_TARGET_GROUP 571
XMSC_WPM_TARGET_SIGNIFICANCE 571
XMSC_WPM_TARGET_TRANSPORT_CHAIN 572
XMSC_WPM_TARGET_TYPE 572
XMSC_WPM_TEMP_Q_PREFIX 573
XMSC_WPM_TEMP_TOPIC_PREFIX 573
XMSC_WPM_TOPIC_SPACE 574
548
Property class
interface definition
for C 205
for C++ 357
PropertyContext class
interface definition
for C 220
for C++ 369
using in .NET 80
using in C 60
using in C++ 69
publish/subscribe messaging
4
Q
queue browser, using 51
queue uniform resource identifiers (URIs)
QueueBrowser class
interface definition
for C 236
for C++ 381
48
R
receiving messages
asynchronously 44
synchronously 45
removing Message Service Client for .NET
Windows
using Add/Remove Programs 19
removing Message Service Client for C/C++
Linux 16
Windows
by running the uninstaller program 16
using Add/Remove Programs 16
repository of administered objects
introduction 7
supported types 97
Requestor class
interface definition
for C 239
for C++ 384
Requestor interface (.NET) 495
requestor, using 52
ResourceAllocationException
.NET 497
ResourceAllocationException class
interface definition 387
response files, for samples 24
return codes 64
running the sample applications 26
runtime libraries 27
S
sample applications
building 27
building C or C++ 26
description 24
running 26
SecurityException
.NET 498
SecurityException class
interface definition 388
selectors, message 93
service integration bus, connecting to
41
Index
583
Session class
interface definition
for C 241
for C++ 389
introduction 4
object properties 533
sessions
asynchronous message delivery 44
introduction 42
synchronous message delivery 45
transacted 42
setting properties
in .NET 80
in C 60
in C++ 69
setup
for an application that connects to a queue manager 21
for an application that connects to a service integration
bus 23
for an application that uses a real-time connection to a
broker 22
silent installation 13
Solaris
compilers 8
installed directories 13
installing XMS 11
starting a connection 40
stopping a connection 40
stream message 92
StreamMessage class
interface definition
for C 254
for C++ 402
string
C functions accepting as input 64
C functions returning by reference 63
C functions returning by value 62
String class
interface definition 412
using in C++ 68
styles of messaging 4
subscriber queue 49
synchronous message delivery 45
T
temporary destinations 48
text message 93
TextMessage class
interface definition
for C 267
for C++ 416
threading model 39
topic uniform resource identifiers (URIs)
trace, configuring 31, 33, 34, 35
trademarks 576
transacted sessions 42
TransactionInProgressException
.NET 522
TransactionInProgressException class
interface definition 418
TransactionRolledBackException
.NET 523
TransactionRolledBackException class
interface definition 419
584
46
Message Service Clients for C/C++ and .NET
U
uniform resource identifiers (URIs)
introduction 45
queue 48
topic 46
uninstalling Message Service Client for .NET
Windows
using Add/Remove Programs 19
uninstalling Message Service Client for C/C++
Linux 16
Windows
by running the uninstaller program 16
using Add/Remove Programs 16
URI 45
W
wildcard characters
in topic URIs 46
in trace specifications 33, 34, 35
Windows
compilers 8
installed directories (.NET) 18
installed directories (C/C++) 15
installing XMS 11
uninstalling Message Service Client for .NET
using Add/Remove Programs 19
uninstalling Message Service Client for C/C++
by running the uninstaller program 16
using Add/Remove Programs 16
writing applications
general 39
in C 59
in C# 79
in C++ 67
X
XMS
compilers 8
installing 11
message model 8
object model 4
operating environments 8
threading model 39
XMSC_CLIENT_CCSID property
definition 545
use in code page conversion 56
XMSC_CLIENT_ID property 546
XMSC_CONNECTION_TYPE property 546
XMSC_DELIVERY_MODE property 546
XMSC_IC_SECURITY_CREDENTIALS property 547
XMSC_IC_URL property 547
XMSC_IS_SUBSCRIPTION_MULTICAST property 548
XMSC_IS_SUBSCRIPTION_RELIABLE_MULTICAST
property 548
XMSC_JMS_MAJOR_VERSION property 548
XMSC_JMS_MINOR_VERSION property 548
XMSC_JMS_VERSION property 549
XMSC_MAJOR_VERSION property 549
XMSC_MINOR_VERSION property 549
XMSC_PASSWORD property 549
XMSC_PRIORITY property 549
XMSC_PROVIDER_NAME property 550
XMSC_RTT_CONNECTION_PROTOCOL property 550
XMSC_RTT_HOST_NAME property 551
XMSC_RTT_LOCAL_ADDRESS property 551
XMSC_RTT_MULTICAST property 551
XMSC_RTT_PORT property 552
XMSC_TIME_TO_LIVE property 553
XMSC_USERID property 553
XMSC_VERSION property 553
XMSC_WMQ_BROKER_CONTROLQ property 554
XMSC_WMQ_BROKER_PUBQ property 554
XMSC_WMQ_BROKER_QMGR property 554
XMSC_WMQ_BROKER_SUBQ property 554
XMSC_WMQ_BROKER_VERSION property 555
XMSC_WMQ_CCSID property 555
XMSC_WMQ_CHANNEL property 556
XMSC_WMQ_CONNECTION_MODE property 556
XMSC_WMQ_DUR_SUBQ property 556
XMSC_WMQ_ENCODING property 557
XMSC_WMQ_FAIL_IF_QUIESCE property 558
XMSC_WMQ_HOST_NAME property 558
XMSC_WMQ_LOCAL_ADDRESS property 559
XMSC_WMQ_MESSAGE_SELECTION property 560
XMSC_WMQ_MSG_BATCH_SIZE property 560
XMSC_WMQ_POLLING_INTERVAL property 561
XMSC_WMQ_PORT property 561
XMSC_WMQ_PUB_ACK_INTERVAL property 561
XMSC_WMQ_QMGR_CCSID property 561
XMSC_WMQ_QUEUE_MANGER property 562
XMSC_WMQ_RECEIVE_EXIT property 562
XMSC_WMQ_RECEIVE_EXIT_INIT property 563
XMSC_WMQ_SECURITY_EXIT property 563
XMSC_WMQ_SECURITY_EXIT_INIT property 563
XMSC_WMQ_SEND_EXIT property 564
XMSC_WMQ_SEND_EXIT_INIT property 564
XMSC_WMQ_SYNCPOINT_ALL_GETS property 565
XMSC_WMQ_TARGET_CLIENT property 565
XMSC_WMQ_TEMP_Q_PREFIX property 566
XMSC_WMQ_TEMPORARY_MODEL property 566
XMSC_WPM_BUS_NAME property 566
XMSC_WPM_CONNECTION_PROTOCOL property 567
XMSC_WPM_CONNECTION_PROXIMITY property 567
XMSC_WPM_DUR_SUB_HOME property 567
XMSC_WPM_HOST_NAME property 568
XMSC_WPM_LOCAL_ADDRESS property 568
XMSC_WPM_ME_NAME property 569
XMSC_WPM_NON_PERSISTENT_MAP property 569
XMSC_WPM_PERSISTENT_MAP property 569
XMSC_WPM_PORT property 570
XMSC_WPM_PROVIDER_ENDPOINTS property 570
XMSC_WPM_TARGET_GROUP property 571
XMSC_WPM_TARGET_SIGNIFICANCE property 571
XMSC_WPM_TARGET_TRANSPORT_CHAIN property 572
XMSC_WPM_TARGET_TYPE property 572
XMSC_WPM_TEMP_Q_PREFIX property 573
XMSC_WPM_TEMP_TOPIC_PREFIX property 573
XMSC_WPM_TOPIC_SPACE property 574
XMSException interface (.NET) 524
XMSFactoryFactory interface (.NET) 525
Index
585
586
Message Service Clients for C/C++ and .NET
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: idrcf@hursley.ibm.com
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
587
588
Message Service Clients for C/C++ and .NET
Printed in USA
SC34-6658-00
Download PDF
Similar pages