Progress SonicESB - Configuration and Management Guide

Configuration and Management Guide
V7.6
Progress Sonic ESB Product Family: Configuration and Management Guide V7.6
2008 Progress Software Corporation. All rights reserved.
Progress software products are copyrighted and all rights are reserved by Progress Software Corporation. This manual is also
copyrighted and all rights are reserved. This manual may not, in whole or in part, be copied, photocopied, translated, or reduced to
any electronic medium or machine-readable form without prior consent, in writing, from Progress Software Corporation.
The information in this manual is subject to change without notice, and Progress Software Corporation assumes no responsibility for
any errors that may appear in this document.
The references in this manual to specific platforms supported are subject to change.
A (and design), Actional, Actional (and design), Affinities Server, Allegrix, Allegrix (and design), Apama, Business Empowerment,
ClientBuilder, ClientSoft, ClientSoft (and Design), Clientsoft.com, DataDirect (and design), DataDirect Connect, DataDirect
Connect64, DataDirect Connect OLE DB, DataDirect Technologies, DataDirect XQuery, DataXtend, Dynamic Routing
Architecture, EasyAsk, EdgeXtend, Empowerment Center, Fathom, IntelliStream, Neon, Neon New Era of Networks, O (and
design), ObjectStore, OpenEdge, PeerDirect, Persistence, POSSENET, Powered by Progress, PowerTier, ProCare, Progress,
Progress DataXtend, Progress Dynamics, Progress Business Empowerment, Progress Empowerment Center, Progress Empowerment
Program, Progress Fast Track, Progress OpenEdge, Progress Profiles, Progress Results, Progress Software Developers Network,
ProVision, PS Select, SequeLink, Shadow, ShadowDirect, Shadow Interface, Shadow Web Interface, ShadowWeb Server, Shadow
TLS, SOAPStation, Sonic ESB, SonicMQ, Sonic Orchestration Server, Sonic Software (and design), SonicSynergy, SpeedScript,
Stylus Studio, Technical Empowerment, Voice of Experience, WebSpeed, and Your Software, Our Technology-Experience the
Connection are registered trademarks of Progress Software Corporation or one of its subsidiaries or affiliates in the U.S. and/or other
countries. AccelEvent, Apama Dashboard Studio, Apama Event Manager, Apama Event Modeler, Apama Event Store, AppsAlive,
AppServer, ASPen, ASP-in-a-Box, BusinessEdge, Cache-Forward, DataDirect Spy, DataDirect SupportLink, DataDirect XML
Converters, Future Proof, Ghost Agents, GVAC, Looking Glass, ObjectCache, ObjectStore Inspector, ObjectStore Performance
Expert, Pantero, POSSE, ProDataSet, Progress ESP Event Manager, Progress ESP Event Modeler, Progress Event Engine, Progress
RFID, PSE Pro, SectorAlliance, SmartBrowser, SmartComponent, SmartDataBrowser, SmartDataObjects, SmartDataView,
SmartDialog, SmartFolder, SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow, Sonic, Sonic
Business Integration Suite, Sonic Process Manager, Sonic Collaboration Server, Sonic Continuous Availability Architecture, Sonic
Database Service, Sonic Workbench, Sonic XML Server, The Brains Behind BAM, WebClient, and Who Makes Progress are
trademarks or service marks of Progress Software Corporation or one of its subsidiaries or affiliates in the U.S. and other countries.
Vermont Views is a registered trademark of Vermont Creative Software in the U.S. and other countries. IBM is a registered trademark
of IBM Corporation. JMX and JMX-based marks and Java and all Java-based marks are trademarks or registered trademarks of Sun
Microsystems, Inc. in the U.S. and other countries. Any other trademarks or service marks contained herein are the property of their
respective owners.
Third Party Acknowledgements:
SonicMQ and Sonic ESB Product Families include code licensed from RSA Security, Inc. Some portions licensed from IBM are
available at http://oss.software.ibm.com/icu4j/.
SonicMQ and Sonic ESB Product Families include the JMX Technology from Sun Microsystems, Inc. Use and Distribution is subject
to the Sun Community Source License available at http://sun.com/software/communitysource.
SonicMQ and Sonic ESB Product Families include software developed by the ModelObjects Group (http://www.modelobjects.com).
Copyright 2000-2001 ModelObjects Group. All rights reserved. The name "ModelObjects" must not be used to endorse or promote
products derived from this software without prior written permission. Products derived from this software may not be called
"ModelObjects", nor may "ModelObjects" appear in their name, without prior written permission. For written permission, please
contact djacobs@modelobjects.com.
SonicMQ and Sonic ESB Product Families include files that are subject to the Netscape Public License Version 1.1 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.mozilla.org/NPL/. Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY
OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the
License. The Original Code is Mozilla Communicator client code, released March 31, 1998. The Initial Developer of the Original
Code is Netscape Communications Corporation. Portions created by Netscape are Copyright 1998-1999 Netscape Communications
Corporation. All Rights Reserved.
SonicMQ and Sonic ESB Product Families include versions 8.3 and 8.9 of the Saxon XSLT and XQuery Processor from Saxonica
Limited (http://www.saxonica.com/) which is available from SourceForge (http://sourceforge.net/projects/saxon/). The Original
Code of Saxon comprises all those components which are not explicitly attributed to other parties. The Initial Developer of the
Original Code is Michael Kay. Until February 2001 Michael Kay was an employee of International Computers Limited (now part of
Fujitsu Limited), and original code developed during that time was released under this license by permission from International
Computers Limited. From February 2001 until February 2004 Michael Kay was an employee of Software AG, and code developed
during that time was released under this license by permission from Software AG, acting as a "Contributor". Subsequent code has been
developed by Saxonica Limited, of which Michael Kay is a Director, again acting as a "Contributor". A small number of modules, or
enhancements to modules, have been developed by other individuals (either written specially for Saxon, or incorporated into Saxon
having initially been released as part of another open source product). Such contributions are acknowledged individually in comments
attached to the relevant code modules. All Rights Reserved. The contents of the Saxon files are subject to the Mozilla Public License
Version 1.0 (the "License"); you may not use these files except in compliance with the License. You may obtain a copy of the License
at http://www.mozilla.org/MPL/. Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY
OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the
License.
SonicMQ and Sonic ESB Product Families include software developed by IBM. Copyright 1995-2002 and 1995-2003 International
Business Machines Corporation and others. All rights reserved. Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons
to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all copies
of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS
INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL
DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. Except as contained in this notice, the name of a copyright holder
shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written
authorization of the copyright holder.
SonicMQ and Sonic ESB Product Families include software Copyright 1999 CERN - European Organization for Nuclear Research.
Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee,
provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in
supporting documentation. CERN makes no representations about the suitability of this software for any purpose. It is provided "as
is" without expressed or implied warranty.
SonicMQ and Sonic ESB Product Families includes software developed by the University Corporation for Advanced Internet
Development <http://www.ucaid.edu>Internet2 Project. Copyright 2002 University Corporation for Advanced Internet
Development, Inc. All rights reserved. Neither the name of OpenSAML nor the names of its contributors, nor Internet2, nor the
University Corporation for Advanced Internet Development, Inc., nor UCAID may be used to endorse or promote products derived
from this software and products derived from this software may not be called OpenSAML, Internet2, UCAID, or the University
Corporation for Advanced Internet Development, nor may OpenSAML appear in their name without prior written permission of the
University Corporation for Advanced Internet Development. For written permission, please contact opensaml@opensaml.org.
Portions of SonicMQ and Sonic ESB Product Families were created using JThreads/C++ by Object Oriented Concepts, Inc.
SonicMQ and Sonic ESB Product Families were developed using ANTLR
SonicMQ and Sonic ESB Product Families include software Copyright 1991-2007 DataDirect Technologies Corp. All rights
reserved. This product includes DataDirect products for the Microsoft SQL Server database which contain a licensed implementation
of the Microsoft TDS Protocol.
SonicMQ and Sonic ESB Product Families include software developed by the OpenSSL Project for use in the OpenSSL Toolkit
(http://www.openssl.org/). Copyright (c) 1998-2007 The OpenSSL Project. All rights reserved. This product includes cryptographic
software written by Eric Young (eay@cryptsoft.com). This product includes software written by Tim Hudson (tjh@cryptsoft.com).
Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com). All rights reserved. The names "OpenSSL Toolkit" and "OpenSSL
Project" must not be used to endorse or promote products derived from this software without prior written permission. For written
permission, please contact openssl-core@openssl.org. Products derived from this software may not be called "OpenSSL" nor may
"OpenSSL" appear in their names without prior written permission of the OpenSSL Project. Software distributed on an "AS IS" basis,
WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and
limitations under the License agreement that accompanies the product.
February 2008
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Progress Sonic ESB Product Family Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Worldwide Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
12
13
14
15
Part I: ESB Configuration Tools and Managed Components

Chapter 1: Using Progress Sonic ESB
Configuration and Management Tools19
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sonic Management Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ESB Configured Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ESB Admin Tool and Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Basic Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SonicFS Maintenance Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ESB Type Maintenance Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
License Container Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Management Container Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deployment Tool Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Shutting Down Sonic Components and Sonic ESB Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
20
21
26
33
34
35
37
39
39
40
47
Contents
Chapter 2: ESB Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Creating ESB Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
ESB Container Intra-container Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
Viewing or Editing ESB Container Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Managing the Services Associated with an ESB Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Adding Services or ESB Process Entry Points to an ESB Container . . . . . . . . . . . . . . . . . . . . .59
Deleting ESB ContainerServices from an ESB Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Changing the Number of Listeners on Services in ESB Containers . . . . . . . . . . . . . . . . . . . . .61
Deploying an ESB Container in a Management Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
Setting Test Mode for ESB Containers Used in Development. . . . . . . . . . . . . . . . . . . . . . . . . .62
Adding JAR files to an ESB Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Changing the State of Management and ESB Containers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
Monitoring Service Metrics and Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Standard Metrics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Standard Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71
Enabling Integration with Actional for Visualization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Logging and Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Using Activation Daemons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
Creating an Activation Daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
Adding an Activation Daemon to a Management Container . . . . . . . . . . . . . . . . . . . . . . . . . . .79
Adding an ESB Container to an Activation Daemons Activation List . . . . . . . . . . . . . . . . . . .81
Chapter 3: ESB Endpoints and Connections. . . . . . . . . . . . . . . . . . . . . . . . . . .83

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
ESB Addresses and References to Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
Entry Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Exit Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Fault Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Rejected Message Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Evaluating Endpoint Requirements on JMS Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
When to Use Topics, When to Use Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
Multiple Brokers, Clusters, and Nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
Configuring Progress SonicMQ Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
Deleting Progress SonicMQ Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99
Fault Tolerant Connections and Reconnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99
Inbound and Outbound Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Fault Tolerant Connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Quality of Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102
Setting the Ping Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
6
Contents
Configuring Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Deleting Progress SonicMQ Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Chapter 4: Configuring Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
111
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Configuring WebService Protocols for ESB Processes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Related Configuration Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Part II:
Configuring XML Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Chapter 5: Monitoring and Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Metrics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 6: Performance Tuning XML Servers . . . . . . . . . . . . . . . . . . . . . . . .

Tools for Tuning XML Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Properties on an XML Service Type Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Properties on a Component in an ESB Container . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting JVM System Properties on a Management Container . . . . . . . . . . . . . . . . . . . . . . . .
Tuning XML Services and Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transactions and Concurrency Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tuning Action Flows, Transactions, and XML Services . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tuning XML Service Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tuning Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tuning Data Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Distributing Documents in Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Message Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Locations for Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tuning Storage Maintenance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing the Transaction Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPath Expressions and XSLT Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPath Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLT Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
117
118
118
121
123
125
126
127
128
129
130
130
132
136
139
140
140
141
143
144
145
146
146
148
Contents
Chapter 7: Backing Up and Restoring Document Collections . . . . . .151

Backing Up Sonic XML Server Document Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152
Designing a Backup Schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152
Files Generated by the Backup and Restore Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
Using the Backup Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
Performing Full Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157
Performing Incremental Backup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158
Restoring Sonic XML Server Document Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158
Using the Restore Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
Restoring from Full Backup Images. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
Restoring from Incremental Backup Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161
Part III:
Configuring Database Services . . . . . . . . . . . . . . . . . . . . .163
Chapter 8: Using the Database Service JDBC Drivers . . . . . . . . . . . . . . .165

JDBC Driver Connection Properties and the Database Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166
Load Balancing, Failover, and Connection Retry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166
Client Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168
Connection Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169
Connection Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170
Specifying Primary and Alternate Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172
Using Activation Daemons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173
Chapter 9: Driver Connection Properties and Data Types by Database Brand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
Progress OpenEdge Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
Progress OpenEdge Connection Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
Progress OpenEdge Connection Failover Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181
Specifying Alternate Servers for the Progress OpenEdge Driver . . . . . . . . . . . . . . . . . . . . . .182
Progress OpenEdge Driver Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184
DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185
DB2 Driver Connection Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185
DB2 Driver Connection Failover Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .198
Specifying Alternate Servers for the DB2 Driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .198
DB2 Driver Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .200
Informix. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .201
Informix Driver Connection Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .201
Informix Driver Connection Failover Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209
8
Contents
Specifying Alternate Servers for the Informix Driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Informix Driver Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Oracle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Oracle Driver Connection Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Oracle Driver Connection Failover Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying Alternate Servers for the Oracle Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Oracle Driver Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Microsoft SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Microsoft SQL Server Driver Connection Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Microsoft SQL Server Driver Connection Failover Properties. . . . . . . . . . . . . . . . . . . . . . . .
Specifying Alternate Servers for the Microsoft SQL Server Driver . . . . . . . . . . . . . . . . . . . .
Microsoft SQL Server Driver Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sybase Driver Connection Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sybase Driver Connection Failover Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying Alternate Servers for the Sybase Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sybase Driver Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
209
210
212
212
223
224
225
227
227
238
238
240
242
242
252
252
254
Chapter 10: SQL Escape Sequences for JDBC
257
258
258
265
266
......................
Date, Time, and Timestamp Escape Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scalar Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Outer Join Escape Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Procedure Call Escape Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 11: Configuring SQL Server Windows Authentication . . . .
267
Setting the Authentication Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Registering Service Principal Names (SPNs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Setting the Active Directory Encryption Property. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Contents
Part IV:
Configuring and Managing BPEL Services . . . . . .271
Chapter 12: Configuring BPEL Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273

Overview of BPEL Service Initialization Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .274
Specifying a BPEL Archive (.bpar) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .277
Setting Persistence Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .278
BPEL Development Container Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .282
Enabling Audit Trails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .282
Audit Trails and Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .283
Setting a Default Partner Link. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .284
Considerations with Dehydrated Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .285
Chapter 13: Managing BPEL Services
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .287
Overview of BPEL Service and Process Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .288
Clearing Process History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289
Terminating Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .290
Searching for Process Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .290
Viewing Audit Trails. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .294
BPEL Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10
297
Preface
This Preface contains the following sections:
About This Guide describes this manual and its intended audience.
Typographical Conventions describes the text formatting, syntax notation, and

flags used in this manual.
Progress Sonic ESB Product Family Documentation describes the books and API
online references packaged with the Sonic ESB Product Family.
Worldwide Technical Support provides information on how to contact Progress

Softwares customer support and evaluation support for the Progress Sonic ESB
Product Family.
11
Preface
About This Guide

This guide is intended for system administrators. This book is in four parts:
Part I, ESB Configuration Tools and Managed Components, includes the chapters:
Chapter 1, Using Progress Sonic ESB Configuration and Management Tools

introduces Progress Sonic ESB and its configuration and management tools.
Chapter 2, ESB Containers describes ESB Containers and Activation

Daemons.
Chapter 3, ESB Endpoints and Connections describes how to use ESB

components and resources.
Chapter 4, Configuring Web Services describes using Web Service standards in

the configuration and management of ESB components and resources.
Part II, Configuring XML Servers, includes the chapters:
Chapter 5, Monitoring and Logging, describes Progress Sonic XML Server

metrics, notifications, and logging.
Chapter 6, Performance Tuning XML Servers, includes suggestions to

optimize XML Server configuration and application design.
Chapter 7, Backing Up and Restoring Document Collections, describes how to

backup and restore Progress Sonic XML Server document collections.
Part III, Configuring Database Services, includes the chapters:
Chapter 8, Using the Database Service JDBC Drivers, explains how to

configure load balancing, failover, and connection retry for connections made
using the drivers.
Chapter 9, Driver Connection Properties and Data Types by Database Brand,

describes the properties and data types for several database brands: Progress
OpenEdge, DB2, Informix, Oracle, Microsft SQL Server, and Sybase.
Chapter 10, SQL Escape Sequences for JDBC, describes the JDBC-defined
escape sequences containing standard syntaxes for several language features.
Chapter 11, Configuring SQL Server Windows Authentication, describes how

to use Windows authentication on Microsoft SQL Server with the Progress Sonic
Database Service JDBC SQL Server driver.
Part IV, Configuring and Managing BPEL Services, includes the chapters:
Chapter 12, Configuring BPEL Services, explains how to configure configure

BPEL services.
Chapter 13, Managing BPEL Services, describes how to manage BPEL

services.
12
Typographical Conventions
Typographical Conventions
This section describes the text formatting conventions used in this guide and a description
of notes, warnings, and important messages. This guide uses the following typographical
conventions:
Bold typeface in this font indicates keyboard key names (such as Tab or Enter) and
the names of windows, menu commands, buttons, and other Sonic user interface
elements. For example, From the File menu, choose Open.
Bold typeface in this font emphasizes new terms when they are introduced.
Monospace typeface indicates text that might appear on a computer screen other than
the names of Sonic user-interface elements, including:
Code examples and code that the user must enter
System output such as responses and error messages
Filenames, pathnames, and software component names, such as method names
Bold monospace typeface emphasizes text that would otherwise appear in monospace
typeface to emphasize some computer input or output in context.
Monospace typeface in italics or Bold monospace typeface in italics (depending

on context) indicates variables or placeholders for values you supply or that might
vary from one case to another.
This guide uses the following syntax notation conventions:
Brackets ([ ]) in syntax statements indicate parameters that are optional.
Braces ({ }) indicate that one (and only one) of the enclosed items is required. A
vertical bar (|) separates the alternative selections.
Ellipses (...) indicate that you can choose one or more of the preceding items.
This guide highlights special kinds of information by shading the information area, and
indicating the type of alert in the left margin.
Note Note indicates information that complements the main text flow. Such information is
especially important for understanding the concept or procedure being discussed.

Important Important indicates information that must be acted upon within the given context in order
for the procedure or task (or other) to be successfully completed.

Warning Warning indicates information that can cause loss of data or other damage if ignored.
13
Preface
Progress Sonic ESB Product Family Documentation

The Sonic ESB Product Family provides the following documentation:
Introducing the Progress Sonic ESB Product Family Introduces components of the
Sonic ESB Product FamilySonic ESB, Sonic Database Service, Sonic XML
Server, and Sonic BPEL Server.
Progress Sonic ESB Product Family: Installation and Upgrade Guide Provides
information about installing, updating, and upgrading Sonic ESB components.
Progress Sonic ESB Product Family: Developers Guide (Progress Sonic Workbench
Online Help) Provides information about developing, testing, and debugging
applications on the Progress Sonic Workbench. Describes the Sonic Workbench, its
editors, and tools. Provides information about how to get started with each component
of the Sonic ESB Product Family and describes sample applications.
Progress Sonic ESB Product Family: Configuration and Management Guide

Provides information about configuring and managing components used by the Sonic
ESB Product Family. Describes deployment configurations for Sonic ESB, Sonic
Database Service, Sonic XML Server, and Sonic BPEL Server
Progress Sonic ESB Product Family: Deployment Guide Provides information

about moving development projects into test and production environments. Describes
recommended build procedures, domain mappings, and reporting features.
Progress Sonic BPEL Server: Management API Guide Describes how to use the
management API to programatically access BPEL server functionality.
Sonic ESB API Reference Online JavaDoc compilation of the Sonic ESB APIs.
14
Worldwide Technical Support
Worldwide Technical Support

Progress Softwares Sonic support staff can provide assistance from the resources on their
Web site at www.progress.com/sonic. There you can access technical support for licensed
Progress Sonic editions to help you resolve technical problems that you encounter when
installing or using Sonic SOA products.
When contacting Technical Support, please provide the following information:
The release version number and serial number of SonicMQ that you are using. This
information is listed on the license addendum. It is also at the top of the SonicMQ
Broker console window and might appear as follows:
SonicMQ Continuous Availability Edition [Serial Number nnnnnnn]
Release nnn Build Number nnn Protocol nnn
The release version number and serial number of Sonic ESB that you are using. This
information is listed on the license addendum. It is also near the top of the console
window for a Sonic ESB Container. For example:
Sonic ESB Fault Tolerant Edition [Serial Number: nnnnnnn]
Release nnn Build Number nnn
You can alternatively access version information programmatically for installed

Sonic components using the Version class in the Sonic API. See the Upgrading
Sonic ESB Product Family Components chapter in Progress Sonic ESB Product
Family: Installation and Upgrade Guide for instructions.
Note
The platform on which you are running Progress Sonic ESB Product Family products,
and any other relevant environment information.
The Java Virtual Machine (JVM) your installation uses.
Your name and, if applicable, your company name.
E-mail address, telephone, and fax numbers for contacting you.
15
Preface
16
Part I
ESB Configuration Tools

and Managed Components
Part I contains the following chapters:
Chapter 1, Using Progress Sonic ESB Configuration and Management Tools
Chapter 2, ESB Containers
Chapter 3, ESB Endpoints and Connections
Chapter 4, Configuring Web Services
17
18
Chapter 1
Using Progress Sonic ESB Configuration

and Management Tools
Chapter 1 describes the tools for configuring and managing the Progress Sonic ESB
product family:
Overview describes how and where the Sonic ESB tools are used.
Sonic Management Console introduces this tool for managing and monitoring
components deployed in containers, including ESB Containers and Progress
SonicMQ brokers. This section also describes the ESB Configured Objects section,
used for configuring components such as ESB Containers, endpoints, services, and
ESB processes, and deploying them in an ESB Container.
ESB Admin Tool and Commands introduces this tool for command line actions that
configure Progress Sonic ESB containers and components, and manage the lifecycle
of Progress Sonic ESB components in management containers.
For information about the Sonic ESB developmemt environment, see the Progress Sonic
ESB Product Family: Deployment Guide in the Sonic Workbenchs Eclipse help.
Important This book assumes that you have deployment installations of Progress Sonic V7.6
products. While the Sonic Workbench has the same toolset, Sonics integration of the
tools into the development environment precludes direct access to these tools. As such, if
you are using the Sonic Workbench, you might find some Start menu commands and
some screenshots in this chapter inconsistent with those in a Workbench installation. You
should avoid manipulating files that support a Sonic Workbench in its Directory Service
unless explicitly instructed to do so, as you could cause unpredictable behavior in your
SonicWorkbench.
19
Chapter 1: Using Progress Sonic ESB Configuration and Management Tools
Overview
The tools provided for configuring and managing Sonic ESB are independent of any
Sonic domain. The tools are typically installed on systems where runtime components
will not run. They connect to domains over the internet protocols to connect to a
management broker for a domain for viewing and maintaining the configuraton objects in
that domain. As a result, administrators can disconnect, relocate, and reconnect to diverse,
distributed domains whenever and wherever needed.
Whats a Sonic domain? A Sonic domain is an administrative grouping of Progress
Sonic management containers, and brokers administered by one central management

node, its Domain Manager. The domain manager is defined by its components:
A management container that provides caching facilities, communicates with its

management node (the broker it hosts), and hosts the other components of the domain
manager.
A broker dedicated to management communications for the domain managers two

essential functions, the Directory Service and the Agent Manager.
A Directory Service that provides a centralized point for configuration information,

runtime management, and configuration storage.
An Agent Manager that monitors the state of all management containers in the
domain.
For information about the domain manager, see the Introduction to Configuration
chapter in the Progress SonicMQ Configuration and Management Guide and the
Distributing Components chapter in the Progress SonicMQ Deployment Guide.
To use the Sonic ESB configuration and management tools, you must have a domain
manager installed and the administration tools for SonicMQ and Sonic ESB installed. See
the Progress Sonic ESB Product Family: Installation and Upgrade Guide for information
on a variety of installations of these product features.
Once the software is installed and acessible, the first step is to start the domain manager.
To start a domain manager:
On Windows, choose:
Start > Programs > Progress > Sonic 7.6 > Start Domain Manager
20
On UNIX or Linux, set a console window to the Progress SonicMQ installation

directory, and type ./bin/startcontainer.sh and press Return.
Sonic Management Console

The Sonic Management Console (SMC) provides a graphic interface for configuring,
managing, and monitoring configureed objects in the Sonic domain as well as launching
supporting tools.
To start the Sonic Management Console:
On Windows, choose:
Start > Programs > Progress > Sonic 7.6 > Sonic Management Console
On UNIX or Linux, set a console window to the Progress SonicMQ installation

directory, and type ./bin/startmc.sh and press Return.
The Sonic Management Console opens. The Create Connection dialog box opens, as
shown:
A Connection Name, the Domain Name, and its Connection URL are required when
security is not enabled on the management broker. When security is enabled on the
management broker, an authentic User Name and Password are also required. The
dialog box displays all the default values except the default users password:
Administrator.
21

To connect the Management Console to the domain:
1.
Enter the connection information for the domain:

Property
Description
Connection Name
Identity to be associated with this connection.
Domain Name
Name of the domain.
Connection URL(s)
URL(s) of the management broker(s).
User Name
The user name for connection.
Password
The password of the user.
For information about using the Advanced settings, see the Sonic Management
Console chapter in the Progress SonicMQ Configuration and Management Guide.
2.
22
Click OK. A Connecting... dialog box and the status bar indicate that the Sonic
Management Console is connecting to the management broker for a domain.
The Sonic Management Console opens a connection window to the domain, and
shows its objects in the Configure view. The following example shows the ESB
Containers folder selected:

3.
In the left panel, expand System > DBService > 7.6 > lib:
These are the supporting files for the configuration objects. They are accessed
through the Sonic File System, SonicFS. Sonic ESB Containers and Sonic
Workbench use the sonicfs protocol to reference files in SonicFS, for example,
sonicfs:///System/DBService/7.6/lib/ssoracle.jar.
The Resources folder stores files you create and that you will reference by
connecting to the domain manager where they are stored and using the syntax
sonicfs:///Resources/myFile. A resource is the term used for a file in SonicFS used
by Progress Sonic ESB components. Resources are referenced in parameters for
services, ESB processes, endpoints, and connections. Resource files can be accessed
from SonicFS. For example, a service can read a script file directly from SonicFS.
23

4.
Select the Manage tab and expand Containers. The following example shows the
runtime state of several containers:
The containers shown in this figure are:
DomainManager The default name of the domain managers container makes it

easy to recognize. It is highlighted in green, indicating that it is running and all its
hosted components are online.
myHost The default name of the additional broker in a typical SonicMQ install
takes the name of the host system. It is highlighted in red, indicating that it is not
running (and therefore its hosted components are offline.)
Service 1 Container through Service 5 Container The five management

containers used for services installed in this domain are all running and the container
that is expanded, Service4 Container, shows that its hosted component Service4 ESB
Container is online.
VerificationContainer Hosts the service to verify a containers setup is offline. See

Verifying an ESB Container Installation in the Progress Sonic ESB Product Family:
Installation and Upgrade Guide for more information about using this container.
24

5.
If you have another domain running, connect to it. The following figure shows two
domain connections in a Sonic Management Console.
The following section explains how to work with the ESB Configured Objects section in
the Configure tab of the Sonic Management Console.
25
ESB Configured Objects

The ESB Configured Objects section, located in the Configure tab of the Sonic
Management Console, enables you to configure ESB Containers, endpoints, services, and
ESB processes. The following procedure describes how to work with the ESB Configured
Objects section in the SMC.
Note The ESB Configured Objects section is available when:
1.
The Sonic installation where the Sonic Management Console (SMC) is launched
includes both the SonicMQ tools and the Sonic ESB tools.
2.
A domain where the Management Console is connected has been enabled by a Sonic
ESB Tools installation.
If the Sonic ESB Tools are not installed for this SMC, yet the domain is enabled for Sonic
ESB, the ESB Configured Objects section is not shown. You can see the /System files for
SonicESB and the /ESB Containers objectsusing a default iconas shown:
You should not attempt to manipulate these objects under these circumstances.
In the reverse casethe Sonic ESB tools are installed for this SMC, but the connected
domain is not Sonic ESB enabledthe ESB Configured Objects section is not shown.
See the Progress Sonic ESB Product Family: Installation and Upgrade Guide for
information about tools installations and the option to specify a domain to be enabled for
the tools.
26

To work with the ESB Configured Objects section in the SMC:
1.
With the Sonic Management Console connected to a domain that has been enabled
for Sonic ESB, the ESB Configured Objects section is available in the Configure tab:
This section can be expanded and contracted by double-clicking ESB Configured

Objects. In this example, the section is shown expanded.
27

2.
In the left panel, click on a container node in the ESB Containers folder, as shown:
The services in the selected ESB Container are listed in the right panel.
3.
28
Click on a name in the right panel to display its information and modifiable
parameters.
See Overview on page 50 for more information about ESB Containers.

4.
Click on an endpoint name in the Endpoints folder, as shown:
The endpoints for the selected endpoint name are displayed in the right panel. A tab
provides access to the connections for the selected endpoint.
5.
Click on an endpoint name in the right panel to display its information and modifiable
parameters.
6.
Choose the Connections tab to see the connections.
7.
Click on a connection in the right panel to display its information and modifiable
parameters.
See Configuring Progress SonicMQ Endpoints on page 95 for more information
about endpoints.
29

8.
In the left panel, click on a service in the Services folder, as shown:
The services of the selected Service type are listed in the right panel.
9.
30
Click on a service in the right panel to display its information and modifiable
parameters. Note that each service type shows its own unique set of initialization
parameters.
Some initialization parameters specify explicit values, and some specify variables. If
an initialization parameter specifies a variable, and the initialization parameter is
editable, you can modify the variable value directly. If you specify a variable, the
system replaces the variable with a parameter value at runtime.
When a variable is used, the system has to obtain an actual parameter value from a
data source. To determine the data source, the system examines the variable itself. The
variable's syntax indicates where the system can find the parameter value. The syntax
for variables is show below (the dollar sign, braces, and colons are literals; the
brackets enclose optional elements):
${variable_source_type:[source_type_qualifier:]parameter_identifier}
where variable_source_type is one of the following string literals:
container The parameter value is defined in the deployment properties of the

ESB container into which the service type is deployed.
system The parameter value is defined in a JVM system property.
property The parameter value from a Java properties file.

and source_type_qualifier is the following string literal:
dynamic The parameter value is dynamically extracted from a specified

properties file. This qualifier is required if variable_source_type is property and
you do not want the property file read from a local cache.
and parameter_identifier is one of the following:
A valid SonicFS URL indicating a property in a Java properties file for

example:
${property:sonicfs:///workspace/myProject/src/myService.properties#myProp}
Name of an ESB container property or name of a JVM system property. If it is the

name of an ESB container property, variable_source_type must be container. If it
is the name of JVM system property, then variable_source_type must be system.
You can edit variables directly, or you can use the Global Parameter dialog box.
For more information, see the Progress Sonic ESB Product Family Developers Guide
in the Eclipse help.
31

10.
Click on Processes, as shown:
The processes are listed in the right panel. In the right panel, choosing a process
displays its information and modifiable parameters.
For more information, see the Progress Sonic ESB Product Family Developers Guide
in the Eclipse help.
32
ESB Admin Tool and Commands

While you can perform most configuration and administrative tasks with the Sonic
Management Console, you can also use the ESB Admin Tool to configure Progress Sonic
ESB containers and components, and to manage the lifecycle of Progress Sonic ESB
components deployed in management containers. You can also use the ESB Container to
manage the Directory Service (SonicFS). One of the most common uses of the ESB
Admin Tool is to import and export service types, services, endpoints, and connections.
See the Progress Sonic ESB Product Family: Deployment Guide for information on using
ESB Admin commands to move configurations from one domain to another.
To start the ESB Admin Tool:
1.
Select Start > Programs > Progress > Sonic 7.6 > Tools > ESB Admin Tool.
The ESB Admin Tool console window opens.
2.
In a default installation, enter the following to connect to the domain manager:

connect Domain1 tcp://localhost:2506 Administrator Administrator
See the following sections and the connect command for additional information.
After using the ESB Admin Tool, follow this procedure to stop the session.
To stop an ESB Admin Tool session:
In an ESB Admin Tool console window, type exit or bye and press Enter.
Each of the ESB Container commands is described in the following section.

Note ESB Admin Tool commands are not case sensitive. Many values are case sensistive; for
example, trying to connect to Domain1, yet entering domain1 will not succeed.
33
Basic Commands
Most of the commands act on a connected Directory Service store so connect is typically
the first command entered in an ESB Admin session.
connect
connect domain URL [username password] [managementNode]
Connect to the domain manager at the specified URL. For example:

connect Domain1 tcp://myHost:2506 anAdmin aPwd
where:
is the Directory Service store where administration will occur.

URL is the IP address or DNS name resolvable to the broker and port of a management
broker of Domain in the form protocol://host:port. A URL list can be used when
delimited by commas and enclosed in quotes. For example:
Domain
connect Domain1 tcp://myHost:2506,tcp://myHostBackup:2506 anAdmin aPwd
username password are
the administrator credentials for authentication on the broker.

managementNode is the routing definition name on the non-management broker or
cluster that routes management communications to the management node. For more
information, see the Management Over Dynamic Routing in the Multiple Nodes
and Dynamic Routing chapter of the Progress SonicMQ Deployment Guide.
Note that the syntax of the connect command requires that, if you need to specify a
managementNode, username and password must be specified as well.
disconnect
disconnect
Disconnect from the domain manager.

exit
bye
exit
The exit commands stop the tool and close its window.
help
help
The help commands list the available ESB Admin commands and their syntax.
34
SonicFS Maintenance Commands

The following file and Directory Service actions are used in maintenance of the Sonic File
System, SonicFS.
add file
add file name filename [override]
Add a file as a resource to the domain with the specified name. If a resource already exists
with that name, the command fails unless you specify override on the command line.
For example, to import PO.xml to the specified location in SonicFS, creating f1 and f2 in
the process:
ESBAdmin> add file /f1/f2/PO.xml C:\PO.xml
Adding file into Directory Service...
name
= /f1/f2/PO.xml
file
= C:\PO.xml
override = false
For example, to import C:\PO.xml to /Resources in SonicFS:

ESBAdmin> add file PO.xml C:\PO.xml
Adding file into Directory Service...
name
= PO.xml
file
= C:\PO.xml
override = false
add directory
add directory sonicfs_directory source_directory
Recursively add the specified source directory (on disk) to the SonicFS in the Directory
Service store. The sonicfs_directory argument can specify a fully qualified path in
SonicFS. If sonicfs_directory is not fully qualified, it is assumed to be in the /Resources
directory in SonicFS.
For example, to add the local directory, myDir, to SonicFS:
add directory /Resources/myDir c:/myDir
35
delete file
delete file filename
Delete the file named filename from the domain. If a fully qualified path is not specified,
the file is assumed to be in the /Resources directory in SonicFS.
For example, to delete def.xml from the /Resources directory in SonicFS:
delete file def.xml
delete directory
delete directory sonicfs_directory
Delete the specified directory from domain

Also deletes all subdirectories and files in those directories.
export file
export file name filename
Export a file from the domain to the specified file and path. The export command is
supported for all file types and supports paths and explicitly specified directories. The
name argument can specify a fully qualified path in SonicFS. If name is not fully qualified,
the file is assumed to be in /Resources.
For example, to export def.xml from /Resources in SonicFS to c:\Testfiles, enter:
export file def.xml c:\Testfiles\def.xml
export directory
export directory sonicfs_directory target_directory
Recursively export the specified directory from the domain to the specified target
directory.
36
ESB Type Maintenance Commands

Several commands that perform actions in the connected domain are qualified by a type
value. The list and dump commands can optionally specify a type. The import, export,
and delete commands require a type parameter to refine the scope of their action.
The following types are valid for the ESB Admin Tool commands that use the type
variablelist, dump, export, import, and delete:
Type Value
accessor
connection
connectionType
endpoint
endpointType
file
license
params
process
service
serviceType
xq_container
list
list [type]
List the names of configurations in the domain. For example, to list the available types:
list
To list the service types in sonicfs:///Resources:

list serviceType
The list command can be constrained to specified directories. For example, to list the
contents of /f1/f2:
list file /f1/f2
If /f1/f2 are subfolders in the /Resources folder, specify the full location:
list file /Resources/f1/f2
37
dump
dump [type] [name] [filename]
Dump is an advanced command. You might be requested to use a specified dump syntax
by Sonic technical support.
To dump all available types, enter dump.
To dump a type, add the type value you want. For example, to dump the endpoints, enter
dump endpoint. The result is a file on the local file system named dump.txt that has all the
endpoints in XML format. The file is placed in the start directory of the tool,
sonic_install_dir/MQ7.6/bin.
dump endpoint ESBSampleQ9
Generates a file on the local file system named dump.txt that has only the endpoint
ESBSampleQ9 in XML format.
dump endpoint ESBsampleQ9 C:\dumpedQ9.txt
Generates a file on the local file system at C:\dumpedQ9.txt that has only the endpoint
ESBSampleQ9 in XML format.
A dump in XML format is useful for storing information, but you should use export rather
than dump in deployments.
export
export type name filename
Export a configuration from a specified type into the domain as the specified file.
The export command supports all configuration types.
import
import type filename [override]
Import a configuration from a specified file into the domain as the specified type. If a
configuration exists with the name defined in the body of the XML file, the command
fails. Specify override to force an overwrite of an existing configuration.
delete
delete type name
Delete a configuration from the domain of the specified type and name.
38
License Container Commands

You can add or export a Sonic ESB license key (control number) in the connected domain.
Within a domain, there is a single ESB license for each version.
add license container
add license container license_key [version]
Add the Progress Sonic ESB license key to SonicFS. The specified license key overwrites
any Sonic ESB license key already in SonicFS. Use the version parameter to add multiple
licenses. Specify the version in the format, Major.Minor, for example, 7.6.
export license container
export license container [version]
Display the license container to the console. Use the version parameter to export an earlier
versions license. Specify the version in the format, Major.Minor, for example, 7.6.
ESBAdmin> export license container 7.6
Displaying license key (control number) for version 7.6 ...
Control Number = nnnnnnnnnnnnnnn
Management Container Commands

Information about containers and operational actions in the connected domain can be
performed by the ESB Container.
container list
container list
Lists the management containers in the domain, with their state, view name, host (when
online), and components.
container shutdown
container shutdown container_name
Shuts down the specified management container (not ESB Container). For example:
container shutdown containerName
39
container status
container status container_name
Reports the status of a management container. For example:

ESBAdmin> container status DomainManager
Container Name = DomainManager, State = Online,
Container Config Name = /Containers/DomainManager,
Host = NBSRUSSO3.bedford.progress.com
Component Name = ActivationDaemon1, State = Online
Component Name = Broker1, State = Online
container [suspend | resume | reload]

container [suspend|resume|reload] container_name component_name
Perform the specified operation on the management container and ESB Container
(a component of the management container).
Deployment Tool Commands

Deployment tool commands are in the following categories:
Analysis for deployment
Exporting for deployment
Tailoring archives for import
Importing or merging for deployment
Analysis for Deployment

The analysis commandsdiff, mqdepends, mqrevdepends, and impactcontrast archive
files, file system structures, and Directory Service stores for differences and
dependencies.
Note The analysis commands are one aspect of the set of deployment tools used in Sonic ESB
deployments. See the Progress Sonic ESB Product Family: Deployment Guide for
information about this set of commands and the import and export tools that facilitate
deployment.
These commands do not require that a connect command was executed as they either work
with file systems and archives outside the Directory Service or establish their connections
within the command.
40
The general syntax of the analysis commands is:
Uses one or more storeType, each with storeParams as follows:
The first -storeType storeParams identifies the source artifact store, and
the next -storeType storeParams identifies the target artifact store.
storeType is { xar | fs | ds }.
storeParams are:
When storeType is xar, the archive location on a file system
When storeType is fs, the root of the hierarchy on a file system
When storeType is ds, the management connection to a domain in the form:

domain url [username password] [managementNode]
Every analysis command produces an output file. The out parameter specifies the
preferred location of the .xml file that reports on the analysis. The directory hierarchy
you specify must exist for the command to succeed.
If you do not specify an output file, a default file is created in the ESB Admin Tools
working directory as follows:
Analysis Tool
Default Output File
diff
Sonic_Diff.xml
mqdepends
Sonic_Dependency.xml
mqrevdepends
Sonic_ReverseDependency.xml
impact
Sonic_ImpactAnalysis.xml
Some analysis commands provide a v switch to enable enhanced verbosity.
41
diff
diff -storeType storeParams -storeType storeParams [-out outFile.xml] [-v]
The diff command assesses the difference between two artifact stores. Unlike a generic
differencing engine, the ESBAdmin diff only assesses specific filetypes in certain store
types. The stores can be Sonic archive filesXAR files(-xar store type), file systems
(-fs store type), or Directory Service stores (-ds store type).
Differences include:
Artifacts that are in both stores yet do not have identical content. You can choose to
identify only that the files are dissimilar or to expose the differences in detail.
Artifacts that are in the source store but not in the target store
Artifacts that are in the target store but not in the source store
As an example, a command comparing a XAR file with a Directory Service store is:
diff -xar sourceStore.xar -ds Domain1 myHost:2506 aUser aPassword
mqdepends
mqdepends -storeType storeParams -out outputFile.xml
[-include artifact1 [artifact2 ...] | -includeFile artifactListFile]
where the optional parameters include:
artifact1 artifact2 ...(a series of specific files in the store to analyze)
artifactListFile (a text file that provides a list of files in the store to analyze)
The mqdepends command assesses a source artifact store to evaluate and report on the
dependencies of ESB artifacts on SonicMQ configuration objects. You can use this
information to create or verify the existence of the specified dependencies in a target
Directory Service store. The stores can be a Sonic archive file, file system, or a Directory
Service store.
Sonic ESB dependencies on SonicMQ artifacts include:
Endpoints for their destination dependencies (topics, queues, or routing).
ESB connections for SonicMQ connection parameters (and, therefore, the broker
location and port where static destinations must be created.
As an example, to produce a dependency report on specified files:
mqdepends -fs C:/myinstalldir/ESB -include processA serviceA serviceB
42
mqrevdepends
mqrevdepends -storeType storeParams [-out outFile.xml]
[-include artifact1 [artifact2 ...] | -includeFile artifactListFile]
where the optional parameters include:
artifact1 artifact2 ... is a series of specific files in the store to analyze
artifactListFile is text file that provides a list of files in the store to analyze
The mqrevdepends command assesses a source artifact store to evaluate and report on the
dependencies of ESB artifacts on SonicMQ configuration objects. You can use this
information to create or verify the existence of the specified dependencies in a target
Directory Service store.
Reverse dependency produces the same set of information as a dependency. However, the
information indicates a required SonicMQ configuration element, and then the ESB
artifacts that depend on it.
As an example, to produce a reverse dependency report on a list of specific files:
mqrevdepends -fs C:/fileDir/ESB -includeFile artifactList.txt
Impact
impact -storeType storeParams -storeType storeParams [-out outFile.xml] [-v]
Assessing impact on a Directory Service store requires a connect command to establish a

connection to the domain prior to invoking impact.
An impact analysis report combines features of diff and mqdepends. Together, these
features define the impact on the target store that would result from merging the source
store into the target store.
Because this report assesses impact, the following information is also included:
If a binary file type is different, the impact analysis report indicates that the file in the
source store will overwrite the one in the target store.
If a file exists in the source store but not in the target store, the impact analysis report
indicates that a new file will be added to the target store. However, if a file exists in
the target store but not in the source store, it is not reported as it is not impacted and
will not be affected by any import actions.
If a dependency indicates that SonicMQ configuration objects must be created, the

impact analysis report describes the requirement. Conversely, if existing SonicMQ
configuration objects are no longer required, the impact analysis report notes that fact.
As an example, to report on the impact of an archive on a Directory Service store:
impact -xar sourceStore.xar -ds Domain1 myHost:2506 aUser aPwd
43
Exporting for Deployment

The deployment export commands create bootfiles and exported artifacts for deployment
to other domains. The Progress Sonic ESB Product Family: Deployment Guide provides
information on using these commands.
export fs
export fs targetFileSysPath [sourceFileSysPath | exportPropFile | all]
Export to a file system path as a file structure.

export archive
export archive targetArchiveFile [sourceArchiveFile | exportPropFile | all]
Export to a Sonic archive file.

export bootfile
export bootfile container_config_name [filename]
Create a boot file to use when starting an ESB Container. By default a boot file is created
in the current working directory with the name, bootname.xml Optionally, specify a file
name to have the boot file created elsewhere.
Tailoring Archives for Import

The tailoring commands create intermediate files that are tuned for a target domain so you
can map archives for import into the domain to the characteristics of the target domain.
The Progress Sonic ESB Product Family: Deployment Guide provides information on
using these commands.
createMap
createMap archive_file map_file [rules file]
Create a tailoring map file that is edited and then applied to a Sonic archive using the
applyMap command.
applyMap
applyMap input_archive_file map_file output_archive file [log file]
Create a tailored archive from a source archive and a tailoring map file.
44
Importing or Merging for Deployment

The import and merge commands transfer the source data into the connected domain.
The Progress Sonic ESB Product Family: Deployment Guide provides information on
using these commands.
import fs
import fs sourceFileSysPath [importPropFile | override]
Import into a domain from a file system path as a file structure where:
sourceFileSysPath is the root of the file system hierarchy that contains the files to be
imported into the connected Directory Services store.
One of the following arguments is used:
importPropFile When an import properties file was created and saved, it can
be applied as a parameter of the command to apply the defined overwrite and
ignore settings.
override Set overwrite of matching files to true.

import archive
import archive sourceArchiveFile [importPropFile | override]
Import into a domain from a Sonic Archive file.
45
merge (standard form)

merge -storeType storeParams -storeType storeParams [-out outFile.xml] [-v]
where:
The first -storeType storeParams identifies the source artifact store, and
the next -storeType storeParams identifies the target artifact store.
storeType is { xar | fs | ds }.
storeParams are:
When storeType is xar, the archive location on a file system
When storeType is fs, the root of the hierarchy on a file system
When storeType is ds, the management connection to a domain in the form:

domain url [username password] [managementNode]
The out parameter lets you specify the preferred location of the .xml file that reports
on the analysis. If you do not specify an output file, a default file (Sonic_Merge.xml)
is created in the ESB Containers working directory
-v requests verbose reporting
For example, to merge an archive into a Directory Service store:

merge -xar sourceStore.xar -ds Domain1 myHost:2506 aUser aPwd -out c:\out.xml
merge (compound form)

A variation in the syntax of the merge command enables the merger of two source stores
into a target store. As a result, the target store is acted on but the two source stores are
unmodified. The source and target stores can be XAR files, file systems, or Directory
Service stores.
The syntax of the advanced merge command in the Sonic ESB Admin Tool is:
merge -sourceStore1Type sourceStore1Params
-sourceStore2Type sourceStore2Params
-targetStoreType targetStoreParams
[-out outFile.xml]
[-v]
where the variation from a standard merge is that sourceStore1 and sourceStore2 are two
distinct source types with their respective parameters that will be sequentially merged into
the target store.
For example, to merge a XAR and a file system into a target file system:
merge -xar source.xar -fs C:/sourceDir/ESB -fs C:/targetDir/ESB -out c:\out.xml
46
Shutting Down Sonic Components and Sonic ESB Tools
Shutting Down Sonic Components and Sonic ESB Tools

To shut down the tools and components in a Progress Sonic ESB environment, perform
an orderly shutdown of Sonic components, and then stop the tools. The following
procedure assumes that you want to stop all the components in connected domains, and
then stop the tools in the local installation.
If you want to stop all the components that are running on the local system where the tools
were started, connect to that domain so that you can perform actions on its components.
To perform an orderly shut down of Sonic components:
In each domain, shut down any running containers:

1.
In the Sonic Management Console, select the Manage tab.
2.
Choose the containers folders, typically /Containers
3.
Right-click on each container name you want to stop, and select

Operations > Shutdown.
4.
Be sure to shut down the container named DomainManager last.
The specified configuration objects are stopped.

To shut down Sonic ESB tools:
1.
Shortly after you stop a domain manager where tools are connected, you are prompted
that there is problem trying to resume connection. That is to be expected. Close the
open windows within the Sonic Management Console to stop their connections.
2.
If the JMS Test Client is running, close it.
3.
If the ESB Container is running, enter bye to stop it.
4.
In the Sonic Management Console, select Action > Exit.
The Sonic ESB tools are stopped.
47
48
Chapter 2
ESB Containers
Progress Sonic ESB is a framework composed of classes and APIs for architecting,
developing, and configuring distributed services. This framework includes an ESB
Container, a centralized configuration service, and key routing and processing services.
This chapter explains how to work with Sonic ESB Containers and describes services and
messages in the Sonic ESB framework.
This chapter contains the following sections:
Overview
Creating ESB Containers
Managing the Services Associated with an ESB Container
Deploying an ESB Container in a Management Container
Changing the State of Management and ESB Containers
Monitoring Service Metrics and Notifications
Enabling Integration with Actional for Visualization
Logging and Tracing
Using Activation Daemons

Note The tasks in this chapter are oriented toward deployment specialists. Sonic ESB Product
Familys development environment, the Sonic Workbench, manages ESB Containers,

starting and stopping them for you, often automatically. When you add or remove
services and processes to your development environment, you do not have to perform
most of the tasks described in this chapter. In the Sonic Workbench, you can perform
many of these actions in the Containers view. See the Sonic ESB Product Family:
Developers Guide in Sonic Workbench online help.
49
Chapter 2: ESB Containers
Overview
ESB Containers host services, endpoints, and ESB processes. Configuration information
is provided to an ESB Container from a centralized Directory Service. The Directory
Service notifies containers of configuration changes and updates each containers cache
of configuration information. An ESB Container also provides access to a common log
file for all the services it hosts. In addition to ESB processes, services, and endpoints, ESB
Container components include:
Management framework access Provides access to the centralized configuration

store and standard facilities for managing the containers assets.
Connectivity components Manage connections and communication with external

resources, including JMS. They include the endpoint manager for access to existing
endpoints (by name) or creation of new ones.
Services and ESB processes Handle the application-level components or services

and manage the interaction of service code with the environment, including the
application manager (which controls the lifecycle of ESB services,) the service
application (which sets up each instance of a service) and the dispatcher (which
passes each message to a service and sends processed messages to the next destination
or endpoint.)
Factory objects Create instances of objects that services require:
MessageFactory Creates new messages to be sent.
EnvelopeFactory Creates new envelopes to associate messages with addresses.
AddressFactory Creates addresses for envelopes allowing messages to be sent

to an ESB process, service, or endpoint.
An ESB Container manages the lifecycle of services and creates a pool of connections to
JMS endpoints (destinations). Each ESB Container within a Sonic domain must have a
unique name.
50
Overview
When an ESB Container starts up, it follows this sequence:

1.
The management container reads its local boot file. This file contains the name of the
management container as well as the connection information (URL, username, and
password) used in enabling the management communications layer. The connection
information must be the same as that used by the Directory Service. This file can be
encrypted (see the Configuring Framework Components chapter in the Progress
SonicMQ Configuration and Management Guide).
2.
The container enables management communications and makes a request for its basic
configuration information.
3.
The Directory Service replies with the name of the ESB Container in the management
container (plus other components, such as an Activation Daemon).
4.
The configuration of the ESB Container is requested.
5.
The Directory Service replies with the list of services to be run within the ESB
Container.
6.
The ESB Container starts its internal components, including services and
connections. This often involves additional requests from the Directory Service for
additional configuration information.
7.
During startup, the ESB Container might make additional JMS connections required
by the services it supports. These connections are independent of the initial
management connection. Typically, the usernames and passwords for these
application connections are different from the username and password used for
management connections.
A running ESB Container continues to make management requests on its own and
responds to administrative requests from the management tools, such as the Sonic
Management Console. Some reasons for this additional communication include:
Additional configuration information is needed by a service. These requests are

directed to the Directory Service, (for example, process configurations.)
Management tools send life cycle management commands to the management

container, for example, to suspend operation, reload configuration information, or
initiate a shutdown operation.
Requests for status from other components or tools.
51
The following events occur as the ESB Container manages message transfer:
1.
The ESB Container reads configuration information from the Directory Service.
2.
The ESB Container establishes JMS connections to Progress SonicMQ destinations

(topics or queues).
3.
The ESB Container pools JMS connections.
4.
Messages arriving on their Progress SonicMQ destinations are allocated to services

that implement the XQService interface by calling their service( ) method, using the
predefined Quality of Service (QoS)EXACTLY_ONCE, AT_LEAST_ONCE, or BEST_EFFORT.
5.
Messages are processed by the services.
6.
Output messages are generated by the services and placed in an OUTBOX.
7.
Messages in the OUTBOX are sent to SonicMQ destinations by the services, or to other
services in the container.
An ESB Container is deployed as a component in a management container. The

management container caches all the information that it looks up in its domain managers
Directory Service store. If the domain manager is not accessible and the management
container is not looking up any new configurations (including resources such as
stylesheets, new services, or endpoints) at that time, then the container can continue
running despite the domain manager failure. However, if a new configuration is necessary
that is not cached, it must wait for the Directory Service to be restarted.
In addition to providing configuration information, a management container also provides
access to a common log file for all of the components it hosts. (For information on
container caching and logging, see the Configuring Containers and Collections and
Managing Containers and Collections chapters in the Progress SonicMQ Configuration
and Management Guide.)
The following sections describe how to manage installed ESB Containers and create new
ESB Containers. Use the Sonic Management Console to add Progress Sonic ESB
components to a container.
52

The following procedure describes how to create an ESB Container using the ESB
Configured Objects section of the Sonic Management Console.
To create a new ESB Container:
1.
In the left panel in the Sonic Management Console, under the ESB Configured
Objects node, click the ESB Containers folder.
2.
In the right panel, click New. The entry fields for the ESB container are as shown:
53

3.
In the ESB Container Maintenance section, specify the following properties:

Property
Description
Name
The name of the ESB container.
Intra-container
Messaging
Select to allow the container to bypass the overhead of sending and

receiving messages to and from endpoints when the services in that ESB
process reside in the same container.
Also used for all OUTBOX processing where dynamic routing is indicated
(when the target destination is a remote destination such as NodeA::T1).
ESB (JMS)
Connection
Specify the ESB connection used to call web services deployed on the
ESB (in contrast to those available at an external HTTP address.)
HTTP Routing
Connection
Specify the HTTP routing connection to the SonicMQ broker that is used
for web services with HTTP addresses.
For more information, see the Progress Sonic ESB Product Family Developers Guide in the
Eclipse help.
4.
In the Actional Integration section, specify the following properties:

Property
Description
Enable Actional
Instrumentation
Select this option to enable Actional Server visualization on this ESB

container. By default, the option is not selected (unchecked). See the
chapter on Instrumenting Sonic ESB in the Actional Interceptor
Guide.
Enable Payload
Capture
When Actional instrumentation is enabled, declares whether the

instrumentation should include the message body.
The Actional Integration feature requires Progress Actional software products to

provide visibility, control, and enforcement of deployed assets. See their Web site at
www.progress.com/actional.
5.
Click Apply to complete the definition of the ESB Container you created.
You now need to add services to the ESB Container.
54

To add services to an ESB Container:
1.
Objects node, exapand the ESB Containers folder.
2.
Select the ESB Container to which you want to add services, and then click New in
the right panel of the Sonic Management Console. The Select Service or Process to
Add to Container dialog box opens.
To select or create an element to add to your ESB Container, see Adding Services or
ESB Process Entry Points to an ESB Container on page 59 for detailed information.
3.
Click OK to close the Select Service or Process to Add to Container dialog box.
You do not have to add ESB Processes to containers unless you want to make them
directly accessible over a JMS Endpoint. This entry endpoint will only be used by
external JMS (or WS-Protocol clients.) ESB services sending to a process always go
to the first step.
Note
4.
Click Apply in the lower right panel of the Sonic Management Console to apply the
changes to your ESB Container.
The service or ESB process you selected appears in the right panel. You can repeat
this step to add services and ESB processes to your ESB Container.
(You can click Reset to restore the previously applied values before you click Apply.)
If you click Undo, any changes made before the previous Apply are undone. The
information reverts to its previous state and Redo becomes available. (Undo does not
undo the last change unless Apply has been clicked.)
55
ESB Container Intra-container Messaging

Intra-container messaging allows a container to bypass the overhead of sending and
receiving messages to and from services in a process when the next service in an ESB
Process resides in the same container. When you select intra-container messaging for an
ESB Container, a message in the Outbox of one service (that is addressed to another
service in the same ESB Container) is sent directly the other service, bypassing the
broker.
Messages sent to a Sonic ESB service where intra-container messaging is enabled bypass
the broker, so any listeners outside the container will not receive these messages. The
Quality of Service (QoS) for the entire message dispatch through a process or chain of
services is dictated by the QoS of the entry endpoint of the service that first receives the
message off the originating JMS destination.
For example, when a service whose entry endpoint has a QoS of EXACTLY_ONCE receives a
message, that message will have QoS of EXACTLY_ONCE throughout the process until it
reaches another JMS destination, regardless of the QoS of any other services it passes
through after the first service. In this example, if a fatal error (such as a container crash,
machine crash, or power failure) occurs, a message that is not committed at the time of
failure will be resent when the container becomes available. The uncommitted message
is resent in this case because it retains the QoS of EXACTLY_ONCE. See Quality of Service
on page 102 for more information about QoS.
56
Viewing or Editing ESB Container Properties

Follow this procedure to view and edit the properties of installed ESB Containers.
To view or edit the properties of installed ESB Containers:
1.
Start the Sonic Management Console. (See Using Progress Sonic ESB
Configuration and Management Tools on page 19.)
2.
In the left panel, under the ESB Configured Objects node, select the ESB Containers
folder.
The right panel lists any installed ESB Containers:
In this example, the ESB Container VerificationContainer is selected so its properties

are displayed.You can edit the properties for the selected container (except its name),
as described in Creating ESB Containers on page 53.
57

Services ESB Containerare deployed in ESB Containers. The following procedure shows
how to view information about the services in an ESB Container.
To view the services associated with an ESB Container:
1.
Objects node, expand the ESB Containers folder and select an ESB Container. The
right panel displays information for the selected ESB Container. For example, select
dev_ESBCore.
You can sort the list of services by Name, Type, Listeners, or Entry Endpoint.
2.
58
Select a service to display information for that service, for example, dev.CBR:
Adding Services or ESB Process Entry Points to an ESB Container

Follow this procedure to add a service or ESB process entry point to an ESB Container.
To add a service or ESB process entry point to an ESB Container:
1.
Objects node, expand the ESB Containers folder, and then select an ESB Container.
2.
In the right panel, click New.

The Select Service or Process to Add to Container dialog box opens. To constrain
the list to services or processes, set either the Show Services or the Show Processes
icons.
Show Services
Show Processes
You can select from available services and ESB processes, or create services and ESB
processes from this dialog box.
You can sort the list by Name, Type, and/or Category.
3.
a.
Select a service or ESB process and click OK to return to the Sonic Management
Console.
b.
Click Apply. Progress Sonic ESB adds your selection to the list in the top right
panel.
To add a new service, select New > Service in the Select Service or Process to Add
to Container dialog box, and select a service type from the list. The Configure
Service dialog box for that service opens.
a.
Enter, accept, or select values for the fields in the Configure Service dialog box.
59
4.
b.
Click OK to close the Configure Service dialog box. Your new service now
appears in the list of services and ESB processes in the Select Service or Process
to Add to Container dialog box.
c.
Select your new service and click OK to close the Select Service or Process to
Add to Container dialog box. Your new service is now set in the Service/Process
Maintenance area.
To add an ESB process, select New > Process in the Select Service or Process to
Add to Container dialog box, and select an ESB process type from the list, then click
New.... The Configure Process dialog box opens.
a.
Enter, accept, or select values for the fields in the Configure Process dialog box.
Click OK to close the Configure Process dialog box. Your new ESB process now
appears in the list of services and ESB processes in the Select Service or Process
to Add to Container dialog box.
b.
Select the new ESB process and click OK to close the Select Service or Process
to Add to Container dialog box. Your new ESB process is now set in the
Service/Process Maintenance area.
Important When you add a service or process to an ESB Container, the container must be restarted
to implement the changes.
Deleting ESB ContainerServices from an ESB Container

Follow this procedure to delete a service from an ESB Container.
To delete a service from an ESB Container:
1.
Objects node, expand the ESB Containers folder and select an ESB Container.
2.
Select the service and click Delete.
3.
Confirm your selection. Progress Sonic ESB removes the selection from the list.
Important When you delete a service or process from an ESB Container, the container must be
restarted to implement the changes.
60
Changing the Number of Listeners on Services in ESB Containers

You can edit a service to change the number of listeners. Each listener is a thread.
To edit the number of listeners on a service associated with an ESB Container:
1.
Objects node, expand the ESB Containers folder and select an ESB Container.
2.
In the right panel, select a service whose listeners you want to edit.
3.
Change the number of listeners to the value you prefer.
4.
After you make a change, click Apply to commit the changes.
Important When you modify a service or process in an ESB Container, the container must be
restarted to implement the changes.

An ESB Container is deployed as a component in a management container. A component
is a software object meant to interact with other components, and encapsulating certain
functionality. A component has clearly defined interfaces and conforms to a prescribed
behavior common to all similar components within an architecture.
The following table lists the appropriate sections in the Configuring Containers and
Collections chapter in the Progress SonicMQ Configuration and Management Guide
that describe how to deploy an ESB Container in a container and other information about
containers.
Topic
Section
Creating a management container
Configuring Containers
Adding an ESB Container as a component in a

management container
Configuring Container Components
Generating a management container boot file
Generating Container Boot Files
Using fault tolerant (backup) management containers
Generating Containers
(Also see the SonicMQ Deployment Guide chapter

Fault Tolerant Application Containers.)
Note that there is no configuration for a fault tolerant
ESB Container.
61
Setting Test Mode for ESB Containers Used in Development

To use a new ESB Container, the Sonic Workbench requires that you set the ESB
Containers property TEST_CONTAINER_MODE to true.
To set an ESB Container to Test Mode:
62
1.
Create an ESB Container, and then create a management container.
2.
Add the ESB Container to the management container as a component.
3.
Click on the management container. On the right panel, right-click on the ESB
Container component, and then choose Properties.
4.
Choose the Deployment Parameters tab, and then click Add.
5.
In the New Deployment Parameter dialog box, enter the Name TEST_CONTAINER_MODE
and the Value true. Click OK.
6.
The deployment parameter appears as shown:
7.
Click OK to apply the setting.
Adding JAR files to an ESB Container

When you have JAR files used by the ESB Container, you need to import the .jar files
into the domain, and then set the classpath for each ESB Container that references classes
in those archives. The following procedure explains how to import a .jar file and set the
classpath for an ESB Container.
To import a .jar file and set the classpath for an ESB Container:
1.
In the Sonic Management Consoles Configure tab, select the configuration path
where you want to locate the .jar file.
2.
Select Action > Import. The archive is imported into the domain. In the following
example, a folder named myJars was created in the Resources folder, and then, with
the new folder selected, the archive myJarOne.jar was imported from the file system.
3.
Expand the ESB Containers folder, right-click on the ESB Container for which you
want to add the classpath, and select Properties.
63

4.
Click the Resources tab, and then click Add. Navigate to your imported .jar file.
The sonicfs:/// prefix is added when you browse to the file location, as shown:
5.
Click OK to close the Add Classpath dialog box, then click OK to close the
Edit Sonic ESB Containers Properties dialog box. The .jar file is now on the
container classpath.
6.
Reload the container. You do not have to restart it.
Note You usually import archives and their classpath reference during the import process of
the service type.
64

Follow this procedure to view and change the state of management containers and ESB
Containers.
To view and change the state of management containers and ESB Containers:
1.
Select the Manage tab in Sonic Management Console and select the folder that
contains the management containers.
Container state can be Online, Offline, or Unavailable.

You can sort the list of management containers by Name, State, or Last Error.
For each management container, you can view its ESB containers; and for each ESB
container, you can view its ESB services and ESB processes.
65

2.
You can select a management container, right click, and select Operations to:
Operation
Description
Launch
Launches the container (provided that management container is

on the activation list of a running Activation Daemon deployed
where the management container is deployed.)
Choosing to launch lets you choose the activation and then the
container to launch.
Restart
Restarts the container
Shutdown
Shuts down the container
Reset Metrics
Resets container-wide metrics
Invoke Diagnostics...
Opens the Sonic Diagnostics dialog box.
For more information on management container operations, see the Managing

Containers and Collections chapter in the Progress SonicMQ Configuration and
Management Guide.
Warning Do not include an external jndi.properties file in the classpath of an ESB Container (or
even the classpath of the JVM used to launch the container), as this will prevent starting
the management container hosting the ESB Container.
66

3.
4.
You can select a management container, right click, and select Container Log to:
Operation
Description
View
Views the contents of the container log.
Clear
Clear the contents of the container log.
Save to File...
Saves the container log to a file.
Select the management container you want to view. In this example, the management
container, dev_ESBCore, contains an ESB container of the same name
(dev_ESBCore), whose state is Online:
An ESB Containers state is Online, Offline, or Unavailable.

You can sort the list of ESB Containers by Name, State, or Last Error. For each ESB
container, you can view its ESB services and ESB processes. The color of each ESB
service or process indicates its state (green indicates the service or process is online,
and red indicates the service or process is offline or in an error state.
67

5.
To perform operations on an ESB Container, right click on it, then select Operations:
Operation
Description
Start
Starts the ESB Container
Stop
Stops the ESB Container
Reload
Unloads the ESB Container, reloads configuration information, and

restarts services in the ESB Container
Abort
Aborts the ESB container, its ESB services, and its ESB processes.
Clear Error
Clears the last error.
Reset Metrics
Resets container-wide metrics.
For more information on component operations (ESB Containers are components in

management containers), see the Managing Containers and Collections chapter in
the Progress SonicMQ Configuration and Management Guide and the Contaniers
view in the Sonic Workbench.
6.
To perform operations on an ESB service, right click on it, then select Operations:
Operation
Description
Start
Starts the ESB service.
Stop
Stops the ESB service.
Abort
Aborts the ESB service.
For more information on ESB container and ESB service lifecycle operations, see the
Progress Sonic ESB Product Family: Developers Guide in the Sonic Workbench
online help.
68

All ESB services deployed in an ESB container support standard metrics and
notifications.
Standard Metrics
All ESB services deployed in an ESB container support the following metrics:
esb.service.messages.Received Records the number of message envelopes

receivedthat is, the number of times service has been invoked on the service
instance. This metric includes any messages received intracontainer, through
dynamically registered entry endpoints, and so on.
esb.service.messages.ReceivedIntraContainer Records the number of message

envelopes received intracontainer.
esb.service.messages.ReceivedPerSecond Records the rate per second at which

this service has been invoked over the collection interval.
esb.service.messages.ReceivedPerMinute Records the rate per minute at which

this service has been invoked over the collection interval.
esb.service.messages.ReceivedPerHour Records the rate per hour at which this

service has been invoked over the collection interval.
esb.service.messages.Rejected Records the number of message envelopes that

were rejected by the service instance.
69
esb.service.messages.Faulted
Records the number of message envelopes that

produced one or more faults. This metric does not record the actual number of fault
messages produced, as in some cases a single invocation can result in many fault
messages.
esb.service.messages.AverageProcessingTime Records the average time (in ms) it
has taken to process a message. This measures the time for the service instance to
return from a call to service; it does not account for processing time before the ESB
framework passes the message to the service instance, or processing time after the
service instance has returned control to the ESB framework.
esb.service.messages.SentWithDispatch Records the number of messages sent
using XQDispatch.
esb.service.messages.SentWithCall Records the number of messages sent using
XQEndpoint.call.
esb.service.messages.SentToOutbox Records the number of messages sent to the
service outbox. A single message received may result in zero, one, or many messages
in the outbox.
To enable a service metric:
70
1.
Open the Sonic Management Console and select the Manage tab.
2.
Select a running ESB Container.
3.
Right-click on the ESB container and select Metrics.... The Monitoring dialog box
opens with its Metrics tab:

4.
Select one metric or a group of metrics (by selecting the parent folder) and select
Enable. The Sonic Management Console enables the metrics you selected, for
example, the entire group of message metrics:
If you select an individual metric, more options become available. You can disable the
metric or watch the metric in a Metrics Watcher window in both a bar chart and line
graph. For information on watching and disabling metrics, as well as general
information on metrics, see the Monitoring chapter in the Progress SonicMQ
Configuration and Management Guide.
Standard Notifications
Notifications are associated with the delivery of event information. The ESB Container
registers service notifications with the management container. The Sonic Management
Console subscribes to notifications and can display notifications in a Watch window.
The following standard service notifications are supported:
Service started successfully
Service failed to start
Service stopped successfully
Service failed to stop
Service aborted
71

To monitor notifications:
1.
2.
Select a running ESB Container, right-click on the container, and select

Notifications... . The Monitoring dialog box opens with its Notifications tab:
3.
You can select one or more notifications, and for each notification, select Watch and
select whether to watch:
By Component (ESB Container)
By Container (management container)
By Domain
The Sonic Management Console marks notifications that are being watched:
The Sonic Management Console opens a Notification Watcher.
72
For general information on notifications and on watching notifications and viewing

notification attributes, see the Monitoring chapter in the Progress SonicMQ
See also the Progress SonicMQ Administrative Programming Guide and the Progress
Sonic Event Monitor Users Guide documentation for information on other options for
tracking these notifcations.For information on watching and disabling metrics, as well as
general information on metrics, see the Monitoring chapter in the Progress SonicMQ

An ESB Container can integrate with Actional, the enterprise-class management and
runtime governance solution that enables users to secure, govern and manage Web
services and SOA processes from end to end. Actional gathers message data and enforces
policy as messages flow through the Services Network, dynamically mapping each and
every transaction.
The Actional Agent is a separately licensed component in the Actional product family.
The Actional Agent software includes interceptors (included in an ESB installation) and
the standalone Analyzer which must be installed separately. The interceptor monitors
traffic flowing through the ESB, while the Analyzer collects information from the
interceptor and forwards statistical information to an instance of the Looking Glass Server
(also available separately).
The Actional Agent can analyze Web service and JMS traffic on the Enterprise Service
Bus. When you enable Actionals interceptor technology on existing ESB infrastructures,
the Analyzer lets you gather data from this interceptor and communicate with an instance
of Actional Server.
The Actional ESB Interceptor is included in an ESB installation; however, it is not
enabled by default. To use the Actional Agent to manage ESB services and processes,
connect the Sonic Management Console to a Sonic domain you want to instrument, and
then select the option to Enable Actional Instrumentation on each ESB Container you
want to enable, as shown:
73
To activate an enabled interceptor requires that the Actional Agent is installed and
running, and that the Agent node is under management by an Actional Server.
If the Actional Agent is not running before the instrumented Sonic ESB Containers are
started, you must restart the enabled Sonic ESB Containers to activate the Actional
visualization feature.
Important If the Actional Agent is installed with a non-default \link directory (the directory where
the Actional Agent creates Uplink.cfg), you must specify the path to the link directory
as a Java system property on the Environment tab of each management containers
properties with the Variable name com.actional.lg.interceptor.config and, for the
Value, the complete path, such as usr1/aUser/Actional/ActionalAgent/LG.Interceptor.
Note When using Actional to view an ESB process that makes a SOAP web service call, the
display might not be correct if that web service is running on a machine which is under
Actional management. The process and the remote web service might appear to be
disconnected. To view these interactions properly, remove the web service from
management through the Actional Server administration interface. Web services that are
running on unmanaged Actional nodes are not affected by this and render correctly.
See www.progress.com/actional for more information. The Instrumenting Sonic ESB
chapter in the Actional Interceptor Guide in the Actional Agent documentation set
provides details and illustrations of this feature.
74
Logging and Tracing
Logging and Tracing

You can turn debug tracing on and off for ESB Containers and specify logging categories
to send messages to the containers message log. The following procedures describe how
to specify logging and tracing and how to make the settings permanent.
For more information on logging and tracing, see the Managing Containers and
Collections chapter in the Progress SonicMQ Configuration and Management Guide.
To specify logging and tracing for an ESB Container:
1.
In the Sonic Management Console, select the Manage tab and select the management
container that hosts the ESB Container.
2.
Right-click on the ESB Container and select Properties.
3.
The identity and status of the ESB Container is displayed:
75

4.
Select the Tracing tab and then select tracing bit masks. In this example, Verbose, Set
Attributes, and Enable Debug Messages are selected.:
These settings include:
Enable Debug Messages (16) Enables application code to generate log output
ESB Invocation Script Tracing (64) Logs generic script engine events
Message Dispatch Tracing (128) Traces in, out, and fault messages
JMS Endpoint Tracing (256) Traces events related to endpoint creation and
usage
ESB Container Tracing (512) Traces ESB Container-specific events, for
example, lifecycle events

5.
Click OK to apply the settings.
Setting tracing on the running container sets it only for the current execution of the
container. Restarting the container resets the tracing selections to their standard
configuration values.
The following procedure describes how to set standard configuration values so that the
tracing options are set whenever the ESB Container starts.
Important While tracing provides valuable information, the logs grow faster than usual when tracing
settings are always active. Try some tracing settings and observe the amount of data that
they add to the logs. Then, try to reserve verbose settings to debugging activities only.
76
Logging and Tracing

To make logging and tracing for an ESB Container permanent:
1.
On the Configure tab in the Sonic Management Console, select the management
container that hosts the ESB Container on which you want to maintain logging and
tracing.
2.
In the right panel, right-click on the ESB Container,and then select Properties.
3.
In the Edit Container Component Properties dialog box, enter the sum of the integer
values for each tracing bit you want to set, as specified in the Edit Sonic ESB
Container Properties dialog box.
In this example, Verbose (1), Set Attributes (2), and Enable Debug Messages(16) are
intended so the sum of 1+2+16, 19 is entered as the Tracing Mask value as shown:
These tracing bits are set in the runtime whenever this container starts.
4.
Click OK to apply the setting. The changed value is immediately applied to the
runtime settings.
Note Tracing options are also available on the management container as temporary runtime
overrides and standard settings that are re-established when the management container
restarts.
77

Using an Activation Daemon is a way to launch new containers as spawned processes of
the container hosting the Activation Daemon. This allows new containers to be launched
by remote administrative clients without the administrator having to log on to that host. A
typical use would be to have the container hosting the Activation Daemon launched as a
Windows service on Windows platforms or a startup process under UNIX.
An Activation Daemon monitors the health of its spawned containers and, depending on
configured rules, restarts those containers upon failure. Normally, one Activation Daemon
is deployed per host. Multiple Activation Daemons can be created per domain.
Containers can be launched by the Activation Daemon:
At Activation Daemon startup time
At a configured time
After a container failure (up to a configurable number of retries)
On demand from the Sonic Management Console or through the Activation

Daemons management API (see the Using the Runtime API for the Sonic
Management Environment chapter in the Progress SonicMQ Administrative
Programming Guide)
This section demonstrates how to create and configure an Activation Daemon to start an
ESB Container. As an example, the procedures describe how to create an Activation
Daemon to automatically start the Service5 container when the Activation Daemons
container starts. See the Configuring Framework Components chapter in the Progress
SonicMQ Configuration and Management Guide for detailed information on using
Activation Daemons. The steps required to create, configure, and test the Activation
Daemon are:
78
1.
Creating an Activation Daemon on page 79
2.
Adding an Activation Daemon to a Management Container on page 79
3.
Adding an ESB Container to an Activation Daemons Activation List on page 81
Creating an Activation Daemon

Create an Activation Daemon from the Sonic Management Console, as shown in the
following procedure. As an example, this procedure creates AD_for_Services.
To create an Activation Daemon:
1.
Start the domain manager where you want to manage the configurations.
2.
Start the Sonic Management Console, and then connect to the domain manager.
See Overview on page 20 for instructions.
3.
In the Sonic Management Consoles Configure tab, right-click the folder where you
want to create the new configurations. For this example, choose Containers.
4.
Right-click on the folder, and then choose New > Configuration > Sonic Management
Environment > Activation Daemon. For this example, name it AD_for_Services.
The New Activation Daemon dialog box opens.
5.
Specify the name of the Activation Daemon in the Name field.
6.
Click OK.
Adding an Activation Daemon to a Management Container

The following procedure shows how to add an Activation Daemon to a management
container. Typically, an Activation Daemon hosts the Activation Daemon in a
management container of its own and to assign other management containers to the
Activation Daemons activation list (which will, in turn, start their hosted components.
(See Using Activation Daemons in the Progress SonicMQ Installation and Upgrade
Guide for an illustration.)
As an example, this procedure adds a new Activation Daemon named AD_Services to a
new management container. When the management container starts, it will start this
Activation Daemon, and the daemon will launch its hosted components.
79

To add an activation daemon to a management container:
1.
In the Sonic Management Consoles Configure tab, right-click the folder where you
want to create the new configurations. For this example, choose Containers.
2.
Choose New > Configuration > Shortcut to Container. For this example, name the
container AD_for_Services_on_myHost. Adjust the connection URL and the
username and password for management communications in the domain.
3.
Right-click on the container you created, and select Add Component. In the New
Container Component dialog boxs General tab specify:
Property
Description
Name
The name of the component you want to add to the container.

For this example, enter AD_for_Services.
Component
Click ... to open the Choose Component dialog box. For this example,
choose /Containers/AD_for_Services.
Auto Start
Specifies whether to automatically start the component when the hosting

container starts. For this example, check Auto Start.
Tracing Mask
Enter the tracing mask integer for this component.
For this example, the New Container Component dialog box should look like this:
4.
80
Click OK to add the component to the container.
Adding an ESB Container to an Activation Daemons Activation List

The following procedure describes how to add a management container that hosts an ESB
Container an Activation Daemons activation list. As an example, this procedure adds the
Service5 management container which hosts an ESB Container of the same name.
To add an ESB Container to an Activation Daemons activation list:
1.
In the Sonic Management Consoles Configure tab, navigate to the Activation

Daemon you created, then right-click on it.
2.
Choose Add Container to Activation List.
3.
Under the General tab, specify the following properties:

Property
Description
Container
Name of the container to associate with the Activation Daemon.

For this example, select ... then select Containers\Service5 Container and
click OK.
Number of
Retries
Number of times the ESB ContainerActivation Daemon should attempt to

restart the spawned container. For this example, use the value 4 instead of
the default value, 0.
Retry Interval
Number of seconds between attempts by the Activation Daemon to restart

the spawned container. For this example, use the value 15 instead of the
default value, 0.
For this example, your Add Container to Activation List dialog box looks like this:
81

4.
Click OK. The Sonic Management Console associates the Activation Daemon with
the container you selected.
In this example, Service5 Container is added to the list of management containers for
AD_for_Services and will try to start four times at fifteen second intervals.
Note Setting JVM System Properties on a Management Container
You can maintainthe JVM system properties for a management container that is on an
Activation Daemons activation list by using the Sonic Management Console to open the
management containers Properties, and then choosing the Environment tab.
For example to specify the JNDI Initial Naming Context, specify the JVM system
property java.naming.factory.initial and set it to the
valuecom.sonicsw.xqimpl.jndi.spi.XQTNSContextFactory
Additional classpath settings are also set in the management container configuration.
For more information on management containers and their environment settings, see the
Configuring Containers and Collections chapter in the Progress SonicMQ
82
Chapter 3
ESB Endpoints and Connections
This chapter first references to endpoints and ESB addresses, and then shows how they
are configured. Then connections are presented and shows how they are configured.
The chapter contains the following sections:
Overview
ESB Addresses and References to Endpoints
Evaluating Endpoint Requirements on JMS Destinations
Configuring Progress SonicMQ Endpoints
Fault Tolerant Connections and Reconnection
Every endpoint has an associated connection. The following procedure describes

how to view existing connections and configure a new connection.
Note In the development environment, the Sonic Workbench handles the creation of endpoints
and connections. For more information, see the Progress Sonic ESB Product Family
Developers Guide in the Eclipse help.
83
Chapter 3: ESB Endpoints and Connections
Overview
ESB endpoints and connections enable communication among services. Endpoints are
destinations where ESB services send and receive messages. The definition of an endpoint
includes its connection, the URL address where the destination resides. An application
accesses a service by sending a request to the services entry endpoint.
Progress Sonic ESB endpoints include Java Messaging Service (JMS) destinations
queues and topicsthat are accessed through connections to SonicMQ messaging
brokers. Endpoints provide queuing and persistence between services. This persistence
allows an ESB process to be fault-tolerant and provides an overall Quality of Service
(QoS) that can guarantee processing in case of provider failure.
Endpoints are defined by three sets of properties:
Name A globally unique name for accessing the endpoint
Connection The logical connection that instantiates the endpoint
Parameters The specific parameters within the logical connection that distinguish
the endpoint (for example, the name of a Progress SonicMQ queue or topic)
The following view of an endpoint in the ESB Configured Objectssection of the Sonic
Management Console shows some of the properties:
84
Note Information for service developers Progress Sonic ESB uses endpoints when it
creates listeners for a service Inbox, or when it delivers messages from the Outbox.
However, as a service developer, you can also send messages directly to an endpoint from
inside a service:
To send messages as the output of the service, you simply place the message in the
services Outbox with the appropriate address.
To send messages synchronously (to wait for a reply on a temporary JMSReplyTo

destination), use the call( ) method on the endpoint.
To send messages asynchronously, use the XQDispatch.

When ESB services and ESB processes are configured, they are associated with an
endpoint that is used to receive messages (the entry endpoint). When messages are
delivered to a service (by the dispatcher), the message is placed in an envelope with an
address. An address is a generic term for ESB processes, services, or endpoints that can
serve as destinations for a service or process exit, fault, or regular message endpoint.
There is also a special REPLY_TO address for services configured as Request/Reply. If the
message sender is a service, the address is interpreted as an endpoint. Messages can be
sent directly to a ESB process or service (as well as to the endpoint itself).
ESB addresses include:
Endpoints A specific destination on a defined connection.
ESB processes Specifies binding to defined endpoints in their definition. That

endpoint is used in their first step (bypassing the entry endpoint)
Services Specifies binding to a defined entry endpoint of the service, or the service
itself when intra-container messaging is in use.
When you define a service or ESB process or adapt a service or ESB process to a target
domain, you specify four categories of ESB addresses: entry, exit, fault, and rejected
message. The following sections discuss each of these categories.
85
Entry Endpoint
An entry endpoint always uses an endpoint address, a destination associated with an
underlying JMS topic or queue used as the entry into an ESB process or service. You can
use intra-container messaging to bypass the entry endpoint if the caller is in the same
container (see ESB Container Intra-container Messaging on page 56). Services that
must be accessed from remote JMS or HTTP clients or from itineraries that start in other
containers should have a JMS-capable entry endpoint.
Exit Endpoint
An exit endpoint can be any type of ESB address (or list of addresses.) It is the configured
last destination of an ESB process or service. The exit endpoint is typically configured as
REPLY_TO, a specially named endpoint that uses as the reply to destination name set on the
message that started the service operation or ESB process. The exit endpoint setting can
be overridden by an ESB process.
Fault Endpoint
A fault endpoint can be any type of ESB address. It is an endpoint to which application
messages with recoverable errors are sent. Messages are sent to the fault endpoint if
requested by the service.
Each service can have an optional fault endpoint for those messages it cannot handle. The
service decides which messages are sent to the fault endpoint as part of normal
processing. The fault endpoint can contain any valid message
The fault endpoint handles recoverable processing errors (for example, an out-of-stock
notice), and interruptions in the normal process that must be handled at the application
level.
The fault endpoint inherits the Quality of Service (QoS) settings of the service application
or ESB process.
The fault endpoint is often set as an address to another service or ESB process. It might
also be an endpoint (Progress SonicMQ destination) or a REPLY_TO destination.
86
Rejected Message Endpoint

The rejected message endpoint (RME) can be any valid XQAddress object including, an
endpoint, a service, and an ESB process. It handles messages that are an invalid type for
the process, messages that throw exceptions in the service() method of the service, and
messages that failed to send to their Fault or Outbox addresses. Messages that cannot be
processed are sent to the RME in the event of processing failures. This provides a similar
function to the SonicMQ Dead Message Queue (DMQ).
Every service can have an RME. Messages that cannot be processed are always sent to the
RME in the event of processing failures. The messages are sent to the RME by the
services framework, not directly by the services.
The RME handles:
Messages that throw exceptions in the service( ) method of the service
Messages that were in the services Fault box or Outbox, but which could not be
delivered (for example, the queue underlying the ESB endpoint does not exist.)
When a message is sent to a rejected message endpoint, it is sent as a multipart message.
The first part provides information about the rejected message, and the balance of the
messages is the original message. If the original rejected message was itself a multipart
message, the first part is the information section and the other parts follow it in the same
sequence as the original message parts.
The first part is a text/xml message with three sections:
rejectedCode A String identifier pointing to the reason for rejection (a list of

rejected codes is available in com.sonicsw.xq.ErrorCodes)
rejectedLocation The location of the failure; it can have these optional attributes:
locationName The name of the computer where the rejection occurred
containerName The name of the ESB Container that rejected the message
serviceName The name of the service that rejected the message
processName The name of the ESB process that was performing the action
stepName The name of the process step at which the message was rejected
rejectedString Details of the failure, including a stack trace of the failure or

exceptions causing the rejected message
87
Rejected Message Behavior Under Failure Conditions

This section describes the behavior of the process framework under various failure
conditions. Where appropriate, the com.sonicsw.xq.ErrorCode value is provided (the
value of the <rejectedCode>XXXX</rejectedCode> element of the rejectedMessageInfo
message).
A service should handle all generated exceptions itself. Normal service exit occurs
through the Outbox. All exception cases are handled by the Fault box.
Abnormal behavior is handled by the dispatcher using the RME. If the service( ) method
throws any exception or error (anything throwable, either java.lang.RuntimeException or
an XQServiceException), the original message is sent to the RME.
The rejectedMessageInfo\rejectedString is the stack trace of linked exceptions:
rejectedCode = XQ_SERVICE_EXCEPTION
Any processing error that occurs in the dispatcher before the message is delivered to the
service( ) method invokes the same RejectedMessageEndpoint behavior. The
rejectedMessageInfo is the stack trace of linked exceptions:
rejectedCode = MESSAGE_RECEIPT_FAILURE
When a QoS discrepancy occurs in the dispatcher between the QoS of the entry endpoint
and the QoS of the ESB process using it, the rejectedMessageInfo contains the intended
QoS:
rejectedCode = PROCESS_QOS_UNSUPPORTED_AT_ENDPOINT
An error outside the service(

sent to the RME.
method, delivering Inbox or Outbox messages, is also
The following scenarios result in rejected message processing:
If the address on an XQMessage in the Outbox or Fault box is invalid or empty:

rejectedCode = SEND_NULL_ADDRESS
If there is an error sending a message returned from the XQEndpoint.send(
) method:
rejectedCode = XQ_ENDPOINT_EXCEPTION
If some other error occurs in the dispatcher processing the message:

rejectedCode = MESSAGE_SEND_FAILURE
Time to live for an ESB process is checked when the message arrives at the service. If the
current time by the local system clock (measured in GMT) is greater than the ESB process
entry timestamp plus timeToLive, the RME is used:
rejectedCode = TIME_TO_LIVE_EXPIRED
Messages sent to the RME have the same QoS as the service from which they are rejected.
88

When configuring JMS destinations for your applications, there are several factors to
consider as you prepare to configure the domain. The abstraction of ESB services and
processes from the specifics of the domain architecture make promotion of artifacts
through a series of stages or across various domains a fundamental task reserved for the
deployment manager rather than the developer.
Factors such estimated traffic volumes, available computing resources, the service level
requirements, the topology of the resourcesthese all contribute to the overall design of
the systems that broker the endpoints.
Will you run multiple instances of a service for scalability and reliability?
What quality of service (QoS) is required?
For EXACTLY_ONCE or AT_LEAST_ONCE QoS, messages can be sent PERSISTENT, and

topic subscribers should be durable.
See Using Concurrent Durable Subscriptions to Topics on page 91.
Are the destinations queues or topics?
If so, use queues, or topics with shared subscriptions. Normal topic subscriptions
broadcast a copy of all messages to each service instance.
See Using Shared Subscriptions to Topics on page 91.
If other applications are already sending to a destination, you cannot change that
destination.
If other applications are listening on the same destinations, you must use topics.
See When to Use Topics, When to Use Queues on page 90.
Does your deployment architecture have multiple brokers, clusters, or nodes?
When using queues, decide whether they should be global and/or clustered.
When using topics, decide whether they should be shared.
See Multiple Brokers, Clusters, and Nodes on page 93.
The recommended best practice for configuring JMS destinations is to use concurrent
durable subscriptions, which provide durability, scalability, and the ability to monitor
your applications.
Note In the Sonic development environment, endpoints are, by default, configured as
nonpersistent topics in the underlying SonicMQ domain. That helps ensure that a run or
test of a project does not interfere with subsequent runs after some services have failed
or became unavailable.
89
Table 1 maps the destination configurations to destination requirements.

Table 1. Mapping Destination Requirements
QoS
Destination
Type
Multiple Services
Single Service Instances
AT_LEAST_ONCE
Topic
Concurrent durable subscription =

true
Shared subscriptions = true
Number of listeners = any number
Durable subscription name must be
non-null
or
EXACTLY_ONCE
BEST_EFFORT

false
Shared subscriptions = false
Number of listeners = 1
non-null
Queue
No additional configuration required
Topic

true
Shared subscriptions = true
Number of listeners = any number
null

false
Shared subscriptions = false
Number of listeners = 1
null
Queue
When to Use Topics, When to Use Queues

When deciding whether to use queues or topics in your applications, consider that the
underlying Progress SonicMQ layer provides some queue-like behavior for topics. The
shared subscription feature enables you to have persistent, load balanced topic subscribers
in your applications, while still allowing other subscribers on the topics.
If you use topics, other services can receive and process messages without interfering with
message flow through a process. Using this implementation, you can monitor business
activity with a monitoring service subscribed to one topic, while message flow continues
uninterrupted through a service subscribed to a different topic. This implementation is
also useful in debugging and testing your applications and processes.
See the Progress SonicMQ Application Programming Guide for a detailed discussion of
the features and benefits of using queues or topics in your applications. If you use topics,
there are other considerations in defining the endpoints that relate to the number of service
instances and the QoS. The following sections describe implementing concurrent durable
subscriptions and shared subscriptions on topics in Sonic ESB.
90
Using Shared Subscriptions to Topics

With topic subscriptions there can be cases where one application acting as a topic
subscriber cannot process messages as fast as messages are being published. This leads to
a bottleneck, where the subscribing application falls farther and farther behind.
You can establish groups of topic subscribers that share subscriptions to allocate the
message load among them. Within these groups, each message is delivered to, and
consumed by, only one member of the group. These group members can be located on
dispersed computers over diverse JMS connections. The implementation is compatible
with clusters of brokers so that the members of a consumer group can connect to different
brokers in a SonicMQ cluster. Regular subscribers, durable subscribers, and participants
in a shared subscription can be active concurrently on a broker.
Sonic ESB prepends the service name to the topic name when defining subscribers within
a group: [[ServiceName]]topicName. When you select a destination for a shared
subscription, Sonic ESB automatically prepends the service name to the topic you select
(if shared subscriptions are enabled for the service, which is the default condition).
For detailed information on implementing shared subscriptions, see the Publish and
Subscribe Messaging chapter in the Progress SonicMQ Application Programming
Guide.
Using Concurrent Durable Subscriptions to Topics

You can configure the entry endpoint of a service to define a durable subscription to a
topic. In Sonic ESB, multiple service instances can concurrently process messages sent to
a durable subscription.
Durable subscriptions are created using a unique prefix appended to the subscription
name configured on the JMS endpoint. The unique prefix consists of the management
container name, the name of the ESB service configuration (the service name), and the ID
of the message listener.
The Concurrent Durable Subscription setting on an endpoint is a boolean value:
When set to False, the number of listeners to is limited to one. Also, only one instance
of the service can be running anywhere in your ESB. This setting is preferred if you
care about guaranteeing order in processing. The effect is similar to setting Exclusive
on a queue.
When set to True, the default value, multiple containers are allowed to run the service,
and each of those containers can have multiple listeners. This setting is appropriate
when you want to load-balance and scale processing, and are not concerned about
order in processing.
91
For detailed information on implementing durable subscriptions, see the Publish and
Subscribe Messaging chapter in the Progress SonicMQ Application Programming
Guide.
The following example illustrates Sonic ESBs naming convention for this feature:
A service named Service1 is deployed in MFContainer1 and MFContainer2.

Service1 has:
Two listeners in MFContainer1
One listener in MFContainer2
The subscription name is myDurableSub
The topic that is subscribed to myDurableSub is T1
These services share a subscription to the topic name [[Service1]]T1 (concurrent

durable subscriptions in Sonic ESB have shared subscriptions enabled by default)
The dynamically generated subscription names are:
MFContainer1:Service1:1:myDurableSub
Three durable subscriptions are created. Distribution to the durable subscriptions is based
on factors including the number of active clients and flow control status.
Each listener on a single service accesses the same, shared durable subscription, thus
improving the throughput of a deployed service instance by enabling concurrent message
processing. When a listener is eliminated, its durable subscription is not automatically
eliminated, which causes that durable subscription to remain inactive until the subscriber
returns .
Note
In conjunction with the shared subscription functionality, messages for a shared durable
subscription that might be stranded in these now-defunct subscriptions are re-allocated
to whichever shared subscribers are connected, whether durable or nondurable.
There is an advantage to using only durable subscribers in a shared subscription as a
failure of a regular subscriber without acknowledgement of a delivered message has no
mechanism for restarting and re-allocating the indoubt message.
92
Multiple Brokers, Clusters, and Nodes

The ability to access services over the underlying SonicMQ messaging layer is an
important consideration when a Progress Sonic ESB service calls out to other services and
expects a reply, or when a Progress Sonic ESB process connects many ESB services.
Sonics Dynamic Routing Architecture (DRA) is a robust, secure way to send messages
through a broker or cluster of brokers to a destination on another broker or cluster. (In
routing, each broker or cluster is a routing node. For more information on DRA, clusters,
and routing nodes, see the Multiple Nodes and Dynamic Routing and Clustered
Brokers chapters in the Progress SonicMQ Deployment Guide.)
In multi-node domains, Progress Sonic ESB uses DRA to make fewer direct connections
to remote nodes by using the ESB (JMS) connection and DRA routes to send to remote
nodes. (Every ESB Container has an ESB (JMS) connection. See Creating ESB
Containers on page 53 for information on specifying the ESB Container connection.)
When a message is sent to a node-qualified destination, the ESB (JMS) connection is used
to send the message to the broker associated with the ESB Container on the bus. You
configure an endpoint using a node-qualified queue or topic name to reference a queue or
topic on a remote node to which the client (ESB service) is not connected. For example,
you can configure the ESB (JMS) connection to NodeA (a routing node) and an endpoint
based on queue, NodeB::Q2. Messages travel over the DRA connection of NodeA to NodeB.
Progress recommends using this node-qualified syntax as a best practice, as it avoids
making new connections from an ESB Container to all the remote nodes. Progress
recommends using the node-qualified syntax even if you are not running over DRA
doing so eases the transition if you decide to implement DRA in the future.
The bus connection broker must have DRA routes defined for each of the remote nodes
that can be sent to. If not, sent messages go to the brokers dead message queue (DMQ).
Important If the DRA connection fails, the message goes to the DMQ rather than to the rejected
message endpoint (RME), provided the message is sent PERSISTENT and

JMS_SonicMQ_preserveUndelivered and JMS_SonicMQ_notifyUndelivered are set to true
(the Progress Sonic ESB QoS is AT_LEAST_ONCE or EXACTLY_ONCE on the process.) For
more information, see the Progress Sonic ESB Product Family Developers Guide in the
Eclipse help.
The only time the bus connection is not used is when the node is sonic.http, an HTTP
outbound routing node. In this case, the ESB Containers HTTP connection is used, as in
outbound web service invocations. (For more information, see the Progress Sonic ESB
Product Family Developers Guide in the Eclipse help.)
93
Table 2 lists JMS destinations for endpoints when using queues or topics in the same
management domain. The table shows different configurations for brokers, clusters, and
nodes used by entry endpoints of called or invoked services.
Table 2. Destination Definition Conventions Within a Domain
Deployment
Queue Definition
Topic Definition
One broker
Use non-clustered queues
Use normal or shared topics
One cluster, multiple

brokers
Use clustered queues
Use normal or shared topics
Multiple nodes with

some nodes as
clusters, some as
brokers
Use global, clustered queues
Use either:
Use node-qualified entry endpoint

names, for example, Node::aQueue
Node-qualified entry endpoint names,

for example, Node::aTopic (shared
subscriptions are not allowed)
GSA and no overlapping topic names
When choosing JMS destinations for queues, consider the following:
For clustered brokers, you should use clustered queues
For multiple nodes, you should use global queues and entry endpoints that are
qualified by the node name
When choosing JMS destinations for topics, consider the following:
All topics are clustered and global
For multiple nodes, either use node-qualified names for the entry endpoint or use
global subscription architecture (GSA) and global subscription nodes. (For
information on GSA, see the Multiple Nodes and Dynamic Routing chapter in the
Progress SonicMQ Deployment Guide.
94

The following procedure describes how to view existing Progress SonicMQ endpoints
and configure a Progress SonicMQ endpoint.
To view and configure Progress SonicMQ endpoints:
1.
In the ESB Configured Objects section of the Sonic Management Console, expand
the Endpoints folder, then click Progress SonicMQ Endpoint. The right panel lists
the available endpoints on the Endpoints tab.
2.
Select an endpoint from the list.

The ESB Configured Objects section of the Sonic Management Console displays the
properties of the selected endpoint, as shown:
95

3.
Click New.
The right panel clears the endpoint property fields in the Endpoint Maintenance area.
Required properties in the Endpoint Maintenance and Init Parameters areas are
marked with an asterisk (*).
4.
Enter, accept, or select values for the following fields:
Property
Description
Endpoint Name
A unique name.
Connection
You must define at least one connection for each endpoint type. (The Connections tab
lists the currently defined connections. You can select one of the connections that ships
with Progress Sonic ESB, jms_defaultConnection or http_defaultConnection)
Quality of Service
Select one:
Best Effort The default. Messages are sent NON_PERSISTENT. There is no guarantee
that a message will not be lost. However, messages can be duplicated.
At Least Once Messages are sent PERSISTENT. Messages cannot be lost. However,
some services might have some messages redelivered in the event of a system failure;
others might not.
WSDL URL
Exactly Once The most reliable processing. Messages are sent PERSISTENT.
Messages are not lost, and services do not receive duplicate messages. EXACTLY_ONCE
is supported for endpoints that map to JMS destinations in either JMS domain as
supported by JMS1.1 (topic or queue) on the same JMS connection.
Optional (to associate an endpoint with a WSDL document that describes its interaction
model).
Enter the WSDL URL or click ... to open the Choose WSDL File Resource dialog box and
choose a WSDL file.
JMS Destination
Type
96
Select Queue or Topic.
Property
Description
Destination Name
The name of a Progress SonicMQ topic or queue. You can either enter the name of an
existing destination in this field, or click New Queue... to create a new queue within a
specified broker or cluster. (Topics cannot be created in this way.)
When you click New Queue... the Create JMS Queue dialog box opens. Enter a
meaningful, unique Queue Name, and select a broker or cluster from the Create In list, then
click OK to create the queue in the named broker or cluster.
For information on configuring queues, see the Configuring Queues chapter in the
Progress SonicMQ Configuration and Management Guide.
See Using Shared Subscriptions to Topics on page 91 for information about destination
names when using shared subscriptions on topics.
Message Selector
Allows a consumer on the endpoint to filter and categorize messages in the message
header and properties with expression strings created with a subset of SQL-92 semantics.
This property is a java.lang.String that is evaluated left to right within precedence level.
(This property is not validated here.)
See the Message Producers and Consumers chapter in the Progress SonicMQ
Application Programming Guide for detailed information about message selectors and
syntax.
Concurrent
Durable
Subscription
Specifies whether the endpoint has a concurrent durable subscription to its destination
topic. This property ensures a unique subscription name so the topic can have multiple
listeners (this property does not dictate whether the subscription is durable). This property
is only relevant for topic-based endpoints. Multiple listeners in multiple service instances
can subscribe to the same durable subscription. This setting is optional, either True or
False; the default is True.
Durable
Subscription
Name
Name of the Progress SonicMQ durable subscription.

See Using Concurrent Durable Subscriptions to Topics on page 91 for information
about durable subscription names.
Priority
Optional. The priority at which Progress SonicMQ sends messages from this endpoint.
Enter a numeric value from 1 to 9 or Inherited; the default is Inherited. When this value is
set to Inherited, the priority of messages sent from this endpoint will be set to the value
with which the message was received, and new messages that are created and sent from
this endpoint will have a default priority of 4. When this parameter is set to a value from
1 to 9, all messages sent to this endpoint will have a priority equal to that value.
97
Property
Description
Time to Live
The lifetime of messages within Progress SonicMQ sent from this endpoint. This optional
numeric value in milliseconds can be any positive integer:
Setting the value to 0 retains the message indefinitely.
Setting the value to an integer greater than 0 causes expired messages to be sent to the
DMQ if the QoS of the entry endpoint is AT_LEAST_ONCE or EXACTLY_ONCE. (For more
information on QoS, see Quality of Service on page 102.)
Setting the value to an integer greater than 0 causes expired messages to be lost if the
QoS of the entry endpoint is BEST_EFFORT.
Message Prefetch
Count
The number of messages the endpoint will consume in a single request from a Progress
SonicMQ queue when the endpoint is used as an entry endpoint. This property is only
relevant to queue-based endpoints. It is an optional numeric value; the default is 1. It can
override the value specified in Progress SonicMQ.
Message Prefetch
Threshold
An optional numeric value to specify that when the number of messages waiting to be
processed by the endpoint falls to, or below, this threshold, a new batch of messages will
be fetched. This number cannot exceed the Message Prefetch Count. This property is only
relevant for queue-based endpoints.
Shared
Subscriptions
Allows automatic load balancing (the default is True, enabling shared subscriptions).
Flow To Disk
Specifies whether messages sent to this endpoint flow to disk. This feature allows
messages to continue to flow when a subscriber to this endpoint is slower than the
publisher and the buffer of the subscriber is full. Specify one of the following settings:
For more information on shared subscriptions, see Using Shared Subscriptions to Topics
on page 91 and the Publish and Subscribe Messaging chapter in the Progress SonicMQ
Application Programming Guide.
Send Timeout
USE_BROKER_SETTING No setting on the endpoint (the broker setting for this

feature is used). The default setting is USE_BROKER_SETTING.
ON All messages to this endpoint will flow to disk.
OFF No messages to this endpoint will flow to disk.
The time interval, in milliseconds, to attempt to send a message from this endpoint. The
default value is 360000 6 minutes.
5.
98
After you configure the properties, click Apply. The Sonic Management Console
displays the new endpoint in the Endpoints tab.
Deleting Progress SonicMQ Endpoints

The following procedure describes how to delete a Progress SonicMQ endpoint.
To delete a Progress SonicMQ endpoint:
1.
Objects node, expand the Endpoints folder and click Progress SonicMQ Endpoint.
The upper right panel lists the endpoints in the Endpoints tab.
2.
Select the endpoint you want to delete, and then click Delete.
3.
Confirm the selection. Progress Sonic ESB deletes the selected endpoint.

Progress Sonic ESB provides fault tolerant client connections that allow ESB services to
become failure resistant when used in a replicated broker environment. Enabling fault
tolerant connections allows your ESB services to recover connections without message
loss or duplication in the following circumstances:
Reconnect to the same broker if the connection is lost due to network failure
Reconnect to the same broker through redundant network interfaces if the connection
in lost due to network failure
Reconnect to a broker that is configured as a backup broker if the primary broker fails
Reconnect to a broker that crashes and recovers from the log if that broker is
configured with full broker crash recovery
The fault tolerant and reconnect properties you can set for a connection are:
Connection Parameter

Property
Default Value
faultTolerant
Enable Fault Tolerant Connection
False
initialConnectTimeout
Initial Connect Timeout
30 seconds
faultTolerantReconnectTimeout
Fault Tolerant Reconnect Timeout
60 seconds
99
Inbound and Outbound Connections

In Progress Sonic ESB, connections are not created until needed. For inbound (entry
endpoint) connections, the connection attempt starts (but does not finish) at service
initialization time. For outbound (exit, fault, and rejected message endpoint (RME))
connections, the connection attempt starts when a service first sends a message over a
given connection. As a result, two connections that have the same URL list might connect
to different brokers in the list. Once a connection is created it can be re-used and can be
shared across multiple sessions within the container. The maximum number of sessions
that share a connection is configurable.
Fault Tolerant Connections

Set the faultTolerant connection parameter to true to enable fault tolerant connections.
When enabled, SonicMQ fault tolerance occurs before the Progress Sonic ESB reconnect
logic is triggered. Only after the SonicMQ client fails to establish or re-establish a
connection using the fault tolerance mechanism will the Progress Sonic ESB reconnect
process start.
To use fault tolerant connections, the broker to which a client connects should be
configured, started, and sychronized as a replication broker or a fully crash recoverable
broker (see Configuring Broker Replication in the Progress SonicMQ Configuration
and Management Guide and Achieving Continuous Availability in the Progress
SonicMQ Deployment Guide for information about using fault tolerant connections and
replication brokers). Otherwise, only the transient network recovery or redundant network
recovery feature can be used at runtime.
Progress recommends that a fault tolerant connection to a replicated broker should specify
primary and backup broker URLs in the URL list. This ensures that both primary and
backup URLs are tried for a successful initial connection. The Connection URL list is
only used when creating the initial connection, not for fault tolerant reconnection
attempts. Fault tolerant reconnection URLs are provided by the broker servicing the ESB
Container at the time a disconnect occurs. See the Configuring Routings chapter in the
Progress SonicMQ Configuration and Management Guide for more information.
100
Reconnection
Progress Sonic ESB endpoints appear as SonicMQ clients. From the perspective of
SonicMQ, the ESB reconnect implementation is a customized client reconnect
implementation.
Progress Sonic ESB always tries to reconnect when a connection fails, regardless of
whether the faultTolerant connection parameter is set to true or false.
The following sections explain how initial connections are created and how interrupted
connections are reconnected.
Initial Connections
The initialConnectTimeout value specifies for how many seconds an ESB endpoint will
try to establish an initial connection. This value is the total time during which the initial
connection is attempted, not the time spent attempting to connect to each URL. This
means that some URLs in the URL list might not be attempted. For non-fault tolerant
connections, this parameter is ignored and the endpoint tries each URL once.
Note Two special timeout values, 0 and -1, are available in SonicMQ but are not available in
Progress Sonic ESB, where configurations are limited to a value range of 1-3600.
If the SonicMQ initial connection cannot be established within the timeout period, the
Progress Sonic ESB reconnect logic will retry. This retry looks like the initial connection
attempt to the SonicMQ implementation. The retry starts trying to establish connections
again, starting with the first URL in the initial connection list. The Progress Sonic ESB
retry will continue until the container is shut down.
Interrupted Connections
The faultTolerantReconnectTimeout value specifies how many seconds an ESB endpoint
will allow for reconnecting a broken connection to the primary or backup broker using the
fault tolerant mechanism. If the connection is re-established before the timeout expires,
the endpoint will not be connected to a broker outside the original fault tolerant pair.
If the connection is not re-established within the reconnect timeout period, SonicMQ
signals that the connection failed and the Sonic ESB reconnect logic tries to create a new
connection using the initial connection process described previously. In this case, it is
possible that a connection can be established to a broker that is not a member of the
original fault tolerant pair.
101
The Progress Sonic ESB reconnect logic continues to attempt to re-establish an

interrupted connection until the container is shut down. After 20 retries, a delay is inserted
between each retry. The delay increases with each retry to a maximum delay of 30
seconds. Each retry cycles through all the URLs in the connection URL list.
Like the initialConnectTimeout value, the faultTolerantReconnectTimeout value is
limited to a range of 1-3600. The faultTolerantReconnectTimeout value is ignored for
non-fault tolerant connections; an interrupted non-fault tolerant connection will
immediately trigger the Sonic ESB reconnect logic.
Quality of Service
In the case of an interrupted connection, the ESB reconnect creates a new connection and
the connection state is lost. (In a fault tolerant connection, the state is preserved and the
connection never appears interrupted). This behavior has the following impact on QoS:
Best Effort Messages may be lost, no Fault or RME message is guaranteed.
At Least Once If the connection is lost before a message is acknowledged, the

acknowledgement fails, but messages already sent to the Outbox and Fault box are
still processed. A copy of an incoming message that is not acknowledged is sent to
the RME. The unacknowledged message is redelivered to the service (for queues), or
to the durable subscription endpoints (for topics).
Exactly Once If the connection is lost while a message is being processed, a copy
of incoming message is sent to the RME. The message is redelivered to the service
(for queues), or to the durable subscription endpoints (for topics). Messages sent to
the Outbox and Fault box are not processed in this case.
102
Configuring Connections
Setting the Ping Interval

You can enable or disable sending active pings on a connection by setting the
pingInterval connection property. When used where messages are sent to the endpoint at
a low frequency, the ping can detect a connection drop and trigger reconnect logic to keep
the connection alive. However, when large messages are sent on a slow network, a small
ping interval can cause a response failure that can be interpreted as a connection drop.
Consider the size and frequency of messages that will be sent to the endpoint when setting
this property:
For non-fault tolerant connections, the default pingInterval value is 90 seconds.
For fault tolerant connections, the default pingInterval value is 30 seconds.

Ping interval behavior for fault tolerant connections differs from that of non-fault tolerant
connections in that the ping does not require a response from the broker in fault tolerant
connections. A lack of response from the broker does not result in a connection failure in
this case.
Every endpoint has an associated connection. The following procedure describes how to
view existing connections and configure a new connection.
To view connections and configure a connection:
1.
In the ESB Configured Objects section of the Sonic Management Console, expand
the Endpoints folder, then select Progress SonicMQ Endpoint.
2.
In the right panel, click the Connections tab to view available connections.
103
104
3.
Select a connection. The lower right panel displays the properties of the selected
connection, as shown:
4.
Click New. The connection property fields in the Connection Maintenance panel are
cleared. Required properties in the Connection Maintenance and Init Parameters
sections are marked with an asterisk (*).
5.
Enter, accept, or select values for the following properties:

Property
Description
Connection Name
A unique, meaningful name.
Connection Type
Accept the required value, Progress SonicMQ Connection.
Connection URLs
One or a comma-delimited list of URLs for the Progress SonicMQ

brokers to make connections are made (in the format
[protocol://]hostname[:port]).
User Name
The user name to authenticate with the Progress SonicMQ broker.
Password
The password to authenticate with the Progress SonicMQ broker.
Login SPI
Classname
Optionally, you can pass the Login SPI classname to the SonicMQ
connection factory.
105

6.
Set the maximum sessions for this connection:

Property
Description
Maximum Receive
Sessions Per
Connection
When configuring a connection, you specify the number of sessions

Progress Sonic ESB creates on an underlying Progress SonicMQ
connection for Progress Sonic ESB entry endpoints:
Unlimited The default for a single connection configuration.
Progress Sonic ESB creates one underlying Progress SonicMQ

connection. All Progress SonicMQ sessions that Progress Sonic
ESB creates for endpoints share that single connection. There is
an unlimited number of receiving Progress SonicMQ sessions per
Progress SonicMQ connection.
Single Progress Sonic ESB creates a dedicated Progress
SonicMQ connection for each Progress SonicMQ session that it

creates for endpoints. There is a single receiving Progress
SonicMQ session per Progress SonicMQ connection. This setting
provides enhanced performance, but results in greater memory
and resource consumption throughput.
Important
106
Maximum
BEST_EFFORT
Sessions
The size of the pool of Progress SonicMQ sessions created for

sending messages at a BEST_EFFORT QoS level. This number should
grow as the number of listeners grows. Specify a numeric value. The
default is 3.
Maximum
AT_LEAST_ONCE
Sessions

sending messages at an AT_LEAST_ONCE QoS level. This number
should grow as the number of listeners grows. Specify a numeric
value. The default is 3.
Maximum
EXACTLY_ONCE
Sessions

sending messages at an EXACTLY_ONCE QoS level. This number should
grow as the number of listeners grows. Specify a numeric value. The
default is 3.
Maximum
Web Service
Sessions
The number of pooled sessions that can be used for Web service
invocations. Specify a positive integer value. The default value is 10.
Sonic ESB creates a SonicMQ temporary destination for each pooled session at the
time that each connection is created.
7.
Set the ping interval and fault tolerant connection parameters:

Property
Description
Ping Interval
The interval in seconds for sending active pings on the connection.

Specify a numeric value:
The default for non-fault tolerant connections is 90.
The default for fault tolerant connections is 30.
A value of 0 or any negative number disables the ping. See Setting the
Ping Interval on page 103 for more information.
Enable Fault
Tolerant
Connection
Specifies whether to enable fault tolerant connections for the endpoint.

This setting is optional, either True or False; the default is False. See
Fault Tolerant Connections and Reconnection on page 99 for more
information.
Initial Connect
Timeout
The interval in seconds during which a client can try to establish an initial
connection. Specify a numerical value; the default is 30 seconds. See
Fault Tolerant Connections and Reconnection on page 99 for more
information.
Fault Tolerant
Reconnect
Timeout
The interval in seconds that a client will allow for reconnection. Specify
a numerical value; the default is 60 seconds. See Fault Tolerant
Connections and Reconnection on page 99 for more information.
JMS
Connection ID
When a JMS Connection ID is entered ( a non-empty string), fault

tolerant clients can reconnect to a broker before the brokers pending
reconnect timeout is reached. However, taking advantage of this
functionality will not allow multiple, simultaneous JMS connections
using use the same JMS connection ID. See Fault Tolerant Connections
and Reconnection on page 99 for more information.
107

8.
Scroll down in the Connection Maintenance area to set the Secure Socket Layer
(SSL) properties. Set these properties only if you are using certificate-based
authentication:
Property
Description
SSL CA Certificates
Location
Specifies the location of the Certificate Authority (CA) certificate

used to connect to the Progress SonicMQ broker.
SSL Certificate Chain

File
Specifies the pathname that points to the file containing the

Progress SonicMQ broker certificate chain for SSL.
SSL Private Key File
Provides the pathname that points to the file containing the brokerencrypted private key for SSL.
SSL Private Key

Password
Provides the password to encrypt the broker private key for SSL.
SSL Certificate Chain

Form
Specifies the format of the file containing the broker certificate

chain:
PKCS7
PKCS12
LIST
SSL Cipher Suites
The value is a comma-delimited list of all cipher suites, in priority

order, supported by the Progress SonicMQ broker connection. For
broker-client communications the broker that initiates the
connection negotiates to the highest-priority cipher suite they both
support. The default is SSL_RSA_WITH_3DES_EDE_CBC_SHA.
SSL Provider Class
Specifies the Progress SonicMQ adapter class name of the SSL

implementation. The supported adapters are:
progress.message.net.ssl.jsafe.jsafeSSLImpl
(the default)
Note
108
progress.message.net.ssl.jsse.JSSEImpl
For information on the supported cipher suites, see Implementing Security in the Progress
SonicMQ Deployment Guide.
Deleting Progress SonicMQ Connections

9.
After you configure the properties, click Apply. The Sonic Management Console
displays the new connection in the Connections tab.
Deleting Progress SonicMQ Connections

The following procedure describes how to delete a Progress SonicMQ connection.
To delete a connection:
1.
Objects node, expand the Endpoints folder, click the Progress SonicMQ Endpoint
folder.
2.
In the right panel, click the Connections tab. The Sonic Management Console lists
the available connections under the Connections tab.
3.
Select a connection and click Delete.
4.
Confirm the selection. Progress Sonic ESB deletes the connection.
109
110
Chapter 4
Configuring Web Services
This chapter describes how to configure Web Services using WS-* standards in the
following sections:
Overview
Configuring WebService Protocols for ESB Processes
Related Configuration Documentation
111
Chapter 4: Configuring Web Services
Overview
Sonic ESB processes can invoke and implement web services that conform to the
WS-Security and WS-ReliableMessaging specifications. To enable this functionality, an
administrator must correctly configure messaging brokers, acceptors, and routings.
Sonic ESB leverages WS-Security and WS-ReliableMessaging support built into
SonicMQ. An overview of how this feature is supported in SonicMQ is described in the
Using HTTP Direct for Web Services chapter of the Progress SonicMQ Deployment
Guide. This chapter discusses the behavior of JMS clients that invoke or implement web
services. The configuration issues are the same for ESB processes as they are for JMS
clients, with one exception regarding the configuration of WebService protocols.
Configuring WebService Protocols for ESB Processes

The configuration of Web service protocols is documented in detail in the Configuring
Acceptors chapter of the Progress SonicMQ Configuration and Management Guide.
This chapter contains a Configuring HTTP(S) Direct Web Service Protocol Handlers
section that describes how to configure Endpoint URLs for web services. This section
refers to the following the dialog box, which is used to configure endpoint URLs:
112
An endpoint URL is used by SOAP/HTTP clients to access a web service implemented

by an ESB process. A URL extension can be mapped to a JMS destination or a URL. If it
is mapped to a URL, the URL must be either a JNDI URL or a sonic URL of the form:
sonic:///node_name/process_name
where node_name is either the literal string local or a valid node name where the process
is deployed.
If you specify the URL of an ESB process, the process must have an entry endpoint and
be deployed in an ESB Container.

For more information about configuring Web services, see the following SonicMQ
documents:
Table 3. Configuring SonicMQ for WS-Security and WS-ReliableMessaging
Configurable
Element
Location
HTTP Direct Acceptor

Web Service Protocol
See the Configuring Acceptors chapter of the Progress SonicMQ

HTTP Web Service

Protocol Routing
See the Configuring Routings chapter of the Progress SonicMQ

Broker
See the Configuring SonicMQ Brokers chapter of the Progress

SonicMQ Configuration and Management Guide.
113
Chapter 4: Configuring Web Services
114
Part II
Configuring XML Servers
Part II contains the following chapters:
Chapter 5, Monitoring and Logging
Chapter 6, Performance Tuning XML Servers
Chapter 7, Backing Up and Restoring Document Collections
115
116
Chapter 5
Monitoring and Logging
Chapter 5 includes the following sections:
Monitoring describes Sonic XML Server metrics and notifications.
Logging describes service-specific information and Sonic XML Server-related

information, including method parameters, inputs, and outputs, and transaction logs.
117
Chapter 5: Monitoring and Logging
Monitoring
Sonic XML Server monitoring includes metrics and notifications, as described in the
following sections.
Metrics
Sonic XML Server registers metrics with its ESB Container once during service
initialization. The ESB Container then registers these metrics with the management
container. Sonic XML Server metrics are dynamic and can be enabled and disabled by the
ESB Container.
Sonic XML Server provides metrics for:
Document actions:
ArchivedPerMinute
GetsPerMinute
(both from the document collections and the Inbox)

PutsPerMinute (both to the document collections and the Outbox)
RemovesPerMinute
Messages:
Processing actions:
118
Processed
TranslationsPerMinute
XQueriesPerMinute
Monitoring
The following procedure describes how to enable Sonic XML Server metrics.
To enable XML Service metrics:
1.
2.
Select a running ESB Container containing an XML Service instance.
3.
Right-click on the service-instance name, and select Metrics.... The Monitoring dialog
box opens with its Metrics tab:
4.
Select one metric or a group of metrics (by selecting the parent folder) and select
Enable. The Sonic Management Console enables the metrics you selected, for
example, the entire group of document metrics:
119
If you select an individual metric, more options become available. You can disable the
metric or watch the metric in a Metrics Watcher window in both a bar chart and line
graph, for example:
For information on watching and disabling metrics, as well as general information on

metrics, see the Monitoring chapter in the Progress SonicMQ Configuration and
Management Guide.
120
Monitoring
Notifications
Notifications are associated with the delivery of event information. The ESB Container
registers Sonic XML Server notifications with the management container. The Sonic
Management Console subscribes to notifications and can display notifications in a Watch
window.
Sonic XML Server provides this notification:
xmlService.invalidArchiveAddress
Notifications from the management containers components include:
system.state.Offline
system.state.Online
The xmlService.invalidArchiveAddress notification is published when a document

collections archive address is invalid at runtime. Its attributes are:
serviceName Name of the XML Service that performed the operation
documentCollectionName Name of the collection on which the operation was

performed
documentName Name of the document being archived when the failure occurred
message Message giving further details of the reason for the failure
The following procedure describes how to monitor notifications.
To monitor notifications:
1.
2.
Select a running ESB Container containing an XML Service instance, right-click on

the service-instance name, and select Notifications... . The Monitoring dialog box
opens with its Notifications tab:
121

3.
You can select one or more notifications, and for each notification, select Watch and
select whether to watch:
By Component (ESB Container)
By Container (management container)
By Domain
The Sonic Management Console marks notifications that are being watched:
The Sonic Management Console opens a Notification Watcher.

For general information on notifications and on watching notifications and viewing
notification attributes, see the Monitoring chapter in the Progress SonicMQ
See also the Progress SonicMQ Administrative Programming Guide and the Progress
Sonic Event Monitor Users Guide documentation for information on other options for
tracking these notifcations.
122
Logging
Logging
Sonic XML Server sends operational information to container logs. Management
containers send application and status messages to the console and to a log file. ESB
Containers also provide access to a common log file for all the services they host. Fatal
errors are always sent as an exception stack trace to the log and show root causes when
available. The default log file is domainName.containerName.log in the management
containers working directory.
Log information includes:
Service-specific information Includes state changes within the service itself
Sonic XML Server-related information Includes method parameters, inputs,

and outputs
You can turn on internal logging for debugging purposes. Set the Java system property
com.sonicsw.xe.logging on the management container hosting the XML Service. In the
Sonic Management Consoles Manage view, edit the containers Properties and enter
your Java system property settings on its Environment tab, using one or more of the
following:
Script
Script.Actions
Script.Actions.Get
Script.Actions.Put
Script.Actions.Remove
Script.Actions.XQuery
Script.Actions.XSLT
Script.Parser
Management.collections
Management.documents
Collections
Collections.Factory
Collections.Storage
Collections.Storage.Utils
Utils
Utils.XPath
XMLService.message
XMLService.service
Archive
123
The following screen shows the Environment tab of a management containers

configuration:
Some of these strings are hierarchical, so you can use one setting such as, Script.Actions,
to include others such as, Script.Actions.Get.
For more information on logging, see the Configuring Containers and Collections
chapter and the Managing Containers and Collections chapter in the Progress SonicMQ
124
Chapter 6
Performance Tuning XML Servers
Most users of Sonic XML Server experience high performance without tuning. This
chapter contains suggestions that can optimize your XML Server configuration and
application design for your applications patterns of data access. Because there can be
trade-offs and tuning is highly application-specific, you should test your application to
determine which suggestions are most effective.
This chapter contains the following sections:
Tools for Tuning XML Servers shows where tuning parameters are accessed.
Tuning XML Services and Collections explains transactions and concurrency and
describes how to tune action flows, XML Services, and collections.
Tuning Data Storage contains suggestions for distributing documents, in

collections, determining locations for collections, using message routing, tuning
storage maintenance, and managing the transaction log.
XPath Expressions and XSLT Transformations discusses ways to optimize XPath

and XSLT performance.
125
Chapter 6: Performance Tuning XML Servers
Tools for Tuning XML Servers

The suggestions and recommendations in this chapter involve several aspects of Sonic
XML Servers. Some are design and operational issues. Others are configuration functions
accessed through the Sonic Management Console connect to the domain that hosts the
XML Services configuration. Three specific tool are used for the settings in this chapter.
126
Setting Properties on an XML Service Type Instance

Maintain properties for an XML Service Type instance through the ESB Configured
Objects section of the Sonic Management Console:
For more information about setting properties on a service instance, see ESB Configured
Objects on page 26.
127
Setting Properties on a Component in an ESB Container

Maintain properties for a component in an ESB Container through the ESB Configured
Objects section of the Sonic Management Console:
This figure shows an ESB Container that has added an instance of XMLServiceType.
In this example, the instance shows that it has 5 listeners. The default value is 1.
For more information about maintaining listeners, see Changing the Number of
Listeners on Services in ESB Containers on page 61
128
Setting JVM System Properties on a Management Container

Maintain JVM system properties for a management container through the Sonic
Management Console by opening the containers Properties, and then choosing the
Environment tab, as shown:
This illustration show an example of a logging setting, as used in Logging on page 123.
For more information on management containers and their environment settings, see the
129
Tuning XML Services and Collections

The following sections discuss update versus read-only transactions, locking vs. nonlocking XML Services, tuning action flows, configuring XML Services and collections,
and managing address space and cache size, and how these impact performance. The first
section provides background information on transactions and concurrency control.
Transactions and Concurrency Control

Each Sonic XML Server contains a transaction scheduler that dynamically balances the
resources required to begin and commit transactions as Sonic XML Server action flows
are executed. Within an XML Service thread, each action flow executes within its own
virtual transaction. This ensures that the data viewed and manipulated by the thread is
correctly isolated from other threads that are executing their own virtual transactions.
A datastore transaction is the actual physical transaction that commits changes in the
datastore; it controls data locking and logging to manage concurrent access by multiple
XML Service threads accessing the same datastore. The transaction scheduler allows
several virtual transactions to execute within a single datastore transaction whenever this
can done without compromising data consistency.
The transaction scheduler ensures that:
A virtual transaction commit operation does not return if any data it accessed or
modified is not fully saved in the datastore through a full datastore transaction
commit.
Different threads that are executing read operations at about the same time can
execute concurrently with minimal thread blocking.
Threads that execute update operations run in exclusive mode. This avoids any
possibility of inconsistency in XML data from update operations in other threads.
This sharing of datastore transactions reduces the relative cost of transaction overhead per
virtual transaction. It also improves response time because less thread synchronization is
required. However, to ensure correct data consistency, it sometimes requires completed
virtual transactions to be blocked until the underlying transaction is committed. This can
increase the response time for the threads that are waiting.
When more than one instance of a Sonic XML Service accesses data within the same
collection, the underlying XML Server concurrency mechanisms ensure transactional
integrity and a consistent data view. This management is performed by a system of lock
coordination among XML Service processes.
130
This system provides forward-caching of XML data in Sonic XML Server, independent
of the storage location of the data. In addition, fine-grained fetching and writing of XML
nodes allows XPath access to perform optimally with very large documents.
This system has the following characteristics:
Every XML Service accesses only committed, consistent data, even if many XML
documents and collections are accessed.
When there is no conflict, control of data and locking migrates from the Sonic XML
Server datastore server to the data cache of the Sonic XML Service. XML Services
then runs in-memory with a minimum of network access. In this manner,
simultaneous read access is supported for many XML Services.
When one XML Service updates data that is cached by another XML Service, the two
XML Services collaborate to call back locks, invalidate stale data, and refresh the
cache of all XML Services that are using the data.
Fetching, refreshing, and writing of data is on-demandit is performed only for those
blocks of data actually read or updated by Sonic XML Server. When an update
operation is in progress, an XML Service in locking mode might have to wait for
completion before it can acquire shared data.
In nonlocking mode, the datastore server provides a time-consistent snapshot of data

to one or more read transactions that might execute concurrently with an update
transaction. This eliminates any lock waiting, though it means that read transactions
do not see changes made by the overlapping update transactions.
131
Tuning Action Flows, Transactions, and XML Services

The following suggestions and settings tune action flows, transactions, and XML
services.
Use Short Running Action Flows

Suggestion: Use short-running action flows.
Long-running action flows can increase the time for an XML datastore transaction to
commit. If you must use long-running action flows, route them to a different XML
Service. For example, assuming you have the flow:
a. Run XQUERY on CollectionA
b. Run XSLT on the result of step a.
c. PUT into CollectionB
d. PUT into Outbox
It would be better to have steps a, b, and d in one xaction, and then do step c separately.
Separate Update and Read-only Action Flows

Suggestion: Separate update and read-only action flows to reduce the processing time of
action flows.
Update action flows run in update transactions that block all other action flows routed to
the same XML Service, even those that access a completely different set of documents.
Update transactions must have write access to the XML datastore. Update transactions
can be performed only by XML Services that have a locking concurrency mode. (Update
transactions have a performance cost since they block concurrent transactions.)
Read-only actions can run concurrently, return immediately upon completion, and do not
block until the datastore transaction commit, as long no update actions have run in the
same datastore transaction. In a nonlocking XML Service, this is always true. Read-only
transactions can be performed by XML Services that have either a locking or nonlocking
concurrency mode. Read-only transactions in a nonlocking XML Service do not obtain
read locks on what they read, but read-only transactions in a locking service do obtain
read locks.
132
Specify auto select for the Transaction Level

Suggestion: Unless you have a specific reason to obtain a write lock for a read-only action
flow, it is more efficient to specify auto select for your transaction level.
Action flows are either update or read-only and you can specify the transaction level for
an action flow as always update to specify that the action flow is always part of an update
transaction or auto select so that the transaction type is determined by Sonic XML Server
based on the contents of the action.
See the online help in the Sonic Workbench for information about action flows.
Access a Document Collection from One Update XML Service.

Suggestion: Access a document collection from only one update XML Service.
XML Services are configured in the ESB Configured Objects section of the Sonic
Manangent Console as either:
Locking Read-only actions are serialized with respect to update actions running
in the same XML Service.
Nonlocking Read-only actions run concurrently with update actions running in a

locking XML Service.
Every collection must have at least one locking XML Service so documents can be added
and removed. For collections that have update actions run against them frequently, each
collection should have its own locking XML Service. Update operations include PUT into
collection, REMOVE from collection, and management operations such as archiving and
creating collections. The exceptions are GET, XSLT, and XQUERY. Occasionally you can have
XSLT or XQUERY actions that are special java or XIS extensions to modify data, but this
is not relevant except in advanced useage. All other actions are read-only. Updates are the
primary operations involved in tuning an application for concurrent access. Sonic XML
Server locks parent elements of a node that is being updated to guarantee the integrity of
the operation. This can limit access to the document for other updating XML Services.
You should identify any key documents that require update access by many users. You can
then optimize the document structure and routing to XML Services to minimize wait time.
Each collection should have no more than one locking XML Service accessing it to
eliminate lock contention and service delays in response. Having a single locking XML
Service per collection also prevents conflicts that can hamper performance.
You can provide as many nonlocking XML Services per collection as you want without
creating conflicts. Since nonlocking caches are nonblocking, read operations do not have
133
to wait for update operations to be finished as they do for locking XML Services. This
allows concurrent read operations on the datastore.
When more than one locking XML Service is involved, normal transaction management
introduces the risk of transaction deadlocks. When an XML Service experiences a
deadlock, it retries the transaction. If the retries are unsuccessful, a deadlock exception is
thrown, the input message is rejected and sent to the rejected message endpoint (RME).
A deadlock ends a datastore transaction and all action flows currently active in that XML
Service, including action flows that have completed and action flows waiting for the
XML datastore commit. All of the action flows currently running in the datastore
transaction must then be explicitly restarted by resending the rejected message to the
XML Service. However, retrying a transaction can impact overall system performance.
To change this property, modify the Concurrency Mode setting for the service instance.
See Setting Properties on an XML Service Type Instance on page 127 for more
information.
Perform Read Transactions by Nonlocking XML Services.

Suggestion: Have read transactions performed by nonlocking XML Services.
Transaction concurrency bottlenecks can be drastically reduced by routing requests to
exclusive XML Services or by specifying nonlocking XML Services. Read-only action
flows running in a locking service can be blocked by update action flows or another
service. Therefore, you get better performance by having read transactions performed by
nonlocking services. Action flows running in a nonlocking service instance are never
blocked by update action flows and never have to wait for the XML datastore commit
before returning results to the client.
To change this property, modify the Concurrency Mode setting for the service instance.
information.
Configure the Transaction Open Interval and Commit Transaction If Idle

Suggestion: Configure the Transaction Open Interval and Commit Transaction If
Idle XML Service properties for best performance.
Both update and read-only actions can be batched in the same datastore transaction. The
Transaction Open Interval specifies the interval during which Sonic XML Server
schedules action flows to execute within a datastore transaction.
134
An XML datastore transaction batch is only open to new action flows until the
Transaction Open Interval elapses. When the interval expires, the XML datastore
transaction commits if there are no active action flows still running in the transaction. An
interval of one to ten seconds is recommended.
Update action flows are always serialized with respect to all other action flows running in
the same XML Service. Update action flows block until the XML datastore transaction
commit. JMS message ordering is not guaranteed, and therefore, the action flows are not
guaranteed to run in any specific order.
Setting Commit Transaction If Idle to true causes the XML Service to commit the
XML datastore transaction before the Transaction Open Interval elapses whenever
there are no action flows waiting to be scheduled. This can result in update actions
returning sooner. However, this also reduces transaction batching and can reduce the
overall service throughput.
To change these properties, modify the Transaction Open Interval value, and toggle its
Commit Transaction if Idle setting. See Setting Properties on an XML Service Type
Instance on page 127 for more information.
Set Multiple Listener Threads on the ESB Container

Suggestion: Configure an XML Service to use multiple listener threads per ESB
Container.
The number of listener threads is specified when an XML Service is deployed in an ESB
Container. Set the number of listener threads to correspond to the number of requests that
can be serviced within the Transaction Open Interval.
The normal range of listener threads is 1-30 threads. Adding additional listener threads
above the 1 specified by default can significantly improve performance. A range of 15-20
listener threads per XML Service is recommended for the average configuration. This
allows multiple action flows to be batched into XML datastore transactions, and spread
the overhead of XML datastore commits over multiple action flows. A value higher than
20 threads provides only marginal improvement in performance.
To change this setting, modify the Listeners on a service instance deployed in an ESB
Container. See Setting Properties on a Component in an ESB Container on page 128 for
more information.
135
Tuning XML Service Resources

Each XML Service instance has the following resources:
Address space Mapped from the virtual memory range reserved for Sonic XML
Server at startup. This allows XML Server to identify and reference XML nodes and
metadata without having to allocate memory or fetch data.
Data cache Allocated within virtual memory and used to retain XML documents
in memory across operations and transactions.
Network connections To the XML Server lock manager and datastore server.
Collection data for each XML Service is retained in memory on a most recently used
basis. Ensure that the size of the cache can comfortably hold the XML nodes and indexes
that are repeatedly accessed. Also ensure that there is enough RAM on the system to
accommodate the XML Services. Otherwise, the standard virtual memory facilities of the
system start swapping, which eliminates many of the benefits of caching.
The following settings describe how you can tune address space size, cache size, and
cache space affinity to optimize cache performance.
Tune the Address Space Size

Suggestion: Adjust the XML Service Address Space Size configuration property.
The address space size specifies the size of the region of virtual memory that is reserved
for in-memory representation of the XML Server datastore. The maximum size of this
regions depends on how virtual memory, swap space, and heap allocation are managed by
the operating system.
Address space is reserved by Sonic XML Server in chunks of 64KB and can be as much
as one gigabyte, if needed. Address space reserved for an XML Service is not available
to other applications or the operating system. The overall performance cost of managing
it is relatively small. The cost consists of CPU time to remap address locations that are
used to reference XML documents, indexes, and metadata.
Each running XML Service has a fixed amount of address space. This space is consumed
as indexes or collections are traversed within a transaction, and then released after
garbage collection, which happens in the background after the transaction commits. By
deferring the recycling of address space, XML Server helps increase the chances of hot
traversal to those pages that are cached in memory and still have all addresses correctly
mapped.
136
Some transactions, such as adding an index to a large collection, automatically release

address space in the middle of an operation. For certain unoptimized queries and for very
long transactions, however, address space is progressively consumed during the
transaction until the transaction is committed. In the worst case, the configured address
space size is exhausted and a restartable exception is thrown. There are several ways you
can avoid this:
Increase the amount of address space allocated to the XML Service when you
configure it in the Sonic Management Console.
Add indexes to optimize queries and avoid lengthy sequential searches.

For key operations, including creation of indexes and insertion into collections, XML
Server dynamically releases address space during execution. This allows a single request
to perform the operation even when the total amount of data managed exceeds the
configured address space limit.
To change this property, modify the Address Space Size setting for the service instance.
information.
In rare cases, you might want to tune the internal trigger points for this address space
release by setting the following environment variables for the container hosting the XML
Service:
XLN_INDEX_NODE_COUNT_AS_RELEASE controls how often address space is released as

you create an index on a large collection (the default is 20,000 nodes).
XLN_DIR_ENTRY_COUNT_AS_RELEASE controls address space release when deleting

documents (the default is every 100 files deleted).
To set these environment variables, use the Sonic Management Consoles Manage view
to edit the containers Properties and enter your settings on its Environment tab, as
illustrated on page 124. For more information about environment settings, see the
137
Adjust Cache Size

Suggestion: Adjust the XML Service cache size (specified by the Cache Size XML
Service configuration property.
Performance for updates and queries is sensitive to cache size. To determine the optimum
cache size for your application, try to minimize the number of times the client must swap
pages out of the cache and send them back to the server. Consider the following factors:
Amount of data that is accessed XML Services that are accessing or updating
large amounts of data need larger caches.
Amount of physical memory on a machine Usually, it is desirable for the cache

to stay in physical memory rather than to be swapped out to disk.
Data access patterns A large datastore of documents might have a relatively small
number of documents that are regularly returned from queries or updated and might
not require as large a cache.
To change this property, modify the Cache Size setting for the service instance.
information.
Take Advantage of Cache Affinity

When queries access documents that have already been retrieved and cached, query speed
is improved. Grouping documents in collections so that queries retrieve cached data can
enhance performance.
For Progress Sonic ESB clients, a high level of cache affinity is ensured by routing
requests to XML Service instances that are appropriately specialized in designated areas
of the storage hierarchy.
Cache affinity describes the degree to which data accessed within a program overlaps with
data already retrieved on behalf of a previous request. Where there is high cache affinity,
strong cache management architectures such as XML Server have a relative performance
advantage.
For an XML Service, the effectiveness of cache affinity has three levels:
Cold access A request accesses XML documents that have not been retrieved
recently by this XML Service, or have been called back for another XML Service to
update. The data must be retrieved from the datastore server and possibly from disk
storage. (A fair amount of disk file caching occurs on the server side.) Cold access is
typical of random queries against a collection.
138
Warm access The request involves data that has been retrieved by a prior
transaction and is still within the XML Servers data cache, but requires remapping
of address space prior to use. Warm access is typical when:
A user executes consecutive XPath expressions, XSL transformations, and update

operations against the same document.
Successful routing rules funnel a large number of requests for a modest-size

directory to a single XML Service instance.
Hot access Required data has already been accessed in the current transaction, and
can be immediately used without any fetching or mapping of data.
It is typical to single out collections with a high query load, and assign each to its own
read-only cache.
Tuning Collections
Suggestions for tuning collections involve document size and use of indexes.
Tune Document Sizes

Suggestion: Tune the size of documents in collections.
Document size can affect the time it takes to load a document, insert it into a collection,
and perform a nonindexed query. The persistent representation of an XML document can
be up to 2.5 times greater in size than the original XML document. This occurs because
the parsed format of a document is optimized for speed of access as opposed to size. Keep
this in mind when you are planning the storage capacity of your system. In addition, large
documents allow less flexibility when assigning data to collections.
Select the Strip Whitespace option when you configure the collection to decrease
document storage size and searching time. (For more information, see the Progress Sonic
ESB Product Family Developers Guide in the Eclipse help.) Whitespace can
significantly add to the size of a persistent document. This increases memory use and I/O
time. (The XML standard requires a text node to be fully represented, even if it contains
only white space.) Appropriate whitespace formatting can easily be reintroduced to the
document through an XSL transformation.
139
Index Large Collections

Suggestion: Define indexes for large collections.
You should evaluate the need for an index before creating one. indexes speed certain
queries by narrowing the number of documents in the collection being queried. However,
indexes also require substantial resources for update and maintenance. Do not define an
index unless you are confident that the index can minimize the number of documents
traversed in searching a collection. Generally, you define indexes only for queries that
must search large quantities of data.
Indexes are most useful when they are defined by the most selective criteria possible. For
example, if you are searching for a person, it is more effective to index on surname than
gender. Similarly, if you are searching for a location, it is more effective to index by
Zipcode than by State.
Tuning Data Storage

The following sections contain suggestions on distributing documents, determining
locations for collections, message routing, and tuning storage maintenance.
Distributing Documents in Collections

For large data sets (greater than 100 MB), consider distributing the XML documents into
separate collections.
How you distribute your documents and collections can have a significant effect on the
speed of queries and transformations. For example, if you have a DepartmentsCollection,
and most of your use cases access the document collection by product category, you can
distribute your documents based on category (for example, PurchasingCollection,
AccountingCollection, and SalesCollection) and have each category updated by a
separate XML Service.
You can have an XQUERY that searches over multiple collections when you need get data
that might be in more than one collection.
140
Tuning Data Storage
Message Routing
You can use the Sonic ESB Content-based Routing (CBR) service to route messages to
the appropriate service instance for a document collection. You can define CBR routing
rules to meet a broad range of scalability and concurrent access requirements. (For
information on the CBR service, see Implementing a Content-based Routing Service in
the Progress Sonic ESB Product Family: Developers Guide in the Eclipse help.)
When you configure services, first identify groups of documents that are accessed
independently of each other. Then organize each such set in its own collection. For
example, different kinds of insurance policies could be organized into separate
collections. Each collection could then be used to define a CBR routing rule that routes
relevant read or update operations to a relatively specialized XML Service instance.
The primary goal is to route requests so that only one XML Service is updating a given
collection. The next priority is to subdivide the work among XML Services so that the
load is balanced. Each cache should have an opportunity to hold a substantial part of its
subset in memory.
When you route requests to a nonlocking, read-only XML Service, you can optimize
queries that overlap in the document elements, indexes, or stylesheets they access.
Because the operations in a nonlocking service are insulated from recent and concurrent
update operations, it is possible that the data they retrieve is slightly out of date. The
administrator can control how out of date this view can become by adjusting the
Transaction Open Interval for the service.
141
The following figure shows messages being routed by content to one or more XML
Service instances:
Use Case
Collection
Service Use
XSLT
50 operations/min
Customers
Read-only
Service
PUT
20 operations/min
Retail
Update
Service
PUT
2 operations/min
Wholesale
XQUERY
2000 operations/min
Policies
Read-only
Services
PUT
400 operations/min
Car
Update
Service
PUT
10 operations/min
Home
Update
Service
PUT
20 operations/min
Life
The Read-only Services for Policies represents multiple service instances with many
listener threads and in separate containers.
142
Tuning Data Storage
Locations for Collection

Typically, a system administrator focuses on collections, and how they relate to actual
disks and files on the network. The administrator:
Defines XML Services to manage the use of disk space on various hosts
Allocates collections for those services based on the expected size and growth factors
for the collections.
Storage decisions are often driven by hardware reliability and recovery concerns. In some
cases, an administrator can improve performance and scalability by the following actions:
Move the XML Server transaction log to an isolated disk with optimal sequential
write performance if applications are update-intensive. (see Managing the
Transaction Log on page 145).
Put collections on fast, defragmented disks and try to balance the disk load for
databases, flat files, and the XML Server transaction log across different physical disk
devices.
Locate collections on the same host as the XML Service to improve the XML retrieval
performance for those service instances. (The datastore server is tuned to use fast,
shared-memory, data transfer when it is on the same machine as the service instance.)
The relative improvement for updating caches is smaller because commit
performance is gated by disk write speed.
Manage the number of collections. Each collection requires some metadata that is
managed by the datastore server. Small collections (less than 1 MB) require the same
schema/storage metadata and server management overhead as larger ones.
Locate XML Services on more than one host to add additional datastore servers (For
more information, see the Progress Sonic ESB Product Family Developers Guide in
the Eclipse help.). This increases the maximum throughput achievable for updateintensive applications, because disk write operations can be distributed across
multiple transaction logs. However, it is uncommon for datastore servers to create
performance bottlenecks.
143
Tuning Storage Maintenance

The following are suggestions for scheduling tasks, backup, and compression to tune
storage.
Do Maintenance on Collections
Suggestion: Perform maintenance on collections for peak efficiency.
Maintaining collections efficiently decreases the number of documents that queries must
search through and also decreases the number of out of date results returned. There are
two ways to maintain collection size:
Manually removing documents
Archiving documents
Compress Collections
Suggestion: Compress collections through backup and restore.
In a collection, Sonic XML Server organizes documents within internal directories that
contain a thousand documents per directory. When documents are removed through timeto-live or are deleted by a DELETE action they are removed from the directory but not
replaced. New documents are added to new directories, not old directories. Older
directories will not contain the maximum number of documents. Therefore, collections
that are subject to frequent document removal take up slightly more space per document
than those that do not have frequent document removal.
Schedule Intensive Operations

Suggestion: Schedule intensive operations in off-peak hours.
Since all update intensive operations affect concurrency, delete operations are optimally
performed in off peak hours. The same is true of documents removed from collections
through the time-to-live (TTL) feature. Delete operations in a collection are often less
time sensitive than updates or queries.
It is possible to perform maintenance at a scheduled time every day. The time when it is
performed depends on the time when the XML Service was started. (You can use
Activation Daemons to schedule these operations. See Using Activation Daemons on
page 78 for information on Activation Daemons.)
144
Tuning Data Storage
However, there is still a requirement to clean out or archive old data in a way that ensures
continuous, scalable operation. Persistent XML can have many dependencies with
indexes and storage structure. XML Server traverses every node within a document you
are deleting. Deletion time scales with the total number of nodes deleted, plus the number
of index entries that must be removed.
You can also delete an entire collection in the Sonic Management Console without going
through these fine-grained operations. (For more information, see the Progress Sonic ESB
Product Family Developers Guide in the Eclipse help.)
Archive Documents
Suggestion: Regular archiving of documents improves query speed.
Query speed improves when there are fewer documents for unindexed queries to search
through. The time-to-live feature can be used to automatically archive documents. For
more information, see the Progress Sonic ESB Product Family Developers Guide in the
Eclipse help.
Managing the Transaction Log

The transaction log, sonicxmlserver_install_dir\XMLDatabase\etc.log, is a binary log
file that contains all transactions that have not yet been propagated to the XML data stores.
Do not modify or delete this file.
The transaction log can grow and affect performance. Moving the transaction log to an
isolated disk with optimal sequential write performance can improve overall
performance.
Important If you decide to relocate the transaction log, contact Sonic Technical Support for
information on how to do this safely.
145
XPath Expressions and XSLT Transformations

The Progress Sonic ESB Product Family: Developers Guide in the Eclipse help
describes how to use XQuery and XSLT with Sonic XML Server. Both XSLT stylesheets
and XQuery expressions include XPath expressions, and the performance of XPath
expressions is an important part of overall XSLT or XQuery performance. For this reason,
most of the suggestions offered for XPath optimization can be used for both XSLT and
XQuery actions.
XPath Expressions
Improving XPath performance begins with an analysis of application use cases that
retrieve stored XML through XPath expressions. When you have a clear sense of the
patterns of access, including relative size and frequency of XPath retrieval for specific
XML nodes, you can identify areas for optimization.
XPath expressions in XML Server are processed dynamically as they are passed to the
XML Server XPath processor. The performance achieved when a given XPath request is
executed depends on several factors:
Time required to evaluate and optimize the XPath expression
Efficiency of the optimized XPath execution tree, which in turn depends on:
Number of XML elements reachable from the target document
Use of indexes to optimize query constraints
XML Server caching of documents and indexes
Data extraction, sorting, and serialization that must be done on the return set
The following suuggestions can improve XPath performance.
Match Indexes to Queries

Suggestion: Design indexes to match queries as closely as possible.
Sonic XML Server uses a value index, which locates all of the nodes that share:
A common ancestor element
A specified XPath key path
Matching text or floating-point data value for nodes matching that key path
146
A value index can quickly compute the subset of nodes that match an XPath predicate.
The more closely the XPath expression matches an existing value index, the more certain
you are that the XPath processor can pick up the index in optimization.
Indexing is not required in all situations. Unlike most XML/RDBMS solutions, XML
Server retains the XML DOM structure within storage. This means that many XPath
operations involve simple in-memory DOM traversals that execute extremely fast, even
without an index. Retrieving child nodes from an element or locating parent nodes occurs
at in-memory speeds and does not require indexing. However, selecting a small set of
XML nodes from a large document or collection can be greatly enhanced with appropriate
indexing.
For example:
//Enterprise/personnelData/[lastName=Smith]
collection(foo) //a/b[c=Fred]
INDEX on collection foo
INDEX path = //a/b
Key path =c
Control Results Set Size

Suggestion: Control the XPath result set size.
The data returned by an XPath expression is well defined by the XPath string and the
DOM structure of the document being queried. The size of the results has an important
impact on XPath performance because:
All child nodes included in the result must be explicitly retrieved from the collection.
Address space reserved for returned nodes cannot be dynamically released during the
transaction, eventually limiting the size of the return set.
If the operation returns an XML string, all tags and text data must be accumulated in
an in-memory buffer.
The amount of work required by the application to process results is generally

proportional to their size.
Analyze Whether Excess Nodes Are Returned.

Suggestion: Analyze the nodes to be returned.
The best way to control result set size is to examine the XPath expression to confirm that
all the nodes returned are required by the application. For example, if you want only the
authors of books with a certain title:
147
The query, collection("bookstore")//book[title = "On Walden Pond"], is too broad

because it returns all book information, not just the authors.
The query, collection("bookstore")//book/author[../Title = On Walden Pond],
returns only author elements, but it requires the query engine to check for a title match
for each author.
The query, collection,("bookstore")//book[title = "On Walden Pond"]/author,
immediately selects the correct books, and then returns only the author information.
XSLT Transformations
XSLT stylesheets transform XML documents into another schema. For example, another
dialect of XML for business process integration. XSLT performs this operation on
demand within XML Server, and makes the result accessible to the action flow. You can
optionally return the output or save it in a collection.
In general, the time required to complete a transformation is a function of the size of the
input document and the complexity of the XSLT stylesheet. The steps in XSLT processing
include:
1.
Preprocess the XSLT file to create an optimized stylesheet.
2.
Select nodes from the XML source document, based on the XPath expressions
specified in the XSLT selection syntax. (Some XPath query optimization occurs here,
as discussed previously.)
3.
Match selected nodes against the patterns in the XSLT templates.
4.
Generate the output document.
The optimized stylesheet object is a transient structure that resides on the server only for
the lifetime of the current transaction.
The following suuggestions can improve XSLT performance.
XSLT Node Selection

Suggestion: Narrow the result set passed to the transformation engine
Selection of the input source is important for efficient transformation. To the degree you
narrow the result set passed to the transformation engine, you reduce the time consumed
in pattern matching and generation. Examine the query statements in your XSLT
stylesheet to restrict the number and size of the XML nodes returned to the smallest
workable set.
148
XSLT Template Matching

Suggestion: Perform filtering in the selection expression rather than the template
matching expression
Depending on the complexity of the XSLT stylesheet, matching the XPath expression of
the template to the selected source data can require intensive computing. You should try
to ensure that any filtering that must be done is achieved in the selection XPath expression
rather than in the template matching XPath expression.
Suggestion: Make XSLT template matching as straightforward as possible.
Use simple XPath expressions that can achieve node comparisons without requiring a lot
of node traversal. Try to avoid recursive XSLT pattern matching. Additional information
about tuning XPath expressions is available in XPath Expressions and XSLT
Transformations on page 146.
XSLT Output Generation

Generating the output document tends to demonstrate predictable, scalable performance.
If the output is stored within Sonic XML Server, rather than in subsequent script actions
or returned from scripts, consider that:
Generating the output takes longer because of XML Server DOM calls that are
required to construct the document.
Subsequent updates and queries should generally perform better because of XML
Server caching.
The application is responsible for synchronizing any changes, that is, regenerating the
output document if any of the inputs have changed significantly.
149
150
Chapter 7
Backing Up and Restoring Document

Collections
The Progress Sonic XML Server backup and restore utilities provide protection from
unintended data corruption or data loss. These utilities support full and incremental
backup and restoration of document collections.
Chapter 7 describes these utilities in the following sections:
Backing Up Sonic XML Server Document Collections describes how to perform

full and incremental backups of Sonic XML Server document collections.
Restoring Sonic XML Server Document Collections describes how to restore Sonic
XML Server document collections.
151
Chapter 7: Backing Up and Restoring Document Collections
Backing Up Sonic XML Server Document Collections

To implement backup procedures for the Sonic XML Server document collections at your
site, you can use a combination of backup operations:
Full backup Backs up specified XML document collections.
Incremental backup For given XML document collections, backs up all

documents that changed since the last full backup or incremental backup at a lower
level.
To design and implement a backup routine for your site, follow these steps:
1.
Design a backup schedule. See Designing a Backup Schedule on page 152.
2.
Choose locations for backup-related files. See Files Generated by the Backup and
Restore Utilities on page 155.
3.
Make a full backup. See Performing Full Backup on page 157.
4.
For each subsequent day in the backup schedule, perform the backup operation for
that day. See Performing Full Backup on page 157 and Performing Incremental
Backup on page 158.
Designing a Backup Schedule

Incremental backup can reduce the amount of data that needs to be backed up, particularly
for Sonic XML Server document collections with a relatively small number of
modifications. Note that using incremental backup can increase the time required for
restoring the XML data stores.
A typical backup schedule assigns backup operations to each day of the week. For each
incremental backup operation, it specifies the backup level to use. To follow the schedule,
you must perform, for each day of the week, the operations assigned to that day.
You should perform each days backup operations during a low traffic time period, that is,
a time period during which there is relatively little access to the Sonic XML Server
document collections being backed up.
Level 0 specifies a full backup. You specify a backup level from 1 to 9 for each
incremental backup. Documents modified since the last backup at a lower level are copied
to the backup image.
152
You can specify XML document collections that were modified since the last backup at a
lower level be copied to the backup image. For example, you could perform a level 2
backup on Monday, followed by a level 4 backup on Tuesday. A subsequent level 3
backup on Wednesday would contain all XML documents modified or added since the
level 2 (Monday) backup.
To perform incremental backups, you must consider what levels to use, and when to back
up at each level. Consider:
Amount of data backed up Increasing the backup level from one day to another
can decrease the amount of data that must be backed up.
Complexity of restoring Increasing the backup level from one day to another can
increase the number of backup images that must be restored.
The following examples show two different backup schedules:
The schedule in Table 4 consists of a full backup on Sunday, and an incremental

backup every subsequent day of the week that backs up every directory that has
changed since the previous days backup. This strategy can result in the backing up
of less data for a given week. But restoration can be more complex than with the
schedule in Table 5. Restoration to Friday, for example, requires the restoration of the
images from Sunday through Friday (six images in all).
:
Table 4. Sample Backup Schedule with Daily Increments
Day
Level
Description
Sunday
0 (full)
Full backup of all specified Sonic XML Server document

collections
Monday
Back up all documents that changed since Sunday
Tuesday
Back up all documents that changed since Monday
Wednesday
Back up all documents that changed since Tuesday
Thursday
Back up all documents that changed since Wednesday
Friday
Back up all documents that changed since Thursday
Saturday
Back up all documents that changed since Friday
153
The schedule in Table 5 consists of a full backup every Sunday, followed by

incremental backups Monday through Wednesday. These include documents that
changed since Sunday. They are followed by incremental backups Thursday through
Saturday that back up directories that have changed since Wednesday. This strategy
can result in backing up more data in a given week. But restoration is simpler than
with the first schedule. Restoration to Friday, for example, requires the restoration of
images from Friday, Wednesday, and Sunday (three images in all).
Table 5. Sample Backup Schedule with Biweekly Increments
154
Day
Level
Description
Sunday
0 (full)
Full backup of all specified Sonic XML Server document

collections
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Files Generated by the Backup and Restore Utilities

Sonic XML Servers backup utility generates or updates the following types of files:
Backup image files Images of documents in the Sonic XML Server document
collections backed up. You specify a path name for the directory to contain the image
files when you perform a full or incremental backup.
Backup record file Internally used information about the backup operations that
have been performed. When you perform a full or incremental backup, you specify a
path name for the record file. The filename should have the file extension, .irf. A
backup operation creates the record file if it does not exist; otherwise it modifies the
existing record file. When you perform an incremental backup, the record file must
be the same file that served as the record file for the associated full backup.
Log files The backup and restore utilities create log files in the current directory
with information about the result of the operations. The log file contents are also sent
to the console. The log files are removed, if present, at the beginning of the
backup/restore script. Therefore, running the tools a second time deletes the logs
from the first run.
Be sure that the following is true for both the image file and record file:
These files should be stored on a separate device from the Sonic XML Server
document collections being backed up and from the transaction log. This protects you
in the event of disk crash. It also allows reads to occur on the source disk and writes
on the target disk, which results in a faster backup.
These files must be stored on a device that contains sufficient space. The image files
can require several times the space occupied by the document collections being
backed up. If you use full backup on every nth day and incremental backup on all
other days, and if all document collections of all documents change each day, then the
backup image files will need about n times the size of the data stores being backed up.
155
Using the Backup Utility

The Sonic XML Server backup utility is invoked by a batch file, backup.bat, on Windows
and a shell script, backup.sh, on UNIX.
Entering backup in a console in the sonicxmlserver_install_dir\bin directory without
options prints a usage message:
backup [-all | ([-meta] [-service <servicename>]
[-coll <collectionname>]) [-path <metadatapath>] [-verbose]
[-level <inc-level>] [-incfile <inc-file>] -dir <backupdir>
Command line options can be abbreviated to their first letter, for example -v for -verbose.
Square brackets indicate optional switches.
Table 6 lists the arguments for the backup utility.
Table 6. Backup Utility Arguments
156
Argument
Description
-all
Back up all document collections and metadata in the installation. An

installation is defined by a metadata location.
-meta
Back up only configuration metadata.
-service servicename
Back up all document collections created by the specified service

instance.
-coll collectionname
Back up one, specified document collection.
-path metadatapath
Path to the metadata store, if it is not the default location.
-verbose
Verbose output.
-level inc-level
Incremental backup level, an integer from 0 to 9. The default is 0, a

full backup.
-incfile inc-file
Incremental backup record data file.
-dir backupdir
Directory for backup data. (Required.)
Performing Full Backup

When performing a backup, the target directory (E:\BU1.1.02 in the following examples)
must not already contain any backups of the Sonic XML Server document collections that
need to be backed up. Use a different directory from the previous run of backup, unless
the backup images from previous runs have been moved. In the following examples, the
-level option specifies level 0, a full backup.
The following command performs a full backup of all Sonic XML Server document
collections for a service named service1. It generates the backup record file,
E:\BU1.1.02\service1.irf, and generates an image file in the directory, E:\BU1.1.02.
backup -service service1 -incfile E:\BU1.1.02\service1.irf -level 0
-dir E:\BU1.1.02
The following command performs a full backup of the configuration metadata. It updates
the backup record file, E:\BU1.1.02\service1.irf, and generates image files in the
directory, E:\BU1.1.02.
backup -meta -incfile E:\BU1.1.02\service1.irf -level 0 -dir E:\BU1.1.02
The following command performs a full backup of all XML data stores in the current
installation.
backup -all -incfile E:\BU1.1.02\service1.irf -incfile 0 -dir E:\BU1.1.02
The following command performs a full backup of the document collection named
employee.
backup -coll employee -incfile E:\BU1.1.02\service1.irf -level 0
-dir E:\BU1.1.02
157
Performing Incremental Backup

Performing incremental backup is like performing full backup, except that you specify a
nonzero level with the -level option, for example:
backup -service service1 -incfile E:\BU1.1.02\service1.irf -level 2
-dir E:\BU1.2.02
backup -meta -incfile E:\BU1.1.02\service1.irf -level 2 -dir E:\BU1.2.02
When you perform incremental backup, the backup record file that you specify with the
-i option must be the same file that served as backup record file for the associated full
backup.
Restoring Sonic XML Server Document Collections

The restore utility restores Sonic XML Server document collections from a backup
image, restoring either the entire backup set or selected document collections within the
set.
Procedures vary based on whether you are restoring a full or incremental backup:
If you performed full backup, restore the document collections from the latest full
backup images made prior to the time to which you want to restore. (See Restoring
from Full Backup Images on page 160.)
If you performed incremental backup, restore from the relevant incremental backup
images. (See Restoring from Incremental Backup Images on page 161.)
Important To restore a document collection that was removed, you must also restore the metadata
by using -meta and -coll. Using -coll alone is not sufficient.
158
Using the Restore Utility

The Sonic XML Server restore utility is invoked by a batch file, restore.bat, on
Windows and a shell script, restore.sh, on UNIX. The script is located in the bin
directory of the installation. Entering restore in a console in the
sonicxmlserver_install_dir\bin directory without options prints a usage message:
restore [-all | ([-meta] [-service <servicename>]
[-coll <collectionname>]) [-path <metadatapath>]
[-remap] [-verbose] -dir <datadir>
Command line options can be abbreviated to their first letter, for example -v for -verbose.
Square brackets indicate optional switches.
Table 7 lists the arguments for the restore utility.
Table 7. Restore Utility Arguments
Argument
Description
-all
Restore all document collections and metadata in the installation. An

installation is defined by a metadata location.
-meta
Restore only configuration metadata.
-service servicename
Restore all document collections for the specified service instance.
-coll collectionname
Restore one, specified document collection.
-path metadatapath
Path to the metadata store to write to if you want to restore to a

different metadata location than the backup destination.
-remap
Perform interactive remapping of host/directory for services. Also

use the -path metadatapath option to restore the metadata as well.
-verbose
Verbose output.
-dir backupdir
Directory containing backup data (required).
159
Restoring from Full Backup Images

To restore from full backup images, use the restore utility and specify the following:
Document collections to restore
Directory containing the backup images of the document collections to restore. These
are the images that are generated by backup when you perform full backup.
The following example restores all the backup images contained in the directory,
E:\BU1.1.02.
restore -all -dir E:\BU1.1.02
If you restore to a different host, use the remap option along with the service or -coll
option instead of the all option. Otherwise, if you run backup using the -all option on
host A and then restore on host B, restore restores the metadata and points to the original
document collections on the host A. This results in both installations pointing to the same
document collections. Changes made to the document collections in either installation are
recorded in the same document collections on host A.
Important The remap option works only when backup and restore are used on the same platform.
To restore both the collections and the metadata to a new location, you must use both
-remap and -path (to remap the location of the metadata).
The following example restores all backup images of Sonic XML Server document
collections created by service1 contained in the directory, E:\BU1.1.02.
restore -service service1 -dir E:\BU1.1.02
160
Restoring from Incremental Backup Images

To restore from incremental backup images from a given day, use the restore utility and
specify:
Document collections to restore. These must be document collections that you

restored from full backup images.
Directory containing the backup images of the document collections to restore. These
are the images that were generated by backup when you performed incremental
backup on the given day.
To determine which days backup images to restore, construct a list of days:
1.
Identify the day to which you want to restore on the list.
2.
Consider each day that is earlier than the day to which you want to restore and later
than the latest prior full backup. Consider each such day in reverse order, from latest
to earliest. For each such day, if its backup level is lower than the backup level of the
lists last day, add the day to the end of the list.
Restore the images from each day on the list, working in reverse order, starting with the
last day on the list. For example, you could perform the following backups:
1.
Full backup on Monday
2.
Level 5 on Tuesday
3.
Level 6 on Wednesday
4.
Level 2 on Thursday
5.
Level 4 on Friday
To restore to Friday, start by putting Friday on the list. Then consider each previous day,
Thursday, Wednesday, and Tuesday. Thursdays level is lower than Fridays level, so
Thursday goes on the list. Wednesdays level is not lower than Thursdays level, so it does
not go on the list. Finally, Tuesdays level is not lower than Thursdays level, so it does
not go on the list either. The final list is: Friday, Thursday. So, after restoring from full
backup images, you should restore from Thursdays images, and then restore from
Fridays images.
161
162
Part III
Configuring Database Services
Part III contains the following chapters:
Chapter 8, Using the Database Service JDBC Drivers
Chapter 9, Driver Connection Properties and Data Types by Database Brand
Chapter 10, SQL Escape Sequences for JDBC
Chapter 11, Configuring SQL Server Windows Authentication

Note This section provides information for the JDBC drivers bundled with Progress Sonic
Database Service. If your installation uses a different JDBC Driver, consult the vendors
documentation for their configuration guidelines.
163
164
Chapter 8
Using the Database Service JDBC Drivers
Chapter 8 includes information on failover, load balancing, and error handling for
Progress Sonic Database Service connections. This chapter includes the following
sections:
JDBC Driver Connection Properties and the Database Service Explains how to
configure and deploy third-party JDBC drivers for use with Sonic Database Service.
Load Balancing, Failover, and Connection Retry Explains how these features are
implemented and provides references to appendixes where the connection properties
for each of the JDBC drivers are listed.
Using Activation Daemons Shows how to use Activation Daemons with

Database Services.
165
Chapter 8: Using the Database Service JDBC Drivers
JDBC Driver Connection Properties and the Database

Service
The Database Service reconnect timeout might expire while the JDBC driver failover or
retry is taking place. In this event, if the JDBC driver failover or connection retry
operations exceed the Database Service connection Timeout limit, the connection will not
succeed and the associated Database Service operation will fail, resulting in an error
message being sent to the rejected message endpoint (RME.)
The Database Service reconnect is not the same as the JDBC driver connection retry. The
Database Service is not aware of a connection failure until the JDBC driver connection
retry is unsuccessful. When the Database Service attempts a reconnection, the JDBC
driver acts as if this is a new database connection and the driver load balancing, failover,
and connection retry parameters are all used as if an initial database connection is being
established.
Load Balancing, Failover, and Connection Retry

To optimize performance, you can implement client load balancing, connection failover,
and connection retry in your Database Service connection properties. To do this, specify
both primary and alternate servers in the connection URL. The following sections explain
these features:
Client Load Balancing on page 168
Connection Failover on page 169
Connection Retry on page 170
166
For details on configuring load balancing, failover, and connection retry properties for
each of the JDBC drivers available with Sonic Database Service, see the following
sections:
Table 8. Documentation for JDBC Driver Connection Properties and Alternate Servers
JDBC Driver
Connection Properties Documentation
Progress Open Edge
Progress OpenEdge Database on page 176
Progress OpenEdge Connection Failover Properties on page 181
Specifying Alternate Servers for the Progress OpenEdge Driver on page 182
Progress OpenEdge Driver Data Types on page 184
DB2 Driver Connection Properties on page 185
DB2 Driver Connection Failover Properties on page 198
Specifying Alternate Servers for the DB2 Driver on page 198
DB2 Driver Data Types on page 200
Informix Driver Connection Properties on page 201
Informix Driver Connection Failover Properties on page 209
Specifying Alternate Servers for the Informix Driver on page 209
Informix Driver Data Types on page 210
Oracle Driver Connection Properties on page 212
Oracle Driver Connection Failover Properties on page 223
Specifying Alternate Servers for the Oracle Driver on page 224
Oracle Driver Data Types on page 225
Microsoft SQL Server Driver Connection Properties on page 227
Microsoft SQL Server Driver Connection Failover Properties on page 238
Specifying Alternate Servers for the Microsoft SQL Server Driver on page 238
Microsoft SQL Server Driver Data Types on page 240
Sybase Driver Connection Properties on page 242
Sybase Driver Connection Failover Properties on page 252
Specifying Alternate Servers for the Sybase Driver on page 252
Sybase Driver Data Types on page 254
DB2
Informix
Oracle
Microsoft SQL
Server
Sybase
167
Client Load Balancing

Client load balancing helps distribute new connections to multiple servers in your
environment so that no one server is overwhelmed with connection requests. When client
load balancing is enabled, the order in which primary and alternate database servers are
tried is random. For example, suppose that client load balancing is enabled as shown in
Figure 1.
Database Server A
(Primary)
Sonic Database Service
Database Server B
(First Alternate)
Database Server C
(Second Alternate)
Figure 1. Client Load Balancing Example
In the example in Figure 1, when client load balancing is enabled the Database Service
first attempts to connect to Database Server B (1). The Database Service then attempts a
connection to Database Server C (2), followed by a connection attempt to Database
Server A (3). In contrast, if client load balancing was not enabled in this scenario, each
database server would be tried in sequential order, primary server first, then each alternate
server based on their entry order in the alternate servers list.
To use client load balancing, specify the following properties in the form property=value
in your connection URL:
LoadBalancing Set this property to true to enable load balancing.
AlternateServers See Specifying Primary and Alternate Servers on page 172.
168
Connection Failover
Connection failover allows an application to connect to an alternate, or backup, database
server if the primary database server is unavailable, for example, because of a hardware
failure or traffic overload. Connection failover ensures that the data your critical JDBC
applications depend on is always available.
You can customize the Database Service JDBC drivers for connection failover by
configuring a list of alternate database servers that are tried if the primary server is not
accepting connections. Connection attempts continue until a connection is successfully
established or until all the alternate database servers have been tried the specified number
of times.
For example, suppose you have the environment shown in Figure 2 with multiple database
servers: Database Server A, B, and C. Database Server A is designated as the primary
database server, Database Server B is the first alternate server, and Database Server C is
the second alternate server.
Database Server A
(Primary)
Sonic Database Service
Database Server B
(First Alternate)
Database Server C
(Second Alternate)
Figure 2. Connection Failover Example
In the example shown in Figure 2, the Database Service first attempts to connect to the
primary database server, Database Server A (1). If connection failover is enabled and
Database Server A fails to accept the connection, the Database Service then attempts to
connect to Database Server B (2). If that connection attempt also fails, the Database
Service attempts to connect to Database Server C (3).
169
In this example, it is probable that at least one connection attempt will succeed, but if no
connection attempt succeeds, the driver can retry each database server (primary and
alternates) for a specified number of attempts. The JDBC drivers allow you to customize
the connection retry feature to specify the number of attempts that are made.
A JDBC driver fails over to the next alternate database server only if a successful
connection cannot be established with the current alternate server. If the driver
successfully establishes communication with a database server and the connection request
is rejected by the database server because the login information is invalid, for example,
the driver does not try to connect to the next database server in the list and generates an
exception.
Connection failover provides protection for new connections only and does not preserve
states for transactions or queries.
To use connection failover, see the appropriate section for your database for a list of
property=value pairs to add to your connection URL:
Progress OpenEdge Connection Failover Properties on page 181

DB2 Driver Connection Failover Properties on page 198
Informix Driver Connection Failover Properties on page 209
Oracle Driver Connection Failover Properties on page 223
Microsoft SQL Server Driver Connection Failover Properties on page 238
Sybase Driver Connection Failover Properties on page 252
Connection Retry
Connection retry allows the JDBC driver to retry connections to a list of database servers
(primary and alternate) until a successful connection is established. Use the
ConnectionRetryCount and ConnectionRetryDelay properties to enable and control how
connection retry works.
In the following examples for the different JDBC drivers, if a successful connection is not
established on the drivers first pass through the list of database servers (primary and
alternate), the driver retries the list of servers in the same sequence twice
(ConnectionRetryCount=2). If a successful connection is not established on the first retry
pass through the list of servers, the driver makes another pass through the list of servers.
Because the connection retry delay has been set to five seconds
(ConnectionRetryDelay=5), the driver waits five seconds between retry passes.
170
Connection Retry Example for Progress OpenEdge Driver

jdbc:sonic::datadirect:openedge://server1:2003;HostName=TestServer;
DatabaseName=TestServer;User=test;Password=secret;
AlternateServers=(server2:2003;DatabaseName=TEST2,server3:2003;
DatabaseName=TEST3);ConnectionRetryCount=2;ConnectionRetryDelay=5
Connection Retry Example for DB2 Driver

jdbc:sonic:db2://server1:50000;DatabaseName=TEST;
AlternateServers=(server2:50000;DatabaseName=TEST2,
server3:50000;DatabaseName=TEST3);ConnectionRetryCount=2;
ConnectionRetryDelay=5
Connection Retry Example for Informix Driver

jdbc:sonic:informix://server1:2003;InformixServer=TestServer;
DatabaseName=TestServer;
DatabaseName=TEST3);ConnectionRetryCount=2;
Connection Retry Example for Oracle Driver

jdbc:sonic:oracle://server1:1521;ServiceName=TEST;
AlternateServers=(server2:1521;ServiceName=TEST2,
server3:1521;ServiceName=TEST3);ConnectionRetryCount=2;
Connection Retry Example for Microsoft SQL Server Driver

jdbc:sonic:sqlserver://server1:1433;DatabaseName=TEST;
171
Connection Retry Example for Sybase Driver

jdbc:sonic:sybase://server1:4100;DatabaseName=TEST;
Specifying Primary and Alternate Servers

The Sonic Database Service JDBC drivers allow you to specify a list of alternate database
servers that are tried at connection time if the primary server is not accepting connections
using the AlternateServers property. Connection attempts continue until a connection is
successfully established or until all the database servers (primary and alternate) have been
tried the specified number of times.
Connection information for alternate servers is specified using the AlternateServers
property in a connection URL. The value of the AlternateServers property is a string that
has the format:
(servername1[:port1][;property=value[;...]],servername2[:port2]
[;property=value[;...]],...)
where:
is the IP address or server name of the first alternate database server,

the IP address or server name of the second alternate database server,
and so on. The IP address or server name is required for each alternate server entry.
port1 is the port number on which the first alternate database server is listening, port2
is the port number on which the second alternate database server is listening, and so
on. Port numbers are optional for each alternate server entry. If unspecified, the port
number specified for the primary server is used. If a port number is unspecified for
the primary server, the default port number is used (see Table 8 on page 167 to locate
the appendix containing information on the default PortNumber values for the JDBC
drivers).
property=value is an optional connection property, based on the JDBC driver to
which you are connecting.
servername1
servername2 is
172
See the following sections for examples that describe how to specify primary and alternate
servers for different JDBC drivers:
Specifying Alternate Servers for the Progress OpenEdge Driver on page 182
Specifying Alternate Servers for the DB2 Driver on page 198
Specifying Alternate Servers for the Informix Driver on page 209
Specifying Alternate Servers for the Oracle Driver on page 224
Specifying Alternate Servers for the Microsoft SQL Server Driver on page 238
Specifying Alternate Servers for the Sybase Driver on page 252

Using an Activation Daemon is a way to launch new containers as spawned processes of
the container hosting the Activation Daemon. This allows new containers to be launched
by remote administrative clients without the administrator having to log on to that host. A
typical use would be to have the container hosting the Activation Daemon launched as a
Windows service on Windows platforms or a startup process under UNIX.
An Activation Daemon monitors the health of its spawned containers and, depending on
configured rules, restarts those containers upon failure. Normally one Activation Daemon
is deployed per host. Multiple Activation Daemons can be created per domain. Containers
can be launched by the Activation Daemon:
At Activation Daemon startup time
At a configured time
After a container failure (up to a configurable number of retries)
On demand from the Sonic Management Console or via the Activation Daemons
management API
You can create and configure an Activation Daemon to start an ESB Container hosting a
Database Service. The steps required to create, configure, and test the Activation Daemon
are:
1.
Create an Activation Daemon
2.
Add the Activation Daemon to a management container
3.
Add a container to an Activation Daemons activation list
Using Activation Daemons on page 78 provides information about how to complete the
steps to create and configure an Activation Daemon to start an ESB Container hosting a
service.
173
174
Chapter 9
Driver Connection Properties and

Data Types by Database Brand
This chapter contains driver connection properties, connection failover properties, and
driver data types for the following database brands:
Progress OpenEdge Database
DB2
Informix
Oracle
Microsoft SQL Server
Sybase
175
Chapter 9: Driver Connection Properties and Data Types by Database Brand

The following sections describe settings for the Sonic Database Services Progress
OpenEdge driver:
Progress OpenEdge Connection Properties
Progress OpenEdge Connection Failover Properties
Specifying Alternate Servers for the Progress OpenEdge Driver
Progress OpenEdge Driver Data Types

See the DataDirect Connect for JDBC Progress OpenEdge Driver Users Guide and
Reference for more information.
Progress OpenEdge Connection Properties

Table 9 describes the JDBC connection properties supported by the Progress OpenEdge
driver. The properties have the format: property=value
Table 9. Connection Properties for the Progress OpenEdge Driver
Property
Description
AlternateServers
A comma-separated list of alternate database servers that the driver will try to
connect to if the primary database server is unavailable. The value of this
property is a string that specifies each alternate server. This string has the
format:
Default: No default
Data type: String
(servername1[:port1][;property=value],servername2[:port2][;property=value],...)
The server name is required for each alternate server entry. Port number and
connection properties (property=value) are optional for each alternate server
entry. If the port is unspecified, the port number of the primary server is used.
The driver only allows one optional property, DatabaseName. For example:
jdbc:datadirect:openedge://server1:4100;
DatabaseName=TEST;User=test;Password=secret
server3:4100;DatabaseName=TEST3)
contains alternate server entries for server2 and server3. The alternate server
entries contain the optional DatabaseName property.
176

Table 9. Connection Properties for the Progress OpenEdge Driver (continued)
Property
Description
ConnectionRetryCount
The number of times the driver retries connections to the primary database
server, and if specified, alternate servers until a successful connection is
established. Valid values are 0 and any positive integer.
Default: 5
Data type: int
If set to 0, the driver does not try to reconnect after the initial unsuccessful
attempt.
For example, in the case where the following properties are specified:
AlternateServers=(server2:2003,server3:2003,server4:2003)
and
ConnectionRetryCount=1
If a connection is not successfully established on the drivers first pass through

the list of database servers, the driver retries all the servers in the list only once.
If an application sets a login timeout value (for example, using
DataSource.loginTimeout or DriverManager.loginTimeout), the login timeout
takes precedence over this property. For example, if the login timeout expires,
any connection attempts to alternate servers stop.
If the LoadBalancing property is set to true, the driver may sequence through the
list of servers (primary and alternate) in a different order each time.
The ConnectionRetryDelay property specifies the wait interval, in seconds, used
between attempts.
ConnectionRetryDelay
Default: 1
Data type: int
The number of seconds the driver waits before retrying connections to the
primary database server, and if specified, alternate servers when
ConnectionRetryCount is set to a positive integer.
and
and
If a connection is not successfully established on the drivers first pass through

the list of database servers, the driver retries the list of servers twice. It waits 3
seconds between the first connection retry attempt and the second connection
retry attempt.
If the LoadBalancing property is set to true, the driver may sequence through the
list of servers (primary and alternate) in a different order each time.
177

Property
Description
DatabaseName
The name of the database to which you want to connect.
Default: No default
Data type: String
HostName
The name of the Progress OpenEdge database server to which you want to
connect.
Default: No default
Data type: String
Specifies either the IP address or the server name (if your network supports
named servers) of the primary database server. For example, 122.23.15.12 or
HostName.
This property is supported only for DataSource connections
InsensitiveResultSet
BufferSize
Default: 2048
Data type: int
{-1 | 0 | x}
Determines the amount of memory used by the driver to cache insensitive result
set data. It must have one of the following values:
If set to -1, the driver caches all insensitive result set data in memory. If the size
of the result set exceeds available memory, an OutOfMemoryException is
generated. Because the need to write result set data to disk is eliminated, the
driver processes the data more efficiently.
If set to 0, the driver caches all insensitive result set data in memory, up to a
maximum of 2 GB. If the size of the result set data exceeds available memory,
the driver pages the result set data to disk. Because result set data may be written
to disk, the driver may have to reformat the data to write it correctly to disk.
If set to x, where x is a positive integer, the driver caches all insensitive result set
data in memory, using this value to set the size (in KB) of the memory buffer for
caching insensitive result set data. If the size of the result set data exceeds the
buffer size, the driver pages the result set data to disk. Because the result set data
may be written to disk, the driver may have to reformat the data to write it
correctly to disk. Specifying a buffer size that is a power of 2 results in more
efficient memory use.
178

Property
Description
LoadBalancing
{true | false}
Default: false
Determines whether the driver will use client load balancing in its attempts to
connect to a list of database servers (primary and alternate). The list of alternate
servers is specified by the AlternateServers property.
Data type: boolean
If set to true, client load balancing is used and the driver attempts to connect to
the list of database servers (primary and alternate servers) in random order.
If set to false (the default), client load balancing is not used and the driver
connects to each server based on their sequential order (primary server first,
then, alternate servers in the order they are specified).
and
LoadBalancing=true
The driver randomly selects from the list of primary and alternate servers which
server to connect to first. If that connection fails, the driver again randomly
selects from this list of servers until all servers in the list have been tried or a
connection is successfully established.
MaxPooledStatements
Default: 0
Data type: int
The maximum number of pooled prepared statements for this connection.

Setting MaxPooledStatements to an integer greater than zero (0) enables the
Progress OpenEdge drivers internal prepared statement pooling, which is
useful when the driver is not running from within an application server or
another application that provides its own prepared statement pooling.
If set to a positive number, the driver uses that value to cache a certain number
of prepared statements created by an application. For example, if the value of
this property is set to 20, the driver caches the last 20 prepared statements
created by the application. If the value set for this property is greater than the
number of prepared statements used by the application, all prepared statements
created by the application are cached. Because CallableStatement is a sub-class
of PreparedStatement, CallableStatements also are pooled.
Password
REQUIRED
Default: No default
Data type: String
The case-sensitive password used to connect to your OpenEdge database. A

password is required only if security is enabled on your database. If so, contact
your system administrator to obtain your password.
The password is automatically encrypted.
179

Property
Description
PortNumber
The TCP port of the primary database server that is listening for connections to
the Progress OpenEdge database.
REQUIRED
Default: Varies with
operating system
This property is supported only for DataSource connections.
Data type: int

SpyAttributes
Default: No default
Data type: String
Enables DataDirect Spy, a tool that can be used to log detailed information about
calls issued by a running application to any DataDirect Connect for JDBC
driver. The format for the value of this property is:
(spy_attribute[;spy_attribute]...)
where spy_attribute is any valid DataDirect Spy attribute.

For example:
SpyAttributes=(log=(file)/tmp/spy.log;linelimit=80)
logs all JDBC activity to a file using a maximum of 80 characters for each line.
NOTE: If coding a path on Windows to the log file in a Java string, the backslash
character (\) must be preceded by the Java escape character, a backslash. For
example: log=(file)C:\\temp\\spy.log.
DataDirect Spy is not enabled by default.
User
REQUIRED
Default: No default
The case-insensitive user name used to connect to your OpenEdge database. A

user name is required only if security is enabled on your database. If so, contact
your system administrator to get your user name.
Data type: String
180
Progress OpenEdge Connection Failover Properties

Table 10 summarizes the connection properties that control how connection failover
works with the Database Service Progress OpenEdge driver. See Table 9 for details about
configuring each property.
Table 10. Connection Failover Properties for the Progress Open Edge Driver
Property
Description
AlternateServers
List of alternate database servers. An IP address or server name identifying each

server is required. Port number and the DatabaseName connection property are
optional. If the port number is unspecified, the port number specified for the primary
server is used.
Number of times the driver retries the primary database server, and if specified,
alternate servers until a successful connection is established. The default is 5.
Wait interval, in seconds, between connection retry attempts when the

ConnectionRetryCount property is set to a positive integer. The default is 1.
DatabaseName
Name of the Progress OpenEdge database server to which you want to connect.
LoadBalancing
Sets whether the driver will use client load balancing in its attempts to connect to the
list of database servers (primary and alternate). If client load balancing is enabled,
the driver uses a random pattern instead of a sequential pattern in its attempts to
connect. The default is false (client load balancing is disabled).
PortNumber
Port listening for connections on the primary database server. This property is
supported only for DataSource connections. The default port number varies,
depending on operating system.
See Client Load Balancing on page 168 and Connection Failover on page 169 for
overviews of these features.
181
Specifying Alternate Servers for the Progress OpenEdge Driver

The following connection URL for the Progress OpenEdge driver specifies connection
information for the primary and alternate servers:
jdbc:datadirect:openedge://server1:2003;HostName=TestServer;
AlternateServers=(server2:2003;HostName=TestServer2,server3:2003)
In this example:
...server1:2003;HostName=TestServer;
DatabaseName=TestServer...
is the part of the connection URL that specifies connection information for the primary
server. Alternate servers are specified using the AlternateServers property. For example:
...;AlternateServers=(server2:2003;
HostName=TestServer2,server3:2003)
Similarly, connection information for the primary server specified using a JDBC data
source would look something like this:
OpenedgeDataSource mds = new OpenedgeDataSource();
mds.setDescription("My OpenedgeDataSource");
mds.setServerName("server1");
mds.setPortNumber(2003);
mds.setHostName("TestServer");
mds.setDatabaseName("TestServer");
mds.setUser("test");
mds.setPassword("secret");
mds.setAlternateServers=(server2:2003;HostName=
TestServer2,server3:2003)
In this example, connection information for the primary server is specified using the
ServerName, PortNumber, HostName, and DatabaseName properties. Connection
information for alternate servers is specified using the AlternateServers property.
182
Using the AlternateServers Property

Connection information for alternate servers is specified using the AlternateServers
property with either a connection URL through the JDBC Driver Manager or a JDBC data
source. The value of the AlternateServers property is a string that has the format:
(servername1[:port1][;property=value[;...]],servername2[:port2]
[;property=value[;...]],...)
where:
is the IP address or server name of the first alternate database server,
servername2 is the IP address or server name ofthe second alternate database server, and
so on. The IP address or server name is required for each alternate server entry.
servername1
port1 is
the port number on which the first alternate database server is listening, port2 is
the port number on which the second alternate database server is listening, and so on. The
port number is optional for each alternate server entry. If unspecified, the port number
specified for the primary server is used.
property=value is either of the following connection properties: DatabaseName or

HostName. These connection properties are optional for each alternate server entry.
For example:
AlternateServers=(server2:2003;HostName=TestServer2;
DatabaseName=TestServer,server3:2003)
If you do not specify an optional connection property in an alternate server entry, the
connection to that alternate server uses the property specified in the URL. For example, if
youspecify HostName=TestServer and DatabaseName=TestServer for the primary server,
but do not specify the HostName and DatabaseName properties in the alternate server
entry as shown in the following URL, the driver uses the HostName and DatabaseName
specified for the primary server and tries to connect to the TestServer database on the
Progress OpenEdge server TestServer:
DatabaseName=TestServer;AlternateServers=(server2:2003,server3:2003)
183
Progress OpenEdge Driver Data Types

Table 11 lists the data types supported by the Progress OpenEdge driver and describes
how they are mapped to JDBC data types.
Table 11. Progress OpenEdge (OED) Data Types
184
Progress OpenEdge Data Type
JDBC Data Type
bigint
BIGINT
binary
BINARY
bit
BIT
blob
BLOB
char
CHAR
clob
CLOB
date
DATE
decimal
DECIMAL
float
FLOAT
int8
BIGINT
integer
INTEGER
longvarbinary
LONGVARBINARY
longvarchar
LONGVARCHAR
numeric
NUMERIC
real
REAL
smallint
SMALLINT
time
TIME
timestamp
TIMESTAMP
timestamp with time zone
CHAR
tinyint
TINYINT
varbinary
VARBINARY
varchar
VARCHAR
DB2
DB2
The following sections describe settings for the Sonic Database Service DB2 driver:
DB2 Driver Connection Properties
DB2 Driver Connection Failover Properties
Specifying Alternate Servers for the DB2 Driver
DB2 Driver Data Types
DB2 Driver Connection Properties

Table 12 describes the JDBC connection properties supported by the DB2 driver. The
properties have the format:
property=value
Note
All connection property names are case-insensitive. For example, Password is the same
as password.
Table 12. DB2 Connection Properties
Property
Description
AddToCreateTable
A string that is appended to the end of all CREATE statements. This property
typically is used to add an in database clause.
OPTIONAL
AlternateID
OPTIONAL
The default schema name that is used to qualify unqualified database

objects in dynamically prepared database queries. Valid values depend on
your DB2 database:
DB2 UDB and DB2 iSeries Sets the value in the DB2 CURRENT
SCHEMA special register. The value of this property must be a valid
DB2 schema name. DB2 UDB and DB2 iSeries do not validate values
specified for the CURRENT SCHEMA register.
DB2 OS/390 Sets the value in the DB2 CURRENT SQLID special
register. The value of this property is validated by the server. Refer to
your IBM documentation for valid values for the CURRENT SQLID
register.
185

Table 12. DB2 Connection Properties (continued)
Property
Description
AlternateServers
A list of alternate database servers that the driver will try to connect to if
the primary database server is unavailable. The value of this property is a
string that specifies each alternate server. This string has the format:
OPTIONAL
(servername1[:port1][;property=value[;...]],
servername2[:port2][;property=value[;...]],...)
The server name is required for each alternate server entry. Port number
and connection properties (property=value) are optional for each
alternate server entry. If the port is unspecified, the port number of the
primary server is used. If the port number of the primary server is
unspecified, the default port number of 50000 is used. Optional connection
properties for the driver are DatabaseName (for DB2 UDB) and
LocationName (for DB2 OS/390 and iSeries). For example:
contains alternate server entries for server2 and server3. The alternate
server entries contain the optional DatabaseName property.
Other properties are:
ConnectionRetryCount Controls the number of times the driver

retries the list of servers (primary and alternate) while attempting to
establish a connection.
ConnectionRetryDelay Sets the wait interval, in seconds, between
retry attempts.
LoadBalancing
Controls the order in which the driver sequences

through the list of servers (primary and alternate) while attempting to
See Specifying Primary and Alternate Servers on page 172 for more
information about specifying connection information for primary and
alternate servers.
186
DB2
Property
Description
BatchPerformanceWorkaround
OPTIONAL
{true | false}
For DB2 UDB 8.1, the native DB2 batch mechanism is used. This
property determines whether certain restrictions are enforced to facilitate
data conversions as follows:
false
The methods used to set the parameter values of a batch

operation performed using a PreparedStatement must match the
database data type of the column the parameter is associated with.
This is because DB2 servers do not perform implicit data conversions.
true This restriction is removed; however, parameter sets may not

be executed in the order they were specified.
The default is false.

CatalogIncludesSynonyms
OPTIONAL
{true | false}
This property value determines behavior as follows:
true
Synonyms are included in the result sets returned from the
DatabaseMetaData.getColumns method.
false
Synonyms are omitted from result sets.
The default is true.

This property is only applicable for DB2 UDB 7.1 and 7.2, DB2 OS/390,
and DB2 iSeries. This property is ignored for DB2 UDB 8.1. The driver
always returns synonyms for the DatabaseMetaData.getColumns method
when connected to DB2 UDB 8.1.
CatalogSchema
OPTIONAL
The DB2 schema to use for catalog functions. The value must be the name
of a valid DB2 schema.
The default is SYSCAT for DB2 UDB, SYSIBM for DB2 OS/390, and
QSYS2 for DB2 iSeries.
To improve performance, views of system catalog tables can be created in
a schema other than the default catalog schema. Setting this property to a
schema that contains views of the catalog tables allows the driver to use
those views. To ensure that catalog methods function correctly, views for
specific catalog tables must exist in the specified schema. The views that
are required depend on your DB2 database.
187

Property
Description
CharsetFor65535
The code page to use to convert character data stored as bit data in
character columns (Char, Varchar, Longvarchar, Char for Bit Data,
Varchar for Bit Data, Longvarchar for Bit Data) defined with CCSID
65535. All character data stored as bit data retrieved from the database
using columns defined with CCSID 65535 is converted using the specified
code page. The value must be a string containing the name of a valid code
page supported by your Java Virtual Machine, for example,
CharsetFor65535=CP950. This property has no effect when writing data to
character columns defined with CCSID 65535.
OPTIONAL
CodePageOverride
OPTIONAL
CollectionId
OPTIONAL
A code page to be used to convert Character and Clob data. The specified
code page overrides the default database code page. All Character and
Clob data retrieved from or written to the database is converted using the
specified code page. The value must be a string containing the name of a
valid code page supported by your Java Virtual Machine, for example,
CodePageOverride=CP950.
The name of the collection or library (group of packages) to which DB2
packages are bound.
The default is NULLID.
This property is ignored for DB2 UDB.
188
DB2
Property
Description
The number of times the driver retries connection attempts to a list of

database servers (primary and alternate) until a successful connection is
OPTIONAL
If set to 0, the driver does not retry connections if a successful connection

is not established on the drivers first pass through the list.
The default is 0.
and
if a connection is not successfully established on the drivers first pass

through the list of database servers, the driver retries all the servers in the
list only once.
DriverManager.loginTimeout), the login timeout takes precedence over
this property. For example, if the login timeout expires, any connection
attempts stop.
The ConnectionRetryDelay property specifies the wait interval, in
seconds, used between retry attempts.
See Connection Retry on page 170 for more information about
specifying connection information for primary and alternate servers.
189

Property
Description
OPTIONAL
The number of seconds the driver will wait between connection retry
attempts when ConnectionRetryCount is set to a positive integer.
The default is 3.
and
and

through the list of database servers, the driver retries the list of servers
twice. The driver waits 3 seconds between the first connection retry
attempt and the second connection retry attempt.
CreateDefaultPackage
OPTIONAL
{true | false}
This property determines behavior as follows:
true The DB2 driver automatically creates any required DB2

packages.
false The driver creates the required DB2 packages automatically
only if they do not already exist.

For DB2 UDB, this property must be used in conjunction with the
ReplacePackage property.
For DB2 OS/390 and DB2 iSeries, DB2 packages are created in the
collection or library specified by the CollectionId property.
DatabaseName

This property is supported only for DB2 UDB.
190
DB2
Property
Description
DiagnosticFilename
OPTIONAL
The path and filename of the file to which you want state information
logged when an exception is generated. If the file does not already exist,
it will be created the first time state information is generated. If this
property is not specified, state information is not logged. When you
contact Technical Support with a problem, you might be asked to generate
a state information log.
Your application should ensure that the driver is granted read/write
permission to the specified file.
DynamicSections
OPTIONAL
The number of statements in the DB2 package that the DB2 driver will
prepare for a single user.
The default is 200.
Grantee
OPTIONAL
The name of the schema to which you want to grant EXECUTE privileges for
DB2 packages. The value must be a valid DB2 schema. This property is
ignored if the GrantExecute property is set to false.
The default is PUBLIC.
GrantExecute
{true | false}
OPTIONAL
Determines which DB2 schema is granted EXECUTE privileges for DB2

packages as follows:
true EXECUTE privileges are granted to the schema specified by the

Grantee property.
false EXECUTE privileges are granted to the schema that created the
DB2 packages.
191

Property
Description
InsensitiveResultSetBufferSize
OPTIONAL
{-1 | 0 | x}
Determines the amount of memory used by the driver to cache insensitive

result set data as follows:
-1 The driver caches all insensitive result set data in memory. If the
size of the result set exceeds available memory, an

OutOfMemoryException is generated. Because the need to write result
set data to disk is eliminated, the driver processes the data more
efficiently.
0 The driver caches all insensitive result set data in memory, up to
a maximum of 2 GB. If the size of the result set data exceeds available
memory, the driver pages the result set data to disk. Because result set
data may be written to disk, the driver may have to reformat the data
to write it correctly to disk.
where x is a positive integer The driver caches all insensitive

result set data in memory, using this value to set the size (in KB) of
the memory buffer for caching insensitive result set data. If the size of
the result set data exceeds the buffer size, the driver pages the result
set data to disk. Because the result set data may be written to disk, the
driver may have to reformat the data to write it correctly to disk.
Specifying a buffer size that is a power of 2 results in more efficient
memory use.
x,
The default is 2048 (KB).
192
DB2
Property
Description
LoadBalancing
{true | false}
OPTIONAL
Determines whether the driver will use client load balancing in its
attempts to connect to a list of database servers (primary and alternate).
The list of alternate servers is specified by the AlternateServers property.
The LoadBalancing property determines behavior as follows:
true Client load balancing is used and the driver attempts to

connect to the list of database servers (primary and alternate servers)
in random order.
false
Client load balancing is not used and the driver connects to

each server based on their sequential order (primary server first, then,
alternate servers in the order they are specified).

and
LoadBalancing=true
the driver randomly selects from the list of primary and alternate servers
which server to connect to first. If that connection fails, the driver again
randomly selects from this list of servers until all servers in the list have
been tried or a connection is successfully established.
See Client Load Balancing on page 168 for more information about
LocationName
The name of the DB2 location that you want to access.

This property is supported only for DB2 OS/390 and iSeries.
193

Property
Description
MaxPooledStatements
OPTIONAL

MaxPooledStatements property values determine behavior as follows:
An integer greater than zero (0) Enables the DB2 drivers internal
prepared statement pooling, which is useful when the driver is not
running from within an application server or another application that
provides its own prepared statement pooling. The driver uses this
value to cache a certain number of prepared statements created by an
application. For example, if the value of this property is set to 20, the
driver caches the last 20 prepared statements created by the
application.
A value greater than the number of prepared statements used by the

application All prepared statements created by the application are
cached.
Because CallableStatement is a sub-class of PreparedStatement,

are pooled.
CallableStatements also
The default is 0.
PackageOwner
OPTIONAL
The owner to be used for any DB2 packages that are created.
Password
A case-sensitive password used to connect to your DB2 database. A

password is required only if security is enabled on your database. Contact
PortNumber
The TCP port of the primary database server that is listening for
connections to the DB2 database.
OPTIONAL
The default is NULL.
The default is 50000.

ReplacePackage
{true | false}
OPTIONAL
Specifies whether the current bind process will replace the existing DB2
packages used by the driver. For DB2 UDB, this property must be used in
conjunction with the CreateDefaultPackage property.
194
DB2
Property
Description
SecurityMechanism
{ClearText | EncryptedPassword | EncryptedUIDPassword}
OPTIONAL
Determines the security method the driver uses to authenticate the user to
the DB2 server when establishing a connection. If the specified
authentication method is not supported by the DB2 server, the connection
fails and the driver generates an exception. This property determines
behavior as follows:
ClearText
The driver sends the password in clear text to the DB2

server for authentication.
EncryptedPassword The driver sends an encrypted password to the
DB2 server for authentication.
EncryptedUIDPassword The driver sends an encrypted user ID and

password to the DB2 server for authentication.
The default is ClearText.
195

Property
Description
SendStreamAsBlob
{true | false}
OPTIONAL
Determines whether binary stream data that is less than 32K bytes is sent
to the database as Long Varchar for Bit Data or Blob data. Binary stream
data that is less than 32K bytes can be inserted into a Long Varchar for
Bit Data column, which has a maximum length of 32K bytes, or a Blob
column. Binary streams that are larger than 32K bytes can only be inserted
into a Blob column. The driver always sends binary stream data larger than
32K bytes to the database as Blob data. This property determines behavior
as follows:
true The driver sends binary stream data that is less than 32K to
the database as Blob data. If the target column is a Long Varchar for
Bit Data column and not a Blob column, the Insert or Update
statement fails. The driver automatically retries the Insert or Update
statement, sending the data as Long Varchar for Bit Data, if the
stream passed into the driver is resettable. Sending binary stream data
that is less than 32K bytes in length initially as a Blob significantly
improves performance if the Insert or Update column is a Blob
column.
false
The driver sends binary stream data that is less than 32K to
the database as Long Varchar for Bit Data data. If the target column
is a Blob column and not a Long Varchar for Bit Data column, the
Insert or Update statement fails. The driver retries the Insert or
Update statement, sending the data as Blob data.

ServerName
196
Specifies either the IP address or the server name (if your network
supports named servers) of the primary database server. For example,
122.23.15.12 or DB2Server.
DB2
Property
Description
StripNewlines
OPTIONAL
{true | false}
Specifies whether new-line characters in a database operation are sent to

the DB2 server:
true The DB2 driver removes all new-line characters from

database operations.
If you know that the database operations used in your

application do not contain new-line characters, setting StripNewLines
to false eliminates parsing by the DB2 server and improves
performance.
false
UseCurrentSchema
{true | false}
OPTIONAL
Specifies whether results are restricted to the tables in the current schema
if a DatabaseMetaData.getTables call is called without specifying a
schema or if the schema is specified as the wildcard character %.
Restricting results to the tables in the current schema improves the
performance of calls for getTables methods that do not specify a schema.
true Results that are returned from the getTables method are
restricted to tables in the current schema.
false Results of the getTables method are not restricted.

User
The case-sensitive user name used to connect to the DB2 database.
WithHoldCursors
{true | false}
OPTIONAL
Determines whether the cursor stays open on commiteither DB2 closes

all open cursors (Delete cursors) after a commit or leaves them open
(Preserve cursors):
true
The cursor behavior is Preserve.
false The cursor behavior is Delete. Rolling back a transaction

closes all cursors regardless of how this property is specified.
197
DB2 Driver Connection Failover Properties

works with the Database Service DB2 driver. See Table 12 for details about configuring
each property.
Table 13. Connection Failover Properties for the DB2 Driver
Property
Description
AlternateServers

server is required. Port number and supported connection properties (DatabaseName
or LocationName) are optional. If the port number is unspecified, the port specified
for the primary server is used. If a port number is not specified for the primary
server, a default port number of 50000 is used.
Number of times the driver retries the list of database servers (primary and alternate)
until a successful connection is established. The default is 0 (connection retry is not
used).
Wait interval, in seconds, used between attempts to connect to a list of database

servers (primary and alternate) when the ConnectionRetryCount property is set to a
positive integer. The default is 3.
DatabaseName
LoadBalancing
connect. The default is false (client load balancing is not used).
Specifying Alternate Servers for the DB2 Driver

The following connection URL for the DB2 driver specifies connection information for
the primary and alternate servers:
198
DB2
In this example:
...server1:50000;DatabaseName=TEST...
server. Alternate servers are specified using the AlternateServers property, in this
example:
...;AlternateServers=(server2:50000;DatabaseName=TEST2, server3:50000;DatabaseName=TEST3)
You can specify the optional connection properties DatabaseName or LocationName for each
alternate server entry. For example:
dbc:sonic:db2://server1:50000;DatabaseName=TEST;
or
jdbc:sonic:db2://server1:50000;LocationName=TEST;
AlternateServers=(server2:50000;LocationName=TEST2,
server3:50000;LocationName=TEST3)
connection to that alternate server uses the property specified in the URL for the primary
server. For example, if you specify DatabaseName=TEST for the primary server, but do not
specify a database name in the alternate server entry as shown in the following URL, the
driver uses the database name specified for the primary server and tries to connect to the
TEST database on the alternate server:
AlternateServers=(server2:50000,server3:50000)
199
DB2 Driver Data Types

Table 14 lists the data types supported by the DB2 driver and describes how they are
mapped to JDBC data types.
Table 14. DB2 Data Types
DB2 Data Type
JDBC Data Type
Database Comments
Bigint
BIGINT
Supported only for DB2 UDB 8.1.
Blob
BLOB
Supported only for DB2 UDB 8.1, DB2 OS/390,

and DB2 iSeries V5R2.
Char
CHAR
Char for Bit Data
BINARY
Clob
CLOB
Date
DATE
DBClob
CLOB
Decimal
DECIMAL
Double
DOUBLE
Float
FLOAT
Integer
INTEGER
Long Varchar
LONGVARCHAR
Long Varchar for Bit Data
LONGVARBINARY
Numeric
NUMERIC
Real
REAL
Rowid
VARBINARY
Smallint
SMALLINT
Time
TIME
Timestamp
TIMESTAMP
Varchar
VARCHAR
Varchar for Bit Data
VARBINARY
200
Supported only for DB2 UDB 8.1, DB2 7.x OS/390,

and DB2 iSeries V5R2.
Supported only for DB2 OS/390 and DB2 iSeries V5R2.
Informix
Informix
The following sections describe settings for the Sonic Database Service Informix driver:
Informix Driver Connection Properties
Informix Driver Connection Failover Properties
Specifying Alternate Servers for the Informix Driver
Informix Driver Data Types
Informix Driver Connection Properties

Table 15 describes the JDBC connection properties supported by the Informix driver. The
property=value
Note
as password.
201
Table 15. Informix Connection Properties
Property
Description
AlternateServers
A comma-separated list of alternate database servers the driver will try to

connect to if the primary database server is unavailable. The value of this
property is a string that specifies each alternate server. This string has the
format:
OPTIONAL
primary server is used. Optional connection properties for the driver are
DatabaseName and InformixServer. For example, the following URL:
jdbc:sonic:informix://server1:2003;
InformixServer=TestServer;DatabaseName=Test;
AlternateServers=(server2:2003;InformixServer=
TestServer2,server3:2003;InformixServer=TestServer3)
server entries contain the optional InformixServer property.

retry attempts.
LoadBalancing

through the list of servers (primary and alternate) while attempting to
alternate servers.
CodePageOverride
OPTIONAL
202
The code page the driver uses when converting character data. The
specified code page overrides the default database code page. All
character data retrieved from or written to the database is converted using
the specified code page. The value must be a string containing the name
of a valid code page supported by your Java Virtual Machine, for example,
CodePageOverride=CP950.
Informix
Table 15. Informix Connection Properties (continued)
Property
Description
The number of times the driver retries connections to a list of database

servers (primary and alternate) until a successful connection is
OPTIONAL
If set to 0, the driver does not retry a connection to the list of database
servers if a connection is not established on the drivers first pass through
the list.
The default is 0.
AlternateServers=(server2:2003,server3:2003,server4:2003))
and

list only once.
If an application sets a login timeout value, the login timeout takes
precedence over this property. For example, if the login timeout expires,
If the LoadBalancing property is set to true, the driver may sequence
through the list of servers (primary and alternate) in a different order each
time.
seconds, used between retry attempts.
203

Property
Description
OPTIONAL
The number of seconds the driver will wait between connection retry
attempts when ConnectionRetryCount is set to a positive integer.
The default is 3.
AlternateServers=(server2:2003,server3:2003,server4:2003))
and
and

twice. It waits 3 seconds between the first connection retry attempt and the
second connection retry attempt.
NOTE: If the LoadBalancing property is set to true, the driver may
sequence through the list of servers (primary and alternate) in a different
order each time.
DatabaseName

If this property is not specified, a connection is established to the specified
server without connecting to a particular database. A connection that is
established to the server without connecting to the database allows an
application to use CREATE DATABASE and DROP DATABASE database queries.
These statements require that the driver cannot be connected to a database.
An application can connect to the database after the connection is
established by executing the DATABASE database query.
Refer to your IBM Informix documentation for details on using the CREATE
and DATABASE database queries.
DATABASE, DROP DATABASE,
204
Informix
Property
Description
DBDate
Sets the Informix DBDate server environment variable for formatting

literal date values when inserting, updating, and retrieving data in DATE
columns. Using this property, you can customize:
OPTIONAL
Order in which the month, day, and year fields appear in a date string
Year field to contain two or four digits
Separator character used to separate the date fields
Valid values are:

DMY2
Y4DM
DMY4
Y4MD
MDY2
Y2DM
MDY4
Y4MD
where D is a 2-digit day field, M is a 2-digit month field, Y2 is a 2-digit year

field, and Y4 is a 4-digit year field.
If unspecified, the format of literal date values conforms to the default
server behavior.
Optionally, a separator character may be specified as the last character of
the value. Valid separator characters are:
Hyphen (-)
Period (.)
Forward slash (/)
If a separator is not specified, a forward slash (/) is used to separate the
fields. For example, a value of Y4MD- specifies a date format that has a 4digit year, followed by the month and then by the day. The date fields are
separated by a hyphen (-). For example: 2004-02-15.
This property does not affect the format of the string in the date escape
syntax. Dates specified using the date escape syntax always use the JDBC
escape format
yyyy-mm-dd.
205

Property
Description
DiagnosticFilename
OPTIONAL
contact Technical Support with a problem, you might be asked to generate
a state information log.
InformixServer
The name of the Informix database server to which you want to connect.
{-1 | 0 | x}
OPTIONAL

result set data:
-1 The driver caches all insensitive result set data in memory. If the
size of the result set exceeds available memory, an

efficiently.
a maximum of 2 GB. If the size of the result set data exceeds available
memory, the driver pages the result set data to disk. Because result set
data may be written to disk, the driver may have to reformat the data
to write it correctly to disk.
x, where x is a positive integer The driver caches all insensitive

the memory buffer for caching insensitive result set data. If the size of
the result set data exceeds the buffer size, the driver pages the result
set data to disk. Because the result set data may be written to disk, the
driver may have to reformat the data to write it correctly to disk.
Specifying a buffer size that is a power of 2 results in more efficient
memory use.
The default is 2048 (KB)
206
Informix
Property
Description
LoadBalancing
{true | false}
OPTIONAL
The list of alternate servers is specified by the AlternateServers property.
The LoadBalancing property determines behavior as follows:
true The driver uses client load balancing and attempts to connect
to the database servers (primary and alternate servers) in random
order.
false
Client load balancing is not used and the driver connects to

each server based on their sequential order (primary server first, then,
alternate servers in the order they are specified).

AlternateServers=(server2:2003,server3:2003;server4:2003)
and
LoadBalancing=true
207

Property
Description
MaxPooledStatements

OPTIONAL
An integer greater than zero (0) Enables the Informix drivers

internal prepared statement pooling, which is useful when the driver
is not running from within an application server or another
application that provides its own prepared statement pooling. The
driver uses this value to cache a certain number of prepared
statements created by an application. For example, if the value of this
property is set to 20, the driver caches the last 20 prepared statements
created by the application.

cached.

are pooled.
The default is 0.
Password
A case-insensitive password used to connect to your Informix database. A

password is required only if security is enabled on your database. If so,
contact your system administrator to obtain your password.
User
The case-insensitive default user name used to connect to the Informix

database. A user name is required only if security is enabled on your
database. If so, contact your system administrator to obtain your user
name.
208
Informix
Informix Driver Connection Failover Properties

works with the Database Service DB2 driver. See Table 15 for details about configuring
each property.
Table 16. Connection Failover Properties for the Informix Driver
Property
Description
AlternateServers

server is required. Port number and supported connection properties (DatabaseName
or InformixServer) are optional. If the port number is unspecified, the port
specified for the primary server is used. If a port number is not specified for the
primary server, the port specified for the primary server is used.
used).

DatabaseName
InformixServer
The name of the Informix database server to which you want to connect.
LoadBalancing
Specifying Alternate Servers for the Informix Driver

The following connection URL for the Informix driver specifies connection information
for the primary and alternate servers:
AlternateServers=(server2:2003;InformixServer=TestServer2,server3:2003)
209
In this example:
...server1:2003;InformixServer=TestServer;DatabaseName=TestServer...
example:
...;AlternateServers=(server2:2003;InformixServer=TestServer2,server3:2003)
You can specify the optional connection properties DatabaseName or InformixServer for
each alternate server entry. For example:
AlternateServers=(server2:2003;InformixServer=TestServer2;
DatabaseName=TestServer,server3:2003)
server. For example, if you specify InformixServer=TestServer and
DatabaseName=TestServer for the primary server, but do not specify the InformixServer
and DatabaseName properties in the alternate server entry as shown in the following URL,
the driver uses the InformixServer and DatabaseName specified for the primary server and
tries to connect to the TestServer database on the Informix server TestServer:
DatabaseName=TestServer;AlternateServers=(server2:2003,server3:2003)
Informix Driver Data Types

Table 17 lists the data types supported by the Informix driver and describes how they are
Table 17. Informix Data Types
210
Informix Data Type
JDBC Data Type
blob
BLOB
boolean
BIT
byte
LONGVARBINARY
Informix
Table 17. Informix Data Types (continued)
Informix Data Type
JDBC Data Type
clob
CLOB
char
CHAR
date
DATE
datetime hour to second
TIME
datetime year to day
DATE
datetime year to fraction(5)
TIMESTAMP
datetime year to second
TIMESTAMP
decimal
DECIMAL
float
FLOAT
int8
BIGINT
integer
INTEGER
lvarchar
VARCHAR
money
DECIMAL
nchar
CHAR
nvarchar
VARCHAR
serial
INTEGER
serial8
BIGINT
smallfloat
REAL
smallint
SMALLINT
text
LONGVARCHAR
varchar
VARCHAR
211
Oracle
The following sections describe settings for the Sonic Database Service Oracle driver:
Oracle Driver Connection Properties
Oracle Driver Connection Failover Properties
Specifying Alternate Servers for the Oracle Driver
Oracle Driver Data Types
Oracle Driver Connection Properties

Table 18 describes the JDBC connection properties supported by the Oracle driver. The
property=value
Note
212
as password.
Oracle
Table 18. Connection Properties for the Oracle Driver
Property
Description
AlternateServers
A comma-separated list of alternate database servers that the driver will

try to connect to if the primary database server is unavailable. The value
of this property is a string that specifies each alternate server. This string
has the format:
OPTIONAL
primary server is used. If the port number of the primary server is
unspecified, the default port number of 1521 is used. Optional connection
properties are ServiceName and SID. For example:
jdbc:datadirect:oracle://server1:1521;
ServiceName=TEST;AlternateServers=(server2:1521;
ServiceName=TEST2,server3:1521;ServiceName=TEST3)
server entries contain the optional ServiceName property. Similarly, you
can use the optional SID property instead.
Other properties include:

retry attempts.
LoadBalancing

through the list of servers (primary and alternate) while attempting
to establish a connection.
If using a tnsnames.ora file to retrieve connection information, do not

specify this property.
alternate servers.
213

Table 18. Connection Properties for the Oracle Driver (continued)
Property
Description
{true | false}
OPTIONAL
Determines the method used to execute batch operations:
true The native Oracle batch mechanism is used. The native

Oracle batch mechanism does not return individual update counts for
each statement or parameter set in the batch. For this reason, the
driver returns a value of SUCCESS_NO_INFO (-2) for each entry in the
returned update count array.
false
The JDBC 3.0-compliant batch mechanism is used. If an

application can accept not receiving update count information,
setting this property to true can significantly improve performance.

CatalogIncludesSynonyms
DEPRECATED
This property is recognized for compatibility with existing data sources,

but we recommend that you use the CatalogOptions property instead to
include synonyms in result sets.
CatalogOptions
{0 | 1 | 2 | 3}
OPTIONAL
Determines the type of information included in result sets returned from

catalog functions:
Result sets contain default DatabaseMetaData results.
Result sets contain Remarks information returned from the
DatabaseMetaData methods: getTables and getColumns.
Result sets contain synonyms returned from the
DatabaseMetaData methods: getColumns, getProcedures,

getProcedureColumns,
and getIndexInfo.
3 Result sets contain remarks and synonyms (as described in

options 1 and 2).
The default is 2.
214
Oracle
Property
Description

OPTIONAL
the list.
The default is 0.
and

list only once.
DriverManager.loginTimeout), the login timeout takes precedence over
this property. For example, if the login timeout expires, any connection
attempts to alternate servers stop.
If the LoadBalancing property also is specified, the driver may sequence
time.
seconds, used between attempts.
215

Property
Description
The number of seconds the driver waits before retrying connections to a

list of database servers (primary and alternate) when
OPTIONAL
The default is 3.
and
and

twice. The driver waits 3 seconds between the first connection retry
attempt and the second connection retry attempt.
If the LoadBalancing property also is specified, the driver may sequence
time.
The ConnectionRetryCount property specifies the number of times the
driver will attempt to connect to all the servers in the list of alternate
servers.
DiagnosticFilename
OPTIONAL
contact Technical Support with a problem, you might be asked to
generate a state information log.
216
Oracle
Property
Description
FetchTSWTZasTimestamp
{true | false}
OPTIONAL
true
Allows column values with the TIMESTAMP WITH TIME ZONE

data type (Oracle9i or higher) to be retrieved as a JDBC TIMESTAMP
data type.
false Column values with the TIMESTAMP

type must be retrieved as a string.
WITH TIME ZONE data

{-1 | 0 | x}
OPTIONAL

result set data:
The driver caches all insensitive result set data in memory. If

the size of the result set exceeds available memory, an
efficiently.
-1
a maximum of 2 GB. If the size of the result set data exceeds

available memory, the driver pages the result set data to disk.
Because result set data may be written to disk, the driver may have
to reformat the data to write it correctly to disk.

the memory buffer for caching insensitive result set data. If the size
of the result set data exceeds the buffer size, the driver pages the
result set data to disk. Because the result set data may be written to
disk, the driver may have to reformat the data to write it correctly to
disk. Specifying a buffer size that is a power of 2 results in more
217

Property
Description
LoadBalancing
{true | false}
OPTIONAL
The list of alternate servers is specified by the AlternateServers
property. The LoadBalancing property determines behavior as follows:

in random order.
false Client load balancing is not used and the driver connects to
each server based on their sequential order (primary server first,

and
LoadBalancing=true
If using a tnsnames.ora file to retrieve connection information, do not
See Client Load Balancing on page 168 or more information about
218
Oracle
Property
Description
MaxPooledStatements

OPTIONAL
An integer greater than zero (0) Enables the Oracle drivers


cached.

are pooled.
The default is 0.
Password
A case-insensitive password used to connect to your Oracle database. A

contact your system administrator to obtain your password.
219

Property
Description
ServerType
{Shared | Dedicated}
OPTIONAL
Specifies whether the connection is established using a shared or

dedicated server process (UNIX) or thread (Windows):
Shared The server process to be used is retrieved from a pool. The
socket connection between the client and server is made to a

dispatcher process on the server. This setting allows there to be fewer
processes than the number of connections, reducing the need for
server resources. Use this value when a server must handle many
users with fewer server resources.
Dedicated
A server process is created to service only that

connection. When that connection ends, so does the process (UNIX)
or thread (Windows). The socket connection is made directly
between the application and the dedicated server process or thread.
When connecting to UNIX servers, a dedicated server process can
provide significant performance improvement, but uses more
resources on the server. When connecting to Windows servers, the
server resource penalty is insignificant. Use this value if you have a
batch environment with low numbers of users.
Unspecified The driver uses the server type set on the server.
If using a tnsnames.ora file to provide connection information, do not

ServiceName
OPTIONAL
The database service name that specifies the database used for the
connection. The service name is a string that is the global database
namea name that typically comprises the database name and domain
name. For example:
sales.us.acme.com
This property is useful to specify connections to an Oracle Real

Application Clusters (RAC) system rather than a specific Oracle instance
because the nodes in a RAC system share a common service name.
220
Oracle
Property
Description
SID
The Oracle System Identifier that refers to the instance of the Oracle
database running on the server. This property is mutually exclusive with
the ServiceName property.
OPTIONAL
The default is ORCL, which is the default SID that is configured when
installing your Oracle database.
TNSNamesFile
OPTIONAL
The path and filename to the tnsnames.ora file from which connection
information is retrieved. The tnsnames.ora file contains connection
information that is mapped to Oracle net service names. Using a
tnsnames.ora file to centralize connection information simplifies
maintenance when changes occur.
The value of this property must be a valid path and filename to a
tnsnames.ora file.
If you specify this property, you also must specify the TNSServerName
property.
If this property is specified, do not specify the following properties to
prevent connection information conflicts:
AlternateServers
LoadBalancing
PortNumber
ServerName
ServerType
ServiceName
SID
If any of these properties are specified in addition to this property, the

driver generates an exception.
221

Property
Description
TNSServerName
The Oracle net service name used to reference the connection

information in a tnsnames.ora file. The value of this property must be a
valid net service name entry in the tnsnames.ora file specified by the
TNSNamesFile property.
OPTIONAL
If this property is specified, you also must specify the TNSNamesFile

property.
If this property is specified, do not specify the following properties to
prevent connection information conflicts:
AlternateServers
LoadBalancing
PortNumber
ServerName
ServerType
ServiceName
SID
If any of these properties are specified in addition to this property, the

driver generates an exception.
User
222
The case-insensitive default user name used to connect to your Oracle

database. A user name is required only if security is enabled on your
database. If so, contact your system administrator to obtain your user
name. Operating System authentication is not currently supported by the
Oracle driver.
Oracle
Oracle Driver Connection Failover Properties

works with the Oracle driver. See Table 18 for details about configuring each property.
Table 19. Connection Failover Properties for the Oracle Driver
Property
Description
AlternateServers

server is required. Port number and the ServiceName or SID connection properties
are optional. If the port number is unspecified, the port specified for the primary
server is used. If a port number is not specified for the primary server, the default
port number of 1521 is used.
used).

LoadBalancing
ServiceName
The database service name that specifies the database used for the connection. This
property is mutually exclusive with the SID property.
SID
The Oracle System Identifier that refers to the instance of the Oracle database
running on the server. The default is ORCL. This property is mutually exclusive with
the ServiceName property.
223
Specifying Alternate Servers for the Oracle Driver

The following connection URL for the Oracle driver specifies connection information for
AlternateServers=(server2:1521;ServiceName=TEST2,server3:1521;
ServiceName=TEST3)
In this example:
...server1:1521;ServiceName=TEST...
example:
...;AlternateServers=(server2:1521;ServiceName=TEST2,
server3:50000;ServiceName=TEST3)
You can specify the optional connection properties ServiceName or SID for each alternate
server entry. These properties are mutually exclusive. For example:
AlternateServers=(server2:1521;ServiceName=TEST2,server3:1521)
or
jdbc:sonic:oracle://server1:1521;SID=ORCL;
AlternateServers=(server2:1521;SID=ORCL2,server3:1521)
server. For example, if you specify SID=ORCL for the primary server, but do not specify a
SID in the alternate server entry as shown in the following URL, the driver uses the SID
specified for the primary server and tries to connect to the ORCL database on the alternate
server:
jdbc:sonic:oracle://server1:1521;SID=ORCL;
224
Oracle
Oracle Driver Data Types

The following sections list data types supported by the Oracle driver, and describe the
XMLType data type supported by Oracle9i and higher drivers.
Oracle Data Types

Table 20 lists the data types supported by the Oracle driver and describes how they are
Table 20. Oracle Data Types
Oracle Database
Oracle Data Type
JDBC Data Type
Oracle8i and higher
BFILE
BLOB
BLOB
BLOB
CHAR
CHAR
CLOB
CLOB
DATE
TIMESTAMP
FLOAT(n)
DOUBLE
LONG
LONGVARCHAR
long raw
LONGVARBINARY
NCHAR
CHAR
NCLOB
CLOB
NUMBER (p, s)
DECIMAL
NUMBER
DOUBLE
NVARCHAR2
VARCHAR
TIMESTAMP
TIMESTAMP
TIMESTAMP WITH LOCAL TIME

ZONE
TIMESTAMP
TIMESTAMP WITH TIME ZONE
VARCHAR
VARCHAR2
VARCHAR
XMLType
CLOB
Oracle9i and higher
225

Table 20. Oracle Data Types (continued)
Oracle Database
Oracle Data Type
JDBC Data Type
Oracle10g only
BINARY_FLOAT
REAL
BINARY_DOUBLE
DOUBLE
XMLType Data Type

The Oracle driver supports tables containing columns specified as XMLType for Oracle9i
and higher. The driver maps the Oracle XMLType data type to the JDBC CLOB data type.
XMLType columns can be used in queries just like any other column type. The data from
XMLType columns can be retrieved as a String, Clob, CharacterStream, or AsciiStream.
When inserting or updating XMLType columns, the data to be inserted or updated must be
in the form of an XMLType data type.
Oracle provides the xmltype() function to construct an XMLType data object. The xmlData
argument of the xmltype() function can be specified as a string literal or a parameter
marker. If a parameter marker is used, the parameter value may be set using the setString,
setClob, setCharacterStream, or setAsciiStream methods.
The following code inserts data into an XMLType column using a statement with a string
literal as the xmlData argument of the xmltype() function:
// Insert xml data as a literal
String sql = "insert into XMLTypeTbl values (1, xmltype('" +
"<emp><empNo>123</empNo><empName>Mark</empName></emp>'))";
Statement stmt = con.createStatement();
stmt.executeUpdate(sql);
The following code inserts data into an XMLType column using a prepared statement:
//
Insert xml data as a String parameter
String xmlStr = "<emp><empNo>234</empNo><empName>Trish</empName></emp>";

String sql = "insert into XMLTypeTbl values (?, xmltype(?))";
PreparedStatement prepStmt = con.prepareStatement(sql);
prepStmt.setInt(1, 2);
prepStmt.setString(2, xmlStr);
prepStmt.executeUpdate();
226
When the data from an XMLType column is retrieved as a Clob, the XMLType data cannot be
updated using the Clob object. Calling the setString, setCharacterStream, or
setAsciiStream methods of a Clob object returned from an XMLType column generates an
SQLException.

The following sections describe settings for the Sonic Database Service Microsoft SQL
Server driver:
Microsoft SQL Server Driver Connection Properties
Microsoft SQL Server Driver Connection Failover Properties
Specifying Alternate Servers for the Microsoft SQL Server Driver
Microsoft SQL Server Driver Data Types
Microsoft SQL Server Driver Connection Properties

Table 21 describes the JDBC connection properties supported by the Microsoft SQL
Server driver. The properties have the format:
property=value
Note
as password.
227

Table 21. Connection Properties for the Microsoft SQL Server Driver
Property
Description
AlternateServers

has the format:
OPTIONAL
(servername1[:port1][;property=value],
servername2[:port2][;property=value],...)
alternate server entry. If the port is unspecified, the port number specified
for the primary server is used. If a port number for the primary server is
unspecified, the default port number of 1433 is used. The driver allows
only one optional connection property, DatabaseName. For example:
jdbc:sonic:sqlserver://server1:1433;
DatabaseName=TEST;AlternateServers=(server2:1433;
DatabaseName=TEST2,server3:1433;DatabaseName=TEST3)
Controls the number of times the driver

retry attempts.
LoadBalancing

See Specifying Primary and Alternate Servers on page 172 or more

alternate servers.
228

Table 21. Connection Properties for the Microsoft SQL Server Driver (continued)
Property
Description
AlwaysReportTriggerResults
{true | false}
OPTIONAL
Determines how the driver reports results generated by database triggers

(procedures that are stored in the database and executed, or fired, when a
table is modified):
true The driver returns all results, including results generated by

triggers. Multiple trigger results are returned one at a time. Use the
Statement.getMoreResults method to retrieve individual trigger
results. Warnings and errors are reported in the results as they are
encountered.
false The driver does not report trigger results if the statement is
a single Insert, Update, or Delete statement. In this case, the only

result that is returned is the update count generated by the statement
that was executed (if errors do not occur). Although trigger results
are ignored, any errors generated by the trigger are reported. Any
warnings generated by the trigger are enqueued. If errors are
reported, the update count is not reported.
CodePageOverride
OPTIONAL
Specifies the code page the driver uses when converting character data.
The specified code page overrides the default database code page. All
of a valid code page supported by your Java Virtual Machine, for
example, CodePageOverride=CP950.
If a value is set for the CodePageOverride property and the
SendStringParametersAsUnicode property is set to true, the driver
ignores the SendStringParametersAsUnicode property and generates a
warning. The driver always sends parameters using the code page
specified by CodePageOverride if this property is specified.
229

Property
Description

OPTIONAL
the list.
The default is 0.
and

list only once.
time.
230

Property
Description
The number of seconds the driver waits before retrying a list of database
servers (primary and alternate) when ConnectionRetryCount is set to a
positive integer.
OPTIONAL
The default is 3.
and
and

twice. It waits 3 seconds between the first connection retry attempt and
the second connection retry attempt.
NOTE: If the LoadBalancing property is set to true, the driver may
sequence through the list of servers (primary and alternate) in a different
order each time.
DatabaseName
OPTIONAL
DiagnosticFilename
OPTIONAL
HostProcess
OPTIONAL
The process ID of the application connecting to Microsoft SQL Server.

The value of this property appears in the hostprocess column of the
master.dbo.sysprocesses table and may be useful for database
administration purposes.
The default is 0.
231

Property
Description
{-1 | 0 | x}
OPTIONAL

result set data. This property must have one of the following values:

efficiently.
-1


232

Property
Description
LoadBalancing
{true | false}
OPTIONAL

in random order.

and
LoadBalancing=true
233

Property
Description
MaxPooledStatements

OPTIONAL
An integer greater than zero (0) Enables the SQL Server drivers

cached.

are pooled.
The default is 0.
NetAddress
OPTIONAL
The Media Access Control (MAC) address of the network interface card
of the application connecting to Microsoft SQL Server. The value of this
property appears in the net_address column of the
master.dbo.sysprocesses table and is used for database administration
purposes.
The default is 000000000000.
Password
OPTIONAL
A case-insensitive password used to connect to your Microsoft SQL

Server database. If a user name is not specified, the driver will use
Windows authentication when connecting to Microsoft SQL Server. In
this case, a password is not required. If a password is required, contact
Refer to the Progress Sonic ESB Product Family: Installation and
Upgrade Guide for product requirements and configuration that must be
met to use Windows authentication with the SQL Server driver.
ProgramName
OPTIONAL
The name of the application connecting to Microsoft SQL Server. The

value of this property appears in the program_name column of the
master.dbo.sysprocesses table and is useful for database administration
purposes.
The default is an empty string.
234

Property
Description
SelectMethod
{direct | cursor}
OPTIONAL
A hint to the driver that determines whether the driver requests a database
cursor for Select statements. Performance and behavior of the driver are
affected by this property, which is defined as a hint because the driver
might not always be able to satisfy the requested method.
Direct
When the driver uses the Direct method, the database

server sends the complete result set in a single response to the driver
when responding to a query. A server-side database cursor is not
created. Typically, responses are not cached by the driver. Using this
method, the driver must process all the response to a query before
another query is submitted. If another query is submitted (using a
different statement on the same connection, for example), the driver
caches the response to the first query before submitting the second
query. Typically, the Direct method performs better than the Cursor
method.
Cursor
When the driver uses the Cursor method, a server-side

cursor is requested. The rows are retrieved from the server in blocks
when returning forward-only result sets. The JDBC Statement
method setFetchSize can be used to control the number of rows that
are retrieved for each request. Performance tests show that the value
of setFetchSize significantly impacts performance when the Cursor
method is used. There is no simple rule for determining the
setFetchSize value that you should use. We recommend that you
experiment with different setFetchSize values to determine which
value gives the best performance for your application. The Cursor
method is useful for queries that produce a large amount of data,
particularly if multiple open result sets are used.
The default is Direct.
235

Property
Description
SendStringParametersAsUnicode
{true | false}
OPTIONAL
Determines whether string parameters are sent to the Microsoft SQL

Server database in Unicode or in the default character encoding of the
database:
true String parameters are sent to Microsoft SQL Server in

Unicode.
false
String parameters are sent in the default encoding, which

can improve performance because the server does not need to
convert Unicode characters to the default encoding. You should,
however, use default encoding only if the parameter string data you
specify is the same as the default encoding of the database.

If a value is specified for the CodePageOverride property and this
property is set to true, this property is ignored and a warning is
generated.
User
The case-insensitive user name used to connect to your Microsoft SQL

Server database. If a user name is not specified, the driver uses Windows
authentication when connecting to the database server. In this case, a user
name is not required. If a user name is required, contact your system
administrator to obtain your user name.
OPTIONAL
Refer to the Progress Sonic ESB Product Family: Installation and

Upgrade Guide for product and configuration requirements that must be
met to use Windows authentication with the SQL Server driver.
UseServerSideUpdatableCursors
{true | false}
Determines whether the driver uses server-side cursors when an

updatable result set is requested:
true Server-side updatable cursors are created when an updatable

result set is requested.
false
The default updatable result set functionality is used.
236

Property
Description
WSID
The workstation ID, which typically is the network name of the computer
on which the application resides. If specified, this value is stored in the
hostname column of the master.dbo.sysprocesses table and can be
returned by sp_who and the Transact-SQL HOST_NAME function. The value
is useful for database administration purposes.
OPTIONAL
The default is an empty string.

XATransactionGroup
OPTIONAL
The transaction group ID that identifies any transactions initiated by the

connection. This ID can be used for distributed transaction cleanup
purposes.
You can use the XAResource.recover method to roll back any
transactions left in an unprepared state. When you call
XAResource.recover, any transactions that match the ID on the
connection used to call XAResource.recover are rolled back. For
example, if you specify XATransactionGroup=ACCT200 and call
XAResource.recover on the same connection, any transactions left in an
unprepared state identified by the transaction group ID of ACCT200 are
rolled back.
237
Microsoft SQL Server Driver Connection Failover Properties

works with the Database Service SQL Server driver. See Table 21 for details about
configuring each property.
Table 22. Connection Failover Properties for the Microsoft SQL Server Driver
Property
Description
AlternateServers

server is required. Port number and supported connection properties (DatabaseName)
are optional. If the port number is unspecified, the port number specified for the
primary server is used. If a port number is unspecified for the primary server, the
default port number of 1433 is used.
used).

DatabaseName
LoadBalancing
Specifying Alternate Servers for the Microsoft SQL Server Driver

The following connection URL for the Microsoft SQL Server driver specifies connection
information for the primary and alternate servers:
jjdbc:sonic:sqlserver://server1:1433;DatabaseName=TEST;
DatabaseName=TEST3)
In this example:
238

....server1:1433;DatabaseName=TEST...
example:
...;AlternateServers=(server2:1433;DatabaseName=TEST2,server3:1433;
DatabaseName=TEST3)
You can specify an optional instance property for each alternate server entry. For
example:
DatabaseName=TEST3)
or, if connecting to named instances:

jdbc:sonic:sqlserver://server1\\instance1:1433;DatabaseName=TEST;
AlternateServers=(server2\\instance2:1433;DatabaseName=TEST2,s
erver3\\instance3:1433;DatabaseName=TEST3)
server. For example, if you specify DatabaseName=TestServer for the primary server, but
do not specify the InformixServer and DatabaseName properties in the alternate server
entry as shown in the following URL, the driver uses the InformixServer and
DatabaseName specified for the primary server and tries to connect to the TEST database on
the alternate server:
The SQL Server driver also allows you to specify connections to named instances,
multiple instances of a Microsoft SQL Server database running concurrently on the same
server. If specifying named instances for the primary and alternate servers, the connection
URL would look like this:
jdbc:datadirect:sqlserver://server1\\instance1;
AlternateServers=(server2\\instance2:1433;DatabaseName=TEST2,
server3\\instance3:1433;DatabaseName=TEST3)
239
Microsoft SQL Server Driver Data Types

Table 23 lists the data types supported by the Microsoft SQL Server driver and describes
how they are mapped to JDBC data types. These data types are for SQL Server 7 and 2000
unless otherwise noted in the table.
Table 23. Microsoft SQL Server Driver Data Types
240

DataBase

Data Type
JDBC Data Type
SQL Server 7 and 2000
binary
BINARY
bit
BIT
char
CHAR
datetime
TIMESTAMP
decimal
DECIMAL
decimal() identity
DECIMAL
float
FLOAT
image
LONGVARBINARY
int
INTEGER
int identity
INTEGER
money
DECIMAL
nchar
CHAR
ntext
LONGVARCHAR
numeric
NUMERIC
numeric() identity
NUMERIC
nvarchar
VARCHAR
real
REAL
smalldatetime
TIMESTAMP
smallint
SMALLINT

Table 23. Microsoft SQL Server Driver Data Types (continued)

DataBase

Data Type
JDBC Data Type
SQL Server 7 and 2000
smallint identity
SMALLINT
smallmoney
DECIMAL
sysname
VARCHAR
text
LONGVARCHAR
timestamp
BINARY
tinyint
TINYINT
tinyint identity
TINYINT
uniqueidentifier
CHAR
varbinary
VARBINARY
varchar
VARCHAR
bigint
BIGINT
bigint identity
BIGINT
sql_variant
VARCHAR
SQL Server 2000 only
241
Sybase
The following sections describe settings for the Sonic Database Service Sybase driver:
Sybase Driver Connection Properties
Sybase Driver Connection Failover Properties
Specifying Alternate Servers for the Sybase Driver
Sybase Driver Data Types
Sybase Driver Connection Properties

Table 24 describes the JDBC connection properties supported by the Sybase driver. The
property=value
Note
242
as password.
Sybase
Table 24. Connection Properties for the Sybase Driver
Property
Description
AlternateServers

has the format:
OPTIONAL
(servername1[:port1][;property=value],
servername2[:port2][;property=value],...)
primary server is used. The driver only allows one optional connection
property, DatabaseName. For example:
jdbc:sonic:sybase://server1:4100;
DatabaseName=TEST;AlternateServers=(server2:4100;
DatabaseName=TEST2,server3:4100;DatabaseName=TEST3)

retry attempts.
LoadBalancing

alternate servers
243

Table 24. Connection Properties for the Sybase Driver (continued)
Property
Description
{true | false}
OPTIONAL
Determines the method used to execute batch operations:

The native Sybase batch mechanism is used.
true
false
The JDBC 3.0-compliant batch mechanism is used.
In most cases, using the native Sybase batch functionality provides

significantly better performance, but the driver may not always be able to
return update counts for the batch.
CodePageOverride
OPTIONAL
244
Specifies the code page the driver uses when converting character data.
The specified code page overrides the default database code page. All
of a valid code page supported by your Java Virtual Machine, for
example, CodePageOverride=CP950.
Sybase
Property
Description

OPTIONAL
the list.
The default is 0.
and

list only once.
time.
245

Property
Description
The number of seconds the driver waits before retrying connections to a

list of database servers (primary and alternate) when
OPTIONAL
The default is 3.
and
and

twice. It waits 3 seconds between the first connection retry attempt and
the second connection retry attempt.
time.
DatabaseName
OPTIONAL
DiagnosticFilename
OPTIONAL
246
Sybase
Property
Description
{-1 | 0 | x}
OPTIONAL

result set data. It must have one of the following values:

efficiently.
-1


247

Property
Description
LoadBalancing
{true | false}
OPTIONAL

in random order.

and
LoadBalancing=true
248
Sybase
Property
Description
MaxPooledStatements

OPTIONAL
An integer greater than zero (0) Enables the Sybase drivers


cached.

are pooled.
The default is 0.
Password
The case-sensitive password used to connect to your Sybase database. A

contact your system administrator to get your password.
249

Property
Description
PrepareMethod
{StoredProc | StoredProclfParam | Direct}
OPTIONAL
Determines whether stored procedures are created on the server for

prepared statements:
StoredProc
A stored procedure is created when the statement is

prepared and is executed when the prepared statement is executed.
StoredProcIfParam
Direct
A stored procedure is created only if the

prepared statement contains one or multiple parameter markers. In
this case, it is created when the statement is prepared and is executed
when the prepared statement is executed. If the statement does not
contain parameter markers, a stored procedure is not created and the
statement is executed directly.
A stored procedure is not created for the prepared
statement and the statement is executed directly. A stored procedure
might be created if parameter metadata is requested.
The default is StoredProclfParam.

Setting this property to StoredProc or StoredProclfParam can improve
performance if your application executes prepared statements multiple
times because, once created, executing a stored procedure is faster than
executing a single database query. If a prepared statement is only
executed once or is never executed, performance can decrease because
creating a stored procedure incurs more overhead on the server than
simply executing a single database query. Setting this property to Direct
should be used if your application does not execute prepared statements
multiple times.
250
Sybase
Property
Description
SelectMethod
{Direct | Cursor}
OPTIONAL
A hint to the driver that determines whether the driver requests a database
cursor for Select statements. Performance and behavior of the driver are
affected by this property, which is defined as a hint because the driver
may not always be able to satisfy the requested method.
When the driver uses the Direct method, the database
server sends the complete result set in a single response to the driver
when responding to a query. A server-side database cursor is not
created. Typically, responses are not cached by the driver. Using this
method, the driver must process all the response to a query before
another query is submitted. If another query is submitted (using a
different statement on the same connection, for example), the driver
caches the response to the first query before submitting the second
query. Typically, the Direct method performs better than the Cursor
method.
Direct
Cursor
When the driver uses the Cursor method, a server-side

database cursor is requested. The rows are retrieved from the server
in blocks when returning forward-only result sets. The JDBC
Statement method setFetchSize can be used to control the number
of rows that are retrieved for each request. Performance tests show
that the value of setFetchSize significantly impacts performance
when the Cursor method is used. There is no simple rule for
determining the setFetchSize value that you should use. We
recommend that you experiment with different setFetchSize values
to find out which value gives the best performance for your
application. The Cursor method is useful for queries that produce a
large amount of data, particularly if multiple open result sets are
used.
The default is Direct.

User
The case-insensitive user name used to connect to your Sybase database.

A user name is required only if security is enabled on your database. If
so, contact your system administrator to get your user name.
251
Sybase Driver Connection Failover Properties

works with the Database Service Sybase driver. See Table 24 for details about configuring
each property.
Table 25. Connection Failover Properties for the Sybase Driver
Property
Description
AlternateServers

server is required. Port number and the DatabaseName connection property are
optional. If the port number is unspecified, the port number specified for the primary
server is used. If a port number is unspecified for the primary server, the port number
specified for the primary server is used.
used).

DatabaseName
LoadBalancing
Specifying Alternate Servers for the Sybase Driver

The following connection URL for the Sybase driver specifies connection information for
DatabaseName=TEST3)
252
Sybase
In this example:
....server1:4100;DatabaseName=TEST...
example:
...;AlternateServers=(server2:4100;DatabaseName=TEST2,
The property property=value is optional for each alternate server entry. For example:
AlternateServers=(server2:4100;DatabaseName=TEST2,server3:4100)
server. For example, if you specify DatabaseName=TEST for the primary server, but do not
specify a database name in the alternate server entry as shown in the following URL, the
driver tries to connect to the TEST database on the alternate server:
jjdbc:sonic:sybase://server1:4100;DatabaseName=TEST;
253
Sybase Driver Data Types

Table 26 lists the data types supported by the Sybase driver and describes how they are
Table 26. Sybase Driver Data Types
254
Sybase DataBase
Sybase Data Type
JDBC Data Type
Sybase 11.5 and higher
binary
BINARY
bit
BIT
char
CHAR
datetime
TIMESTAMP
decimal
DECIMAL
decimal() identity
DECIMAL
float
FLOAT
image
LONGVARBINARY
int
INTEGER
money
DECIMAL
nchar
CHAR
numeric
NUMERIC
nvarchar
VARCHAR
real
REAL
smalldatetime
TIMESTAMP
smallint
SMALLINT
smallmoney
DECIMAL
sysname
VARCHAR
text
LONGVARCHAR
timestamp
VARBINARY
tinyint
TINYINT
varbinary
VARBINARY
varchar
VARCHAR
Sybase
Table 26. Sybase Driver Data Types (continued)
Sybase DataBase
Sybase Data Type
JDBC Data Type
Sybase 12.5 and 12.5.1 only
date
DATE
time
TIME
unichar
CHAR
univarchar
VARCHAR
Note For users of Adaptive Server 12.5 and 12.5.1: The Sybase driver supports extended new
limits (XNL) for character and binary columnscolumns with lengths greater than 255.
Refer to your Sybase documentation for more information about XNL for character and
binary columns.
255
256
Chapter 10
SQL Escape Sequences for JDBC
Language features, such as outer joins and scalar function calls, are commonly
implemented by database systems. The syntax for these features is often databasespecific, even when a standard syntax has been defined. This chappter describes the
JDBC-defined escape sequences containing standard syntaxes for the following language
features:
Date, Time, and Timestamp Escape Sequences
Scalar Functions
Outer Join Escape Sequences
Procedure Call Escape Sequences

The escape sequence used by JDBC is:
{extension}
The escape sequence is recognized and parsed by Progress Sonic Database Service JDBC
drivers, and replaces the escape sequences with data store-specific grammar.
257
Date, Time, and Timestamp Escape Sequences

The escape sequence for date, time, and timestamp literals is:
{literal-type 'value'}
where literal-type is one of the following:

literal-type
Description
Value Format
Date
yyyy-mm-dd
Time
h:mm:ss [1]
ts
Timestamp
yyyy-mm-dd hh:mm:ss[.f...]
For example:
UPDATE Orders SET OpenDate={d '1995-01-15'}
WHERE OrderID=1023
Scalar Functions
You can use scalar functions in database queries with the following syntax:
{fn scalar-function}
where scalar-function is a scalar function supported by Database Service JDBC drivers,

as listed in Table 27.
For example:
SELECT id, name FROM emp WHERE name LIKE {fn UCASE('Smith')}
258
Scalar Functions
Table 27. Scalar Functions Supported by Database Service JDBC Drivers
Data Store
String Functions
Numeric
Functions
Timedate
Functions
System
Functions
Progress
OpenEdge
CONCAT
ABS
CURRDATE
DATABASE
LEFT
ACOS
CURRTIME
USER
LENGTH
ASIN
DAYOFMONTH
LTRIM
ATAN
DAYOFWEEK
REPLACE
ATAN2
MONTH
RTRIM
COS
NOW
SUBSTRING
COT
TIMESTAMP
EXP
TIMESTAMPADD
FLOOR
TIMESTAMPDIFF
LOG
YEAR
LOG10
MOD
POWER
ROUND
SIN
SQRT
TAN
TRUNCATE
259

Table 27. Scalar Functions Supported by Database Service JDBC Drivers (continued)
Data Store
String Functions
Numeric
Functions
Timedate
Functions
System
Functions
DB2
ASCII
ABS or ABSVAL
DATE
COALESCE
BLOB
ACOS
DAY
DEREF
CHAR
ASIN
DAYNAME
DLCOMMENT
CHR
ATAN
DAYOFWEEK
DLLINKTYPE
CLOB
ATANH
DAYOFYEAR
DLURLCOMPLETE
CONCAT
ATAN2
DAYS
DLURLPATH
DBCLOB
BIGINT
HOUR
DLURLPATHONLY
DIFFERENCE
CEILING or CEIL
JULIAN_DAY
DLURLSCHEME
GRAPHIC
COS
MICROSECOND
DLURLSERVER
HEX
COSH
MIDNIGHT_SECONDS
DLVALUE
INSERT
COT
MINUTE
EVENT_MON_STATE
LCASE or LOWER
DECIMAL
MONTH
GENERATE_UNIQUE
LCASE (SYSFUN schema)
DEGREES
MONTHNAME
NODENUMBER
LEFT
DIGITS
QUARTER
NULLIF
LENGTH
DOUBLE
SECOND
PARTITION
LOCATE
EXP
TIME
RAISE_ERROR
LONG_VARCHAR
FLOAT
TIMESTAMP
TABLE_NAME
LONG_VARGRAPHIC
FLOOR
TIMESTAMP_ISO
TABLE_SCHEMA
LTRIM
INTEGER
TIMESTAMPDIFF
TRANSLATE
LTRIM (SYSFUN schema)
LN
WEEK
TYPE_ID
POSSTR
LOG
YEAR
TYPE_NAME
REPEAT
LOG10
TYPE_SCHEMA
REPLACE
MOD
VALUE
RIGHT
POWER
RTRIM
RADIANS
RTRIM (SYSFUN schema)
RAND
SOUNDEX
REAL
SPACE
ROUND
SUBSTR
SIGN
TRUNCATE or TRUNC
SIN
UCASE or UPPER
SINH
VARCHAR
SMALLINT
VARGRAPHIC
SQRT
TAN
TANH
TRUNCATE
260
Scalar Functions
Data Store
String Functions
Numeric
Functions
Timedate
Functions
System
Functions
Informix
CONCAT
ABS
CURDATE
DATABASE
LEFT
ACOS
CURTIME
USER
LENGTH
ASIN
DAYOFMONTH
LTRIM
ATAN
DAYOFWEEK
REPLACE
ATAN2
MONTH
RTRIM
COS
NOW
SUBSTRING
COT
TIMESTAMPADD
EXP
TIMESTAMPDIFF
FLOOR
YEAR
LOG
LOG10
MOD
PI
POWER
ROUND
SIN
SQRT
TAN
TRUNCATE
261

Data Store
String Functions
Numeric
Functions
Timedate
Functions
System
Functions
Oracle
ASCII
ABS
CURDATE
IFNULL
BIT_LENGTH
ACOS
DAYNAME
USER
CHAR
ASIN
DAYOFMONTH
CONCAT
ATAN
DAYOFWEEK
INSERT
ATAN2
DAYOFYEAR
LCASE
CEILING
HOUR
LEFT
COS
MINUTE
LENGTH
COT
MONTH
LOCATE
EXP
MONTHNAME
LOCATE2
FLOOR
NOW
LTRIM
LOG
QUARTER
OCTET_LENGTH
LOG10
SECOND
REPEAT
MOD
WEEK
REPLACE
PI
YEAR
RIGHT
POWER
RTRIM
ROUND
SOUNDEX
SIGN
SPACE
SIN
SUBSTRING
SQRT
UCASE
TAN
TRUNCATE
262
Scalar Functions
Data Store
String Functions
Numeric
Functions
Timedate
Functions
System
Functions
Microsoft
SQL Server
ASCII
ABS
DAYNAME
DATABASE
CHAR
ACOS
DAYOFMONTH
IFNULL
CONCAT
ASIN
DAYOFWEEK
USER
DIFFERENCE
ATAN
DAYOFYEAR
INSERT
ATAN2
EXTRACT
LCASE
CEILING
HOUR
LEFT
COS
MINUTE
LENGTH
COT
MONTH
LOCATE
DEGREES
MONTHNAME
LTRIM
EXP
NOW
REPEAT
FLOOR
QUARTER
REPLACE
LOG
SECOND
RIGHT
LOG10
TIMESTAMPADD
RTRIM
MOD
TIMESTAMPDIFF
SOUNDEX
PI
WEEK
SPACE
POWER
YEAR
SUBSTRING
RADIANS
UCASE
RAND
ROUND
SIGN
SIN
SQRT
TAN
TRUNCATE
263

Data Store
String Functions
Numeric
Functions
Timedate
Functions
System
Functions
Sybase
ASCII
ABS
DAYNAME
DATABASE
CHAR
ACOS
DAYOFMONTH
IFNULL
CONCAT
ASIN
DAYOFWEEK
USER
DIFFERENCE
ATAN
DAYOFYEAR
INSERT
ATAN2
HOUR
LCASE
CEILING
MINUTE
LEFT
COS
MONTH
LENGTH
COT
MONTHNAME
LOCATE
DEGREES
NOW
LTRIM
EXP
QUARTER
REPEAT
FLOOR
SECOND
RIGHT
LOG
TIMESTAMPADD
RTRIM
LOG10
TIMESTAMPDIFF
SOUNDEX
MOD
WEEK
SPACE
PI
YEAR
SUBSTRING
POWER
UCASE
RADIANS
RAND
ROUND
SIGN
SIN
SQRT
TAN
264

JDBC supports the SQL92 left, right, and full outer join syntax. The escape sequence for
outer joins is:
{oj outer-join}
where outer-join is:

table-reference {LEFT | RIGHT | FULL} OUTER JOIN
{table-reference | outer-join} ON search-condition
where:
table-reference is
a database table name

search-condition is the join condition you want to use for the tables
For example:
SELECT Customers.CustID, Customers.Name, Orders.OrderID, Orders.Status
FROM {oj Customers LEFT OUTER JOIN
Orders ON Customers.CustID=Orders.CustID}
WHERE Orders.Status='OPEN'
Table 28 lists the outer join escape sequences supported by Database Service JDBC
drivers for each data store.
Table 28. Outer Join Sequences Supported by Database Service JDBC Drivers
Data Store
Progress OpenEdge
Left outer joins

Right outer joins
Nested outer joins
DB2
Left outer joins

Right outer joins
Nested outer joins
Informix
Left outer joins

Right outer joins
Nested outer joins
265

Table 28. Outer Join Sequences Supported by Database Service JDBC Drivers
Data Store
Oracle
Left outer joins

Right outer joins
Nested outer joins
Left outer joins

Right outer joins
Full outer joins
Nested outer joins
Sybase
Left outer joins

Right outer joins
Nested outer joins
Procedure Call Escape Sequences

A procedure is an executable object stored in the data store. Generally, it is one or more
database queries that have been precompiled. The escape sequence for calling a procedure
is:
{[?=]call procedure-name[(parameter[,parameter]...)]}
where:
specifies the name of a stored procedure
parameter specifies a stored procedure parameter
procedure-name
Note For DB2, a schema name cannot be used when calling a stored procedure. Also, for DB2
UDB 8.1, literal parameter values are supported for stored procedures. Other supported
DB2 versions do not support literal parameter values for stored procedures.
266
Chapter 11
Configuring SQL Server

Windows Authentication
The Progress Sonic Database Service JDBC SQL Server driver supports Windows
authenticated connections to Microsoft SQL Server 2000 and Microsoft SQL Server 2000
Enterprise Edition (64-bit) in a domain running Windows Active Directory for Windows
clients.
See Table 29 for a summary of the configuration that is required to use Windows
authentication on Microsoft SQL Server with the Database Service JDBC SQL Server
driver.
Table 29. Configuring Windows Authentication on Microsoft SQL Server
Component
Collection

Database Server
Set the authentication mode (seeSetting the Authentication Mode on page 268).
Confirm that a Service Principal Name (SPN) is registered for each Microsoft SQL
Server instance (see Registering Service Principal Names (SPNs) on page 268).
Domain Controller
Confirm that the Active Directory encryption property is set to use DES encryption
in the Microsoft SQL Server Service Startup Account (see Setting the Active
Directory Encryption Property on page 269).
267
Chapter 11: Configuring SQL Server Windows Authentication
Setting the Authentication Mode

To use Windows authentication, the authentication mode in Microsoft SQL Server on the
database server can be set to either Windows Only authentication or Mixed authentication.
If SQL Server authentication will be used in addition to Windows authentication, set the
authentication mode to use Mixed authentication.
Registering Service Principal Names (SPNs)

An SPN must be registered for each Microsoft SQL Server instance. An SPN is a unique
name that maps the Microsoft SQL Server service for a particular machine and port to an
account name used to start the service (Service Startup Account). An SPN is composed
of a service class name of MSSQLSvc, the host name of the machine running Microsoft SQL
Server, and the port number on which the Microsoft SQL Server instance is listening. For
example:
MSSQLSvc/DBServer.test:1433
is an SPN for a Microsoft SQL Server instance running on a machine named DBServer in
the test domain and listening on port 1433.
Check with your system administrator to confirm that the appropriate SPNs have been
registered for each Microsoft SQL Server instance. To list registered SPNs, use the
following Windows command:
ldifde
If necessary, your system administrator can register SPNs using the Setspn tool available
with the Windows Resource Kit. For example:
setspn -A MSSQLSvc/DBServer.test:1433 sqlsvc
registers an SPN that maps the Service Startup Account named sqlsvc to a Microsoft SQL
Server instance running on a machine named DBServer in the test domain and listening on
port 1433. The Setspn tool is available from the following Web site:
http://www.microsoft.com/windows2000/techinfo/reskit/tools/
existing/setspn-o.asp
Refer to the Microsoft documentation accompanying the Setspn tool for instructions on
using it.
Note If the Microsoft SQL Server Service Startup Account is changed, SPNs for Microsoft
SQL Server must be deleted and re-registered.
268
Setting the Active Directory Encryption Property
Setting the Active Directory Encryption Property

A Windows domain running Windows Active Directory uses the Kerberos authentication
protocol to protect logon credentials that travel across the network. Messages passed
between the Kerberos Key Distribution Center (KDC), which runs on every domain
controller as part of Active Directory, and Microsoft SQL Server are encrypted.
The Active Directory property "Use DES encryption types for this account" must be
set in the Microsoft SQL Server Service Startup Account on the domain controller.
Setting this property is a one-time task that you must do only when the Active Directory
account is first created. Check with your system administrator to verify that this property
is set for the Microsoft SQL Server Service Startup Account on the domain controller.
269
Chapter 11: Configuring SQL Server Windows Authentication
270
Part IV
Configuring and Managing BPEL Services
Part IV explains how to configure and manage BPEL services using the Sonic
Management Console, and contains the following chapters:
Configuring BPEL Services
Managing BPEL Services
271
272
Chapter 12
Configuring BPEL Services
This chapter describes how to configure BPEL services using the Sonic Management
Console. This chapter contains the following sections:
Overview of BPEL Service Initialization Parameters
Specifying a BPEL Archive (.bpar)
Setting Persistence Options
Enabling Audit Trails
Audit Trails and Persistence
Setting a Default Partner Link
273
Chapter 12: Configuring BPEL Services

A BPEL project contains a single BPEL service and one or more BPEL processes. A
BPEL service can execute a single BPEL process or multiple processes. This chapter
explains how to configure BPEL services using the Sonic Management Console (SMC).
(See the Progress Sonic BPEL Server Developers Guide in the Sonic Workbench
(Eclipse) help for detailed information about BPEL services and processes.)
Note In the development environment, you can also configure BPEL Service parameters using
the BPEL Service editor in Sonic Workbench. See the BPEL Service Editor section of the
Sonic Workbench (Eclipse) help for information.
The BPEL service configuration pane in the SMC includes areas for viewing and
configuring Service Maintenance parameters and Initialization parameters, as shown in
this example using the sample BPEL service, LoanApproval:
274
The Service Maintenance parameters are configured as for any ESB service:
Service Name
Entry Endpoint
Exit Endpoints
Fault Endpoint
Rejected Message Endpoint
WSDL URL
The WSDL URL is exposed when BPEL processes are used directly by other services on
the ESB. Each BPEL process has a separate WSDL, which is configured in the
development environment in Sonic Workbench. For information about configuring these
parameters, see the Progress Sonic BPEL Server Developers Guide in the Sonic
Workbench (Eclipse) help.
275
BPEL services have the following Initialization Parameters:

Initialization Parameter
Description
BPEL Archive
The URL of a BPEL archive file (*.bpar) located in the Sonic

file system.
Required.
See Specifying a BPEL Archive (.bpar) on page 277
Staging Directory
Enter a local file system directory where the BPAR can be

unpacked. The default value is a directory named
bpel_staging, relative to the working directory of the ESB
container in which the service is deployed (./bpel_staging).
Required.
Note: The BPEL service may delete files in this directory on
service startup.
276
Persistence
Select a value to define how the service is to persist (if at all)

its state. The default value is Embedded Storage.
Required.
See Setting Persistence Options on page 278.
Enable Audit Trail Recording
Select whether audit trails are captured for process instances.

The default value is True.
Required.
See Audit Trails and Persistence on page 283.
Default Partner Link
Specify the default process and partner link to use.

Optional.
See Setting a Default Partner Link on page 284.
HTTP Callback URL
The address used as the Reply To address when using WSA

headers in asynchronous invocations.
Optional.

A BPAR file (*.bpar) is an archive of all resources required to execute a set of BPEL
processes. A BPAR is created by Sonic Workbench when a BPEL project is uploaded.
When configuring a BPEL service in the SMC you must point to an existing BPAR file.
A single BPAR can be used by one more than one service. (See the Progress Sonic BPEL
Server Developers Guide in the Sonic Workbench (Eclipse) help for more information
about BPAR files.)
Note It is recommended that BPAR files be stored in the Sonic file system (sonicfs://),
however, local system paths may be specified.

To specify a BPEL archive file:
1.
In the Init Parameters area of the SMC, click ... next to the BPEL Archive field to open
the Edit BPEL Archive file chooser, as shown in this example:
2.
Browse to and select a BPEL archive file (*.bpar).
3.
Click Open.
The URL of the BPEL archive file is now displayed in the BPEL Archive field of the
SMC.
277

Persistence refers to the storage of active processes deployed to a server. Engine
persistence must be configured to allow persistent processes and audit trails (see
Enabling Audit Trails on page 282). If a service is configured to allow persistence, each
process can then be configured to utilize it or not using its deployment descriptor file
(*.bpdd). See the BPEL Deployment Descriptor editor section of the Progress Sonic
BPEL Server Developers Guide in the Sonic Workbench (Eclipse) help for information.
BPEL services can run in either of two process modes:
Persistent process mode: In this mode, BPEL process instances can have their
lifetimes persist across container lifetime. All state information is stored in the server
database. The persistent processes are supported by either the embedded Hypersonic
database, or an external database (either MySQL or Oracle).
To select this mode, select the configuration option Embedded Storage (Hypersonic
database) or Other Database (MySQL or Oracle) option for the persistence.
The default process mode for BPEL services is Embedded Storage (Hypersonic
database).
When using an external database, each BPEL service instance must be configured
with its own database. (Multiple databases can be created on the same server.) When
using the embedded database, the service manages a separate instance for each
service instance.
Important
Transient process mode: In this mode, processes that have not completed when the
service container is shut down are terminated at shutdown. No process information is
stored in the server database when a process terminates.
To select this mode, select the In Memory configuration option for the persistence.
A BPEL service must be configured with persistence to allow persistence for any of the
processes deployed in it. Deploying persistent processes into a service configured in
transient mode effectively disables persistence for the process. Service and process
persistence modes are summarized in the following table:
278
Service
Process
Persistent
Can be Persistent or Transient, as

configured for the process.
Transient
Always Transient, regardless of process

configuration.
The following procedure explains how to set the persistence for a BPEL service using the
SMC.
To set persistence for a BPEL service:
1.
In the Init Parameters area of the SMC, click ... next to the Persistence field. The
Persistence Editor dialog box opens:
Embedded Storage is the default persistence setting.

2.
Select the Data Source Type, either:
In Memory This option sets the persistence mode to transient. When you select
this option, the Persistence field in the Init Parameters section of the SMC will
display the value In Memory.
279
Embedded Storage This option sets the persistence mode to persistent, using
the embedded Hypersonic database. Optionally, you can specify a storage

directory for the persistent processes. If you do not specify a storage directory, the
default is the staging directory. The database is created as needed in the specified
storage directory when the service starts. If you move or delete the database, a
new database is created the next time the service starts. Existing databases in the
staging directory are deleted (on service restart) when you specify a new storage
location.
When you select Embedded Storage, the Persistence field in the Init Parameters
section of the SMC will display the value Embedded Storage.
(This is the default mode.)
Other Database This option sets the persistence mode to persistent, using a
database other than the embedded database. When this option is selected, you
must provide additional details required to connect to the database. Only Oracle
and MySQL database types are supported (see Step 3). When you select this
option, the Persistence field in the Init Parameters section of the SMC will
display a value for the selected database type:
Oracle:
type=oracle username=username host=localhost port=1521
MySQL:
type=mysql name=dbname username=username host=localhost
port=1521
When using an external database, each BPEL service instance must be

configured with its own database.
Important
3.
If you selected Other Database as the data source type, enter the following Database
Options:
Important
280
Database Type Select either Oracle or MySQL

Database Name Optional
Machine Name Optional
Database Port Optional
Username Optional
Password Optional
When using an Oracle or MySQL database, you must add the JDBC driver JAR file
to the container classpath (see Adding JAR files to an ESB Container on page 63
for instructions).

4.
Click OK to set the persistence mode and close the dialog box.
281
BPEL Development Container Configuration

The BPEL development container, dev_BPEL, is configured to terminate all process
instances at startup. This container uses embedded storage by default. All historical
information (terminated processes and audit trails) remains available in the database and
can be accessed through the SMC Management tab. You can safely delete the database
from the storage directory.
Enabling Audit Trails

An audit trail captures a history of the process instance as it executes. You can query and
view this history under the Manage tab in the SMC (see Viewing Audit Trails on
page 294).
Note Audit trails are only supported in persistent process mode by selecting either Embedded
Storage or Other Database for the persistence parameter (see Setting Persistence
Options on page 278).

As with persistence, you can configure audit trails for each process using its deployment
descriptor file (*.bpdd) (see the BPEL Deployment Descriptor editor section of the
Progress Sonic BPEL Server Developers Guide in the Sonic Workbench (Eclipse) help
for information). If audit trails are enabled for the service, then the per-process settings
for audit trail (if any) are used. If audit trails are disabled for the service, then the perprocess settings are ignored and audit trails are always disabled.
See Viewing Audit Trails on page 294 for information about the details you can view is
audit trails.
To enable audit trail recording:
282
In the Init Parameters area of the SMC, select True from the Enable Audit Trails pulldown list. (Selecting False disables audit trails.)

Audit trails are stored in the database with the process instance state (when using
persistent process mode). The following modes of operation are typical:
Persistent process mode with audit trails enabled This is the standard
configuration. All current and historical process state is saved.
Non-persistent process mode with audit trails not enabled No process state is
saved. Process instances do not survive a container restart and support only limited
management capabilities. This mode is useful for short-duration processes where
performance is more important than recoverability.
Persistent process mode with audit trails not enabled Only the current process state
is saved. This mode is useful to limit database growth, particularly with processes that
might generate very long histories. Note that without audit trails the management
capabilities are limited.
283
Setting a Default Partner Link

When a BPEL Service is invoked it uses WS-Addressing reference parameters to identify
the process and partner link associated with the invocation. If the message does not
specify this information then the default process and partner link are used.
The default partner link is optional. If no default is specified and the service cannot
determine the process and partner link from the invocation message, the service will
produce a fault.
The processes (and partner links) in the Edit Default Partner Link dialog box are obtained
from the BPEL archive, so you must specify the archive before you can edit the default
partner link.
You can set or edit the default partner link for a BPEL service when configuring the
service in the SMC.
To set or edit the default partner link:
1.
In the Init Parameters area of the SMC, click ... to the right of the Default Partner Link
field. The Default Partner Link dialog box opens, as shown in this example:
If the BPEL service does not have any partner link configured, then the dialog box
displays the value None.
284
2.
Select the Process and Partner Link for the BPEL service from the pull-down lists of
processes and partner links.
3.
To remove a partner link, click Clear.
Considerations with Dehydrated Processes
Considerations with Dehydrated Processes

With dehydration, Sonic BPEL Server stores the process and its state in the database while
waiting for a response, thus freeing up server resources. Hydration occurs when the
engine receives the response and restores the process and its state from the database and
continues executing the process.
Process instances cannot be dehydrated unless the following conditions are met:
You are not in development mode (TEST_CONTAINER_MODE is not set, or set to FALSE).
(See Setting Test Mode for ESB Containers Used in Development on page 62.)
You are using a Persistent store (that is, not In Memory). (See Setting Persistence
Options on page 278.)
All activities must be in a waiting state (that is, no alerts are set).
There are no synchronous inbound connections.
285
286
Chapter 13
Managing BPEL Services
This chapter describes how to manage BPEL services. This chapter contains the following
sections:
Overview of BPEL Service and Process Management
Clearing Process History
Terminating Processes
Searching for Process Instances
Viewing Audit Trails
BPEL Profiling
287
Overview of BPEL Service and Process Management

Under the Manage tab in the Sonic Management Console (SMC), you can view BPEL
services in ESB containers and perform management operations. You can also view and
manage all BPEL processes for each BPEL service.
To view and manage BPEL services and processes in the SMC:
In the left pane of the SMC under the Manage tab, select a BPEL service and view the
associated processes in the right pane. In this example, selecting the sample BPEL
service LoanApproval in the left pane displays the processes loanAssessor,
pubSubApproval, and loanApproval in the right pane:
Management operations can be performed on all the processes in a BPEL service when
executed on the right pane, or on a specific process when executed in the left pane. For
example, right-clicking a service in the left pane and selecting Terminate All terminates
all instances of all processes for that service. Right-clicking a process in the right pane
and selecting Terminate All terminates only instances of the selected process.
288
The SMC provides the following management capabilities for BPEL services and
processes:
Clear history for a process or for all processes in a service (see Clearing Process
History on page 289).
Terminate a process or all processes in a service (see Terminating Processes on

page 290).
Search for a set of process instances that match your specified criteria (see Searching
for Process Instances on page 290).
View audit trails for a selected process instance (see Viewing Audit Trails on
page 294).
View aggregate information for all the process instances created by a selected process
(see BPEL Profiling on page 296).

You can clear the history for a single process (for all its expired instances) or for all
processes in a service. Clearing the history removes audit trails and terminated process
instances.
To clear process history:
1.
To clear the process history for all processes in a service, right-click on a BPEL
service (in the left pane) and select Clear History. The Clear History dialog box opens:
Select whether to remove only processes that ended on or before a cutoff date (you
must specify the date), or to remove all processes.
289

2.
To clear the process history for a selected process, right-click on a BPEL process (in
the right pane) and select Clear History. The Clear History dialog box opens:
Select whether to remove only instances of the selected process that ended on or
before a cutoff date (you must specify the date), or to remove all instances of the
selected process.
Terminating Processes
You can terminate a single process or all processes in a service.
To terminate processes:
1.
To terminate all processes in a service, right-click on a BPEL service (in the left
pane) and select Terminate All. This action terminates all live instances of all the
processes listed for the BPEL service.
2.
To terminate a selected process, right-click on a BPEL process (in the right pane) and
select Terminate All. This action terminates all live instances of the selected process.

You can use Process Instance Search tool to find instances of a process that match a set
of criteria. You can specify the following search criteria:
Process instance state (live, terminated, or either)
Start or termination time
Received or sent message parts
XPath expressions, which include access to process variables

Note If you search for all instances of a process, you cannot also select a start or termination
time.
290
The following procedure explains how to search for BPEL process instances using the
Process Instance Search tool in the SMC.
To search for BPEL process instances:
1.
In the Manage tab of the SMC, select a BPEL service in the left pane, then select a
BPEL process in the right pane. In the lower right pane, click Search. The Process
Instance Search window opens, as shown in this example using the sample BPEL
process, pubSubApproval:
2.
In the Search Criteria section specify a Search Filter:
All Instances
Live Instances
Terminated Instances
Note
If you select All Instances of a process, you cannot also select a start or termination
time.
291

3.
4.
Optionally, in the Date section, enter a date and time in either or both the Started After
and Terminated Before fields.
When the Date is specified, a search returns processes as follows for different Search
Filter selections:
Search Filter
Processes Returned by Search
All Instances
The Started After and Terminated Before fields are disabled when
All Instances is selected.
Live Instances
Returns processes that started between the times specified in the

fields Started After and Terminated Before.
Terminated Only
Returns processes that terminated between the times specified in

the fields Started After and Terminated Before.
Optionally, in the Messages section, click Add to specify the following search criteria
in the table:
Destination Select Any, Inbound, or Outbound (Required)
If you specify an asterisk (*) as the value for any of the criteria, that value is ignored.
Note
5.
Note
292
Message Namespace
Message Local Name
Part
Search Value
Optionally, in the Boolean XPath Expressions section, click Add to specify the
comparison of a BPEL variable. The following expressions allow access to variables
and their properties:
Variable
Description
$variableName
The value of the variable.
bpws:getVariableProperty(name,property)
The value of the property with respect

to the variable identified.
The properties must be specified as namespace qualified identities. The

namespace prefixes available are those defined in the BPEL process (see the
Progress Sonic BPEL Server Developers Guide in the Sonic Workbench
(Eclipse) help for information about defining namespaces in a BPEL process).
Specifying an XPath expression enables you to select process instances based on

variable values and conditions applied to them. The conditions are expressed as XPath
2.0 expressions.
6.
Click Search. The search results are displayed in the Process Instance Search
Results section, as shown in this example:
The search results are a list of process instances satisfying your search criteria with
the following column values:
Process ID The unique ID of the process instance
Terminated The date, if terminated, or live.
Correlation (if correlation set(s) are defined for the process) Zero or more
columns. Each correlation set is potentially an array of properties. The column
name is the correlation set name and the value is a comma separated list of
property values. For example:
Property1=value,Property2=value
The correlation column is dynamic, and is only shown when a process has
correlation values.
Note
7.
To terminate a process instance, select the instance in the Process Instance Results
section and click Terminate.
8.
To view the audit trail of a process instance, select the instance in the Process
Instance Results section and click Audit Trail. (See Viewing Audit Trails on
page 294.)
9.
Close the Process Instance Search window to return to the SMC.
293

When a BPEL service configuration has the Enable Audit Trails option set to True (see
Audit Trails and Persistence on page 283) and the Persistence option set to something
other than In Memory (see Setting Persistence Options on page 278), you can view
activities and event details of a BPEL process instance.
To view audit trails and event details:
1.
294
In the Search Process Instance window, select a process instance and click Audit
Trail (see Searching for Process Instances on page 290). The Audit Trail dialog box
opens and displays the audit trail for the selected process instance, as shown in this
example using the sample BPEL process, loanApproval:
The Audit Events pane displays the following information:
Activity Type
Activity XML:ID The value of the ID attribute in the processs XML document
Activity ID A unique number for the specific instance of the activity. When
multiple audit events are logged for the same activity, this number can be used to
correlate all related events. (For example, see Activity ID 27 in the preceding
example.)
Time The time, including date, at which the activity was recorded.
Many activities generate multiple audit trail events. For instance, many activities
generate a START event and a COMPLETE event, as in the preceding example.
Note
2.
Select an activity in the left pane. If the activity has additional details, the details of
the selected activity are displayed in the Events Details pane, as shown in this
example:
Event details include the following information, depending on the selected activity:
Messages received by a RECEIVE activity
Messages sent by an INVOKE activity
Variable manipulation performed by an ASSIGN activity
Fault information
295
BPEL Profiling
You can view the activities of a BPEL process in the BPEL Profile dialog box under the
Manage tab in the SMC. This information represents aggregate performance information
of all process instances recorded for a particular process in the service. Clearing the
history (see Clearing Process History on page 289) resets the profiling information.
To view detailed activities of a BPEL process:
In the Manage tab of the SMC, select a BPEL process then click BPEL Profile. The
BPEL Profile dialog box opens, as shown in this example:
The BPEL Profile dialog box lists the activities for a process by ID, and contains the
following information:
Activity XML:ID
Activity Description, including the name attribute specified in the BPEL process,
if any
296
Times Completed: Minimum, average, and maximum [ms]
Individual time: Minimum, average, and maximum [ms]
Total time: Minimum, average, and maximum [ms]
Index
A
action flows
tuning 133
Activation Daemon 78, 173
retry rules 81
add directory command 35
add file command 35
add license container command 39
address factory 50
address space size 136
addresses 85
alternate servers 172
DB2 186
Informix 202
Microsoft SQL Server 228
Oracle 213
Progress OpenEdge 176, 181
Sybase 243
application performance
transformation 148
XML document update 133
applyMap command 44
arguments
backup utility 156
restore utility 159
B
backing up document collections 152
backup image files 155
backup record files 155

backup utility 156
backups
full 152, 157
incremental 152, 158
scheduling 152
Blob and binary stream data (DB2) 196
boot files 51
BPAR 277
BPEL
archive file 277
audit trail 282, 294
partner link 284
process instance search 290
profiling 296
BPEL services
configuring 273
broker
Actional instrumentation 54
payload in Actional instrumentation 54
C
cache
size 138
cache resources 136
certificate-based authentication 108
cipher suites 108
clearing management container logs 67
client load balancing 168
code page
297
Index
converting character data

DB2 188
Informix 202
Sybase 244
overriding
DB2 188
Informix 202
commands, ESB Admin Tool 33
commit transaction if idle 135
concurrency control and performance 130
concurrent durable subscriptions 91, 97
configuring
BPEL services 273
connections 103
SonicMQ endpoints 95
connect command 34
connecting to domain manager 20
connection
configuring 103
connection URLs 105
deleting 109
ESB 54
for endpoints 96
HTTP(S) 54
JMS 54
maximum at least once sessions 106
maximum best effort sessions 106
maximum exactly once sessions 106
maximum receive sessions 106
maximum Web Service sessions 106
name 105
name of domain 22
ping interval 107
type 105
connection failover 169
alternate servers
DB2 186
Informix 202
Oracle 213
Sybase 243
connection retry 170
DB2 189
Informix 203
298

Oracle 215
Sybase 245
DB2 190
Informix 204
Oracle 216
Sybase 246
DatabaseName
connection URLs
connections 105
domain 22
container list command 39
createMap command 44
D
data stores
backing up 152
restoring from backup 158
date format (Informix) 205
DB2
code page
character data, converting 188
connection properties
CodePageOverride 188
ConnectionRetryCount 189
ConnectionRetryDelay 190
DiagnosticFilename 191
InsensitiveResultSetBufferSize 192
LoadBalancing 193
MaxPooledStatements 194
ConnectionRetry 189
DBClob data type mapping 200
load balancing 193
scalar functions 260
state information log 191
DBDate (Informix) 205
debug tracing 75
debugging 123
Index
delete command 36, 38

delete directory command 36
delete file command 34
deleting
SonicMQ connections 109
SonicMQ endpoints 99
stored data, performance 144
destination name for endpoints 97
DiagnosticFilename
DB2 191
Informix 206
Oracle 216
Sybase 246
disconnect command 34
document collections
archiving 144
backing up 152
indexes 140
tuning disk storage 143
domain manager
connecting to 20
starting 20
domains
connection name 22
connection URL(s) of management broker 22
name 22
DRA, using 93
dump command 38
durable subscription, concurrent 97
E
enable Actional instrumentation
broker 54
endpoints
configuring 95
connections 96
deleting 99
durable subscription 97
entry 86
exit 86
fault 86
JMS destination name 97
JMS destination type 96
load balancing 98
message prefetch count 98
message prefetch threshold 98
name 96
priority 97
Qualify of Service 96
RME 87
shared subscriptions 98
time to live 98
WSDL URL 96
entry endpoints 86
envelope factory 50
ESB (JMS) connection 54
ESB Admin 33
ESB Admin Tool
commands 33
ESB Configured Objects 26
ESB Container
listeners 61
exit endpoint 86
export archive command 44
export bootfile command 44
export command 38
export directory command 36
export file command 36
export license container command 39
F
factory
address 50
envelope 50
message 50
objects for container services 50
failover 169
fault endpoint 86
fault tolerant client connections 99
files
backup image 155
backup record 155
log 155
transaction log 145
full backup 152, 157
299
Index
HTTP routing connection 54

http_defaultConnection 96
JMS destination type 96

JMS destinations 89
jms_defaultConnection 96
I
import archive command 45
import command 38
import file system command 45
incremental backup 152, 158
indexes
document collections 140
value 146
Informix
code page
DBDate 205
InformixServer 206
LoadBalancing 207
ConnectionRetry 203
date format 205
load balancing 207
DB2 192
Informix 206
Oracle 217
Progress OpenEdge 178
Sybase 247
instrumentation payload, broker 54
instrumentation, broker 54
invalid archive address notification 121
300
L
launching management containers 66
list command 37
listener threads, tuning 135
listeners 58
listeners, number 61
load balancing 168
DB2 193
Informix 207
Oracle 218
Sybase 248
load balancing, endpoints 98
LoadBalancing
log files 155
logging 75, 123
M
management broker
connection URL(s) 22
management container logs
clearing 67
saving 67
viewing 67
management containers
launching 66
operations 66
reload command 40
resetting metrics 66
restarting 66
resume command 40
shutdown command 39
shutting down 66
status command 40
suspend command 40
maximum
Index
at least once sessions 106

best effort sessions 106
exactly once sessions 106
receive sessions 106
Web Service sesions 106
MaxPooledStatements
DB2 194
Informix 208
Oracle 219
Sybase 249
message
factory 50
prefetch threshold 98
message prefetch count 98
message routing tuning 141
metrics 118
code page
LoadBalancing 233
ConnectionRetry 230
load balancing 233
N
names
connections 105
domain 22
endpoints 96
nonindexed XPath traversal 147
notifications 71, 121
O
operations
management containers 66
Oracle
LoadBalancing 218
ConnectionRetry 215
load balancing 218
outer joins 265
P
Password
payload, Actional instrumentation
broker 54
performance
action flows 133
address space management 136
archiving 144
cache affinity 138
cache resources 136
cache size management 138
commit transaction if idle 135
concurrency control 130
deleting stored data 144
indexes 140
listener threads 135
message routing tuning 141
reducing transaction deadlock 130
return set 147
transaction level 133
transaction management 130
transaction open interval 134
transformation 148
tuning disk storage 143
301
Index
tuning storage maintenance 144

value indexes 146
XML document update 133
XML Service 133
XPath processing 146
XPath, nonindexed traversal 147
XSLT node selection 148
XSLT output generation 149
XSLT template matching 149
ping interval, connection property 103, 107
PortNumber
primary servers 172
priority
endpoints 97
Progress OpenEdge 178, 179, 180, 181
alternate servers 176, 181
ConnectionRetryCount 177, 181
ConnectionRetryDelay 177, 181
DatabaseName 178, 181
Hostname 178
LoadBalancing 179, 181
Password 179
PortNumber 180, 181
SpyAttributes 180
User 180
ConnectionRetry 177, 181
DatabaseName 178, 181
LoadBalancing 179, 181
Password 179
PortNumber 180, 181
SpyAttributes 180
User 180
Q
Quality of Service, endpoints 96
queues
creating 97
302
R
reconnection 101
rejected message endpoint 87
reload command 40
resetting
management container metrics 66
resources 23
restarting
management containers 66
restoring document collections
from full backup images 160
from incremental backup images 161
resume command 40
return set 147
S
saving management container logs 67
scalar functions
DB2 260
Informix 261
Oracle 262
Sybase 264
shared subscriptions 91
endpoints 98
shutdown container 39
shutting down management containers 66
Sonic Management Console 21
SonicFS 23
Spy (DataDirect) 180
SpyAttributes
SSL
CA certificates location 108
certificate chain file 108
certificate chain form 108
cipher suites 108
private key file 108
private key password 108
provider class 108
starting
domain manager 20
Index
state information log

DB2 191
Informix 206
Oracle 216
Sybase 246
support, technical 15
suspend command 40
Sybase
code page
LoadBalancing 248
ConnectionRetry 245
load balancing 248
T
technical support 15
threads, listener 61
time to live
endpoints 98
transaction level property 133
transaction log 145
transaction open interval 134
transactions
management and performance 130
transformation performance 148
tuning storage maintenance 144
type, connections 105
U
User
V
value indexes 146
viewing management container logs 67
W
Web Service sessions
maximum 106
WSDL URL
endpoints 96
X
XML document update performance 133
XML Service
address space size 136
cache size 138
tuning 133
XPath
nonindexed traversal 147
processing performance 146
XSLT
node selection 148
output generation 149
template matching 149
303
Index
304

Progress SonicESB - Configuration and Management Guide

Cargado por

Información del documento

Derechos de autor

Formatos disponibles

Compartir este documento

Compartir o incrustar documentos

Opciones para compartir

¿Le pareció útil este documento?

¿Este contenido es inapropiado?

Copyright:

Formatos disponibles

Progress SonicESB - Configuration and Management Guide

Cargado por

Copyright:

Formatos disponibles

Configuration and Management Guide

Part I: ESB Configuration Tools and Managed Components

Chapter 2: ESB Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49

Chapter 3: ESB Endpoints and Connections. . . . . . . . . . . . . . . . . . . . . . . . . . .83

Configuring Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Chapter 4: Configuring Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Configuring XML Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Chapter 5: Monitoring and Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 6: Performance Tuning XML Servers . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 7: Backing Up and Restoring Document Collections . . . . . .151

Configuring Database Services . . . . . . . . . . . . . . . . . . . . .163

Chapter 8: Using the Database Service JDBC Drivers . . . . . . . . . . . . . . .165

Specifying Alternate Servers for the Informix Driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 10: SQL Escape Sequences for JDBC

Chapter 11: Configuring SQL Server Windows Authentication . . . .

Configuring and Managing BPEL Services . . . . . .271

Chapter 12: Configuring BPEL Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273

Chapter 13: Managing BPEL Services

This Preface contains the following sections:

Typographical Conventions describes the text formatting, syntax notation, and

Worldwide Technical Support provides information on how to contact Progress

About This Guide

Chapter 1, Using Progress Sonic ESB Configuration and Management Tools

Chapter 2, ESB Containers describes ESB Containers and Activation

Chapter 3, ESB Endpoints and Connections describes how to use ESB

Chapter 4, Configuring Web Services describes using Web Service standards in

Part II, Configuring XML Servers, includes the chapters:

Chapter 5, Monitoring and Logging, describes Progress Sonic XML Server

Chapter 6, Performance Tuning XML Servers, includes suggestions to

Chapter 7, Backing Up and Restoring Document Collections, describes how to

Part III, Configuring Database Services, includes the chapters:

Chapter 8, Using the Database Service JDBC Drivers, explains how to

Chapter 9, Driver Connection Properties and Data Types by Database Brand,

Chapter 11, Configuring SQL Server Windows Authentication, describes how

Chapter 12, Configuring BPEL Services, explains how to configure configure

Chapter 13, Managing BPEL Services, describes how to manage BPEL

Code examples and code that the user must enter

System output such as responses and error messages

Filenames, pathnames, and software component names, such as method names

Monospace typeface in italics or Bold monospace typeface in italics (depending

Brackets ([ ]) in syntax statements indicate parameters that are optional.

especially important for understanding the concept or procedure being discussed.

for the procedure or task (or other) to be successfully completed.

Progress Sonic ESB Product Family Documentation

Progress Sonic ESB Product Family: Configuration and Management Guide

Progress Sonic ESB Product Family: Deployment Guide Provides information

Worldwide Technical Support

Worldwide Technical Support

You can alternatively access version information programmatically for installed

ESB Configuration Tools

Part I contains the following chapters:

Chapter 1, Using Progress Sonic ESB Configuration and Management Tools

Chapter 2, ESB Containers

Chapter 3, ESB Endpoints and Connections

Chapter 4, Configuring Web Services

Using Progress Sonic ESB Configuration

Chapter 1: Using Progress Sonic ESB Configuration and Management Tools

Sonic management containers, and brokers administered by one central management

A management container that provides caching facilities, communicates with its

A broker dedicated to management communications for the domain managers two

A Directory Service that provides a centralized point for configuration information,

On UNIX or Linux, set a console window to the Progress SonicMQ installation

Sonic Management Console

Sonic Management Console