Progress Sonic 8.0 ESB Configuration and Management Guide

PROGRESS® 

SONIC® 

Sonic ESB 

Configuration and Management Guide

Progress® Sonic® ESB Configuration and Management Guide 8.0 

© 2010 Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved. 

These materials and all Progress® software products are copyrighted and all rights are reserved by Progress Software 

Corporation. The information in these materials is subject to change without notice, and Progress Software Corporation 

assumes no responsibility for any errors that may appear therein. The references in these materials to specific platforms 

supported are subject to change. 

Actional, Apama, Apama (and Design), Artix, Business Empowerment, DataDirect (and design), DataDirect Connect, 

DataDirect Connect64, DataDirect Technologies, DataDirect XML Converters, DataDirect XQuery, DataXtend, Dynamic 

Routing Architecture, EdgeXtend, Empowerment Center, Fathom, FUSE Mediation Router, FUSE Message Broker, FUSE 

Services Framework, IntelliStream, IONA, IONA (and design), Making Software Work Together, Mindreef, ObjectStore, 

OpenEdge, Orbix, PeerDirect, POSSENET, Powered by Progress, PowerTier, Progress, Progress DataXtend, Progress 

Dynamics, Progress Business Empowerment, Progress Empowerment Center, Progress Empowerment Program, Progress 

OpenEdge, Progress Profiles, Progress Results, Progress Software Developers Network, Progress Sonic, ProVision, PS 

Select, SequeLink, Shadow, SOAPscope, SOAPStation, Sonic, Sonic ESB, SonicMQ, Sonic Orchestration Server, 

SonicSynergy, SpeedScript, Stylus Studio, Technical Empowerment, WebSpeed, Xcalia (and design), and Your Software, 

Our Technology-Experience the Connection are registered trademarks of Progress Software Corporation or one of its 

affiliates or subsidiaries in the U.S. and/or other countries. AccelEvent, Apama Dashboard Studio, Apama Event Manager, 

Apama Event Modeler, Apama Event Store, Apama Risk Firewall, AppsAlive, AppServer, ASPen, ASP-in-a-Box, 

BusinessEdge, Business Making Progress, Cache-Forward, DataDirect Spy, DataDirect SupportLink, FUSE, Future Proof, 

GVAC, High Performance Integration, ObjectStore Inspector, ObjectStore Performance Expert, OpenAccess, Orbacus, 

Pantero, POSSE, ProDataSet, Progress ESP Event Manager, Progress ESP Event Modeler, Progress Event Engine, 

Progress RFID, Progress Software Business Making Progress, PSE Pro, Savvion, SectorAlliance, SeeThinkAct, Shadow 

z/Services, Shadow z/Direct, Shadow z/Events, Shadow z/Presentation, Shadow Studio, SmartBrowser, SmartComponent, 

SmartDataBrowser, SmartDataObjects, SmartDataView, SmartDialog, SmartFolder, SmartFrame, SmartObjects, 

SmartPanel, SmartQuery, SmartViewer, SmartWindow, 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 and/or its subsidiaries or affiliates in the U.S. and other countries. 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 

contained herein are the property of their respective owners. 

Third Party Acknowledgements: 

Progress SonicMQ and Progress Sonic ESB Product Families v8.0 incorporate Xalan-J v2.4.1 from the Apache 

Foundation. Such technology is subject to the following terms and conditions: The Apache Software License, Version 1.1 

- Copyright (c) 1999-2003 The Apache Software Foundation. All rights reserved. Redistribution and use in source and 

binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions 

of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions 

in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the 

documentation and/or other materials provided with the distribution. 3. The end-user documentation included with the

edistribution, if any, must include the following acknowledgment: "This product includes software developed by the 

Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software 

itself, if and wherever such third-party acknowledgments normally appear. 4. The names "Xalan" and "Apache Software 

Foundation" must not be used to endorse or promote products derived from this software without prior written permission. 

For written permission, please contact apache@apache.org. 5. Products derived from this software may not be called 

"Apache", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation. 

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, 

BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 

PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION 

OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, 

OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 

GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 

CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 

(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 

EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. This software consists of voluntary contributions 

made by many individuals on behalf of the Apache Software Foundation and was originally based on software copyright 

© 1999, Lotus Development Corporation., http://www.lotus.com. For more information on the Apache Software 

Foundation, please see http://www.apache.org/. 

Progress SonicMQ and Progress Sonic ESB Product Families v8.0 incorporate DSTC Xs3P version 1.1 from DSTC Pty 

Ltd. PSC will, at Licensee's request, provide copies of the source code for this third party technology, including 

modifications, if any, made by PSC. PSC may charge reasonable shipping and handling charges for such distribution. 

Licensee may also obtain the source code through http://communities.progress.com/pcom/docs/DOC-16051 by following 

the instructions set forth therein. - DSTC Public License. The contents of this file are subject to the DSTC Public License 

Version 1.1 (the 'License') (provided herein); you may not use this file except in compliance with the License. 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 xs3p. The Initial Developer of the Original Code is DSTC. Portions created by DSTC are Copyright © 2001, 2002 DSTC 

Pty Ltd. All Rights Reserved. 

Progress SonicMQ and Progress Sonic ESB Product Families v8.0 incorporate version 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/). PSC will, at Licensee's request, provide copies of the source code for this third 

party technology, including modifications, if any, made by PSC. PSC may charge reasonable shipping and handling 

charges for such distribution. Licensee may also obtain the source code through 

http://communities.progress.com/pcom/docs/DOC-16051 by following the instructions set forth therein. - Mozilla Public 

License Version 1.0 (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/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. 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. 

Progress SonicMQ and Progress Sonic ESB Product Families v8.0 incorporate Model Object Framework v2. Such 

technology is subject to the following terms and conditions: The ModelObjects Group Software License, Version 1.0 - 

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following 

conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the 

following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions 

and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. The end-user 

documentation included with the redistribution, if any, must include the following acknowledgement: "This product 

includes software developed by the ModelObjects Group (http://www.modelobjects.com)." Alternatively, this 

acknowledgement may appear in the software itself, if and wherever such third-party acknowledgements normally appear. 

4. The name "ModelObjects" must not be used to endorse or promote products derived from this software without prior 

written permission. For written permission, please contact jacobs@modelobjects.com. 5. Products derived from this 

software may not be called "ModelObjects", nor may ModelObjects" appear in thier name, without prior written permission 

of the ModelObjects Group. THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED 

WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY 

AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE MODEL 

OBJECTS GROUP OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 

SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 

PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 

INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 

STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF 

THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 

Progress SonicMQ and Progress Sonic ESB Product Families v8.0 incorporate OpenSAML Java Distribution v1.0.1. Such 

technology is subject to the following terms and conditions: The OpenSAML License, Version 1. Copyright (c) 2002 - 

University Corporation for Advanced Internet Development, Inc. All rights reserved. Redistribution and use in source and 

binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions 

of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions 

in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the 

documentation and/or other materials provided with the distribution, if any, must include the following acknowledgment: 

"This product includes software developed by the University Corporation for Advanced Internet Development 

Internet2 Project. Alternately, this acknowledegement may appear in the software itself, if and 

wherever such third-party acknowledgments normally appear. 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 without specific prior written permission. For written

permission, please contact opensaml@opensaml.org. 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. THIS 

SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND WITH ALL 

FAULTS. ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 

WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON- 

INFRINGEMENT ARE DISCLAIMED AND THE ENTIRE RISK OF SATISFACTORY QUALITY, 

PERFORMANCE, ACCURACY, AND EFFORT IS WITH LICENSEE. IN NO EVENT SHALL THE COPYRIGHT 

OWNER, CONTRIBUTORS OR THE UNIVERSITY CORPORATION FOR ADVANCED INTERNET 

DEVELOPMENT, INC. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 

CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 

GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 

CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 

(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 

EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 

Progress SonicMQ and Progress Sonic ESB Product Families v8.0 incorporate Colt cern.colt* packages v1.0.3 (ca1420- 

20040626). Such technology is subject to the following terms and conditions: Packages cern.colt* , cern.jet*, cern.clhep 

- Copyright (c) 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. 

Progress SonicMQ and Progress Sonic ESB Product Families v8.0 incorporate Mozilla Rhino v1.5R3. The contents of this 

file 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 (C) 1998-1999 Netscape Communications 

Corporation. All Rights Reserved. PSC will, at Licensee's request, provide copies of the source code for this third party 

technology, including modifications, if any, made by PSC. PSC may charge reasonable shipping and handling charges for 

such distribution. Licensee may also obtain the source code through http://communities.progress.com/pcom/docs/DOC- 

16051 by following the instructions set forth therein. 

Progress SonicMQ and Progress Sonic ESB Product Families v8.0 incorporate NET Security Library v1.0. Such 

technologies are subject to the following terms and conditions: Copyright © 2002-2003, The KPD-Team All rights 

reserved. http://www.mentalis.org/ Redistribution and use in source and binary forms, with or without modification, are 

permitted provided that the following conditions are met: - Redistributions of source code must retain the above copyright 

notice, this list of conditions and the following disclaimer. - Neither the name of the KPD-Team, nor the names of its 

contributors may be used to endorse or promote products derived from this software without specific prior written 

permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"

AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 

WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN 

NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 

INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 

TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 

BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 

CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY 

WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 

Copyright © 2002-2003, The KPD-Team. 

Progress SonicMQ and Progress Sonic ESB Product Families v8.0 incorporate Another Tool for Language Recognition 

v2.7.4. Such technologies are subject to the following terms and conditions: ANTLR Software License 

http://www.antlr.org/rights.html We reserve no legal rights to the ANTLR--it is fully in the public domain. An individual 

or company may do whatever they wish with source code distributed with ANTLR or the code generated by ANTLR, 

including the incorporation of ANTLR, or its output, into commercial software. We encourage users to develop software 

with ANTLR. However, we do ask that credit is given to us for developing ANTLR. By "credit", we mean that if you use 

ANTLR or incorporate any source code into one of your programs (commercial product, research project, or otherwise) 

that you acknowledge this fact somewhere in the documentation, research report, etc... If you like ANTLR and have 

developed a nice tool with the output, please mention that you developed it using ANTLR. In addition, we ask that the 

headers remain intact in our source code. As long as these guidelines are kept, we expect to continue enhancing this system 

and expect to make other tools available as they are completed. 

March 2010

Contents 

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 

About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 

Typographical Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 

Progress Sonic Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 

Sonic ESB Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 

Worldwide Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 

Part I: ESB Configuration Tools and Managed Components 

19 

Chapter 1: Using Progress Sonic ESB Configuration and Management 

Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 

Sonic Management Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 

ESB Configured Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 

ESB Admin Tool and Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 

Basic Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 

SonicFS Maintenance Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 

ESB Type Maintenance Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 

License Container Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 

Management Container Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 

Deployment Tool Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 

Shutting Down Sonic Components and Sonic ESB Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 

Progress Sonic ESB Configuration and Management Guide 8.0 7

Contents 

Chapter 2: ESB Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51 

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52 

Creating ESB Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55 

ESB Container Intra-container Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58 

Viewing or Editing ESB Container Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59 

Managing the Services Associated with an ESB Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60 

Adding Services or ESB Process Entry Points to an ESB Container. . . . . . . . . . . . . . . . . . . . .61 

Deleting ESB ContainerServices from an ESB Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62 

Changing the Number of Listeners on Services in ESB Containers . . . . . . . . . . . . . . . . . . . . .63 

Deploying an ESB Container in a Management Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63 

Setting Test Mode for ESB Containers Used in Development. . . . . . . . . . . . . . . . . . . . . . . . . .64 

Adding JAR files to an ESB Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65 

Changing the State of Management and ESB Containers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67 

Monitoring Service Metrics and Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71 

Standard Metrics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71 

Standard Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73 

Enabling Integration with Actional for Visualization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74 

Logging and Tracing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76 

Using Activation Daemons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79 

Creating an Activation Daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80 

Adding an Activation Daemon to a Management Container . . . . . . . . . . . . . . . . . . . . . . . . . . .80 

Adding an ESB Container to an Activation Daemon’s Activation List . . . . . . . . . . . . . . . . . . .82 

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

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86 

ESB Addresses and References to Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87 

Entry Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88 

Exit Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88 

Fault Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88 

Rejected Message Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89 

Evaluating Endpoint Requirements on JMS Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91 

When to Use Topics, When to Use Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92 

Multiple Brokers, Clusters, and Nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95 

Configuring Progress SonicMQ Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97 

Deleting Progress SonicMQ Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101 

Fault Tolerant Connections and Reconnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101 

Inbound and Outbound Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102 

Fault Tolerant Connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102 

8 Progress Sonic ESB Configuration and Management Guide 8.0

Contents 

Quality of Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 

Setting the Ping Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 

Configuring Connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 

Deleting Progress SonicMQ Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 

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

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 

Configuring WebService Protocols for ESB Processes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 

Related Configuration Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 

Part II: Configuring Database Services. . . . . . . . . . . . . . . . . . . . . 117 

Chapter 5: Using the Database Service JDBC Drivers . . . . . . . . . . . . . . 119 

JDBC Driver Connection Properties and the Database Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 

Load Balancing, Failover, and Connection Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 

Client Load Balancing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 

Connection Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 

Connection Retry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 

Specifying Primary and Alternate Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 

Using Activation Daemons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 

Chapter 6: Driver Connection Properties and Data Types by Database 

Brand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 

Progress OpenEdge Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 

Progress OpenEdge Connection Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 

Progress OpenEdge Connection Failover Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 

Specifying Alternate Servers for the Progress OpenEdge Driver . . . . . . . . . . . . . . . . . . . . . . 136 

Progress OpenEdge Driver Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 

DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 

DB2 Driver Connection Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 

DB2 Driver Connection Failover Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 

Specifying Alternate Servers for the DB2 Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 

DB2 Driver Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 

Informix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 

Informix Driver Connection Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 

Informix Driver Connection Failover Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 

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

Informix Driver Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 


Contents 

Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166 

Oracle Driver Connection Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166 

Oracle Driver Connection Failover Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177 

Specifying Alternate Servers for the Oracle Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178 

Oracle Driver Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179 

Microsoft SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181 

Microsoft SQL Server Driver Connection Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181 

Microsoft SQL Server Driver Connection Failover Properties . . . . . . . . . . . . . . . . . . . . . . . .192 

Specifying Alternate Servers for the Microsoft SQL Server Driver . . . . . . . . . . . . . . . . . . . .192 

Microsoft SQL Server Driver Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194 

Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196 

Sybase Driver Connection Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196 

Sybase Driver Connection Failover Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206 

Specifying Alternate Servers for the Sybase Driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206 

Sybase Driver Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .208 

Chapter 7: SQL Escape Sequences for JDBC. . . . . . . . . . . . . . . . . . . . . . . . .211 

Date, Time, and Timestamp Escape Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .212 

Scalar Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .212 

Outer Join Escape Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219 

Procedure Call Escape Sequences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .220 

Chapter 8: Configuring SQL Server Windows Authentication . . . . . .221 

Setting the Authentication Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222 

Registering Service Principal Names (SPNs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222 

Setting the Active Directory Encryption Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .223 

Part III: Configuring and Managing BPEL Services . . . . . .225 

Chapter 9: Configuring BPEL Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .227 

Overview of BPEL Service Initialization Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228 

Specifying a BPEL Archive (.bpar) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231 

Setting Persistence Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232 

BPEL Development Container Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236 

Enabling Audit Trails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236 

Audit Trails and Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237 

Setting a Default Partner Link. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .238 

Considerations with Dehydrated Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .239 


Contents 

Chapter 10: Managing BPEL Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 

Overview of BPEL Service and Process Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 

Clearing Process History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 

Terminating Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 

Searching for Process Instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 

Viewing Audit Trails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 

BPEL Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 

Part IV: Integrating Sonic and Actional. . . . . . . . . . . . . . . . . . . . . . 251 

Chapter 11: Using Actional with Sonic Components. . . . . . . . . . . . . . . . 253 

Instrumenting Sonic ESB. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 

Enabling the ESB Interceptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 

Using Stabilizers with Sonic ESB. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258 

Using ESB-Specific Message Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 

Startup Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 

Trust Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 

Auditing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 

Instrumenting Sonic BPEL Sever . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 

Instrumenting SonicMQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 

Visualization When Both SonicMQ Broker and Sonic ESB are Instrumented. . . . . . . . . . . . . . . . . 265 

Specifying the Uplink Configuration Location in Sonic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 

Chapter 12: Using Actional Trust Zones in Sonic ESB. . . . . . . . . . . . . . 269 

Progress Actional Trust Zones. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270 

Implementing Trust Zones in Progress Sonic ESB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 

Enable Actional Instrumentation in Sonic ESB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 

Register a Web Service with Actional Intermediary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 

Define Trust Zones on Actional Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 


Contents 


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 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 

Software’s customer support and evaluation support for the Progress Sonic ESB 

Product Family. 


Preface 

About This Guide 

This guide is intended for system administrators. This book is in three 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 Database Services,” includes the chapters: 

■ Chapter 5, “Using the Database Service JDBC Drivers,” explains how to 

configure load balancing, failover, and connection retry for connections made 

using the drivers. 

■ Chapter 6, “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 7, “SQL Escape Sequences for JDBC,” describes the JDBC-defined 

escape sequences containing standard syntaxes for several language features. 

■ Chapter 8, “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 III, “Configuring and Managing BPEL Services,” includes the chapters: 

■ Chapter 9, “Configuring BPEL Services,” explains how to configure configure 

BPEL services. 

■ Chapter 10, “Managing BPEL Services,” describes how to manage BPEL 

services. 

● Part IV, “Integrating Sonic and Actional,” includes the chapters: 

■ Chapter 11, “Using Actional with Sonic Components,” shows how Sonic looks 

from rthe actional viewpoint.. 

■ Chapter 12, “Using Actional Trust Zones in Sonic ESB,” describes how to use it 

as an additional layer of security in SOA environments. 


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. 


Preface 

Progress Sonic Documentation 

Sonic installations always have a welcome page that provides links to Sonic 

documentation, release notes, communities, and support. See the release’s Product 

Update Bulletin book to see what’s new and what’s changed since prior releases. 

The Sonic documentation set includes the following books and API references. 

Sonic ESB Documentation 

Sonic ESB provides the following documentation: 

● Progress Sonic Installation and Upgrade Guide — Provides information about 

installing, updating, and upgrading Sonic ESB components. 

● Progress Sonic Workbench User 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 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, and 

Sonic BPEL Server 

● Progress Sonic ESB 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. 


Worldwide Technical Support 

Worldwide Technical Support 

Progress Software’s 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 Progress Sonic 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 Continuous Availability Edition [Serial Number: nnnnnnn] 

Release nnn Build Number nnn 

● The platform on which you are running Progress Sonic 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. 


Preface 


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” 



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 Deployment Guide in the Sonic Workbench’s Eclipse help. 

Important This book assumes that you have deployment installations of Progress Sonic 8.0 

products. While the Sonic Workbench has the same toolset, Sonic’s 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. 


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. 

What’s 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 manager’s 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 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 8.0 > Start Domain Manager 

❖ On UNIX or Linux, set a console window to the Progress Sonic installation’s 

Containers/Domain1.DomainManager directory, and then enter launchcontainer.sh. 


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 8.0 > 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 user’s password: 

Administrator. 



◆ 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. 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 > 8.0 > 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/8.0/lib/openedge.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. 



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 manager’s container makes it 

easy to recognize. It is highlighted in green, indicating that it is running and all its 

hosted components are online. 

● 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 container’s setup is offline. See 

“Verifying an ESB Container Installation” in the Progress Sonic Installation and 

Upgrade Guide for more information about using this container. 



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. 



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 objects—using a default icon—as shown: 

You should not attempt to manipulate these objects under these circumstances. 

In the reverse case—the Sonic ESB tools are installed for this SMC, but the connected 

domain is not Sonic ESB enabled—the ESB Configured Objects section is not shown. 

See the Progress Sonic Installation and Upgrade Guide for information about tools 

installations and the option to specify a domain to be enabled for the tools. 


◆ 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. 



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. Click on a name in the right panel to display its information and modifiable 

parameters. 

See “Overview” on page 52 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 97 for more information 

about endpoints. 

8. In the left panel, click on a service in the Services folder. The services of the selected 

Service type are listed in the right panel. 



9. Click on a service in the right panel to display its information and modifiable 

parameters, as shown: 

Note that each service type shows its own unique set of classloading configurations 

and 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 Developer’s Guide 

in the Eclipse help. 



10. Click on Processes, as shown: 

The processes are listed in the right panel. In the right panel, choosing a process 

displays its information, modifiable parameters, and tracking. 

For more information, see the Progress Sonic ESB Product Family Developer’s Guide 

in the Eclipse help. 


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 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 8.0 > 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. 



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: 

● Domain 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: 

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. 


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 



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. 


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 

variable—list, 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 



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/MQ8.0/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. 


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, 8.0. 

export license container 

export license container [version] 

Display the license container to the console. Use the version parameter to export an earlier 

version’s license. Specify the version in the format, Major.Minor, for example, 8.0. 

ESBAdmin> export license container 8.0 

Displaying license key (control number) for version 8.0 ... 

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 



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 commands—diff, mqdepends, mqrevdepends, and impact—contrast 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 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. 


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 Tool’s 

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. 



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 files—XAR 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 



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 



Exporting for Deployment 

The deployment export commands create bootfiles and exported artifacts for deployment 

to other domains. The Progress Sonic ESB 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 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. 


Importing or Merging for Deployment 


The import and merge commands transfer the source data into the connected domain. 

The Progress Sonic ESB 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 Service’s 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. 



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 Container’s 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 


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. 




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 

Family’s 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: 

Developer’s Guide in Sonic Workbench online help. 


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 container’s 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 container’s 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. 


When an ESB Container starts up, it follows this sequence: 

Overview 

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. 



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 manager’s 

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. 


Creating ESB Containers 


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: 



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


Name The name of the ESB container. 

Intra-container 

Messaging 

ESB (JMS) 

Connection 

HTTP Routing 

Connection 

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). 

For more information, see the Progress Sonic ESB Product Family Developer’s Guide in the 

Eclipse help. 

4. In the Actional Integration section, specify the following properties: 


Enable Actional 

Instrumentation 

Enable Payload 

Capture 

Specify the ESB connection used to call web services deployed on the 

ESB (in contrast to those available at an external HTTP address.) 

Specify the HTTP routing connection to the SonicMQ broker that is used 

for web services with HTTP addresses. 

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. 

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. 


◆ To add services to an ESB Container: 



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 61 for detailed information. 

3. Click OK to close the Select Service or Process to Add to Container dialog box. 

Note 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. 

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.) 



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 105 for more information about QoS. 


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 21.) 

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 55. 



Managing the Services Associated with an ESB Container 

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: 


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. Select a service to display information for that service, for example, dev.CBR: 


Managing the Services Associated with an ESB Container 

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: 


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. 

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. 

3. 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. 



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. 

4. 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: 


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. 


Deploying an ESB Container in a Management Container 

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: 


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 

(Also see the SonicMQ Deployment Guide chapter 

“Fault Tolerant Application Containers.”) 

Note that there is no configuration for a fault tolerant 

ESB Container. 

“Generating Containers” 



Setting Test Mode for ESB Containers Used in Development 

To use a new ESB Container, the Sonic Workbench requires that you set the ESB 

Container’s property TEST_CONTAINER_MODE to true. 

◆ To set an ESB Container to Test Mode: 

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 Console’s 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. 



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. 


Changing the State of Management and ESB Containers 


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. 



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. 

3. You can select a management container, right click, and select Container Log to: 


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. 



4. 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 Container’s 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. 



5. To perform operations on an ESB Container, right click on it, then select Operations: 


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: 


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 Workbench User Guide in the Sonic Workbench online help. 


Monitoring Service Metrics and Notifications 


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 

received—that 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. 

● esb.service.messages.Faulted — Records the number of message envelopes that 

produced 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.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: 

1. Open the Sonic Management Console, and connect to the domain you are managing. 

2. Select the Configure tab to specify persistent settings, or select the Manage tab to 

specify temporary or overriding settings. 

3. Select a running ESB Container. 

4. Right-click on the ESB container and select Metrics.... The Monitoring dialog box 

opens with its Metrics tab: 

5. 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 setting metrics using instances, patterns, and groups, 

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 

◆ To monitor notifications: 

1. Open the Sonic Management Console and select the Manage tab. 

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. 

For general information on notifications and on watching notifications and viewing 

notification attributes, see the “Monitoring” chapter in the Progress SonicMQ 

Configuration and Management Guide. 

See also the Progress SonicMQ Administrative Programming Guide and the Progress 

Sonic Event Monitor User’s 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 


Enabling Integration with Actional for Visualization 

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). 


Enabling Integration with Actional for Visualization 

The Actional Agent can analyze Web service and JMS traffic on the Enterprise Service 

Bus. When you enable Actional’s 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: 

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 container’s 

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. 



Logging and Tracing 

You can turn debug tracing on and off for ESB Containers and specify logging categories 

to send messages to the container’s 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: 


Logging and Tracing 

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. 



◆ 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. 


Using Activation Daemons 


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 

Daemon’s 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 Daemon’s 

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: 

1. “Creating an Activation Daemon” on page 80 

2. “Adding an Activation Daemon to a Management Container” on page 80 

3. “Adding an ESB Container to an Activation Daemon’s Activation List” on page 82 



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 22 for instructions. 

3. In the Sonic Management Console’s 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 Daemon’s activation list (which will, in turn, start their hosted components. 

(See “Using Activation Daemons” in the Progress Sonic 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. 


◆ To add an activation daemon to a management container: 


1. In the Sonic Management Console’s 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 box’s General tab specify: 


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. Click OK to add the component to the container. 



Adding an ESB Container to an Activation Daemon’s Activation List 

The following procedure describes how to add a management container that hosts an ESB 

Container an Activation Daemon’s 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 Daemon’s activation list: 

1. In the Sonic Management Console’s 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: 


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: 



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 Daemon’s activation list by using the Sonic Management Console to open the 

management container’s 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 





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: 


● “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 

Developer’s Guide in the Eclipse help. 


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 service’s entry endpoint. 

Progress Sonic ESB endpoints include Java Messaging Service (JMS) destinations— 

queues and topics—that 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: 


ESB Addresses and References to Endpoints 

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 

service’s 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. 



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 58). 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. 


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 



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 XXXX 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( ) method, delivering Inbox or Outbox messages, is also 

sent to the RME. 

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. 


Evaluating Endpoint Requirements on JMS Destinations 


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 resources—these 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? 

■ 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 93. 

● 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 93. 

● Are the destinations queues or topics? 

■ 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 92. 

● 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 95. 

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. 



Table 1 maps the destination configurations to destination requirements. 

Table 1. Mapping Destination Requirements 

QoS 

AT_LEAST_ONCE 

or 

EXACTLY_ONCE 

Destination 

Type Multiple Services Single Service Instances 

Topic ● Concurrent durable subscription = 

true 

● Shared subscriptions = true 

● Number of listeners = any number 

● Durable subscription name must be 

non-null 

When to Use Topics, When to Use Queues 

● Concurrent durable subscription = 

false 

● Shared subscriptions = false 

● Number of listeners = 1 


non-null 

Queue ● No additional configuration required ● No additional configuration required 

BEST_EFFORT Topic ● Concurrent durable subscription = 

true 

● Shared subscriptions = true 

● Number of listeners = any number 


null 

● Concurrent durable subscription = 

false 

● Shared subscriptions = false 

● Number of listeners = 1 


null 

Queue ● No additional configuration required ● No additional configuration required 

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. 


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 


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. 



For detailed information on implementing durable subscriptions, see the “Publish and 

Subscribe Messaging” chapter in the Progress SonicMQ Application Programming 


The following example illustrates Sonic ESB’s 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. 


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. 

Sonic’s 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 55 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 broker’s 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 Developer’s 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 Container’s HTTP connection is used, as in 

outbound web service invocations. (For more information, see the Progress Sonic ESB 

Product Family Developer’s Guide in the Eclipse help.) 



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 

Multiple nodes with 

some nodes as 

clusters, some as 

brokers 

Use clustered queues Use normal or shared topics 

Use global, clustered queues 

Use node-qualified entry endpoint 

names, for example, Node::aQueue 

Use either: 

When choosing JMS destinations for queues, consider the following: 

● For clustered brokers, you should use clustered queues 

● Node-qualified entry endpoint names, 

for example, Node::aTopic (shared 

subscriptions are not allowed) 

● GSA and no overlapping topic names 

● 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. 


Configuring Progress SonicMQ Endpoints 


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: 



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: 


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. 

● 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. 

WSDL URL 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 

Select Queue or Topic. 




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 93 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 

Durable 

Subscription 

Name 

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. 

Name of the Progress SonicMQ durable subscription. 

See “Using Concurrent Durable Subscriptions to Topics” on page 93 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: 

● Inherited — The priority of messages sent from this endpoint is set to the value with 

which the message was received. New messages that are created and sent from this 

endpoint have a priority of 4. 

● 1 to 9 — All messages sent to this endpoint have a priority equal to that value. 




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. 

Message Prefetch 

Count 

Message Prefetch 

Threshold 

Shared 

Subscriptions 

● 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 105.) 

● 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. 

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. 

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. 

Allows automatic load balancing (the default is True, enabling shared subscriptions). 

For more information on shared subscriptions, see “Using Shared Subscriptions to Topics” 

on page 93 and the “Publish and Subscribe Messaging” chapter in the Progress SonicMQ 

Application Programming Guide. 

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: 

● 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. 

Send Timeout The time interval, in milliseconds, to attempt to send a message from this endpoint. The 

default value is 360000 — 6 minutes. If the timeout expires, a runtime or JMS exception 

could cause the message to get rejected. 

5. After you configure the properties, click Apply. The Sonic Management Console 

displays the new endpoint in the Endpoints tab. 


Fault Tolerant Connections and Reconnection 





Deleting Progress SonicMQ Endpoints 

The following procedure describes how to delete a Progress SonicMQ endpoint. 

◆ To delete a Progress SonicMQ endpoint: 


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 Sonic Management Console 

Property 

faultTolerant Enable Fault Tolerant Connection False 

Default Value 



Connection Parameter Sonic Management Console 

Property 

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 

Default Value 

initialConnectTimeout Initial Connect Timeout 30 seconds 

faultTolerantReconnectTimeout Fault Tolerant Reconnect Timeout 60 seconds 

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. 



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. 



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. 



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. 

Configuring Connections 

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. 



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: 


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. 


6. Set the maximum sessions for this connection: 


Maximum Receive 

Sessions Per 

Connection 

Maximum 

BEST_EFFORT 

Sessions 

Maximum 

AT_LEAST_ONCE 

Sessions 

Maximum 

EXACTLY_ONCE 

Sessions 

Maximum 

Web Service 

Sessions 


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. 

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. 


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. 


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. 

The number of pooled sessions that can be used for Web service 

invocations. Specify a positive integer value. The default value is 10. 

Important 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: 


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 106 for more information. 

Enable Fault 

Tolerant 

Connection 

Initial Connect 

Timeout 

Fault Tolerant 

Reconnect 

Timeout 

JMS 

Connection ID 

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 101 for more 

information. 

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 101 for more 

information. 

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 101 for more information. 

When a JMS Connection ID is entered ( a non-empty string), fault 

tolerant clients can reconnect to a broker before the broker’s 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 101 for more information. 



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: 


SSL CA Certificates 

Location 

SSL Certificate Chain 

File 

Specifies the location of the Certificate Authority (CA) certificate 

used to connect to the Progress SonicMQ broker. 

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 

SSL Certificate Chain 

Form 

Provides the password to encrypt the broker private key for SSL. 

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) 

● progress.message.net.ssl.jsse.JSSEImpl 

Note For information on the supported cipher suites, see “Implementing Security” in the Progress 

SonicMQ Deployment Guide. 



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: 


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. 


Chapter 4 Configuring Web Services 

This chapter describes how to configure Web Services using WS-* standards in the 

following sections: 


● “Configuring WebService Protocols for ESB Processes” 

● “Related Configuration Documentation” 


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: 


Related Configuration Documentation 

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. 

Related Configuration Documentation 

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 

HTTP Web Service 

Protocol Routing 

See the “Configuring Acceptors” chapter of the Progress SonicMQ 


See the “Configuring Routings” chapter of the Progress SonicMQ 


Broker See the “Configuring SonicMQ Brokers” chapter of the Progress 

SonicMQ Configuration and Management Guide. 


Chapter 4: Configuring Web Services 


Part II Configuring Database Services 

Part II contains the following chapters: 

● Chapter 5, “Using the Database Service JDBC Drivers” 

● Chapter 6, “Driver Connection Properties and Data Types by Database Brand” 

● Chapter 7, “SQL Escape Sequences for JDBC” 

● Chapter 8, “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 vendor’s 

documentation for their configuration guidelines. 



Chapter 5 Using the Database Service JDBC Drivers 

Chapter 5 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. 


Chapter 5: 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 122 

● “Connection Failover” on page 123 

● “Connection Retry” on page 124 



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 4. Documentation for JDBC Driver Connection Properties and Alternate Servers 

JDBC Driver Connection Properties Documentation 

Progress Open Edge ● “Progress OpenEdge Database” on page 130 

● “Progress OpenEdge Connection Failover Properties” on page 135 

● “Specifying Alternate Servers for the Progress OpenEdge Driver” on page 136 

● “Progress OpenEdge Driver Data Types” on page 138 

DB2 ● “DB2 Driver Connection Properties” on page 139 

● “DB2 Driver Connection Failover Properties” on page 152 

● “Specifying Alternate Servers for the DB2 Driver” on page 152 

● “DB2 Driver Data Types” on page 154 

Informix ● “Informix Driver Connection Properties” on page 155 

● “Informix Driver Connection Failover Properties” on page 163 

● “Specifying Alternate Servers for the Informix Driver” on page 163 

● “Informix Driver Data Types” on page 164 

Oracle ● “Oracle Driver Connection Properties” on page 166 

● “Oracle Driver Connection Failover Properties” on page 177 

● “Specifying Alternate Servers for the Oracle Driver” on page 178 

● “Oracle Driver Data Types” on page 179 

Microsoft SQL 

Server 

● “Microsoft SQL Server Driver Connection Properties” on page 181 

● “Microsoft SQL Server Driver Connection Failover Properties” on page 192 

● “Specifying Alternate Servers for the Microsoft SQL Server Driver” on page 192 

● “Microsoft SQL Server Driver Data Types” on page 194 

Sybase ● “Sybase Driver Connection Properties” on page 196 

● “Sybase Driver Connection Failover Properties” on page 206 

● “Specifying Alternate Servers for the Sybase Driver” on page 206 

● “Sybase Driver Data Types” on page 208 



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. 

Sonic Database Service 

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 126. 

122 Progress Sonic ESB Configuration and Management Guide 8.0 

3 

1 

2 

Database Server A 

(Primary) 

Database Server B 

(First Alternate) 

Database Server C 

(Second Alternate)

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. 

Sonic Database Service 

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). 

Progress Sonic ESB Configuration and Management Guide 8.0 123 

1 

2 

3 

Database Server A 

(Primary) 

Database Server B 

(First Alternate) 

Database Server C 

(Second Alternate)


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 135 

● “DB2 Driver Connection Failover Properties” on page 152 

● “Informix Driver Connection Failover Properties” on page 163 

● “Oracle Driver Connection Failover Properties” on page 177 

● “Microsoft SQL Server Driver Connection Failover Properties” on page 192 

● “Sybase Driver Connection Failover Properties” on page 206 

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 driver’s 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. 



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; 






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: 

● servername1 is the IP address or server name of the first alternate database server, 

servername2 is 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 4 on page 121 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. 



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 136 

● “Specifying Alternate Servers for the DB2 Driver” on page 152 

● “Specifying Alternate Servers for the Informix Driver” on page 163 

● “Specifying Alternate Servers for the Oracle Driver” on page 178 

● “Specifying Alternate Servers for the Microsoft SQL Server Driver” on page 192 

● “Specifying Alternate Servers for the Sybase Driver” on page 206 


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 Daemon’s 

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 Daemon’s activation list 

“Using Activation Daemons” on page 79 provides information about how to complete the 

steps to create and configure an Activation Daemon to start an ESB Container hosting a 

service. 




Chapter 6 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” 


Chapter 6: Driver Connection Properties and Data Types by Database Brand 

Progress OpenEdge Database 

The following sections describe settings for the Sonic Database Service’s 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 User’s Guide and 

Reference for more information. 

Progress OpenEdge Connection Properties 

Table 5 describes the JDBC connection properties supported by the Progress OpenEdge 

driver. The properties have the format: property=value 

Table 5. Connection Properties for the Progress OpenEdge Driver 


AlternateServers 

Default: No default 

Data type: String 

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: 

(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. 


Table 5. Connection Properties for the Progress OpenEdge Driver (continued) 


ConnectionRetryCount 

Default: 5 

Data type: int 

ConnectionRetryDelay 

Default: 1 



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. 

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 driver’s 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. 

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. 







If a connection is not successfully established on the driver’s 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. 





DatabaseName 



HostName 



InsensitiveResultSet 

BufferSize 

Default: 2048 


The name of the database to which you want to connect. 

The name of the Progress OpenEdge database server to which you want to 

connect. 

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 

{-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. 




LoadBalancing 

Default: false 

Data type: boolean 

MaxPooledStatements 

Default: 0 


Password 

REQUIRED 



{true | 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. 

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). 




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. 

The maximum number of pooled prepared statements for this connection. 

Setting MaxPooledStatements to an integer greater than zero (0) enables the 

Progress OpenEdge driver’s 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. 

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. 





PortNumber 

REQUIRED 

Default: Varies with 

operating system 


SpyAttributes 



User 

REQUIRED 



The TCP port of the primary database server that is listening for connections to 

the Progress OpenEdge database. 

This property is supported only for DataSource connections. 

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. 

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. 


Progress OpenEdge Connection Failover Properties 


Table 6 summarizes the connection properties that control how connection failover works 

with the Database Service Progress OpenEdge driver. See Table 5 for details about 

configuring each property. 

Table 6. Connection Failover Properties for the Progress Open Edge Driver 


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. 

ConnectionRetryCount 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. 

ConnectionRetryDelay 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 122 and “Connection Failover” on page 123 for 

overviews of these features. 



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. 


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: 

servername1 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. 

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) 



Progress OpenEdge Driver Data Types 

Table 7 lists the data types supported by the Progress OpenEdge driver and describes how 

they are mapped to JDBC data types. 

Table 7. Progress OpenEdge (OED) Data Types 

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 

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 8 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 8. DB2 Connection Properties 


AddToCreateTable 

OPTIONAL 

AlternateID 

OPTIONAL 

A string that is appended to the end of all CREATE statements. This property 

typically is used to add an in database clause. 


DB2 

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.


Table 8. DB2 Connection Properties (continued) 



OPTIONAL 

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: 

(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 126 for more 

information about specifying connection information for primary and 

alternate servers. 




BatchPerformanceWorkaround 

OPTIONAL 

CatalogIncludesSynonyms 

OPTIONAL 

CatalogSchema 

OPTIONAL 


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. 


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. 


DB2 

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.




CharsetFor65535 

OPTIONAL 

CodePageOverride 

OPTIONAL 

CollectionId 

OPTIONAL 

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. 

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. 





OPTIONAL 

The number of times the driver retries connection attempts to a list of 

database servers (primary and alternate) until a successful connection is 


If set to 0, the driver does not retry connections if a successful connection 

is not established on the driver’s first pass through the list. 

The default is 0. 






DB2 

if a connection is not successfully established on the driver’s 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 124 for more information about 

specifying connection information for primary and alternate servers.





OPTIONAL 

CreateDefaultPackage 

OPTIONAL 

The number of seconds the driver will wait between connection retry 

attempts when ConnectionRetryCount is set to a positive integer. 









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. 


specifying connection information for primary and alternate servers. 


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 The name of the database to which you want to connect. 

This property is supported only for DB2 UDB. 




DiagnosticFilename 

OPTIONAL 

DynamicSections 

OPTIONAL 

Grantee 

OPTIONAL 

GrantExecute 

OPTIONAL 


DB2 

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. 

The number of statements in the DB2 package that the DB2 driver will 

prepare for a single user. 


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. 


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. 

The default is true.




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. 

● 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. 

The default is 2048 (KB). 




LoadBalancing 

OPTIONAL 



DB2 

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). 






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 122 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.





OPTIONAL 

PackageOwner 

OPTIONAL 


MaxPooledStatements property values determine behavior as follows: 

● An integer greater than zero (0) — Enables the DB2 driver’s 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, 

CallableStatements also are pooled. 


The owner to be used for any DB2 packages that are created. 

The default is NULL. 

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 

OPTIONAL 

ReplacePackage 

OPTIONAL 

The TCP port of the primary database server that is listening for 

connections to the DB2 database. 



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. 





SecurityMechanism 

OPTIONAL 

{ClearText | EncryptedPassword | EncryptedUIDPassword} 


DB2 

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.




SendStreamAsBlob 

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 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. 




StripNewlines 

OPTIONAL 

UseCurrentSchema 

OPTIONAL 


DB2 


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. 

● false — 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. 



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 

OPTIONAL 


Determines whether the cursor stays open on commit—either 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. 

The default is true.


DB2 Driver Connection Failover Properties 

Table 9 summarizes the connection properties that control how connection failover works 

with the Database Service DB2 driver. See Table 8 for details about configuring each 

property. 

Table 9. Connection Failover Properties for the DB2 Driver 



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. 

ConnectionRetryCount 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). 

ConnectionRetryDelay 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. 





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: 






...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) 


DB2 


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)


DB2 Driver Data Types 

Table 10 lists the data types supported by the DB2 driver and describes how they are 

mapped to JDBC data types. 

Table 10. 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 Supported only for DB2 UDB 8.1, DB2 7.x OS/390, 

and DB2 iSeries V5R2. 

Decimal DECIMAL 

Double DOUBLE 

Float FLOAT 

Integer INTEGER 

Long Varchar LONGVARCHAR 

Long Varchar for Bit Data LONGVARBINARY 

Numeric NUMERIC 

Real REAL 

Rowid VARBINARY Supported only for DB2 OS/390 and DB2 iSeries V5R2. 

Smallint SMALLINT 

Time TIME 

Timestamp TIMESTAMP 

Varchar VARCHAR 

Varchar for Bit Data VARBINARY 


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 11 describes the JDBC connection properties supported by the Informix driver. The 




as password. 



Table 11. Informix Connection Properties 



OPTIONAL 


OPTIONAL 

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: 






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. 








through the list of servers (primary and alternate) while attempting to 





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. 


Table 11. Informix Connection Properties (continued) 



OPTIONAL 

Informix 

The number of times the driver retries connections to a list of database 

servers (primary and alternate) until a successful connection is 


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 driver’s first pass through 

the list. 



AlternateServers=(server2:2003,server3:2003,server4:2003)) 






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. 








OPTIONAL 

The number of seconds the driver will wait between connection retry 

attempts when ConnectionRetryCount is set to a positive integer. 



AlternateServers=(server2:2003,server3:2003,server4:2003)) 







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. 




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 

DATABASE, DROP DATABASE, and DATABASE database queries. 




DBDate 

OPTIONAL 

Informix 

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: 

● 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. 






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. 


OPTIONAL 

{-1 | 0 | x} 


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. 



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) 




LoadBalancing 

OPTIONAL 


Informix 



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. 


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) 














OPTIONAL 



● An integer greater than zero (0) — Enables the Informix driver’s 

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. 




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. 


Informix Driver Connection Failover Properties 

Informix 

Table 12 summarizes the connection properties that control how connection failover 

works with the Database Service DB2 driver. See Table 11 for details about configuring 

each property. 

Table 12. Connection Failover Properties for the Informix Driver 



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). 





InformixServer The name of the Informix database server to which you want to connect. 







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) 




...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 13 lists the data types supported by the Informix driver and describes how they are 


Table 13. Informix Data Types 

Informix Data Type JDBC Data Type 

blob BLOB 

boolean BIT 

byte LONGVARBINARY 


Table 13. 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 


float FLOAT 

int8 BIGINT 

integer INTEGER 

lvarchar VARCHAR 

money DECIMAL 

nchar CHAR 

nvarchar VARCHAR 

serial INTEGER 

serial8 BIGINT 

smallfloat REAL 


text LONGVARCHAR 


Informix 



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 14 describes the JDBC connection properties supported by the Oracle driver. The 




as password. 


Table 14. Connection Properties for the Oracle Driver 



OPTIONAL 

Oracle 

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 







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: 







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. 






Table 14. Connection Properties for the Oracle Driver (continued) 



OPTIONAL 

CatalogIncludesSynonyms 

DEPRECATED 

CatalogOptions 

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. 


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. 

{0 | 1 | 2 | 3} 

Determines the type of information included in result sets returned from 

catalog functions: 

● 0 — Result sets contain default DatabaseMetaData results. 

● 1 — Result sets contain Remarks information returned from the 

DatabaseMetaData methods: getTables and getColumns. 

● 2 — 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). 






OPTIONAL 

Oracle 






the list. 










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. 








OPTIONAL 


OPTIONAL 

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

list of database servers (primary and alternate) when 











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. 







contact Technical Support with a problem, you might be asked to 

generate a state information log. 






FetchTSWTZasTimestamp 

OPTIONAL 


OPTIONAL 



Oracle 

● 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 WITH TIME ZONE data 

type must be retrieved as a string. 


{-1 | 0 | x} 


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. 



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 







LoadBalancing 

OPTIONAL 




The list of alternate servers is specified by the AlternateServers 

property. The LoadBalancing property determines behavior as follows: 





each server based on their sequential order (primary server first, 











If using a tnsnames.ora file to retrieve connection information, do not 


See “Client Load Balancing” on page 122 or more information about 






OPTIONAL 

Oracle 



● An integer greater than zero (0) — Enables the Oracle driver’s 










cached. 




Password A case-insensitive password used to connect to your Oracle database. A 


contact your system administrator to obtain your password. 





ServerType 

OPTIONAL 

ServiceName 

OPTIONAL 

{Shared | Dedicated} 

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 


The database service name that specifies the database used for the 

connection. The service name is a string that is the global database 

name—a 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. 






SID 

OPTIONAL 

TNSNamesFile 

OPTIONAL 

Oracle 

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. 

The default is ORCL, which is the default SID that is configured when 

installing your Oracle database. 



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. 





TNSServerName 

OPTIONAL 

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. 

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 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 Driver Connection Failover Properties 

Oracle 


works with the Oracle driver. See Table 14 for details about configuring each property. 

Table 15. Connection Failover Properties for the Oracle Driver 



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). 








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. 





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) 


...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; 

AlternateServers=(server2:1521,server3:1521) 


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 

Oracle 

Table 16 lists the data types supported by the Oracle driver and describes how they are 


Table 16. 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 

Oracle9i and higher TIMESTAMP TIMESTAMP 

TIMESTAMP WITH LOCAL TIME 

ZONE 

TIMESTAMP 

TIMESTAMP WITH TIME ZONE VARCHAR 

VARCHAR2 VARCHAR 

XMLType CLOB 



Table 16. Oracle Data Types (continued) 

Oracle Database Oracle Data Type JDBC Data Type 

Oracle10g only BINARY_FLOAT REAL 

XMLType Data Type 

BINARY_DOUBLE DOUBLE 

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('" + 

"123Mark'))"; 

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 = "234Trish"; 

String sql = "insert into XMLTypeTbl values (?, xmltype(?))"; 

PreparedStatement prepStmt = con.prepareStatement(sql); 

prepStmt.setInt(1, 2); 

prepStmt.setString(2, xmlStr); 

prepStmt.executeUpdate(); 


Microsoft SQL Server 

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 17 describes the JDBC connection properties supported by the Microsoft SQL 

Server driver. The properties have the format: 



as password. 



Table 17. Connection Properties for the Microsoft SQL Server Driver 



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) 












See “Specifying Primary and Alternate Servers” on page 126 or more 




Table 17. Connection Properties for the Microsoft SQL Server Driver (continued) 


AlwaysReportTriggerResults 

OPTIONAL 


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. 


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. 






OPTIONAL 






the list. 














time. 









OPTIONAL 

DatabaseName 

OPTIONAL 


OPTIONAL 

HostProcess 

OPTIONAL 


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. 










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. 












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. 







OPTIONAL 

{-1 | 0 | x} 


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





efficiently. 


















LoadBalancing 

OPTIONAL 





























OPTIONAL 

NetAddress 

OPTIONAL 

Password 

OPTIONAL 

ProgramName 

OPTIONAL 



● An integer greater than zero (0) — Enables the SQL Server driver’s 










cached. 




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. 


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 Installation and Upgrade Guide for product 

requirements and configuration that must be met to use Windows 

authentication with the SQL Server driver. 

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. 




SelectMethod 

OPTIONAL 

{direct | cursor} 


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. 





SendStringParametersAsUnicode 

OPTIONAL 

User 

OPTIONAL 


UseServerSideUpdatableCursors {true | false} 

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. 

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. 

Refer to the Progress Sonic Installation and Upgrade Guide for product 

and configuration requirements that must be met to use Windows 

authentication with the SQL Server driver. 

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. 





WSID 

OPTIONAL 

XATransactionGroup 

OPTIONAL 


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. 

The default is an empty string. 

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. 



Microsoft SQL Server Driver Connection Failover Properties 


works with the Database Service SQL Server driver. See Table 17 for details about 

configuring each property. 

Table 18. Connection Failover Properties for the Microsoft SQL Server Driver 



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). 











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) 



....server1:1433;DatabaseName=TEST... 




example: 

...;AlternateServers=(server2:1433;DatabaseName=TEST2,server3:1433; 


You can specify an optional instance property for each alternate server entry. For 

example: 




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) 



Microsoft SQL Server Driver Data Types 

Table 19 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 19. Microsoft SQL Server Driver Data Types 


DataBase 


Data Type JDBC Data Type 

SQL Server 7 and 2000 binary BINARY 

bit BIT 

char CHAR 

datetime TIMESTAMP 


decimal() identity DECIMAL 

float FLOAT 

image LONGVARBINARY 

int INTEGER 

int identity INTEGER 

money DECIMAL 

nchar CHAR 

ntext LONGVARCHAR 


numeric() identity NUMERIC 


real REAL 

smalldatetime TIMESTAMP 



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


DataBase 

SQL Server 7 and 2000 smallint identity SMALLINT 

smallmoney DECIMAL 

sysname VARCHAR 


timestamp BINARY 


tinyint identity TINYINT 

uniqueidentifier CHAR 



SQL Server 2000 only bigint BIGINT 

bigint identity BIGINT 

sql_variant VARCHAR 



Data Type JDBC Data Type 



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 20 describes the JDBC connection properties supported by the Sybase driver. The 




as password. 


Table 20. Connection Properties for the Sybase Driver 



OPTIONAL 

Sybase 





(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) 














alternate servers 



Table 20. Connection Properties for the Sybase Driver (continued) 



OPTIONAL 


OPTIONAL 


Determines the method used to execute batch operations: 

● true — The native Sybase batch mechanism is used. 

● 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. 


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. 





OPTIONAL 

Sybase 






the list. 














time. 










OPTIONAL 

DatabaseName 

OPTIONAL 


OPTIONAL 

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

list of database servers (primary and alternate) when 











twice. It waits 3 seconds between the first connection retry attempt and 

the second connection retry attempt. 



time. 
















OPTIONAL 

{-1 | 0 | x} 

Sybase 


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





efficiently. 



















LoadBalancing 

OPTIONAL 



























OPTIONAL 

Sybase 



● An integer greater than zero (0) — Enables the Sybase driver’s 










cached. 




Password The case-sensitive password used to connect to your Sybase database. A 


contact your system administrator to get your password. 





PrepareMethod 

OPTIONAL 

{StoredProc | StoredProclfParam | Direct} 

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 — 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. 

● Direct — 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. 




SelectMethod 

OPTIONAL 

{Direct | Cursor} 

Sybase 

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. 

● 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 

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. 



Sybase Driver Connection Failover Properties 


works with the Database Service Sybase driver. See Table 20 for details about configuring 

each property. 

Table 21. Connection Failover Properties for the Sybase Driver 



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). 











Specifying Alternate Servers for the Sybase Driver 

The following connection URL for the Sybase driver specifies connection information for 







....server1:4100;DatabaseName=TEST... 

Sybase 



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; 




Sybase Driver Data Types 

Table 22 lists the data types supported by the Sybase driver and describes how they are 


Table 22. Sybase Driver Data Types 

Sybase DataBase Sybase Data Type JDBC Data Type 

Sybase 11.5 and higher binary BINARY 

bit BIT 

char CHAR 

datetime TIMESTAMP 


decimal() identity DECIMAL 

float FLOAT 

image LONGVARBINARY 

int INTEGER 

money DECIMAL 

nchar CHAR 



real REAL 

smalldatetime TIMESTAMP 


smallmoney DECIMAL 

sysname VARCHAR 


timestamp VARBINARY 





Table 22. 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 

Sybase 

Note For users of Adaptive Server 12.5 and 12.5.1: The Sybase driver supports extended new 

limits (XNL) for character and binary columns—columns with lengths greater than 255. 

Refer to your Sybase documentation for more information about XNL for character and 

binary columns. 




Chapter 7 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. 


Chapter 7: SQL Escape Sequences for JDBC 

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 

d Date yyyy-mm-dd 

t 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 23. 

For example: 

SELECT id, name FROM emp WHERE name LIKE {fn UCASE('Smith')} 


Table 23. Scalar Functions Supported by Database Service JDBC Drivers 

Data Store String Functions 

Progress 

OpenEdge 

CONCAT 

LEFT 

LENGTH 

LTRIM 

REPLACE 

RTRIM 

SUBSTRING 

Numeric 

Functions 

ABS 

ACOS 

ASIN 

ATAN 

ATAN2 

COS 

COT 

EXP 

FLOOR 

LOG 

LOG10 

MOD 

POWER 

ROUND 

SIN 

SQRT 

TAN 

TRUNCATE 

Timedate 

Functions 

CURRDATE 

CURRTIME 

DAYOFMONTH 

DAYOFWEEK 

MONTH 

NOW 

TIMESTAMP 

TIMESTAMPADD 

TIMESTAMPDIFF 

YEAR 


System 

Functions 

DATABASE 

USER 



Table 23. Scalar Functions Supported by Database Service JDBC Drivers (continued) 


DB2 ASCII 

BLOB 

CHAR 

CHR 

CLOB 

CONCAT 

DBCLOB 

DIFFERENCE 

GRAPHIC 

HEX 

INSERT 

LCASE or LOWER 

LCASE (SYSFUN schema) 

LEFT 

LENGTH 

LOCATE 

LONG_VARCHAR 

LONG_VARGRAPHIC 

LTRIM 

LTRIM (SYSFUN schema) 

POSSTR 

REPEAT 

REPLACE 

RIGHT 

RTRIM 

RTRIM (SYSFUN schema) 

SOUNDEX 

SPACE 

SUBSTR 

TRUNCATE or TRUNC 

UCASE or UPPER 

VARCHAR 

VARGRAPHIC 

Numeric 

Functions 

ABS or ABSVAL 

ACOS 

ASIN 

ATAN 

ATANH 

ATAN2 

BIGINT 

CEILING or CEIL 

COS 

COSH 

COT 

DECIMAL 

DEGREES 

DIGITS 

DOUBLE 

EXP 

FLOAT 

FLOOR 

INTEGER 

LN 

LOG 

LOG10 

MOD 

POWER 

RADIANS 

RAND 

REAL 

ROUND 

SIGN 

SIN 

SINH 

SMALLINT 

SQRT 

TAN 

TANH 

TRUNCATE 

Timedate 

Functions 

DATE 

DAY 

DAYNAME 

DAYOFWEEK 

DAYOFYEAR 

DAYS 

HOUR 

JULIAN_DAY 

MICROSECOND 

MIDNIGHT_SECONDS 

MINUTE 

MONTH 

MONTHNAME 

QUARTER 

SECOND 

TIME 

TIMESTAMP 

TIMESTAMP_ISO 

TIMESTAMPDIFF 

WEEK 

YEAR 

System 

Functions 

COALESCE 

DEREF 

DLCOMMENT 

DLLINKTYPE 

DLURLCOMPLETE 

DLURLPATH 

DLURLPATHONLY 

DLURLSCHEME 

DLURLSERVER 

DLVALUE 

EVENT_MON_STATE 

GENERATE_UNIQUE 

NODENUMBER 

NULLIF 

PARTITION 

RAISE_ERROR 

TABLE_NAME 

TABLE_SCHEMA 

TRANSLATE 

TYPE_ID 

TYPE_NAME 

TYPE_SCHEMA 

VALUE 




Informix CONCAT 

LEFT 

LENGTH 

LTRIM 

REPLACE 

RTRIM 

SUBSTRING 

Numeric 

Functions 

ABS 

ACOS 

ASIN 

ATAN 

ATAN2 

COS 

COT 

EXP 

FLOOR 

LOG 

LOG10 

MOD 

PI 

POWER 

ROUND 

SIN 

SQRT 

TAN 

TRUNCATE 

Timedate 

Functions 

CURDATE 

CURTIME 

DAYOFMONTH 

DAYOFWEEK 

MONTH 

NOW 

TIMESTAMPADD 

TIMESTAMPDIFF 

YEAR 


System 

Functions 

DATABASE 

USER 





Oracle ASCII 

BIT_LENGTH 

CHAR 

CONCAT 

INSERT 

LCASE 

LEFT 

LENGTH 

LOCATE 

LOCATE2 

LTRIM 

OCTET_LENGTH 

REPEAT 

REPLACE 

RIGHT 

RTRIM 

SOUNDEX 

SPACE 

SUBSTRING 

UCASE 

Numeric 

Functions 

ABS 

ACOS 

ASIN 

ATAN 

ATAN2 

CEILING 

COS 

COT 

EXP 

FLOOR 

LOG 

LOG10 

MOD 

PI 

POWER 

ROUND 

SIGN 

SIN 

SQRT 

TAN 

TRUNCATE 

Timedate 

Functions 

CURDATE 

DAYNAME 

DAYOFMONTH 

DAYOFWEEK 

DAYOFYEAR 

HOUR 

MINUTE 

MONTH 

MONTHNAME 

NOW 

QUARTER 

SECOND 

WEEK 

YEAR 

System 

Functions 

IFNULL 

USER 




Microsoft 

SQL Server 

ASCII 

CHAR 

CONCAT 

DIFFERENCE 

INSERT 

LCASE 

LEFT 

LENGTH 

LOCATE 

LTRIM 

REPEAT 

REPLACE 

RIGHT 

RTRIM 

SOUNDEX 

SPACE 

SUBSTRING 

UCASE 

Numeric 

Functions 

ABS 

ACOS 

ASIN 

ATAN 

ATAN2 

CEILING 

COS 

COT 

DEGREES 

EXP 

FLOOR 

LOG 

LOG10 

MOD 

PI 

POWER 

RADIANS 

RAND 

ROUND 

SIGN 

SIN 

SQRT 

TAN 

TRUNCATE 

Timedate 

Functions 

DAYNAME 

DAYOFMONTH 

DAYOFWEEK 

DAYOFYEAR 

EXTRACT 

HOUR 

MINUTE 

MONTH 

MONTHNAME 

NOW 

QUARTER 

SECOND 

TIMESTAMPADD 

TIMESTAMPDIFF 

WEEK 

YEAR 


System 

Functions 

DATABASE 

IFNULL 

USER 





Sybase ASCII 

CHAR 

CONCAT 

DIFFERENCE 

INSERT 

LCASE 

LEFT 

LENGTH 

LOCATE 

LTRIM 

REPEAT 

RIGHT 

RTRIM 

SOUNDEX 

SPACE 

SUBSTRING 

UCASE 

Numeric 

Functions 

ABS 

ACOS 

ASIN 

ATAN 

ATAN2 

CEILING 

COS 

COT 

DEGREES 

EXP 

FLOOR 

LOG 

LOG10 

MOD 

PI 

POWER 

RADIANS 

RAND 

ROUND 

SIGN 

SIN 

SQRT 

TAN 

Timedate 

Functions 

DAYNAME 

DAYOFMONTH 

DAYOFWEEK 

DAYOFYEAR 

HOUR 

MINUTE 

MONTH 

MONTHNAME 

NOW 

QUARTER 

SECOND 

TIMESTAMPADD 

TIMESTAMPDIFF 

WEEK 

YEAR 

System 

Functions 

DATABASE 

IFNULL 

USER 


Outer Join Escape Sequences 

Outer Join Escape Sequences 

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: 

For example: 

table-reference is a database table name 

search-condition is the join condition you want to use for the tables 

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 24 lists the outer join escape sequences supported by Database Service JDBC 

drivers for each data store. 

Table 24. Outer Join Sequences Supported by Database Service JDBC Drivers 

Data Store Outer Join Escape Sequences 

Progress OpenEdge Left outer joins 

Right outer joins 

Nested outer joins 

DB2 Left outer joins 



Informix Left outer joins 





Table 24. Outer Join Sequences Supported by Database Service JDBC Drivers 

Data Store Outer Join Escape Sequences 

Oracle Left outer joins 



Microsoft SQL Server Left outer joins 


Full outer joins 


Sybase Left 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: 

procedure-name specifies the name of a stored procedure 

parameter specifies a stored procedure parameter 

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. 


Chapter 8 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 25 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 25. Configuring Windows Authentication on Microsoft SQL Server 

Component Collection 


Database Server 

Set the authentication mode (see“Setting the Authentication Mode” on page 222). 

Confirm that a Service Principal Name (SPN) is registered for each Microsoft SQL 

Server instance (see “Registering Service Principal Names (SPNs)” on page 222). 

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 223). 


Chapter 8: 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. 


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. 


Chapter 8: Configuring SQL Server Windows Authentication 


Part III Configuring and Managing BPEL Services 

Part III explains how to configure and manage BPEL services using the Sonic 

Management Console, and contains the following chapters: 

● “Configuring BPEL Services” 

● “Managing BPEL Services” 



Chapter 9 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” 


Chapter 9: Configuring BPEL Services 

Overview of BPEL Service Initialization Parameters 

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 Developer’s 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: 


Overview of BPEL Service Initialization Parameters 

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 Developer’s Guide in the Sonic 

Workbench (Eclipse) help. 



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 231 

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. 

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 232. 

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 237. 

Default Partner Link Specify the default process and partner link to use. 

Optional. 

See “Setting a Default Partner Link” on page 238. 

HTTP Callback URL The address used as the Reply To address when using WSA 

headers in asynchronous invocations. 

Optional. 


Specifying a BPEL Archive (.bpar) 

Specifying a BPEL Archive (.bpar) 

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 Developer’s 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. 



Setting Persistence Options 

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 236). 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 Developer’s 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). 

Important 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. 

● 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: 

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. 



■ 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” 

Important When using an external database, each BPEL service instance must be 

configured with its own database. 

3. If you selected Other Database as the data source type, enter the following Database 

Options: 

■ Database Type — Select either Oracle or MySQL 

■ Database Name — Optional 

■ Machine Name — Optional 

■ Database Port — Optional 

■ Username — Optional 

■ Password — Optional 

Important 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 65 

for instructions). 


4. Click OK to set the persistence mode and close the dialog box. 




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 248). 

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 232). 

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 Developer’s 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 248 for information about the details you can view is 

audit trails. 

◆ To enable audit trail recording: 

❖ In the Init Parameters area of the SMC, select True from the Enable Audit Trails pulldown 

list. (Selecting False disables audit trails.) 


Audit Trails and Persistence 

Audit Trails and Persistence 

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. 



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. 

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 64.) 

● You are using a Persistent store (that is, not In Memory). (See “Setting Persistence 

Options” on page 232.) 

● All activities must be in a waiting state (that is, no alerts are set). 

● There are no synchronous inbound connections. 




Chapter 10 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” 


Chapter 10: Managing BPEL Services 

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. 


Clearing Process History 

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 243). 

● Terminate a process or all processes in a service (see “Terminating Processes” on 

page 244). 

● Search for a set of process instances that match your specified criteria (see “Searching 

for Process Instances” on page 244). 

● View audit trails for a selected process instance (see “Viewing Audit Trails” on 

page 248). 

● View aggregate information for all the process instances created by a selected process 

(see “BPEL Profiling” on page 250). 

Clearing Process History 

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. 



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. 

Searching for Process Instances 

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. 



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. 



3. 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. 

4. Optionally, in the Messages section, click Add to specify the following search criteria 

in the table: 

■ Destination — Select Any, Inbound, or Outbound (Required) 

■ Message Namespace 

■ Message Local Name 

■ Part 

■ Search Value 

Note If you specify an asterisk (*) as the value for any of the criteria, that value is ignored. 

5. 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. 

Note 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 Developer’s 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 

Note The correlation column is dynamic, and is only shown when a process has 

correlation values. 

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 248.) 

9. Close the Process Instance Search window to return to the SMC. 



Viewing Audit Trails 

When a BPEL service configuration has the Enable Audit Trails option set to True (see 

“Audit Trails and Persistence” on page 237) and the Persistence option set to something 

other than In Memory (see “Setting Persistence Options” on page 232), you can view 

activities and event details of a BPEL process instance. 

◆ To view audit trails and event details: 

1. In the Search Process Instance window, select a process instance and click Audit 

Trail (see “Searching for Process Instances” on page 244). 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 

Viewing Audit Trails 

■ Activity XML:ID— The value of the ID attribute in the process’s 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. 

Note Many activities generate multiple audit trail events. For instance, many activities 

generate a START event and a COMPLETE event, as in the preceding example. 

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 



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 243) 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 

■ Times Completed: Minimum, average, and maximum [ms] 

■ Individual time: Minimum, average, and maximum [ms] 

■ Total time: Minimum, average, and maximum [ms] 


Part IV Integrating Sonic and Actional 

Part IV contains the following chapters: 

● Chapter 11, “Using Actional with Sonic Components” 

● Chapter 12, “Using Actional Trust Zones in Sonic ESB” 



Chapter 11 Using Actional with Sonic Components 

The Sonic Enterprise Service Bus (ESB) and SonicMQ interceptors provide service 

visibility through a stand-alone instance of Actional Agent. The ESB interceptor provides 

a logical view of all the interactions in the bus, and the MQ interceptor provides visibility 

in to the message flows in brokers. The Sonic interceptors are packaged and always 

installed with Sonic ESB containers and SonicMQ brokers. The interceptors require you 

to specifically enable them on each installed container and broker, as described in this 

chapter and in Progress Actional documentation. 

The sections in this chapter are: 

● “Instrumenting Sonic ESB” 

● “Instrumenting Sonic BPEL Sever” 

● “Instrumenting SonicMQ” 

● “Visualization When Both SonicMQ Broker and Sonic ESB are Instrumented” 

● “Specifying the Uplink Configuration Location in Sonic” 


Chapter 11: Using Actional with Sonic Components 

Instrumenting Sonic ESB 

Figure 3. ESB Process 

Sonic ESB 8.0 installations include the actional-sdk.jar that is packaged in the ESB 

library archives and the Sonic ESB interceptor in the xq_lginterceptor.jar. 

The ESB interceptor maps Sonic ESB message interactions to Actional Management 

Server levels as follows: 

Actional 

Management 

Server Level Sonic ESB Itineraries Sonic ESB non-Itineraries 

1 Host Name Host Name 

2 ESB Service Name ESB Service Name 

3 ESB Process Name "Standalone" 

4 Step Name - 

A Sonic ESB process, when visualized in the Actional Management Server, might look 

similar to the following: 

where Step_1, Step_2, and Step_3 are the steps in the ESB process Sample.XPathCBR. 


Figure 4. ESB Service 


Services running on ESB might not be part of an ESB process. When Sonic ESB responds 

to a simple service request the fourth level does not have meaning, so the call looks more 

the one below for the dev.Runservice: 

The Actional Item Breakdown shows subnode data and the distribution of calls from ESB 

containers in the node. The syntax for each subnode is 

DomainName.ManagementContainerName.ESBContainerName. In the following illustration, 

two containers contributed to the inbound call volume to dev.CBR: 

Figure 5. Sonic Subnode 



Enabling the ESB Interceptor 

The Sonic ESB Interceptor is installed whenever a Sonic ESB container is installed on a 

system. The interceptor is not, by default, enabled. In order to use the Actional Agent to 

manage services and processes on a system, you must install and provision the Actional 

Agent on the system where the ESB service runs, and then enable the interceptor by 

making configuration changes to the ESB Container, typically through the Sonic 

Management Console. Integration is set on each ESB container you want to monitor by 

enabling the instrumentation in Sonic. 

◆ To enable Sonic ESB instrumentation on an ESB container: 

1. Start the Sonic Management Console and connect to the Directory Service that 

manages the ESB service. 

2. In the left panel, expand the ESB Configured Objects tree. 

3. In the navigation panel, click on ESB Containers. 

4. Select a container in the ESB Container Name section in the right panel. 

5. In the Actional Integration section of the screen, check the Enable Instrumentation 

checkbox, and, optionally, whether to enable capturing of each message's payload. 



The result of enabling ESB container instrumentation looks the following: 

Figure 6. Enabled ESB Container Instrumentation 

6. On the management container that hosts the ESB Container, specify the location of 

the uplink.cfg file. For more information, “Specifying the Uplink Configuration 

Location in Sonic” on page 266. 

The container logs the information, as shown for this example where the myESB ESB 

container was enabled and hosts the dev_CBR Service: 

Code Sample 1. ESB Container Log of Actional Instrumentation Information 

[date-time] ID=My ESB (info) [ESBService] Initializing Service 'dev.CBR' 

[date-time] ID=My ESB (info) [ESBService] Service 'dev.CBR' initialized: 1 thread(s) 

listening on Endpoint dev.CBR.Entry 

[date-time] ID=My ESB (info) Actional instrumentation is enabled for this container 

[date-time] ID=My ESB (info) Actional payload capture is disabled. 

[date-time] ID=My ESB (info) Actional agent is running. 

[date-time] ID=My ESB (info) Initializing Mitigation context factory class: 

com.sonicsw.xqimpl.actional.lg.visitor.StabilizerHelper 

[date-time] (info) Loaded ID=My ESB 



Using Stabilizers with Sonic ESB 

From within ESB at runtime, the value of stabilizer switches can be obtained from the 

service context. A stabilizer switch is a custom-defined flag set by the Actional 

Management Server to indicate certain user-specified system conditions. It can be used by 

ESB to set up custom routing in response to changing network or application conditions. 

You can access stabilizers in three ways: through interfaces in the Sonic ESB API, 

through JavaScript, and through XPath. If Actional is not instrumented for the ESB 

container, then accessing stabilizers with any of the three mechanisms will always return 

false. If no stabilizer switch is defined, then these return false as well. 

Accessing Stabilizers in the Sonic ESB API 

This example uses the XQMitigationContext and XQServiceContext interfaces from the 

com.sonicsw.xq package. 

Custom ESB services written in Java can call these methods starting with the service 

context instance passed to the service() method. More commonly, however, stabilizer 

switches will be used from within a Content Base Routing (CBR) step in an ESB process. 

This allows the ESB process to route messages, at runtime, based on the value of a 

stabilizer switch. First, the application must retrieve an instance of XQMitigationContext, 

by calling the following method on the XQServiceContext interface: 

public XQMitigationContext getMitigationContext() 

Then, on the returned object, call this method to return the value of the switch: 

public boolean getMitigationSwitch(java.lang.String switchName) 

This method returns false if the switch is not defined. 

Acccessing Stabilizers in Javascript 

Typically, a CBR step in a process is configured to use a Javascript program to perform 

the routing logic. The Javascript program must define a function called rule() that ESB 


Code Sample 2. 


calls at runtime. In this rule() function, you can access the appropriate runtime interfaces, 

as shown: 

function isLGStabilizerSet(switchName) 

{ 

if (switchName == null) 

{ 

XQ_logInformation("#### No Stabilizer Switch name specified."); 

return false; 

} 

XQ_logInformation("#### Fetching MitigationContext" ); 

mCtx = XQServiceContext.getMitigationContext(); 

if( mCtx == null ) 

{ XQ_logInformation("#### No MitigationContext found, LG is probably not enabled."); 

} 

} 

} 

return false; 

XQ_logInformation("#### Fetching Stabilizer Switch value for: " + switchName ); 

stabilizerSwitch = mCtx.getMitigationSwitch(switchName); 

XQ_logInformation("#### Returning Stabilizer Switch value: 

" + switchName + "=" + stabilizerSwitch); 

return stabilizerSwitch; 

function rule() 

{ 

if (isLGStabilizerSet("ESBStabilizerSwitch1")) 

{ 

return XQ_getStepAddress("Step_StabilizerTrue"); 

} 

else 

{ 

return XQ_getStepAddress("Step_StabilizerFalse"); 

} 

In this example, the rule() function calls the is LGStabilizerSet function to determine the 

value of a switch. If this switch is set, the CBR routes to a process StabilizerSet step; if 

the switch is not set, the CBR routes to the StabilizerNotSet step. 

Consult the ESB documentation for information on defining Content Base Routing steps. 

For more information on stabilizer switches and how they are used in Actional 

Management Server, see the “Stabilizer Switches” chapter of the Actional Management 

Server Guide. 

Accessing Stabilizers in XPath 

To use stabilizers from XPath, define a namespace that maps a prefix (say, stabilizer) to 

java:com.sonicsw.xqimpl.actional.lg.visitor.StabilizerHelper. In the expression, 

enter the following to access the value of a stabilizer switch called Stabilizer1: 

stabilizer:getMitigationSwitch(stabilizer:new(),'Stabilizer1') 



Using ESB-Specific Message Fields 

The ESB message fields provide information that is not reported “natively” by the 

Actional Management Server. The ESB interceptor defines four message fields that are 

not defined for other platforms: 

Message Field 

Name Description 

ESB-Container The name of the ESB container — This field keeps track of the specific 

ESB container that either invokes a call or is invoked by a call. Actional 

Management Server is not aware of containers as such—it tracks 

information at the managed-node level. In cases where several containers 

are running on the same node, this message field will specify which 

container is in use. 

ESB-Top-Process The name of the top-level process of a nested ESB process — This 

field is useful when tracking the progress of a nested ESB process. In those 

cases, it keeps track of the name of the ESB top process that “owns” the 

current call. 

ESB-Process The name of the current ESB process — When applicable, this field 

reports on the current ESB Process, which may itself be part of a higher 

level ESB Process. 

ESB-Service The name of the ESB service invoked at a given step — When 

applicable, this field reports the name of the current ESB Service that was 

invoked by an ESB Process step. 

Enabling ESB Message Fields 

To enable this feature, the named message fields must be created (each with no default 

value) in the Actional Management Server administration interface. See the “Message 

Fields” chapter of the Actional Management Server Guide for more information on 

creating message fields. 


Startup Order 

Trust Zones 

Auditing 


The Sonic ESB interceptor verifies that the Actional Agent is running when the ESB 

container is launched. If the interceptor does not detect a running Actional Agent, ESB 

instrumentation is disabled, even if it has been manually enabled in the Sonic 

Management Console. Therefore make sure that the Actional Agent is running, taken 

under management and provisioned before the ESB container is launched on the same 

node. 

Trust Zones can be enforced by the ESB interceptor. See the following chapter, “Using 

Actional Trust Zones in Sonic ESB” on page 269 for more information. 

The Sonic ESB interceptor can be configured to capture payload data. The ESB 

interceptor captures the contents of the first part of the message only if that part is XML; 

otherwise, no payload information is reported to the agent. 



Instrumenting Sonic BPEL Sever 

The Progress Sonic BPEL Server product extends Progress Sonic ESB with the 

functionality of the Business Process Execution Language. While the ESB 

instrumentation of the ESB container that hosts a BPEL Service provides interceptors for 

BPEL processes, certain visualizations are realized only when BPEL Servers are 

monitored. 

The Actional levels are mapped to the Sonic BPEL Process structure, as follows: 

Actional Level Sonic 

1 Host Name 

2 "BPEL-Process" 

3 BPEL Process Name 

4 Partner Link :: Operation 

When a Sonic BPEL Service emits events, they are visualized through the interceptor in 

the ESB container that hosts a BPEL service, and might look similar to the following: 

Figure 7. Sonic BPEL Service 


Instrumenting SonicMQ 

Instrumenting SonicMQ 

Progress SonicMQ broker installations include the actional-sdk.jar in the SonicMQ 

library archives and the SonicMQ interceptor in the broker.jar. 

When a SonicMQ broker is enabled for Actional instrumentation, and both the broker and 

agent are running, SonicMQ interceptors are in the flow between the message producers 

and message consumers. They intercept all inbound and outbound messages and feed 

information about those interactions to the agent as asynchronous events. The SonicMQ 

interceptor maps the messaging interactions on an instrumented broker to Actional levels 

as follows: 

Actional Level Sonic 

1 Host Name 

2 Sonic Node Name :: Broker Name 

3 Destination Name 

4 - 

A SonicMQ message flow from producer to consumer, when visualized in the Actional 

Management Server, might look similar to the following: 

Figure 8. SonicMQ Message Flow 

where producer P1 published to topic T.1 on broker br3 (a member of Sonic cluster that is 

referenced as Sonic routing node A). Subscribers S1and S2 are active consumers on broker 

br3 with patterns that include the T.1 topic 

Enabling the SonicMQ Interceptor 

The SonicMQ Interceptor is installed whenever a SonicMQ broker is installed on a 

system. The interceptor is not, by default, enabled. In order to use the Actional Agent to 

manage services and processes on a system, you must install and provision the Actional 

Agent on the system where the SonicMQ broker runs, and then enable the interceptor by 

making configuration changes to the SonicMQ broker, typically through the Sonic 

Management Console. Actional integration is set on each broker running on a system. 



Related SonicMQ brokers placed on different systems (and therefore different Actional 

nodes) should have their Actional Agent instances managed on the same Actional 

Management Server to visualize interbroker flows such as clusters, Dynamic Routing, 

and Continuous Availability failover. Correspondingly, SonicMQ brokers registered in 

different SonicMQ domains but colocated on the same managed node will record their 

events on the same Actional Management Server. 

◆ To enable SonicMQ instrumentation on a SonicMQ broker: 

1. Start the Sonic Management Console, and connect to the Directory Service that 

manages the broker. 

2. On the configuration tab's left panel, locate the broker configuration you want to 

instrument. 

3. Right click on the broker name, and then choose Properties. 

4. Select the Monitoring tab. 

5. Check the Enable Actional Instrumentation checkbox, and, optionally, whether to 

enable capturing of each message's payload. You can specify the payload capture as 

NONE, HEADER, BODY, or ALL (both header and body). The result of enabling SonicMQ 

broker instrumentation and choosing to capture payload headers is as follows: 

Figure 9. Enabled SonicMQ Broker Instrumentation 

The log of the management container that hosts the broker immediately indicates the 

status of the instrumentation, as shown for this example: 

Code Sample 3. Broker’s Container Log of Actional Instrumentation Information 

[date-time] ID=Br1 (info) Actional instrumentation is enabled with payload capture disabled 

[date-time] ID=Br1 (info) Successfully connected to Actional agent 

6. On the management container that hosts the broker, specify the location of the 

uplink.cfg file. For more information, see “Specifying the Uplink Configuration 

Location in Sonic” on page 266. 


Visualization When Both SonicMQ Broker and Sonic ESB are Instrumented 

Visualization When Both SonicMQ Broker and Sonic 

ESB are Instrumented 

If you enable instrumentation on an Actional managed node for both SonicMQ brokers 

that monitor message traffic, and the Sonic ESB services that are producing and 

consuming messages, then the hybrid visualization of the messages flowing through the 

endpoints on the brokers might look similar to the following for an ESB process: 

Figure 10. Hybrid SonicMQ/Sonic ESB Instrumentation 



The hybrid visualization of the messages flowing through the endpoints on the brokers 

might look similar to the following for a standalone service through a call to the dev.Run 

service: 

Figure 11. Standalone Service 

Specifying the Uplink Configuration Location in Sonic 

You need to explicitly declare the location of the Actional Agent’s uplink.cfg file in the 

Sonic context. In Sonic, you do this by setting a Java System property in each 

management container configuration where Actional instrumentation is enabled. 

◆ To specify the location of the uplink.cfg file: 

1. In the Sonic Management Console, open (in turn) the Properties dialog box of each 

management container that hosts a messaging broker or ESB Container where you 

enabled Actional instrumentation. 

2. Choose the Environment tab. 

3. Click New. 

a. For the Variable, enter com.actional.lg.interceptor.config. 

b. For the Value enter a location for the file, usually a new folder within the Actional 

Agent directory. 

4. Click OK on the two dialog boxes 


The property is listed as shown, with your value entry: 

Figure 12. Actional Property 

Specifying the Uplink Configuration Location in Sonic 




Chapter 12 Using Actional Trust Zones in Sonic ESB 

This chapter describes support for Progress Actional trust zones in Progress Sonic ESB 

in the following sections: 

● “Progress Actional Trust Zones” 

● “Implementing Trust Zones in Progress Sonic ESB” 


Chapter 12: Using Actional Trust Zones in Sonic ESB 

Progress Actional Trust Zones 

You can use Progress Sonic ESB 8.0 with Progress Actional 8.0.5 (or higher) to 

implement trust zones, which provide an additional layer of security in a SOA 

environment. In Sonic ESB 8.0, trust zones are only supported for SOAP messages over 

HTTP. 

Trust zones secure the last mile and guard against threats from the following attacks: 

● Replay — Unauthorized third party tries to reuse an intercepted message header to 

restart or continue a session in place of the original requester system. 

● Man in the middle — Unauthorized third party intercepts communications between 

two systems, acting as a relay and capturing private information. 

The key components in Actional trust zone technology are: 

● Trust assertor (TA) — Actional Intermediary by default and agents if they are 

configured. The Actional Intermediary interceptor is the trust assertor and it inserts a 

trust header in a message before sending it to the internal network. 

● Trust enforcement point (TEP) - All agents can be enforcement points. During trust 

enforcement the Actional manifest header of the incoming message is checked. If the 

header does not contain valid trust information, the message is rejected. 

When an interceptor in the same trust zone performs trust enforcement on an incoming 

message, it validates the trust information and prevents the message from reaching the 

application if the trust information is invalid. Trust information is invalid if: 

● Trust assertion is missing (the message did not come in through a trust assertor) 

● Trust interval has expired 

● Invalid source IP address (if the caller's IP address checking is enabled) 

● Trust information was compromised (security breach) 

Trust zones limit the processing of a request to once within the trust interval, a trust-zonewide 

configuration property (the default is 5 minutes). You must synchronize the clocks 

on all nodes in a trust zone to ensure that the difference between clocks does not exceed 

the trust interval; otherwise, all requests within the trust zone are rejected. To set the trust 

interval, see the “Actional Server and Actional Intermediary” chapter in the Actional 

Server Continuous Service Optimization Guide. 

Notes If a message remains in a JMS queue longer than the trust interval, trust zone enforcement 

fails when the message is processed.If a message is redelivered, trust enforcement rejects 

the second message since it has the same request ID. If the message is redelivered after 

the JVM is restarted or after the time window expires, it is not rejected. 


Implementing Trust Zones in Progress Sonic ESB 


To implement trust zone enforcement in Sonic ESB, you enable Actional instrumentation 

on ESB containers, add the nodes on which the ESB containers are deployed to a trust 

zone, and configure appropriate service groups in Actional Intermediary for the web 

services exposed in ESB. 

The following is an overview of how to implement trust zones with Sonic ESB: 

1. Use 8.0.5 (or higher) versions of the Actional product family (Agent, Server, and 

Intermediary). 

2. Enable Actional instrumentation: 

■ Enable Actional instrumentation on ESB 8.0 containers. 

■ Do not enable Actional instrumentation on any brokers that Sonic ESB uses for 

messaging. 

See “Enable Actional Instrumentation in Sonic ESB” on page 272. 

3. Configure Actional Intermediary with appropriate service groups for the web services 

exposed in Sonic ESB. 

See “Register a Web Service with Actional Intermediary” on page 275. 

4. Configure trust zones appropriately for Sonic ESB and ensure that the agents are 

provisioned: 

■ Disable the Check Caller IP Address setting 

■ Enable the Trust Calls within Trust Zones setting 

See “Define Trust Zones on Actional Server” on page 280. 



Enable Actional Instrumentation in Sonic ESB 

For each ESB process that will run in a trust zone, you must enable Actional 

instrumentation on every ESB container that participates in the execution of the ESB 

process. Sonic ESB performs trust enforcement to check whether a message is trusted 

before letting a service execute. After service execution, Sonic ESB adds a trust assertion 

so the message is trusted at subsequent steps in the ESB process. Sonic ESB only adds a 

trust assertion if the Trust Calls within Trust Zones setting is enabled (see page 282). 

See the “Instrumenting Sonic ESB” chapter in the Actional Interceptor Guide for more 

information. 

Important Instrument only Sonic ESB, not SonicMQ. Do not enable Actional instrumentation on 

any SonicMQ broker to which an ESB application can connect. If SonicMQ is 

instrumented, calls from outside the trust zone going directly to SonicMQ are viewed as 

trusted. This is because after Actional instrumentation is enabled, all entities act as trust 

assertors and automatically write a trust assertion in messages coming from SonicMQ. 

This behavior poses a security risk. 

Enabling trust zones affects flow visualization. All calls come into Sonic ESB through 

Actional Intermediary, which causes an extra node in the flow 

If an ESB container is not Actional-instrumented and an incoming message contains an 

Actional manifest header, Sonic ESB preserves and propagates the header to all messages 

in the Outbox. The Actional manifest header contains all the information relevant to 

Actional and by propagating this header Sonic ESB preserves the Actional flow even 

when the message travels through a non-instrumented Sonic ESB node. 

This behavior is modified in 8.0 when trust zones are enabled. A non-instrumented ESB 

container will not propagate the Actional manifest header if a message is received from 

a trusted node. This prevents a trusted downstream node from falsely trusting a message 

that arrived from this non-trusted ESB container. 



Enabling Actional Instrumentation on an ESB Container 

You can use the Sonic Management Console or Sonic Workbench to enable Actional 

instrumentation on an ESB container. 

◆ To enable Actional instrumentation using the Sonic Management Console: 

1. Select the ESB Containers folder in the left panel under ESB Configured Objects. 

2. Select the ESB container in the list in the right panel. 

3. Under Actional Integration in the right panel, select Enable Actional 

Instrumentation: 

◆ To enable Actional instrumentation using Sonic Workbench: 

1. In the Containers view, select a container, right-click and select Properties. 

2. In the General Properties page, select Enable Actional Instrumentation: 



Disabling Trust Enforcement on a Management Container (Optional) 

You can optionally disable trust enforcement, for example, if you have other services or 

ESB processes that call into a service that is part of an ESB process that does not require 

trust enforcement. You can disable trust enforcement selectively on particular 

management containers in a node (rather than all of the containers in the node). However, 

disabling trust enforcement in a management container affects all of the ESB containers 

deployed in that management container. 

◆ To disable trust enforcement on a management container: 

1. In the Sonic Management Console Configure tab, expand the Containers folder under 

Configured Objects. 

2. Select the management container, right-click, and select Properties. The Edit 

Container Properties dialog box opens. 

3. Select the Environment tab and enter the following JVM argument in the Java VM 

options section and set it to true: 

-Dactional.interceptor.DisableTrustZoneEnforcement=true 



Register a Web Service with Actional Intermediary 

Since all SOAP/HTTP calls go through Actional Intermediary, you must provide a way to 

contact Actional Intermediary and for Actional Intermediary to contact an ESB process 

exposed as a web service. Message traffic flows through a service group, a set of managed 

web services, web service access points, and message processing blocks. 

You expose an ESB process as a web service and configure Actional Intermediary with 

service groups for the web services exposed in Sonic ESB. For information on exposing 

an ESB process as a web service, see the “Wrapping an ESB process as a Web service” 

topic under “ESB Process editor” in the Sonic Workbench online help. 

◆ To register a web service with Actional Intermediary: 

1. Open a browser to the administration console for Actional Intermediary using the 

URL, your_system_name:4400/sst. 

2. Select Service Groups on the left side of the window. The Services page opens on the 

right side: 

3. Click Add Service Group. The Service Group Creation page opens: 



4. Select a wizard, for example the Pass Through wizard, which brings a single Web 

service under management and creates an access point for that managed service. The 

Service Group - Identification page opens: 

5. Enter values for the service group properties: 


Name Enter a name for the service group. 

Type Optionally, specify the general type of service you are managing. 

Description Optionally, enter any additional information about the service group 

to help identify it later. 

6. Click Next. The Service Group - WSDL Source page opens: 

7. Enter the URL of the WSDL for the ESB process exposed as a web service. 



You can use the Sonic Management Console to find the WSDL URL: 

When you enter the WSDL URL you can append ?wsdl and Actional Intermediary 

will use dynamic WSDL retrieval to find the WSDL for the web service. Actional 

Intermediary imports the WSDL file from the location you specify and stores the 

WSDL internally. 

8. After dynamic WSDL retrieval, the Service Group - Select Service Port page shows 

the services, and their port, binding, operations, transport, and endpoint. In this 

example, there is one service exposed by the WSDL: 



9. Click Next and accept the default settings in the following Service Group - Select 

pages for: 

a. Operations — visible at the access point. For Sonic ESB it is the ESB process 

exposed by the WSDL. 

b. Sender — delivers the SOAP request to the managed service. For Sonic ESB, the 

transport is HTTP. 

c. Application — Web service you are bringing under management. In this example 

it is the default application. 

d. Documentation — optionally link to or enter. 

e. Security Contract — for the access point. This example uses HTTP with no 

security contract. 

f. Enable — URL to contact Actional Intermediary. 

10. Then click Finish. The Status page shows that the service group was successfully 

created: 

11. The service group is not activated by default. Click Activate to activate the service 

group. 

The Components section of the page shows the message flow through Actional 

Intermediary and its: 

■ Access points — where messages enter Actional Intermediary 

■ Managed services — where messages leave Actional Intermediary (the ESB 

process) 



12. If you select Service Groups in the list on the left side of the window, you can confirm 

that the new service group was added to the list on the Services page: 

For more information on service groups, see: 

● “Working with Service Groups” chapter in the Actional Intermediary Administration 

Guide 

● “Instrumenting Sonic ESB” chapter in the Actional Agent Interceptor Guide 



Define Trust Zones on Actional Server 

Follow these steps to define trust zones on Actional Server: 

1. “Bring Nodes under Actional Management” 

2. “Create and Configure Trust Zones” 

3. “Add Managed Nodes to a Trust Zone” 

Bring Nodes under Actional Management 

In Actional, a node is a system on the current network where an agent is running. You 

must bring the nodes where the Actional-enabled ESB containers are deployed as well as 

Actional Intermediary under Actional management. 

◆ To bring nodes under Actional management: 

1. Open a browser to the Actional Server administration console using the URL, 

your_system_name:4040/lgserver. 

2. In the Configure view, select the Network tab and select Nodes. The Network Nodes 

page shows the nodes under Actional management: 

3. To add a node, follow the steps in the “Configuring the Network” chapter in the 

Actional Server SOA Operations Administration Guide: 

■ The URL for the LG agent is typically host_name:port_number/lgagent. 

■ The default port number is 4041. 


Create and Configure Trust Zones 


The “Actional Server and Actional Intermediary” chapter in the Actional Server 

Continuous Service Optimization Guide describes how to configure Actional trust zones. 

However, certain default settings are not appropriate to use with Sonic ESB. 

◆ To create and configure an Actional trust zone for Sonic ESB: 

1. Select the Network tab and select Trust Zones. The Trust Zones page opens: 

2. Click Add. The New Trust Zone - General Information page opens with the default 

settings: 



3. Define the following properties for the trust zone: 


Name Assign a specific name to the trust zone. 

Trust Calls 

within Trust 

Zones 

Check Caller's 

IP Address 

Check this box (the default is unchecked). Non-Actional Intermediary 

interceptors can insert Actional trust assertion into the outbound 

headers. The message can go directly to any other service that is 

managed (for which an interceptor is checking for trust assertion) and 

it will pass the trust enforcement check. 

Remove the check from this box. The IP address of the caller (in the 

Actional headers) will not be checked. 

Next, specify the managed nodes for the trust zone. 


Add Managed Nodes to a Trust Zone 


The last step in defining trust zones is to add managed nodes to a trust zone and provision 

the agents. 

◆ To add managed nodes to a trust zone: 

1. Click Next in the New Trust Zone - General Information page. The New Trust Zone - 

Trusted Nodes page opens: 

2. Select the nodes (including the Actional Intermediary node) and click Add to add 

them to the list of nodes in the trust zone. (If you do not see a node you want to add, 

it might be in another trust zone. If so, select List all managed nodes.) 



3. Click Finish. The Trust Zone Details page shows the trust zone settings and the 

trusted nodes: 

4. Click the Provisioning link. The Provisioning page opens 

5. Select all the nodes added to the trust zone and click Provision. 


Index 

A 

Activation Daemon 79, 127 

retry rules 82 

add directory command 37 

add file command 37 

add license container command 41 

address factory 52 

addresses 87 

alternate servers 126 

DB2 140 

Informix 156 

Microsoft SQL Server 182 

Oracle 167 

Progress OpenEdge 130, 135 

Sybase 197 

applyMap command 46 

B 

Blob and binary stream data (DB2) 150 

boot files 53 

BPAR 231 

BPEL 

archive file 231 

audit trail 236, 248 

partner link 238 

process instance search 244 

profiling 250 

BPEL services 

configuring 227 

broker 

Actional instrumentation 56 

payload in Actional instrumentation 56 


C 

certificate-based authentication 111 

cipher suites 111 

clearing management container logs 68 

client load balancing 122 

code page 

converting character data 

DB2 142 

Informix 156 


Sybase 198 

overriding 

DB2 142 

Informix 156 

commands, ESB Admin Tool 35 

concurrent durable subscriptions 93, 99 

configuring 

BPEL services 227 

connections 106 

SonicMQ endpoints 97 

connect command 36 

connecting to domain manager 22 

connection 


connection URLs 108 

deleting 112

Index 

ESB 56 

for endpoints 98 

HTTP(S) 56 

JMS 56 

maximum at least once sessions 109 

maximum best effort sessions 109 

maximum exactly once sessions 109 

maximum receive sessions 109 

maximum Web Service sessions 109 

name 108 

name of domain 24 

ping interval 110 

type 108 

connection failover 123 

alternate servers 

DB2 140 

Informix 156 


Oracle 167 


Sybase 197 

connection retry 124 


DB2 143 

Informix 157 


Oracle 169 


Sybase 199 


DB2 144 

Informix 158 


Oracle 170 


Sybase 200 

DatabaseName 


connection URLs 


domain 24 

container list command 41 

createMap command 46 


D 

date format (Informix) 159 

DB2 

code page 

character data, converting 142 

connection properties 


CodePageOverride 142 

ConnectionRetryCount 143 

ConnectionRetryDelay 144 

DiagnosticFilename 145 

InsensitiveResultSetBufferSize 146 

LoadBalancing 147 

MaxPooledStatements 148 

ConnectionRetry 143 


DBClob data type mapping 154 

load balancing 147 

scalar functions 214 

state information log 145 

DBDate (Informix) 159 

debug tracing 76 

delete command 38, 40 

delete directory command 38 

delete file command 36 

deleting 

SonicMQ connections 112 

SonicMQ endpoints 101 

destination name for endpoints 99 


DB2 145 

Informix 160 


Oracle 170 

Sybase 200 

disconnect command 36 

domain manager 

connecting to 22 

starting 22 

domains 

connection name 24 

connection URL(s) of management broker 24 

name 24 

DRA, using 95 

dump command 40 

durable subscription, concurrent 99

E 

enable Actional instrumentation 

broker 56 

endpoints 



deleting 101 

durable subscription 99 

entry 88 

exit 88 

fault 88 

JMS destination name 99 

JMS destination type 98 


message prefetch count 100 

message prefetch threshold 100 

name 98 

priority 99 

Qualify of Service 98 

RME 89 

shared subscriptions 100 

time to live 100 

WSDL URL 98 

entry endpoints 88 

envelope factory 52 

ESB (JMS) connection 56 

ESB Admin 35 

ESB Admin Tool 

commands 35 

ESB Configured Objects 28 

ESB Container 

listeners 63 

exit endpoint 88 

export archive command 46 

export bootfile command 46 

export command 40 

export directory command 38 

export file command 38 

export license container command 41 

F 

factory 

address 52 

envelope 52 

message 52 

objects for container services 52 

failover 123 

fault endpoint 88 

fault tolerant client connections 101 

Index 


H 

HTTP routing connection 56 

http_defaultConnection 98 

I 

import archive command 47 

import command 40 

import file system command 47 

Informix 

code page 







DBDate 159 


InformixServer 160 






date format 159 





DB2 146 

Informix 160 


Oracle 171 

Progress OpenEdge 132 

Sybase 201

Index 

instrumentation payload, broker 56 

instrumentation, broker 56 

J 

JMS destination type 98 

JMS destinations 91 

jms_defaultConnection 98 

L 

launching management containers 68 

list command 39 

listeners 60 

listeners, number 63 


DB2 147 

Informix 161 


Oracle 172 

Sybase 202 

load balancing, endpoints 100 

LoadBalancing 


logging 76 

M 

management broker 

connection URL(s) 24 

management container logs 

clearing 68 

saving 68 

viewing 68 

management containers 

launching 68 

operations 68 

reload command 42 

resetting metrics 68 

restarting 68 

resume command 42 

shutdown command 41 

shutting down 68 

status command 42 

suspend command 42 

maximum 

at least once sessions 109 

best effort sessions 109 

exactly once sessions 109 

receive sessions 109 

Web Service sesions 109 


DB2 148 

Informix 162 


Oracle 173 


Sybase 203 

message 

factory 52 

prefetch threshold 100 

message prefetch count 100 


code page 

















N 

names 


domain 24 

endpoints 98 

notifications 73

O 

operations 

management containers 68 

Oracle 














outer joins 219 

P 

Password 


payload, Actional instrumentation 

broker 56 

ping interval, connection property 106, 110 

PortNumber 


primary servers 126 

priority 

endpoints 99 

Progress OpenEdge 132, 133, 134, 135 


alternate servers 130, 135 

ConnectionRetryCount 131, 135 

ConnectionRetryDelay 131, 135 

DatabaseName 132, 135 

Hostname 132 


LoadBalancing 133, 135 


Password 133 

PortNumber 134, 135 

SpyAttributes 134 

User 134 

ConnectionRetry 131, 135 


DatabaseName 132, 135 


LoadBalancing 133, 135 


Password 133 

PortNumber 134, 135 


SpyAttributes 134 

User 134 

Index 


Q 

Quality of Service 

endpoints 98 

queues 

creating 99 

R 

reconnection 104 

rejected message endpoint 89 

reload command 42 

resetting 

management container metrics 68 

resources 25 

restarting 

management containers 68 

resume command 42 

S 

saving management container logs 68 

scalar functions 

DB2 214 

Informix 215 


Oracle 216 


Sybase 218 

shared subscriptions 93 

endpoints 100 

shutdown container 41

Index 

shutting down management containers 68 

Sonic Management Console 23 

SonicFS 25 

Spy (DataDirect) 134 

SpyAttributes 


SSL 

CA certificates location 111 

certificate chain file 111 

certificate chain form 111 

cipher suites 111 

private key file 111 

private key password 111 

provider class 111 

starting 

domain manager 22 

state information log 

DB2 145 

Informix 160 


Oracle 170 

Sybase 200 

support, technical 17 

suspend command 42 

Sybase 

code page 
















T 

technical support 17 

threads, listener 63 

time to live 

endpoints 100 

type, connections 108 


U 

User 


V 

viewing management container logs 68 

W 

Web Service sessions 

maximum 109 

WSDL URL 

endpoints 98

Progress Sonic 8.0 ESB Configuration and Management Guide

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?