Web Methods JDBC Adapter User's Guide 6.0.3

webMethods JDBC Adapter
Users Guide
VERSION 6.0.3
webMethods, Inc. South Tower 3877 Fairfax Ridge Road Fairfax, VA 22030 USA 703.460.2500 http://www.webmethods.com
webMethodsAccess,webMethodsAdministrator,webMethodsBroker,webMethodsDashboard,webMethodsDeveloper,webMethodsFabric,webMethods Glue,webMethodsInstaller,webMethodsIntegrationServer,webMethodsMainframe,webMethodsManager,webMethodsModeler,webMethodsMonitor, webMethodsOptimize,webMethodsPortal,webMethodsServicenet,webMethodsTradingNetworks,andwebMethodsWorkflowaretrademarksof webMethods,Inc.webMethodsandthewebMethodslogoareregisteredtrademarksofwebMethods,Inc. AcrobatandAdobeareregisteredtrademarks,andReaderisatrademarkofAdobeSystemsIncorporated.Amdocsisaregisteredtrademark,andClarifyCRM isatrademarkofAmdocs.AribaisaregisteredtrademarkofAriba,Inc.BEA,BEAWebLogicServer,Jolt,andTuxedoareregisteredtrademarks,andBEA WebLogicPlatformisatrademarkofBEASystems,Inc.ActionRequestSystem,BMCSoftware,PATROL,andRemedyareregisteredtrademarksofBMC Software,Inc.BroadVisionisaregisteredtrademarkofBroadVision,Inc.ChemeStandardsandCIDXaretrademarksofChemicalIndustryDataExchange. UnicenterisaregisteredtrademarkofComputerAssociatesInternational,Inc.PopChartisaregisteredtrademarkofCORDATechnologies,Inc.Kenanand ArborareregisteredtrademarksofCSGSystems,Inc.DataConnectionandSNAPIXareregisteredtrademarksofDataConnectionCorporation.DataDirect, DataDirectConnect,andSequeLinkareregisteredtrademarksofDataDirectTechnologies.D&BandDUNSareregisteredtrademarksofDun&Bradstreet Corporation.EntrustisaregisteredtrademarkofEntrust,Inc.papiNetisaregisteredtrademarkoftheEuropeanUnionandtheUnitedStates.Financial InformationeXchange,F.I.X,andF.I.XProtocolaretrademarksofFIXProtocolLtd.UCCnetandeBusinessReadyareregisteredtrademarks,and1SYNCand TransoraaretrademarksofGS1US.HewlettPackard,HP,HPUX,OpenView,PARISC,andSNAplus2aretrademarksofHewlettPackardCompany.i2isa registeredtrademarkofi2Technologies,Inc.AIX,AS/400,CICS,DB2,Domino,IBM,Informix,Infoprint,Lotus,LotusNotes,MQSeries,OS/390,OS/400, RACF,RS/6000,SQL/400,S/390,System/390,VTAM,z/OS,andWebSphereareregisteredtrademarks;andCommunicationsSystemforWindowsNT,DB2 UniversalDatabase,IMS,MVS,andSQL/DSaretrademarksofIBMCorporation.InnoDBisatrademarkofInnobaseOy.Itaniumisaregisteredtrademarkof IntelCorporation.JBossisaregisteredtrademark,andJBossGroupisatrademarkofJboss,Inc.LinuxisaregisteredtrademarkofLinusTorvalds.W3Cisa registeredtrademark,andXWindowSystemisatrademarkoftheMassachusettsInstituteofTechnology.MetaSolvisaregisteredtrademarkofMetasolv Software,Inc.ActiveX,Microsoft,Outlook,VisualBasic,Windows,andWindowsNTareregisteredtrademarks;andWindowsServerisatrademarkof MicrosoftCorporation.SixSigmaisaregisteredtrademarkofMotorola,Inc.Firefoxisaregisteredtrademark,andMozillaisatrademarkoftheMozilla Foundation.MySQLisaregisteredtrademarkofMySQLAB.nCipherisatrademarkofnCipherCorporationLtd.TeradataisaregisteredtrademarkofNCR International,Inc.NetscapeisaregisteredtrademarkofNetscapeCommunicationsCorporation.SUSEisaregisteredtrademarkofNovell,Inc.ServletExecis aregisteredtrademark,andNewAtlantaisatrademarkofNewAtlantaCommunications,LLC.CORBAisaregisteredtrademarkofObjectManagement Group,Inc.JDEdwards,OneWorld,Oracle,PeopleSoft,Siebel,andVantiveareregisteredtrademarks,andPeopleSoftPureInternetArchitectureand WorldSoftwarearetrademarksofOracleCorporation.InfranetandPortalaretrademarksofPortalSoftware,Inc.RedHatisaregisteredtrademarkofRed Hat,Inc.PIPandRosettaNetaretrademarksofRosettaNet,anonprofitorganization.SAPandR/3areregisteredtrademarksofSAPAG.SWIFTand SWIFTNetareregisteredtrademarksofSocietyforWorldwideInterbankFinancialTelecommunicationSCRL.SPARCandSPARCStationareregistered trademarksofSPARCInternational,Inc.SSAisaregisteredtrademark,andBaanandSSAGlobalaretrademarksofSSAGlobalTechnologies,Inc.EJB, EnterpriseJavaBeans,Java,JavaServer,JDBC,JSP,J2EE,Solaris,Sun,andSunMicrosystemsareregisteredtrademarks;andJavaNamingandDirectory Interface,SOAPwithAttachmentsAPIforJava,JavaServerPages,andSunSoftaretrademarksofSunMicrosystems,Inc.Sybaseisaregisteredtrademarkof Sybase,Inc.VERITASisaregisteredtrademark,andVERITASClusterServerisatrademarkofSymantecCorporation.UNIXisaregisteredtrademarkofThe OpenGroup.UnicodeisatrademarkofUnicode,Inc.VeriSignisaregisteredtrademarkofVerisign,Inc. Allothermarksarethepropertyoftheirrespectiveowners. Copyright20032006bywebMethods,Inc.Allrightsreserved,includingtherightofreproductioninwholeorinpartinanyform.
Document ID: ADAPTER-JDBC-UG-603-20060704
Contents
Contents
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7
7 8
Chapter 1. Overview of the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

About the JDBC Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Architectural Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using JDBC Drivers to Connect to Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transaction Management of JDBC Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connection Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Runtime Behavior of Connection Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Built-In Services For Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the Connection Associated with an Adapter Service or Notification at Design Time . Changing the Connection Associated with an Adapter Service at Runtime . . . . . . . . . . . . . . . . Adapter Service Transaction Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Notification Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exactly Once Notification Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Notification Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Insert Notifications, Update Notifications, and Delete Notifications . . . . . . . . . . . . . . . . . . . Basic Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stored Procedure Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ordered Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Polling Notification Support in Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Polling Notifications and States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . webMethods Manager Support for the JDBC Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Different Perspectives of the webMethods Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing the Adapters Update Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9
10 11 13 13 14 15 16 16 16 17 19 19 20 21 22 23 24 24 24 28 31 35 41 41 43 43 44
Chapter 2. Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
45
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 JDBC Adapter Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Package Dependency Requirements and Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
webMethods JDBC Adapter Users Guide Version 6.0.3
Contents
Enabling and Disabling Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Importing and Exporting Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Group Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC Adapter in a Clustered Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What is webMethods Integration Server Clustering? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC Adapter Polling Notification Support in Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Polling Notification Support in Clusters with Integration Server Version 6.0.1 SP2 . . . . . . Polling Notification Support in Clusters with Integration Server Version 6.5 . . . . . . . . . . . . Adapter Service Support in Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Replicating Packages to webMethods Integration Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling the Redirection of Administrative Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Clustering Considerations and Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Requirements for Each Integration Server in a Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . Considerations When Installing JDBC Adapter Packages . . . . . . . . . . . . . . . . . . . . . . . . . Considerations When Configuring Connections with Connection Pooling Enabled . . . . . .
48 49 49 49 49 50 50 54 61 61 61 62 62 63 63
Chapter 3. JDBC Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Before Configuring or Managing Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting the Environment Variable for Oracle JDBC OCI Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing the JDBC Driver on the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring JDBC Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dynamically Changing a Services Connection at Runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Adapter Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Copying Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 66 67 67 68 81 82 82 83 84 85 85
Chapter 4. Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Before Configuring or Managing Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring SelectSQL Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring InsertSQL Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring UpdateSQL Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring BatchInsertSQL Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring BatchUpdateSQL Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring DeleteSQL Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring CustomSQL Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring DynamicSQL Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 88 89 92 95 99 102 106 109 111
Contents
Using Input and Output Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring a DynamicSQL Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a DynamicSQL Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring StoredProcedure Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validating Adapter Service Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reloading Adapter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
112 112 113 115 119 119 120 120 121 121
Chapter 5. Adapter Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Before Configuring or Managing Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring InsertNotifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring UpdateNotifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring DeleteNotifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring BasicNotifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring StoredProcedureNotifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring OrderedNotifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Polling Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Exactly Once Notification Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling Exactly Once Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exporting Configured Adapter Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validating Adapter Notification Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reloading Adapter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 124 125 129 134 138 142 145 149 152 152 153 153 154 154 155 155
Chapter 6. Logging and Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC Adapter Message Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC Adapter Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AdapterException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AdapterConnectionException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SQLException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing the Adapters List of Fatal Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC Adapter Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 158 159 159 160 160 160 161
Contents
Appendix A. Data Type Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

JDBC Data Type to Java Data Type Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 JDBC Data Type to Java Data Type Mapping Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 SQL Data Type to JDBC Data Type Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Appendix B. Built-In Transaction Management Services . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Transaction Management Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transaction Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XA Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implicit and Explicit Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implicit Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Explicit Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implicit and Explicit Transaction Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Flow Example: ValidMixed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Flow Example: SingleLocalInsert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Flow Example: ValidMixed2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Flow Example: ValidDoubleLocal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Built-In Transaction Management Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pub.art.transaction:commitTransaction 183 pub.art.transaction:rollbackTransaction 184 pub.art.transaction:setTransactionTimeout 184 pub.art.transaction:startTransaction 185 Changing the Integration Server Transaction Timeout Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 174 174 175 175 175 176 177 179 180 181 182 183
186
Appendix C. Database Driver Known Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Driver Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Appendix D. Determining Whether to Use the WmDB Package or the JDBC Adapter . . . 193
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 When to Use the WmDB Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 When to Use the webMethods JDBC Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
About This Guide
About This Guide

ThisguidedescribeshowtoconfigureandusethewebMethodsJDBCAdapter Version 6.0.3.Itcontainsinformationforadministratorsandapplicationdeveloperswho wanttoexchangedatawithrelationaldatabasesusingaJDBCdriver. Tousethisguideeffectively,youshouldbefamiliarwith: JDBCdrivers DatabaseconceptsandbasicSQL Terminologyandbasicoperationsofyouroperatingsystem webMethodsIntegrationServerandDeveloperbasicconceptsandtasks
Document Conventions
Convention Bold Italic Description Identifieselementsonascreen. Identifiesvariableinformationthatyoumustsupplyorchange basedonyourspecificsituationorenvironment.Identifies termsthefirsttimetheyaredefinedintext.Alsoidentifies serviceinputandoutputvariables. IdentifiesstoragelocationsforservicesonthewebMethods IntegrationServerusingtheconventionfolder.subfolder:service. Identifiescharactersandvaluesthatyoumusttypeexactlyor messagesthatthesystemdisplaysontheconsole. Identifieskeyboardkeys.Keysthatyoumustpress simultaneouslyarejoinedwiththe+symbol. Directorypathsusethe\directorydelimiterunlessthe subjectisUNIXspecific. Optionalkeywordsorvaluesareenclosedin[].Donottype the[]symbolsinyourowncode.
Narrow font
Typewriter font
UPPERCASE \ []
About This Guide
Additional Information
ThewebMethodsAdvantageWebsiteathttp://advantage.webmethods.comprovidesyou withimportantsourcesofinformation: Troubleshooting Information.webMethodsprovidestroubleshootinginformationfor manywebMethodscomponentsinthewebMethodsKnowledgeBase. Documentation Feedback.ToprovidedocumentationfeedbacktowebMethods,gotothe DocumentationFeedbackFormonthewebMethodsBookshelf. Additional Documentation.AllwebMethodsdocumentationisavailableonthe webMethodsBookshelf.Besuretocheckforanyupdatesoradditionalinformation abouttheJDBCAdapter.
CHAPTER
Overview of the Adapter

About the JDBC Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Architectural Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11 Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Adapter Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 webMethods Manager Support for the JDBC Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Viewing Different Perspectives of the webMethods Developer . . . . . . . . . . . . . . . . . . . . . . . 43 Viewing the Adapters Update Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
CHAPTER 1 Overview of the Adapter
About the JDBC Adapter

ThewebMethodsJDBCAdapterisanaddontothewebMethodsIntegrationServerthat enablesyoutoexchangedatawithrelationaldatabasesthroughtheuseofaJDBCdriver. Theadapterprovidesseamlessandrealtimecommunicationwiththedatabasewithout requiringchangestoyourexistingapplicationinfrastructure. UsingtheJDBCAdapter,webMethodsIntegrationServerclientscancreateandrun servicesthatexecutetransactionstoretrievedatafrom,andinsertandupdatedatain, relationaldatabases. Forexample,youcanusetheJDBCAdaptertoaddacustomertoanOracledatabase basedondatafromanothersystemconnectedtotheIntegrationServer.Oryoucanuse theJDBCAdaptertopollaMicrosoftSQLServerdatabaseforcustomersthathavebeen addedtothedatabase,andtosendthatdatatotheIntegrationServertobeinsertedinto anotherresource. TheJDBCAdaptersupportsthefollowingdatabases: DB2forAS/400 DB2forOS/390 DB2UniversalDatabase(UDB) IBMInformix MicrosoftSQLServer Oracle Sybase Teradata Foralistofthedatabaseversions,JDBCdrivers,andplatformsthattheJDBCAdapter supports,seethewebMethodsJDBCAdapterInstallationGuide. Foralistofknowndriverlimitations,seeDatabaseDriverKnownLimitationson page 187. InadditiontotheJDBCAdapter,webMethodsalsoprovidestheWmDBpackagethatyou canusetoconnecttodatabases.However,theJDBCAdapterprovidesmorefunctionality, improvedperformance,andsupportsadapternotifications.Tohelpyoudetermine whetheryoushouldusetheWmDBpackageortheJDBCAdapter,seeAppendix D, DeterminingWhethertoUsetheWmDBPackageortheJDBCAdapter.Formore informationabouttheWmDBpackage,seetheWmDBusersguide.
10
Architectural Overview
Architectural Overview
TheJDBCAdapterprovidesasetofuserinterfaces,services,andtemplatesthatenable youtocreateintegrationswithdatabasesusingaJDBCdriver.Theadapterisprovidedas asinglepackagethatmustbeinstalledonthewebMethodsIntegrationServer.For detailedinstallationinstructionsandsoftwarerequirements,seethewebMethodsJDBC AdapterInstallationGuide. BecausetheJDBCAdapterusesaJDBCdrivertoperformoperationsondatabases,the adapterrequiresasupportedJDBCdrivertobeinstalledandloadedinthepackages directoryoftheIntegrationServer.SeeJDBCAdapterPackageManagementonpage 46 formoredetails. TheJDBCAdapterenablesyoutoconfigurethefollowingcomponents: Adapter connections:EnabletheIntegrationServertoconnecttodatabasesystemsat runtime.Youmustconfigureanadapterconnectionbeforeyoucanconfigureadapter servicesoradapternotifications.SeeAdapterConnectionsonpage 13foradetailed descriptionofadapterconnections. Adapter services:EnabletheIntegrationServertoinitiateandperformdatabase operationsonadatabase.Forexample,anadapterservicecouldenableatrading partnertoqueryyourinventorydatabasetodeterminewhetheraparticularitemis currentlyinstock.Youconfigureadapterservicesusingadapterservicestemplates, whichareprovidedwiththeJDBCAdapter.SeeAdapterServicesonpage 17fora detaileddescriptionofadapterservices. Adapter notifications:MonitoradatabaseandnotifytheIntegrationServerwhenan action(notinitiatedbytheIntegrationServer)hasoccurredonaparticulardatabase table.Forexample,anadapternotificationcouldnotifytheIntegrationServerwhen anupdateoperationwasperformedonaparticulardatabasetable.SeeAdapter Notificationsonpage 22foradetaileddescriptionofadapternotifications.
11
Thefollowingdiagramshowsatahighlevelhowanadapterserviceusesanadapter connectionandaJDBCdrivertoconnecttoandperformanoperationonadatabase.
webMethods Integration Server (WmART) JDBC Adapter (WmJDBCAdapter) Adapter Service Adapter Connection Database JDBC Driver
Thenextdiagramshowsabusinessintegrationwhereanadapterserviceisusedtoupdate adatabasewithemployeedata.Theemployeedatacouldbeprovidedbyseveraldifferent typesofexternalIntegrationServer(IS)clients.

Various backend systems send Employee data to the Integration Server via an IS client, invoking a service on the Integration Server. A flow or Java service on the Integration Server invokes an adapter service created using the Adapter X. The adapter service uses an adapter connection to connect to the database via a JDBC driver.
Legacy System
Java, C/C++, VB webMethods Client
Employee ___ ____ ___ I N T E R N E T
webMethods Integration Server Flow/Java Service JDBC Adapter Adapter Service Adapter Connection
webMethods Integration Server ERP System Services
Employee ___ ____ ___
Web browser or webMethods Client
Employee ___ ____ ___
JDBC Driver
The adapter service issues a SQL statement to update the database with the Employee data.
Database
12
Package Management
Thearchitectureforintegrationsusingadapternotificationsissimilartothearchitecture forintegrationsusingadapterservicesshownabove,butitvariesaccordingtothetypeof notification.Theprimarydifferencebetweenthesetypesofintegrationsisthat notificationsareinitiatedbyeventsthatoccuronthedatabase,notbyactionsthatoccur ontheIntegrationServer. Withadapternotifications,youcancaptureeventdatafromthedatabaseanduseitto initiateanotheractionwithintheIntegrationServer.Forexample,youcouldcreatean adapternotificationtomonitoranemployeetablewithinadatabaseandwheneveran employeeisaddedtothetable,youcouldpostthatemployeedatatoawebMethods Broker.webMethodsBrokerclientscouldthensubscribetothatnotificationspublishable document. SeeAdapterNotificationsstartingonpage 22formoreinformationaboutthe architectureforthedifferenttypesofadapternotifications.
Package Management
TheJDBCAdapterisprovidedasapackagecalledWmJDBCAdapterthatyoumanage likeanypackageontheIntegrationServer. Thereareseveralconsiderationsregardinghowyousetupandeffectivelymanageyour packagesontheIntegrationServer: Youmustcreateuserdefinedpackagesforyourconnections,adapterservices,and notifications.SeeJDBCAdapterPackageManagementonpage 46fordetails. Youshouldunderstandhowpackagedependenciesworksoyoumakethebest decisionsregardinghowyoumanageyouradapterservicesandnotifications.See PackageDependencyRequirementsandGuidelinesonpage 47fordetails. Youcontrolwhichdevelopmentgroupshaveaccesstowhichadapterservicesand notifications.SeeGroupAccessControlonpage 49fordetails. Youshouldunderstandhowclustering,anadvancedfeatureofthewebMethods IntegrationServer,workstoeffectivelymanageyouradapterservices.SeeJDBC AdapterinaClusteredEnvironmentonpage 49fordetails.
Adapter Connections
TheJDBCAdapterconnectstoadatabasethroughaJDBCdriveratruntime.Youcreate oneormoreconnectionsatdesigntimetouseinintegrations.Thenumberofconnections youcreate,andthetypesofthoseconnections,dependonthetypesofdatabasesyouare connectingtoandyourintegrationneeds.Forexample,ifyouareconnectingtoanOracle databaseandaDB2Serverdatabase,youwillneedtocreateconnectionsthatareunique tothosetwodatabases.Additionally,ifyouhavemultipleinstallationsofthesamekinds ofdatabases,youaccesseachusingdifferentconnections.Forexample,ifyouhaveadata
13
warehousesystemandanERPsystemthatuseyourOracledatabase,youcreatea connectionforeachsystem. JDBCAdapterconnectionscontainparametersthattheIntegrationServerusestomanage connectionstothedatabasesothattheycanbeusedbytheJDBCAdaptertoprovide services.YouconfigureconnectionsusingthewebMethodsIntegrationServer Administratortool.YoumusthavewebMethodsadministratorprivilegestoaccessthe JDBCAdaptersadministrativescreens. Forinstructionsforconfiguring,viewing,editing,enabling,anddisablingJDBCAdapter connections,seeJDBCAdapterConnectionsonpage 65.Forinformationaboutsetting userprivileges,seethewebMethodsIntegrationServerAdministratorsGuide. Foralistoftasksthatyoumustdobeforeyoucancreateyourconnections,seeBefore ConfiguringorManagingAdapterConnectionsonpage 66.
Using JDBC Drivers to Connect to Databases

JDBCAdapterconnectionsaccessdatabasesusingeitherthedriversDataSourceor XADataSourceobjectsprovidedbyyourJDBCdriver.Formoreinformationabout DataSourceandXADataSourceobjects,seethedocumentationprovidedwithyourJDBC driver. TheJDBCdrivermustbeinstalledontheIntegrationServermachineandloadedwhen theserverstarts.SeeInstallingtheJDBCDriverontheIntegrationServeronpage 67for instructions. Note: IfyouplantouseCLOBsorBLOBsthatexceed4KB,besuretouseanOracleOCI driverorOracle10gThindriver. FormoreinformationaboutthetransactiontypessupportedintheJDBCAdapter,see TransactionManagementofJDBCAdapterConnectionsonpage 15. ForacompletelistoftheJDBCdriversthattheadaptersupports,seethewebMethodsJDBC AdapterInstallationGuide. Foralistofknowndriverlimitations,seeDatabaseDriverKnownLimitationson page 187.
14
Adapter Connections
Transaction Management of JDBC Adapter Connections

JDBCAdapterconnectionssupportthefollowingtransactiontypes: Transaction Type NO_TRANSACTION Description Theconnectionprovidesnotransactioncontroloverthe operationsbeingperformed.Thatis,theconnection automaticallycommits(AutoCommit)alloperations. Withthistransactiontype,alloftheoperationsonthe sameconnectioninonetransactionboundarywillbe committedorrolledbacktogether.Atransaction boundarymeansthescopeofthetransaction,fromthe beginningtotheendofatransaction.Itcanbeinone adapterservice,oneflowservice,oneJavaservice,or severalstepsinaflowservice. Thistransactiontypeallowstheconnectiontosupport twophasetransactionsexecutedacrossmultiple databases.Inonetransactionboundary,allofthe operationsonmultipleconnectionswillbecommittedor rolledbacktogether.Atransactionboundarymeansthe scopeofthetransaction,fromthebeginningtotheend ofatransaction.Itcanbeinoneadapterservice,one flowservice,oneJavaservice,orseveralstepsinaflow service. Note: Alloftheconnectionsinvolvedinatwophase transactionmustsupporttheXA_TRANSACTION transactiontype.
LOCAL_TRANSACTION
XA_TRANSACTION
Note: InsertNotifications,UpdateNotifications,DeleteNotificationsandOrdered NotificationssupportLOCAL_TRANSACTIONmodeonly. Whenyoudefineaconnection,thetransactiontypethatyouchoosedeterminesthetype oftransactionmanagementthattheconnectionsoperationsuseimplicitly.Implicit transactions,whichincludethetransactionstypesintheprecedingtable,aremanagedby theIntegrationServertransactionmanager. Youcanalsoexplicitlymanagetransactionsusingbuiltinservices.SeeAppendix B, BuiltInTransactionManagementServices,forinformationabout,andexamplesof, explicitlymanagingtransactions.
15
Connection Pools
TheIntegrationServerincludesaconnectionmanagementservicethatdynamically managesconnectionsandconnectionpoolsbasedonconfigurationsettingsthatyou specifyfortheconnection.Alladapterservicesuseconnectionpooling. Aconnectionpoolisacollectionofconnectionswiththesamesetofattributes.The IntegrationServermaintainsconnectionpoolsinmemory.Connectionpoolsimprove performancebyenablingadapterservicestoreuseopenconnectionsinsteadofopening newconnections.
Runtime Behavior of Connection Pools

Whenyouenableaconnection,theIntegrationServerinitializestheconnectionpool, creatingthenumberofconnectioninstancesyouspecifiedintheconnectionsMinimum Pool Sizefieldwhenyouconfiguredtheconnection.Wheneveranadapterserviceneedsa connection,theIntegrationServerprovidesaconnectionfromthepool.Ifnoconnections areavailableinthepool,andthemaximumpoolsizehasnotbeenreached,theserver createsoneormorenewconnections(accordingtothenumberspecifiedinthePool Increment Sizefield)andaddsthemtotheconnectionpool.Ifthepoolisfull(asspecifiedin Maximum Pool Size field),therequestingservicewillwaitfortheIntegrationServerto obtainaconnection,uptothelengthoftimespecifiedintheBlock Timeoutfield,untila connectionbecomesavailable.Periodically,theIntegrationServerinspectsthepooland removesinactiveconnectionsthathaveexceededtheexpirationperiodthatyouspecified intheExpire Timeout field. IfyouareusingversionsoftheIntegrationServerearlierthan6.1andtheconnectionpool initializationfailsbecauseofanetworkconnectionfailureorsomeothertypeofexception, youmustdisabletheconnection,fixtheproblem,andreenabletheconnection.When usingIntegrationServer6.1orlater,however,youcanenablethesystemtoretrythe initializationanynumberoftimes,atspecifiedintervals.Forinformationabout configuringconnections,seeChapter 3,JDBCAdapterConnections,onpage 65.
Built-In Services For Connections

Beginningwithversion6.1,theIntegrationServerprovidesbuiltinservicesthatenable youtoprogrammaticallycontrolconnections.Youcanusethemtoenableanddisablea connection,andtoreturnusagestatisticsandthecurrentstate(EnabledorDisabled)and errorstatusforaconnection.TheseservicesarelocatedintheWmARTpackage,inthe pub.art.connectionfolder. Therearetwobuiltinservices,setAdapterServiceNodeConnection and setPollingNotificationNodeConnection,thatenableyoutochangetheconnectionassociatedwith anadapterserviceornotificationrespectively.SeeChangingtheConnectionAssociated withanAdapterServiceorNotificationatDesignTimeonpage 19. Fordetails,seethewebMethodsIntegrationServerBuiltInServicesReference,whichis availablefromtheHelpmenuofthewebMethodsDeveloper.
16
Adapter Services
Adapter Services
TousetheJDBCAdapter,youcreateadapterservices.Adapterservicesallowyouto connecttotheadaptersresourceandinitiateanoperationontheresourcefromthe IntegrationServer. YoucalladapterservicesfromfloworJavaservicestointeractwithdatabasetables.The adapterservicesperformdatabaseoperationsbycallingJDBCAPIs.TheIntegration Serverthenusesadapterconnectionsthatyoudefinedearliertoexecutetheadapter services.SeeAdapterServiceTransactionProcessingonpage 21fordetails. AdapterservicesarebasedontemplatesprovidedwiththeJDBCAdapter.Eachtemplate representsaspecifictechniquefordoingworkonaresource,suchasusingtheSelectSQL templatetoretrievespecifiedinformationfromadatabase. Anadapterservicetemplatecontainsallthecodenecessaryforinteractingwiththe resourcebutwithoutthedataspecifications.Youprovidethesespecificationswhenyou createanewadapterservice. Creatinganewservicefromanadapterservicetemplateisstraightforward.Usingthe webMethodsDeveloper,youassigntheserviceadefaultadapterconnection. Afteryouselecttheconnectionfortheadapterservice,youselecttheadapterservice templateandsupplythedataspecificationsusingthewebMethodsDeveloper.Some familiaritywithusingthewebMethodsDeveloperisrequired.SeethewebMethods DeveloperUsersGuideformoreinformation. TheJDBCAdapterprovidesthefollowingadapterservicetemplates: Adapter Service Type SelectSQL Adapter Service Template SelectSQL
Description Retrievesspecifiedinformationfroma databasetable. SeeConfiguringSelectSQLServiceson page 89forinstructions.
InsertSQL
InsertSQL
Insertsnewinformationintoadatabasetable. SeeConfiguringInsertSQLServiceson page 92forinstructions.
UpdateSQL
UpdateSQL
Updatesexistinginformationinadatabase tableandincludesamappingforanoutput fieldthatstoresthenumberofaffectedrows. SeeConfiguringUpdateSQLServiceson page 95forinstructions.
17
Adapter Service Type BatchInsertSQL
Adapter Service Template BatchInsertSQL
Description Insertsnewinformationintoadatabasetable. Usethisservicewhenyouwillbeinsertinga largevolumeofdataintoasingletable.The datasourcefortheservicecanbefromaflat fileorfromotherservicesthatgeneratean IntegrationServerdocumentlist. SeeConfiguringBatchInsertSQLServices onpage 99forinstructions.
BatchUpdate SQL
BatchUpdateSQL
Updatesinformationinadatabasetablewhen dealingwithalargevolumeofdata.Usethis servicewhenyouwillbeupdatingalarge volumeofdatainasingletable.Thedata sourcefortheservicecanbefromaflatfileor fromotherservicesthatgeneratean IntegrationServerdocumentlist. SeeConfiguringBatchUpdateSQLServices onpage 102forinstructions.
DeleteSQL
DeleteSQL
Deletesrowsfromatableandincludesa mappingforanoutputfieldthatstoresthe numberofaffectedrows. SeeConfiguringDeleteSQLServiceson page 106forinstructions.
CustomSQL
CustomSQL
DefinesandexecutescustomSQLtoperform databaseoperations.Youcanexecutealmost anySQLstatementrequiredbyintegrations, suchasdatamanagementstatements. SeeConfiguringCustomSQLServiceson page 109forinstructions.
DynamicSQL
DynamicSQL
DefinesandexecutesaSQLstatement,partof whichyousetatruntimethroughtheinput field. SeeConfiguringDynamicSQLServiceson page 111forinstructions.
StoredProcedure
StoredProcedure
Callsastoredproceduretoperformdatabase operations. SeeConfiguringStoredProcedureServices onpage 115forinstructions.
18
Adapter Services
Using Adapter Services

Thefollowingtableliststhetasksrequiredtouseadapterservices: For this task... 1 2 Createanadapterconnection.SeeJDBCAdapter Connectionsonpage 65fordetails. Selecttheappropriateadapterservicetemplateand configuretheadapterservice.Dependingonthetypeof adapterservice,youspecifythe: Adapterconnection Databasetable SQLexpressionusedtomodifyorselectdata,ora storedproceduretoexecuteagainstthedatabase(for StoredProcedureAdapterServices) Inputfield(s)andtype(s)asneeded Outputfield(s)andtype(s)asneeded SeeAdapterServicesonpage 87formoreinformation aboutconfiguringadapterservices. 3 IfyouplantouseanIntegrationServerfloworJava servicetoinvoketheadapterservice,designtheflowor Javaservicetousethisadapterservice. Managetheadapterservice.SeePackageManagement onpage 45,AdapterServicesonpage 87,andLogging andExceptionHandlingonpage 157fordetails. Developer Use these tools... IntegrationServer Administrator Developer
Developerand IntegrationServer Administrator
Changing the Connection Associated with an Adapter Service or Notification at Design Time
WhenusingversionsoftheIntegrationServerearlierthan6.1youmaynotassigna differentconnectiontoanadapterserviceornotificationafteryouconfiguretheadapter service.(Youmay,however,changetheparametersoftheconnection.)Ifyouwanttousea differentconnection,youmustcreateanewadapterserviceornotificationthatspecifies thisnewconnection.Forexample,thismeansthatinordertousethesameadapterservice formultipledatabaseservers,youmustconfiguremultiple,separateadapterservices,one foreachconnectionyouuse. Beginningwithversion6.1,theIntegrationServersolvesthislimitationbyproviding builtinservicesthatyoucanuseatdesigntimetochangetheconnectionassociatedwith anadapterserviceornotification.Thesebuiltinservicesarenamed setAdapterServiceNodeConnection and setPollingNotificationNodeConnection andareprovidedinthe
19
WmARTpackagespub.art.servicefolder.Usingthisfunction,youcanchangethespecific connectionassociatedwithanadapterserviceatdesigntimesothatyoudonotneedto createandmaintainmultipleadapterservices. Note: Thisbuiltinservicecanberunatdesigntimeonly;donotuseitwithinan IntegrationServerfloworJavaservice.Youmustrunthisservicedirectlyfromthe DeveloperbyselectingtheserviceintheDeveloperandrunningit. Fordetails,seethewebMethodsIntegrationServerBuiltInServicesReference,whichis availablefromtheHelpmenuofthewebMethodsDeveloper. Otherbuiltinservicesenableyoutocontrolconnections;formoreinformation,seeBuilt InServicesForConnectionsonpage 16.
Changing the Connection Associated with an Adapter Service at Runtime

Beginningwithversion6.5,theIntegrationServerenablesyoutodynamicallyselectthe connectionaserviceusestointeractwiththeadaptersresource.Thisfeatureenablesone servicetointeractwithmultiple,similarbackendresources. Forexample,aservicecanbedefinedtouseadefaultconnectionthatinteractswithyour companysproductiondatabase.However,atruntimeyoucanoverridethedefault connectionandinsteaduseanotherconnectiontointeractwiththecompanystest database. Formoreinformationaboutoverridingaservicesdefaultconnectionatruntime,see DynamicallyChangingaServicesConnectionatRuntimeonpage 81.
20
Adapter Services
Adapter Service Transaction Processing

ThefollowingdiagramillustrateshowtheJDBCAdapterprocessesadapterservicesat runtime.
webMethods Integration Server
webMethods Integration Server client
Connection Pool
Adapter Service
Connection
3 4
JDBC Driver Database
Step
1
Description AnIntegrationServerclient,typicallyusingafloworJavaservice,invokes aJDBCAdapterserviceonthewebMethodsIntegrationServertoperform anoperationonadatabase. YouconfiguredtheadapterserviceearlierusingthewebMethods Developer.
Theadapterservicegetsaconnectionfromtheservicesconnectionpool. Adapterconnectionscontainconnectioninformationforthedatabase, includingJDBCdriverparameters.
TheadapterserviceusestheJDBCdrivertoconnecttothedatabase. Youcreatedandenabledtheadapterconnectionearlierusingthe IntegrationServerAdministrator.
21
Step
4
Description TheadapterserviceperformsaSQLoperationagainstthedatabase. ForSelectSQL,InsertSQL,UpdateSQL,DeleteSQL,CustomSQL,and DynamicSQLservices,theadapterserviceexecutesaSQLstatement againstthedatabase. ForBatchInsertSQLandBatchUpdateSQLservices,theadapterservice executesbatchSQLstatementsagainstthedatabase.Theadapter servicewillcontinuetoloopthroughthedocumentlistthatisusedas input,setthefieldstotheparametersoftheSQLstatementandthen addthatcommandsettothebatch.Uponcompletion,theadapter sendstheentirebatchtothedatabaseresourceforexecution. ForStoredProcedureservices,theadapterserviceexecutesastored procedureagainstthedatabase.
Dependingontheadapterservicetype,suchasaSelectSQLservice,the adapterservicemayreturndatatotheIntegrationServer. Iftheoperationissuccessful,theservicereturnstheoutputfromthe servicesdatabaseoperation,ifapplicable. WithBatchInsertSQLandBatchUpdateSQLservices,ifallcommands aresuccessfullyexecuted,theadaptercommitsallcommandsinthe batchandreturnsalistofStringvalues.Thesevalueswillvaryby driver;refertoyourdriverdocumentationfordetails. Iftheoperationisunsuccessful,theservicereturnsanerrorsuchasan AdapterException.Ifthedatabasethrowsanexceptionwhile performingtheadapterservicesoperation,theadapterpassesthe exceptiontotheIntegrationServerlogs. Formoreinformationabouthowtheadapterhandlesexceptions,see JDBCAdapterExceptionHandlingonpage 159.
Adapter Notifications
Anadapternotificationmonitorsaspecifieddatabasetableforchanges,suchasaninsert, update,ordeleteoperation,sothattheappropriateJavaorflowservicescanmakeuseof thedata,suchassendinganinvoiceorpublishingittotheIntegrationServer. JDBCAdapternotificationsarepollingbased.Thatis,theIntegrationServerwillinvoke thenotificationperiodicallybasedonthepollingintervalthatyouspecifywhenyou schedulethenotificationasdescribedinManagingPollingNotificationsonpage 149.
22
Adapternotificationsvarysomewhatinhowtheywork,dependingonthetypeofthe adapternotification.BesuretoreviewNotificationTypesbeginningonpage 24to understandhowtheiroperationsdiffer.
Adapter Notification Templates

TheJDBCAdapterprovidesthefollowingadapternotificationtemplates: Notification Type Insert Notification Notification Template InsertNotification Description Publishesnotificationofinsertoperations onadatabasetable. SeeConfiguringInsertNotificationson page 125forinstructions. Update Notification UpdateNotification Publishesnotificationofupdate operationsonadatabasetable. SeeConfiguringUpdateNotifications onpage 129forinstructions. Delete Notification DeleteNotification Publishesnotificationofdeleteoperations onadatabasetable. SeeConfiguringDeleteNotificationson page 134forinstructions. BasicNotification BasicNotification PollsadatabasetablefordatausingaSQL Selectoperation. SeeConfiguringBasicNotificationson page 138forinstructions. StoredProcedure Notification StoredProcedure Notification Publishesnotificationdatabycallinga storedprocedureinsideofadatabase. SeeConfiguring StoredProcedureNotificationson page 142forinstructions. Ordered Notification OrderedNotification Publishesnotificationdataformultiple insert,update,ordeleteoperationson multipletablesforagivendatabase. SeeConfiguringOrderedNotifications onpage 145forinstructions.
23
Exactly Once Notification Feature

Mostadapternotifications,suchasInsertNotificationsandUpdateNotifications,canuse theExactlyOncenotificationfeature.Thisfeatureensuresthatnotificationdatawillnotbe duplicatedevenifafailureoccursduringprocessing.Thisisachievedbyassigning uniqueIDsforeachpublishabledocument.Afteraprocessingfailure,theIntegration ServerchecksforduplicaterecordsinstorageandignoresanyduplicateIDs. Note: StoredProcedureNotificationsdonotsupporttheExactlyOncenotificationfeature becausetheydonotusepublishabledocumentuniqueIDs. SeeUsingtheExactlyOnceNotificationFeatureonpage 152formoredetails.
Notification Types
Therearesixtypesofnotifications:Insert,Update,Delete,Basic,StoredProcedure,and OrderedNotifications.Theyvaryinhowtheyarestructuredandoperate,asdescribedin thefollowingsections.
Insert Notifications, Update Notifications, and Delete Notifications

InsertNotifications,UpdateNotifications,andDeleteNotificationsuseacombinationof triggersandbuffertablestocaptureeventsthathappenonspecifictablesinadatabase. Youconfigurethetriggersandbuffertableswhenyouconfigurethenotifications. Thesetypesofnotificationsoperatesimilarly,withtheexceptionofthetypeofSQL operation(insert,update,ordelete)thattheymonitor.Theadaptercreatesthetriggerand buffertablewhenyouenableanotification.Thebuffertable,whichyouspecifiedwhen youconfiguredthenotification,holdsthedataselectedbythetrigger.Therearenospecial sizeconstraintsforthebuffertables.Thetriggermonitorsthedatabasetableyouspecified whenyouconfiguredthenotificationandinsertsdataintothebuffertable.Whenyou disableanotification,theadapterdropsthetriggerandbuffertable. Whenyouenableanotification,thedatabasetriggermonitorsthetableandinsertsthe dataintothebuffertable.WhentheIntegrationServerinvokesthenotification,itretrieves therowsofdatafromthebuffertable,publisheseachrowinthenotificationspublishable document,andthenremovesthisrowfromthebuffertable. Afteryouenablethesetypesofnotifications,thetriggerandbuffertableremaininthe databasetablewhenyou: ShutdowntheIntegrationServer Disablethepackagecontainingtheenablednotification Reloadthepackagecontainingtheenablednotification Suspendthenotification(IntegrationServer6.5)
24
Inthemeantime,thetriggercontinuestomonitorthetableandtoinsertdataintothe buffertable.TheIntegrationServerinvokestheenablednotificationwhenitrestarts,or whenitenablesorreloadsthepackagethatcontainsthisnotification.SeeInsert,Update, andDeleteNotificationsTransactionProcessingonpage 27formoreinformationabout howthesetypesofnotificationswork. SeeConfiguringInsertNotificationsonpage 125,ConfiguringUpdateNotifications onpage 129,orConfiguringDeleteNotificationsonpage 134forinstructionsfor configuringthistypeofadapternotification. FormoredetailsabouttheIntegrationServerpublishabledocuments,whenusing versionsoftheIntegrationServerearlierthan6.1,seetheBuildingIntegrationSolutions UsingPublicationdocument,andwhenusingIntegrationServer6.1orlater,seethe PublishSubscribeDevelopersGuide. Using Insert, Update, and Delete Notifications Thefollowingtableliststhetasksrequiredtousethesetypesofnotification: For this task... 1 2 Createanadapterconnection.SeeConfiguringJDBC AdapterConnectionsonpage 68fordetails. Configurethenotificationandspecifythe: Adapterconnection Sourcetable Publishabledocumenttocontainthedatafromthe buffertable.Thereisasinglepublishabledocument usedforalleventsassociatedwiththenotification. FormoredetailsabouttheIntegrationServer publishabledocuments,whenusingversionsofthe IntegrationServerearlierthan6.1,seetheBuilding IntegrationSolutionsUsingPublicationdocument,and whenusingIntegrationServer6.1orlater,seethe PublishSubscribeDevelopersGuide. Outputdatafieldscontainedinthepublishable document Databasetriggerandbuffertable SeeAdapterNotificationsonpage 123forinstructions forconfiguringnotifications. Use these tools... IntegrationServer Administrator Developer
25
For this task... 3 IfyouplantouseanIntegrationServerfloworJava service,designittoreacttothedatachangescontainedin thenotificationspublishabledocument.Createthe IntegrationServertriggertousethenotifications publishabledocument.SeethewebMethodsDeveloper UsersGuidefordetails. Scheduleandenabletheadapternotification.Whenyou enablethenotification: Itautomaticallycreatesthedatabasetriggerandbuffer tableyouconfiguredwhenyoucreatedthe notification. TheIntegrationServerSchedulerinvokesthe notificationandcontinuestodosoperiodically,based onthepollingscheduleparametersyoucreated earlier. SeeManagingPollingNotificationsonpage 149for instructionsforschedulingandenablingnotifications. 5 Managethenotification.SeePackageManagementon page 45,AdapterNotificationsonpage 123,and LoggingandExceptionHandlingonpage 157for details.
Use these tools... Developer
IntegrationServer Administrator
26
Insert, Update, and Delete Notifications Transaction Processing Thefollowingdiagramandstepsillustratewhathappenswhenthesetypesof notificationsareinvoked.TheIntegrationServercontinuestoinvokethenotification periodically,asdefinedwhenyouconfiguredthescheduleparametersforpollingthe notification.
Insert, Update, and Delete Notifications Database Operation: Database Operation: Insert, Insert, Update, Update, or Delete or Delete Database Flow or Java Service
webMethods Integration Server Adapter Connection Pool Connection
Database
6
Trigger
Source Source Table Table
5
Adapter Notification Publishable Document
Trigger
3
JDBC Driver Buffer Table
Step
1
Description InsertNotifications,UpdateNotifications,andDeleteNotifications monitoranoperationthathappenstoadatabasetable,suchasaninsert, update,ordeleteoperation.Youspecifiedthesourcetabletomonitorat thetimeyouconfiguredtheadapter. Thenotificationgetsaconnectionfromtheservicesconnectionpool. Adapterconnectionscontainconnectioninformationforthedatabase, includingJDBCdriverparameters.
ThenotificationusestheJDBCdrivertoconnecttothedatabase. Youcreatedandenabledtheadapterconnectionearlierusingthe IntegrationServerAdministrator.
27
Step
4
Description Thenotificationretrievestherowsofdatafromthebuffertable. Thebuffertableholdsthedataselectedbythetrigger.Whiletheadapter remainsenabled,thetriggercontinuestomonitorthedatabasetableand insertdataintothebuffertable.
Thenotificationcreatesthepublishabledocument,whichcontainsarowof datafromthebuffertable.Thenotificationpublishesthepublishable document. FormoredetailsabouttheIntegrationServerpublishabledocuments, whenusingversionsoftheIntegrationServerearlierthan6.1,seethe BuildingIntegrationSolutionsUsingPublicationdocument,andwhenusing IntegrationServer6.1orlater,seethePublishSubscribeDevelopersGuide.
UsinganIntegrationServertriggeryouconfiguredtousethenotifications publishabledocument,afloworJavaserviceontheIntegrationServeris invokedtoreacttothedatachangescontainedinthepublishable document. Afterthedataispublished,thedataisremovedfromthebuffertable.
Basic Notifications
IncontrastwithInsertNotifications,UpdateNotifications,andDeleteNotifications,Basic Notificationsrequireyoutodefineabuffertable,andadatabasetriggerorothermeansof monitoringdatabasechangessothatchangesarewrittenintothebuffertable. Tomonitordatabasechanges,aBasicNotificationqueriesthebuffertable.Basic Notificationsprovideyouwiththeflexibilitytomanagebuffertables,suchasatablewith userprivileges,andtotailoryourowndatabasemonitoringmethodsforproducing notificationdata.Bydefault,afterthedataisretrievedandprocessed,itisdeletedfrom thebuffertabletoensurethatthedataisnotprocessedmultipletimes.Ifyoudonot choosethedefault,thatis,ifyoudononotallowtheadaptertodeletedatafromthebuffer table,besurethatyouusesomeothermeanstopurgethedatasothatdatadoesnotget publishedmorethanonce. SeeBasicNotificationsTransactionProcessingonpage 30formoreinformationabout howBasicNotificationswork. SeeConfiguringBasicNotificationsonpage 138forinstructionsforconfiguringthis typeofadapternotification.
28
Using Basic Notifications Thefollowingtableliststhetasksrequiredtousethisnotification: For this task... 1 2 3 Ifneeded,createyourownbuffertableanddatabase trigger(orothermeans)tomonitorfordatabasechanges. Createanadapterconnection.SeeConfiguringJDBC AdapterConnectionsonpage 68fordetails. Configurethenotificationandspecifythe: Adapterconnection Buffertablesthatyoucreatedindependently Publishabledocumenttocontainthedatafromthe buffertable.Thereisasinglepublishabledocument usedforalleventsassociatedwiththenotification. FormoredetailsabouttheIntegrationServer publishabledocuments,whenusingversionsofthe IntegrationServerearlierthan6.1,seetheBuilding IntegrationSolutionsUsingPublicationdocument,and whenusingIntegrationServer6.1orlater,seethe PublishSubscribeDevelopersGuide. Outputdatafieldscontainedinthepublishable document SeeConfiguringBasicNotificationsonpage 138for instructionsforconfiguringthistypeofnotification. 4 IfyouplantouseanIntegrationServerfloworJava service,designittoreacttothedatachangescontainedin thenotificationspublishabledocument.Createthe IntegrationServertriggertousethenotifications publishabledocument.SeethewebMethodsDeveloper UsersGuidefordetails. Scheduleandenabletheadapternotification. Whenyouenablethenotification,theIntegrationServer Schedulerinvokesthenotificationperiodicallyand continuestodoso,basedonthepollingschedule parametersyoucreatedearlier. SeeManagingPollingNotificationsonpage 149for instructionsforschedulingandenablingnotifications. Developer Use these tools... Userdefined IntegrationServer Administrator Developer
29
For this task... 6 Managethenotification.SeePackageManagementon page 45,AdapterNotificationsonpage 123,and LoggingandExceptionHandlingonpage 157for details.
Use these tools... Developerand IntegrationServer Administrator
Basic Notifications Transaction Processing ThefollowingdiagramandstepsillustratewhathappenswhenaBasicNotificationis invoked.TheIntegrationServercontinuestoinvokethenotificationperiodically,as definedwhenyouconfiguredthepollingscheduleparametersforthenotification.

Basic Notifications Database Operation: Insert, Update, or Delete
webMethods Integration Server Adapter Connection Pool Connection Flow or Java Service
Database Database Source Table Source Table
7
Trigger
Adapter Notification
6
Publishable Document
Trigger (User-created)
3
JDBC Driver
Buffer Table (User-created and maintained)
Step
1
Description BasicNotificationsmonitoranoperationthathappenstoadatabasetable, suchasaninsert,update,ordeleteoperation.Youspecifiedthebuffertable tomonitoratthetimeyouconfiguredtheadapter. Thenotificationgetsaconnectionfromtheservicesconnectionpool. Adapterconnectionscontainconnectioninformationforthedatabase, includingJDBCdriverparameters.
30
Step
3
Description ThenotificationusestheJDBCdrivertoconnecttothedatabase. Youcreatedandenabledtheadapterconnectionearlierusingthe IntegrationServerAdministrator.
UnlikeInsertNotifications,UpdateNotifications,andDeleteNotifications, youcreateyourownbuffertableandtrigger,orothermeansofmonitoring databasechanges.Thediagramandstepslistedhereassumeyouare creatingyourownbuffertableandtriggertomonitorforchanges. Thebuffertableyoudefinewillholdthedataselectedbyanytriggeryou create.Thetriggerwillmonitorthedatabasetableandinsertdataintothe buffertable.
5 6
Thenotificationretrievestherowsofdatafromthebuffertable. Thenotificationcreatesthepublishabledocument,whichcontainsarowof datafromthebuffertable.Thenotificationpublishesthepublishable document. FormoredetailsabouttheIntegrationServerpublishabledocuments, whenusingversionsoftheIntegrationServerearlierthan6.1,seethe BuildingIntegrationSolutionsUsingPublicationdocument,andwhenusing IntegrationServer6.1orlater,seethePublishSubscribeDevelopersGuide.
UsinganIntegrationServertriggeryouconfiguredtousethenotifications publishabledocument,afloworJavaserviceontheIntegrationServeris invokedtoreacttothedatachangescontainedinthepublishable document. Afterthedataispublished,thedatainthebuffertablewillberetainedor removed,dependingonhowyouconfiguredyourbuffertableandtrigger.
Stored Procedure Notifications

AStoredProcedureNotificationcallsastoredprocedureyoucreatedearliertopublish notificationdatainthenotificationspublishabledocument(s).SeeStoredProcedure NotificationsTransactionProcessingonpage 33formoreinformationabouthowStored ProcedureNotificationswork. SeeConfiguringStoredProcedureNotificationsonpage 142forinformationabout configuringthistypeofadapternotification. Note: StoredProcedureNotificationsdonotsupporttheExactlyOncenotificationfeature becausetheydonotusepublishabledocumentuniqueIDs.(SeeUsingtheExactlyOnce NotificationFeatureonpage 152fordetailsaboutthisfeature.)
31
Using Stored Procedure Notifications Thefollowingtableliststhetasksrequiredtousethisnotification: For this task... 1 Toensurethatthesamedataisnotpublishedmultiple times,designandtestyourstoredproceduresothat wheneverthestoredprocedureisinvoked,youare assuredthatitprovidesthecorrectdata. Createanadapterconnection.SeeConfiguringJDBC AdapterConnectionsonpage 68fordetails. Configurethenotificationandspecifythe: Adapterconnection Storedprocedure Publishabledocumenttocontainthedata.Thereisa singlepublishabledocumentusedforallevents associatedwiththenotification. FormoredetailsabouttheIntegrationServer publishabledocuments,whenusingversionsofthe IntegrationServerearlierthan6.1,seetheBuilding IntegrationSolutionsUsingPublicationdocument,and whenusingIntegrationServer6.1orlater,seethe PublishSubscribeDevelopersGuide. Anyoutputdatafieldstobecontainedinthe publishabledocument SeeConfiguringStoredProcedureNotificationson page 142forinstructionsforconfiguringthistypeof notification. 4 IfyouplantouseanIntegrationServerfloworJava service,designittoreacttothedatachangescontainedin thenotificationspublishabledocument.Createthe IntegrationServertriggertousethenotifications publishabledocument.SeethewebMethodsDeveloper UsersGuidefordetails. Developer Use these tools... Userdependent
2 3
IntegrationServer Administrator Developer
32
For this task... 5 Scheduleandenabletheadapternotification.Whenyou enablethenotification,theIntegrationServerScheduler invokesthenotificationandcontinuestodoso periodically,basedonthepollingscheduleparameters youcreatedearlier. SeeManagingPollingNotificationsonpage 149for instructionsforschedulingandenablingnotifications. 6 Managethenotification.SeePackageManagementon page 45,AdapterNotificationsonpage 123,and LoggingandExceptionHandlingonpage 157for details.
Use these tools... IntegrationServer Administrator
Stored Procedure Notifications Transaction Processing ThefollowingdiagramandstepsillustratewhathappenswhenaStoredProcedure Notificationisinvoked.

Stored Procedure Notifications
webMethods Integration Server Adapter Connection Pool Connection Database Operation: Insert, Update, or Delete
Flow or Java Service
7
Trigger
2
Adapter Notification
6
Publishable Document
Database
3
JDBC Driver
Stored Procedure Called
4
Stored Procedure
33
Step
1
Description AStoredProcedureNotificationusesastoredprocedureyoucreatedinthe databasetomonitoranoperationthathappenstoadatabasetable,suchas aninsert,update,ordeleteoperation. WhentheStoredProcedureNotificationcallsthestoredprocedure,it storesanyoutputinthenotificationspublishabledocument(s).
Thenotificationgetsaconnectionfromtheservicesconnectionpool. Adapterconnectionscontainconnectioninformationforthedatabase, includingJDBCdriverparameters.
4 5 6
TheIntegrationServercallsthestoredprocedure. Thenotificationretrieveseachrowofdatafromthestoredprocedure. Eachrowofdataispublishedusingthenotificationspublishable document.Dependingonthestoredprocedure,theStoredProcedure Notificationspublishabledocument(s)cancontainanyofthefollowing: Outputparameter(s):ifthecalledstoredprocedurehasanyoutput parameters,theyarecontainedinanypublishabledocumentsforthe StoredProcedureNotification. Returnvalue(s):ifthecalledstoredprocedurereturnsanyvalues,then areturnvalueiscontainedinapublishabledocumentfortheStored ProcedureNotification. Singleresultset(orOracleREFCURSOR):StoredProcedure Notificationscansupportoneresultset.Ifacalltothestored procedureproducesaresultset,thenthesingleresultsetiscontained inoneormorepublishabledocumentsfortheStoredProcedure Notification.Insomecases,acalltoaStoredProcedureNotification canproduceasingleresultsetthatcontainsmultiplerecords.Inthis case,eachrecordwillhaveaseparatepublishabledocument, containingonerowandoneormorecolumns,thatisreturnedtothe adapter. FormoredetailsabouttheIntegrationServerpublishabledocuments, whenusingversionsoftheIntegrationServerearlierthan6.1,seethe BuildingIntegrationSolutionsUsingPublicationdocument,andwhenusing IntegrationServer6.1orlater,seethePublishSubscribeDevelopersGuide.
34
Step
7
Description UsinganIntegrationServertriggeryouconfiguredtousethenotifications publishabledocument,afloworJavaserviceontheIntegrationServeris invokedtoreacttothedatachangescontainedinthepublishable document.
Ordered Notifications
YouuseOrderedNotificationstomonitormultipleinsert,update,ordeleteoperationson oneormoretablesforagivendatabasebycreatingasinglenotificationusingthesame publishabledocument.SimilartoInsertNotifications,UpdateNotifications,andDelete Notifications,OrderedNotificationsusetriggersandbuffertablestocaptureeventsthat happenonspecifictablesinadatabase. AfteryouenabletheOrderedNotification,thetrigger,buffertable,andsequenceremain inthedatabasetablewhenyou: ShutdowntheIntegrationServer. DisablethepackagecontainingtheenabledOrderedNotification. ReloadthepackagecontainingtheenabledOrderedNotification. Inthemeantime,thetriggercontinuestomonitorthetableandtoinsertdataintothe buffertable.TheIntegrationServerinvokestheenabledOrderedNotificationwhenit restarts,orwhenitenablesorreloadsthepackagethatcontainsthisnotification. Whenyoudisableanotification,theadapterdropsthetriggerandbuffertable. SeeOrderedNotificationsTransactionProcessingonpage 38formoreinformation abouthowOrderedNotificationswork. Considerations when Using Ordered Notifications UsetheOrderedNotificationonlyifyouneedtopreservetheorderinwhichthe operationsoccur;otherwise,useInsertNotifications,UpdateNotifications,and DeleteNotificationsbecausetheyhavebetterperformance. OrderedNotificationsensurethattheoperationsprocessinthecorrectorderwhen theyoccursequentiallyinonetransaction;however,orderpreservationisnot guaranteediftheoperationsoccurinconcurrenttransactions.Forexample,seethe followingdiagrams.ExamplesAandBwillprocessoperationsinthecorrectorder. ExampleCisnotguaranteedtoprocessoperationsinthecorrectorder.
35
Example A: Over Time Transaction A Order of Operations: Operations for Transaction A occur one after another. The operations will process in the correct order.
Operation 3 Operation 1 Operation 2
Operations: 1 2 3
Example B: Over Time Transaction A Order of Operations: Operation 2 Operations: 1 2 3 Operations for Transactions A and B occur one after another. The operations will process in the correct order.
Transaction B Operation 1 Operation 3
Example C: Order of Operations: Over Time Transaction A Operation 1 Operation 2 Transaction B Operation 4 Operation 3 Order of operations not guaranteed Some or all operations for Transactions A and B occurred at the same time. The operations are not guaranteed to process in the correct order.
Configuring an Integration Server Trigger and Flow Service WithOrderedNotifications,youtypicallyconfigureanIntegrationServertriggerto subscribetothenotificationspublishabledocumentandaflowservicethatthetrigger invokes.BecausetheprimaryreasontouseOrderedNotificationsistopreservetheorder
36
inwhichtheoperationsoccur,besuretousetheProcess Document Seriallyoptiononthe SettingstabintheDeveloperwhenyoucreatethetriggerandflowservice. FormoreinformationaboutusingconfiguringIntegrationServertriggersandflow services,seethewebMethodsDeveloperUsersGuide. Using Ordered Notifications Note: Youcancreateonlyonetriggerforeachoperationonatable.Foreachnotification, youcanconfigureonlyonetriggerforeachtable. Thefollowingtableliststhetasksrequiredtousethisnotification: For this task... 1 2 Createanadapterconnection.SeeConfiguringJDBC AdapterConnectionsonpage 68fordetails. Configurethenotificationandspecifythe: Adapterconnection Sourcetables TypeofoperationassociatedwiththeOrdered Notification;thatis,aninsert,update,ordelete operation OperationIDyoucreateforeachoperation Outputdatafieldstobepublishedforeachoperation Databasetriggerandbuffertable Thebuffertablewillholdthedataselectedbythe trigger.Thetriggerwillmonitorthedatabasetable andinsertdataintothebuffertable.SeeConfiguring anIntegrationServerTriggerandFlowServicefor moredetails. Use these tools... IntegrationServer Administrator Developer
37
For this task... Publishabledocumenttocontainthedatafromthe buffertable.Thereisasinglepublishabledocument usedforalleventsassociatedwiththenotification. FormoredetailsabouttheIntegrationServer publishabledocuments,whenusingversionsofthe IntegrationServerearlierthan6.1,seetheBuilding IntegrationSolutionsUsingPublicationdocument,and whenusingIntegrationServer6.1orlater,seethe PublishSubscribeDevelopersGuide. SeeConfiguringOrderedNotificationsonpage 145for instructionsforconfiguringthistypeofnotification. 3 IfyouplantouseanIntegrationServerfloworJava service,designittoreacttothedatachangescontainedin thenotificationspublishabledocument.Createthe IntegrationServertriggertousethenotifications publishabledocument.SeethewebMethodsDeveloper UsersGuidefordetails. Ifyouuseatrigger,besuretoenabletheProcess Document Seriallyoption.SeeConfiguringanIntegrationServer TriggerandFlowServiceonpage 36fordetails. 4 Scheduleandenabletheadapternotification.Whenyou enablethenotification,itautomaticallycreatesthe databasetrigger,sequence,andbuffertableyou configuredwhenyoucreatedthenotification.The IntegrationServerSchedulerinvokesthenotificationand continuestodoso.SeeManagingPollingNotifications onpage 149forinstructionforschedulingandenabling notifications. Managethenotification.SeePackageManagementon page 45,AdapterNotificationsonpage 123,and LoggingandExceptionHandlingonpage 157for details.
Use these tools...
Developer
Ordered Notifications Transaction Processing ThefollowingdiagramandstepsillustratewhathappenswhenanOrderedNotificationis invoked.TheIntegrationServercontinuestoinvokethenotificationperiodically,as definedwhenyouconfiguredthepollingscheduleparametersforthenotification.
38
Ordered Notifications webMethods Integration Server Adapter Connection Pool Connection Flow or Java Service
7
Trigger
2 6
Publishable Document Adapter Notification
JDBC Driver
Database Table(s) and Trigger(s) Insert Trigger Source Table 1 Update Trigger Buffer Table 1
Insert Trigger Source Table n Update Trigger Database Operation: Insert, Update, or Delete
Buffer Table 3
Buffer Table n
Sequence
Buffer Table 2
39
Step
1
Description OrderedNotificationsmonitormultipleinsert,update,ordelete operationsononeormoretablesbycreatingasinglenotificationusingthe samepublishabledocument. Thenotificationgetsaconnectionfromtheservicesconnectionpool. Adapterconnectionscontainconnectioninformationforthedatabase, includingJDBCdriverparameters.
Thebuffertableholdsthedataselectedbythetrigger.Whiletheadapter remainsenabled,thetriggercontinuestomonitorthedatabasetableand insertdataintothebuffertable. WithOrderedNotifications,theadaptercreatesthetrigger,sequence,and buffertablesforeachoperationyouwanttomonitorwhenyouenablethe notification.Thedatabasetriggermonitorsthetable(s)andinsertsdata intothebuffertable.WhentheIntegrationServerinvokesthenotification, thenotificationwillpollallofthebuffertablesandpublishthedatainthe sameorderinwhichtheoperationsoccurred.Thisensuresthattheorderof theoperationsispreserved.
Thenotificationretrievestherowsofdatafromthebuffertable. EachOrderedNotificationgeneratesonerowforeachoperation.The notificationusestheOperationIDandanOperationTypefieldyou specifiedwhenyouconfiguredthenotificationtouniquelyidentifythis row.TheOperationIDisuserdefined.
Thenotificationcreatesthepublishabledocument,whichcontainsarowof data,includingtheOperationIDandOperationType,fromthebuffer table. Thenotificationpublishesthepublishabledocument.
40
Step
7
Description UsinganIntegrationServertriggeryouconfiguredtousethenotifications publishabledocument,afloworJavaserviceontheIntegrationServeris invokedtoreacttothedatachangescontainedinthepublishable document. TheflowservicethatprocessesthepublishabledocumentfortheOrdered NotificationneedstochecktheOperationIDfieldinthedocumentand retrievedatafromtherecordwiththenameidentifiedbytheOperationID forprocessing.Forexample,aflowservicecheckstoseeiftheOperation IDhasavalueofUPDATE.Ifthisistrue,thentheflowservicepicksupthe datafromtheUPDATErecordasinputandprocessesit.IftheOperation IDvalueisINSERT,theflowservicepicksupdatafromtheINSERTrecord asinputandprocessesaccordingly. SeeConfiguringanIntegrationServerTriggerandFlowServiceon page 36formoreinformationaboutusingtriggersandflowserviceswith OrderedNotifications. Afterthedataispublished,thedataisdeletedfromthebuffertable.
Polling Notification Support in Clusters

TheJDBCAdapterprovidestheabilitytoenablemultipleinstancesofthesamepolling notificationinyourIntegrationServerclusters,andtocoordinatetheirschedulesand execution. Formoreinformation,seeJDBCAdapterPollingNotificationSupportinClusterson page 50.
Polling Notifications and States

Beforeversion6.5,theIntegrationServerprovidedtwostatesinwhichpolling notificationscouldexist:EnabledandDisabled.Ifuserswantedtostoptheactivitiesofa pollingnotificationforexample,toperformsystemmaintenanceormakeminorchanges tothepollingnotificationsconfiguration(suchaschangingitsschedule)theywere forcedtodisablethepollingnotification.However,disablingapollingnotificationcould resultindataloss. Beginningwithversion6.5,theIntegrationServeraddedathirdstate:Suspended.The Suspendedstateprovidesamechanismfortemporarilystoppingtheactivitiesofapolling notificationwithoutdataloss. Thetablebelowsummarizesthestatesandhowtheyaffectthetriggers,buffertables,and dataprocessingofapollingnotification.
41
State name Enabled
Status of trigger and buffer table when polling notification enters this state Databasetrigger andbuffertable arecreated. Databasetrigger andbuffertable persist.Table retainsitsrows.
Data processing while in this state Thepolling notification performsas scheduled. Thepolling notificationis removedfrom thescheduler anddoesnot executewhile suspended.Any instances executingatthe timethe Suspendedstate isinitiatedare unaffected. Thepolling notificationis removedfrom thescheduler anddoesnot execute.
Comments
Suspended
TheSuspendedstateisavailable onlyinIntegrationServer version 6.5. Youmaysuspendpolling notificationsinanEnabledstate. Youmaynotsuspendpolling notificationsinaDisabledstate. Youmaycopyorexport suspendedpollingnotifications. Youmaynotmove,rename,or deletesuspendedpolling notifications.
Disabled
Databasetrigger andbuffertable aredropped.
ThetableaboveappliestoInsertNotifications,UpdateNotifications,DeleteNotifications, andOrderedNotifications.However,thetableabovedoesnotapplytoBasicNotifications orStoredProcedureNotificationsbecausewiththese,theresourceadministrator(notthe JDBCAdapter)isresponsibleformaintainingthetriggerandbuffertable. Forinstructionsonenabling,suspending,anddisablingpollingnotifications,seethe explanationoftheStatefieldonpage 151.
42
webMethods Manager Support for the JDBC Adapter
webMethods Manager Support for the JDBC Adapter

ThewebMethodsManagerServerisasystemsmanagementfacilitybasedontheOpen ManagementInterface(OMI).ItautomaticallymanagestheJDBCAdaptercomponentsif theManagerServermanagestheIntegrationServeronwhichtheJDBCAdapteris installed.ThemanagedJDBCAdaptercomponentsare: Adapterconnections Adapterservices Pollingnotifications SeethewebMethodsManagerServerProgrammersGuideforinformationabouttheobject interfacesavailabletotheJDBCAdapter.Theseobjectinterfacesarethespecificattributes andoperationsthatyoucanperformtomanagetheJDBCAdaptercomponents.
Viewing Different Perspectives of the webMethods Developer

Beginningwithversion6.1,webMethodsDeveloperenablesyoutoviewitsinterfacein threedifferentperspectives:Edit,Test,andDetails. Theseperspectivesenableyoutodisplayonlythoseareasthatarerelevanttoyourcurrent task.Youcanswitchperspectivesbyusingthefollowingicons,whicharelocatedonthe toprightoftheDeveloperwindow.Alternatively,youcanaccessthemfromtheWindow menu. Perspective Name Edit Perspective Test Perspective
Icon
Description DisplaysallDeveloperareasbutminimizestheResults panel.Useforopeningandeditingelement. HidestheNavigationandRecentElementspanelsand maximizestheeditorandResultspanel.Usefortestingand debugginganadapterservicewhereyouwanttoviewthe resultsoftheservicesexecution,itsinputsandoutputs,and itspipelinevariables. HidestheNavigationandRecentElementspanelsand minimizestheResultspanel.Usewhenyouwanttosee elementdetails.
Details Perspective
43
Viewing the Adapter s Update Level

WhenusingtheJDBCAdapterwithIntegrationServer6.5,youcanviewthelistof updatesthathavebeenappliedtotheadapter.ThelistofupdatesappearsintheUpdates fieldontheadaptersAboutpageintheIntegrationServerAdministrator. Note: UpdatesthatwerecreatedbeforethereleaseofIntegrationServer6.5willnotappear intheUpdatesfield.
44
CHAPTER
Package Management
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 JDBC Adapter Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Group Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 JDBC Adapter in a Clustered Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
45
CHAPTER 2 Package Management
Overview
ThefollowingsectionsdescribehowtosetupandmanageyourJDBCAdapterpackages, setupAccessControlLists(ACL),andusetheadapterinaclusteredenvironment.
JDBC Adapter Package Management

TheJDBCAdapterisprovidedasapackagecalledWmJDBCAdapter.Youmanagethe WmJDBCAdapterpackageasyouwouldmanageanypackageontheIntegrationServer. Whenyoucreateconnections,adapterservices,andadapternotifications,definethemin userdefinedpackagesratherthanintheWmJDBCAdapterpackage.Doingsowillallow youtomanagethepackagemoreeasily. Asyoucreateuserdefinedpackagesinwhichtostoreconnections,adapterservices,and adapternotifications,usethepackagemanagementfunctionalityprovidedinthe Developerandsettheuserdefinedpackagestohaveadependencyonthe WmJDBCAdapterpackage.Thatway,whentheWmJDBCAdapterpackageloadsor reloads,theuserdefinedpackagesloadautomatically.Seethefollowingdiagram:
JDBC Connections Package (user-defined) WmART WmJDBCAdapter JDBC Adapter Services Package (user-defined) JDBC Notifications Package (user-defined) Adapter n Connections Package (user-defined)
Adapter n
KEY: A sets a dependency on B: A B
Adapter n Services Packages (user-defined) Adapter n Notifications Packages (user-defined)
46
JDBC Adapter Package Management
Packagemanagementtasksinclude: Settingpackagedependencies(seePackageDependencyRequirementsand Guidelinesonpage 47) EnablingandDisablingPackagesonpage 48 ImportingandExportingPackagesonpage 49 GroupAccessControlonpage 49
Package Dependency Requirements and Guidelines

Thissectioncontainsalistofdependencyrequirementsandguidelinesforuserdefined packages.Forinstructionsforsettingpackagedependencies,seethewebMethodsDeveloper UsersGuide. Auserdefinedpackagemusthaveadependencyonitsassociatedadapterpackage, WmJDBCAdapter.(TheWmJDBCAdapterpackagehasadependencyontheWmART package.) PackagedependenciesensurethatatstartuptheIntegrationServerautomatically loadsorreloadsallpackagesintheproperorder:theWmARTpackagefirst,the adapterpackagenext,andtheuserdefinedpackage(s)last.TheWmARTpackageis automaticallyinstalledwhenyouinstalltheIntegrationServer.Youshouldnotneed tomanuallyreloadtheWmARTpackage. Iftheconnectionsandadapterservicesofanadapteraredefinedindifferent packages,then: Apackagethatcontainstheconnection(s)musthaveadependencyonthe adapterpackage. Packagesthatcontainadapterservicesmusthaveadependencyontheir associatedconnectionpackage. Keepconnectionsfordifferentadaptersinseparatepackagessothatyoudonotcreate interdependenciesbetweenadapters.Ifapackagecontainsconnectionsfortwo differentadapters,andyoureloadoneoftheadapterpackages,theconnectionsfor bothadapterswillreloadautomatically. TheIntegrationServerwillnotallowyoutoenableapackageifithasadependency onanotherpackagethatisdisabled.Thatis,beforeyoucanenableyourpackage,you mustenableallpackagesonwhichyourpackagedepends.Forinformationabout enablingpackages,seeEnablingandDisablingPackagesonpage 48.
47
TheIntegrationServerwillallowyoutodisableapackageevenifanotherpackage thatisenabledhasadependencyonit.Therefore,youmustmanuallydisableany userdefinedpackagesthathaveadependencyontheadapterpackagebeforeyou disabletheadapterpackage.Forinformationaboutdisablingpackages,seeEnabling andDisablingPackagesonpage 48. Youcannameconnections,adapterservices,andnotificationsthesamename providedthattheyareindifferentfoldersandpackages.
Enabling and Disabling Packages

Allpackagesareautomaticallyenabledbydefault.Whenyouwanttotemporarily prohibitaccesstotheelementsinapackage,disablethepackage.Whenyoudisablea package,theserverunloadsallofitselementsfrommemory.Disablingapackage preventstheIntegrationServerfromloadingthatpackageatstartup. To enable a package 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuofthenavigationarea,clickManagement. ClickNointheEnabledcolumn.Theserverdisplaysa column. andYesintheEnabled
Note: Enablinganadapterpackagewillnotcauseitsassociateduserdefinedpackage(s)to bereloaded.Forinformationaboutreloadingpackages,seethewebMethodsDeveloper UsersGuide. Important! Beforeyoumanuallyenableauserdefinedpackage,youmustfirstenableits associatedadapterpackage(WmJDBCAdapter).Similarly,ifyouradapterhasmultiple userdefinedpackages,andyouwanttodisablesomeofthem,disabletheadapter packagefirst.Otherwise,errorswillbeissuedwhenyoutrytoaccesstheremaining enableduserdefinedpackages.
To disable a package 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuofthenavigationarea,clickManagement. ClickYesintheEnabledcolumnforthepackagethatyouwanttodisable.Theserver issuesaprompttoverifythatyouwanttodisablethepackage.ClickOKtoenablethe package.Whenthepackageisdisabled,theserverdisplaysNointheEnabledcolumn.
48
Group Access Control
Adisabledadapterwill: RemaindisableduntilyouexplicitlyenableitusingtheAdministrator. NotbelistedinthewebMethodsDeveloper.
Importing and Exporting Packages

YouimportandexportpackagesusingtheDeveloper.Exportingallowsyoutoexportthe packagetoa.zipfileandsaveittoyourharddrive.The.zipfilecanthenbeimportedfor usebyanotherpackage. Important! Donotrenamepackagesyouexport;therenamefunctioniscomparableto movingapackage,andwhenyouimporttherenamedpackage,youloseanytriggers, connections,andnotificationsassociatedwiththispackage. Fordetailsaboutimportingandexportingpackages,seethewebMethodsDeveloperUsers Guide.
Group Access Control

Tocontrolwhichgroupshaveaccesstowhichadapterservices,useaccesscontrollists (ACLs).Forexample,youcanuseACLstopreventonedevelopmentgroupfrom inadvertentlyupdatingtheworkofanothergroup,ortoallowordenyaccesstoservices thatarerestrictedtoonegroupbutnottoothers. ForinformationaboutassigningandmanagingACLs,seethewebMethodsDeveloperUsers Guide.
JDBC Adapter in a Clustered Environment

What is webMethods Integration Server Clustering?
ClusteringisanadvancedfeatureofthewebMethodsIntegrationServerthatsubstantially extendsthereliability,availability,andscalabilityoftheIntegrationServer. TheclusteringfeatureusesasharedclusterstoretoholdwebMethodsIntegrationServer stateinformationandutilizationmetricsforuseinloadbalancingandautomaticfailover support.Becausethisactivityistransparenttotheclient,clusteringmakesmultiple serverslookandbehaveasone.
49
Withclustering,yougetthefollowingbenefits: Load balancing. Thisfeature,providedautomaticallywhenyousetupaclustered environment,allowsyoutospreadtheworkloadoverseveralservers,thusimproving performanceandscalability. Failover support. Clusteringenablesyoutoavoidasinglepointoffailure.Ifaservercannot handlearequest,orbecomesunavailable,therequestisautomaticallyredirectedto anotherserverinthecluster. Note: webMethodsIntegrationServerclusteringredirectsHTTPandHTTPSrequests,but doesnotredirectFTPorSMTPrequests. Scalability.Youcanincreaseyourcapacityevenfurtherbyaddingnewmachinesrunning webMethodsIntegrationServertothecluster. FordetailsonwebMethodsIntegrationServerclustering,seethewebMethodsIntegration ServerClusteringGuide.
JDBC Adapter Polling Notification Support in Clusters

Thissectioncontainsthesesubsections: PollingNotificationSupportinClusterswithIntegrationServerVersion6.0.1SP2 onpage 50 PollingNotificationSupportinClusterswithIntegrationServerVersion6.5on page 54
Polling Notification Support in Clusters with Integration Server Version 6.0.1 SP2
TheIntegrationServerandtheJDBCAdapterdonotsupporthavingmorethanasingle instanceofagivenpollingnotificationenabledwithinacluster. WhenusingtheJDBCAdapterspollingnotificationsinaclusteredenvironment,youmay onlyenableasingleinstanceofagivennotificationononeIntegrationServerwithinthe cluster.Ifyourunmultipleinstancesofagivennotificationwithinthecluster,youwill encounterdocumentorderingproblems,andtheadapterwillproduceerrormessages. Additionally,evenwhenyourunasingleinstanceofanotificationwithinacluster,you couldencounterdocumentduplicationproblems.Theseissuesandlimitationsare describedinthefollowingsections. Duplicate Documents WhenusingtheJDBCAdapterwithversionsoftheIntegrationServerearlierthan6.1,the IntegrationServerprovidesduplicatedocumentdetectionusingitsclientsidequeuing facility.However,whenanIntegrationServerisaddedtoacluster,theserversclientside queuingmechanismbecomesdisabled,preventingtheIntegrationServerfromdetecting duplicatedocuments.ToworkaroundthisissuewhenusingversionsoftheIntegration
50
Serverearlierthan6.1,youcanenableasingleinstanceofagivennotificationwithinthe clusterandthenpublishthenotificationsdocumentstoanIntegrationServerthatisnot includedinthecluster,asshowninthefollowingdiagram.
Integration Server Cluster Integration Server 1 JDBC Adapter The UpdateRecord notification may only be enabled on one Integration Server in the cluster. Integration Server 4 UpdateRecord Notification Integration Server 2 JDBC Adapter The UpdateRecord notification publishes a document to Integration Server 4, which is outside of the cluster.
Integration Server 3 JDBC Adapter
WhenusingtheJDBCAdapterwithIntegrationServer6.1orlater,theserverprovides supportforduplicatedocumentdetectioninaclusterusingitspublicationandsubscribe facility.SeethePublishSubscribeDevelopersGuidefordetailsaboutconfiguringthis facility.Usingthismechanism,youcanenableasingleinstanceofagivenpolling notificationwithinaclusterofIntegrationServersandnotreceiveduplicatedocuments, asshowninthefollowingdiagram.
51
Integration Server Cluster Integration Server 1 JDBC Adapter Notification 1 may only be enabled on one Integration Server in the cluster.
Notification 1
Integration Server 2 JDBC Adapter Notification 1 publishes a document to the Integration Server cluster. In this example, Integration Server 3 picks up the document.
Ordering of Documents Ifyouenablemorethanoneinstanceofapollingnotificationwithinacluster,the IntegrationServersintheclustercannotmaintaintheorderinwhichthedocumentswere originallyobtainedfromthedatabasewhentheIntegrationServerspublishthose documents.BecausetheIntegrationServerdoesnotcoordinatetheorderinwhicha messageispublishedbetweenservers,messagescanbereceivedinadifferentorderthan theorderinwhichtheywerereadfromthedatabase.Thefollowingdiagramillustrates whytheIntegrationServercannotmaintainmessageorderwhentherearemultiple instancesofapollingnotificationenabledinacluster. SupposeyouhaveaclusteroffourIntegrationServers.EachserverhastheJDBCAdapter installed,andallareconnectedtothesameBroker,whichhasasingleclient.Allserversin theclusterarerunningthesameUpdateNotification(UpdateRecordinthisexample)and pullingrowsfromthesametable(TableA).
52
Integration Server Cluster Integration Server 1 Rows are inserted in sequential order: Row 1 Row 2 Row 3 Row 4 JDBC Adapter
UpdateRecord Notification Notification Document 1
Integration Server 2 JDBC Adapter Notification Document 2
Broker webMethods Client Subscriber Document 3 Document 1 Order Documents Received: Document 3 Document 1 Document 4 Document 2
Database Table A
UpdateRecord Notification
Document 4 Notification Document 3 Document 2
4
Notification Document 4 Documents received do not correspond to the order of the rows inserted in Table A of the database
53
Step
1 2
Description Rowsareinsertedintothedatabaseinsequentialorder. Thenotificationsarepollinginrandomorderandreadtherowsinthe followingorder: IntegrationServer1:UpdateNotificationreadsrow1 IntegrationServer2:UpdateNotificationreadsrow2 IntegrationServer3:UpdateNotificationreadsrow3 IntegrationServer4:UpdateNotificationreadsrow4
BecausetheIntegrationServerscannotcoordinatetheorderinwhichthe documentswerereceived,theserverspublishthenotificationdocuments inthefollowingorder: IntegrationServer1:NotificationDocument3 IntegrationServer3:NotificationDocument1 IntegrationServer2:NotificationDocument4 IntegrationServer4:NotificationDocument2
Theclientsubscriberreceivesthedocumentsinthefollowingorder,which istheorderinwhichtheywerepublishedbytheBroker: NotificationDocument3 NotificationDocument1 NotificationDocument4 NotificationDocument2 Thereforethedocumentsreceiveddonotcorrespondtotheorderofthe rowsinsertedinTableAofthedatabase.
Polling Notification Support in Clusters with Integration Server Version 6.5

WhenusingtheJDBCAdapterwithIntegrationServer6.5,theJDBCAdapterenablesthe coordinatedexecutionofpollingnotificationswithinawebMethodsIntegrationServer cluster.TheJDBCAdapterprovidestheabilitytoenablemultipleinstancesofthesame pollingnotificationinyourcluster,andtocoordinatetheirschedulesandexecution.This providesenhancedqualityofservicebyallowingconfigurationsforautomatedfailover betweennotificationsanddistributedprocessingofpollingnotifications. YoucanconfigureapollingnotificationtorunineitherStandbyorDistributedmode.You canalsoconfigureadditionalsettingsforclusteredpollingnotifications.
54
Standby Mode and Distributed Mode InStandbymode,aparticularinstanceofapollingnotificationwillexecutethe notificationaccordingtoitsconfiguredschedule.Whenyoustartthecluster,thepolling notificationthatexecutesthefirstscheduledrunisconsideredtobetheprimary notification.Thisinstancewillcontinuetoexecutethescheduledrunsaslongasitis enabledandfullyfunctional.Ifatanytimethisnotificationbecomesdisabled,another notificationintheclusterwillassumecontrol.Thenotificationthatassumescontrolis arbitrary.Afteranotificationhascontrol,itwillcontinuetoexecutethescheduleforas longasitisenabledandfullyfunctional. InDistributedmode,anyinstanceofthepollingnotificationcanexecutethecurrently scheduledrun.Thenotificationthatexecutesthecurrentscheduledrunisarbitrary.Ifa notificationdoesnotcompleteexecutingwithintheamountoftimespecifiedinthe Max Process Timefield,thesystemconsidersthatnotificationtobedead.(Fordetails aboutMax Process Time,seeNotificationSpecificSettingsonpage 59.)Another(enabled) instanceintheclusterwillrecognizethissituationandwillattempttoexecutethe scheduledrun. Settings Allsettingsthatpertaintoclusteredpollingnotificationsareignoredordisableduntilyou includetheserverinacluster.Allsettingshavedefaultvalues.Therearethreelevelsof settings:serverwide,adapterspecific,andnotificationspecific. ServerWideSettings TheserverwidesettingsarecommontoallwebMethods6.xadaptersrunningonthe IntegrationServer.Theserverusestheminanalgorithmthatdetermineswhethera pollingnotificationinstanceshouldbeconsidereddead. Server-wide Setting Name watt.art.clusteredPollingNotification. keepAliveInterval Values and Description Anintegervaluespecifyingthefrequency(in milliseconds)atwhichanotificationinstance tellstheclusteritisstillalive.Default:The valueofmaxlockdurationintherepository2.cnf file. Anintegervaluespecifyingthenumberof millisecondsthatakeepAliveIntervalsettingcan belatebeforeitisassumedthataninstance hasfailed.Default:Thevalueof keepAliveInterval. Note: Youshouldallowforclockdrift.For details,seeClockSynchronizationon page 60.
watt.art.clusteredPollingNotification. keepAliveExpireTimeout
55
AdapterSpecificSettings TheadapterspecificsettingsapplytoallthepollingnotificationsinyourJDBC Adapter. TheJDBCAdaptergeneratesaconfigurationfileforyourpollingnotification templates.Thisfile,WmJDBCAdapter\config\clusterProperties.cnf,isanXMLfile thatcontainsapairofsettings(callbackSchemeandruntimeModeLimit)foreachpolling notificationtemplatedefinedinyouradapter.Forexample,ifyoucreated notificationsusingthenotificationtemplatesBasicNotification,UpdateNotification, andInsertNotification,youwillseethesesettingsforeachtemplate.Foranexample file,seeExampleJDBCclusterProperties.cnfFileonpage 57. ThecallbackSchemesettingspecifiestheruntimeoperationstheadaptershould handleforthenotifications,suchasenablinganddisablingthenotifications. TheruntimeModeLimitsettingspecifiestheschedulingmodeforthenotifications: Standbymode,Distributedmode,orneither(thatis,nonclustered).Thesemodesare describedinStandbyModeandDistributedModeonpage 55.Thevalueyouassign tothissettingdetermineswhichmode(s)thattheadapterusersmayselectinthe Coordination ModefieldonthePollingNotificationSchedulepage(seeNotification SpecificSettingsonpage 59).
56
Theavailablevaluesforthesesettingsareasfollows: Adapter-specific Setting Name callbackScheme
Values and Description 0:Nocallbackcoordination. 1:Default.Coordinatestheenableanddisable operations. 2:Coordinatesthestartupandshutdownoperations. 3:Coordinatestheenable,disable,startup,and shutdownoperations. Important! Thisvaluemustalwaysbe1fortheJDBC Adapter.
runtimeModeLimit
disable:Preventstheadapteruserfromselecting StandbyorDistributemodesontheadaptersPolling NotificationSchedulepage. standby:Default.Enablestheadapterusertoselect eithertheDisablemodeortheStandbymode. distribute:Enablestheadapterusertoselecteitherthe Disable,StandbyorDistributemode. Formoreinformation,seeStandbyModeandDistributed Modeonpage 55.
ExampleJDBCclusterProperties.cnfFile ThefollowingexampleclusterProperties.cnffilefortheJDBCAdaptershowsthe entriesforallthepossibletemplatesassociatedwiththeJDBCpollingnotifications. ThisexamplefileenablesallnotificationstobeconfiguredwithaCoordinationMode ofDistributed.
57
<?xml version="1.0"?> <clusterProps> <pollingNotifications> <!-The following entries define the default settings used when the ART framework adds a new template entry to the file. For the JDBC Adapter the callbackSchema must always be 1. --> <callbackScheme>1</callbackScheme> <runtimeModeLimit>distribute</runtimeModeLimit> 
<template className="com.wm.adapter.wmjdbc.notifications.DeleteNotification">
<callbackScheme>1</callbackScheme> <runtimeModeLimit>distribute</runtimeModeLimit> </template> 
<template className="com.wm.adapter.wmjdbc.notifications.ProcedureNotification">
<callbackScheme>1</callbackScheme> <runtimeModeLimit>distribute</runtimeModeLimit> </template>  <template className="com.wm.adapter.wmjdbc.notifications.BasicNotification"> <callbackScheme>1</callbackScheme> <runtimeModeLimit>distribute</runtimeModeLimit> </template>  <template className="com.wm.adapter.wmjdbc.notifications.UpdateNotification"> <callbackScheme>1</callbackScheme> <runtimeModeLimit>distribute</runtimeModeLimit> </template>  <template className="com.wm.adapter.wmjdbc.notifications.InsertNotification"> <callbackScheme>1</callbackScheme> <runtimeModeLimit>distribute</runtimeModeLimit> </template>  <template className="com.wm.adapter.wmjdbc.notifications.OrderedNotification"> <callbackScheme>1</callbackScheme> <runtimeModeLimit>distribute</runtimeModeLimit> </template> </pollingNotifications> </clusterProps>
58
NotificationSpecificSettings Thenotificationspecificsettingsenableyoutoconfigurecertainschedulingaspectsof pollingnotificationsonanindividualbasis. TwonewfieldsappearonthePollingNotificationSchedulepage:Coordination Mode andMax Process Time.ThesefieldsbecomeeditablewhenyouaddyourIntegration Servertoacluster. TheCoordination Modefieldcontrolsthecoordinationofthenotificationschedules acrossthecluster.DependingonthevalueyouassignedtotheruntimeModeLimit setting(seeAdapterSpecificSettingsonpage 56),theadapteruserwillbeable toselectsomecombinationofthefollowingvaluesintheCoordination Modefieldas follows: This runtimeModeLimit value ... disable standby distribute
Displays these values in the Coordination Mode field ... disable disableandstandby disable,standby,anddistribute
TheMax Process Timefieldenablesothernotificationstodeterminewhethera currentlyexecutingnotificationshouldbeconsideredtobedead.Ifa notificationexecutesascheduledrunanditfailstocompletebeforetheMax ProcessTime,thenanothernotificationinstancewillconsideritdead;thisother notificationwillassumecontrolandexecuteascheduledrun.Thedefaultvalueis equaltothevalueinthewatt.art.clusteredPollingNotification.keepAliveExpireTimeout settingintheserver.cnffile. IftheMax Process Timesettingisnothighenough,youmayencounterasituation inwhichanotificationisexecutingnormallybutanothernotificationassumesitis dead.Whentheoriginalnotificationcompletes,itwillrecognizethatitwas prematurelyconsidereddead.Inthiscase,thesystemlogsanIllegalOverlap exceptionwithmessageid[ART.116.3715].Ifthisexceptionoccurs,increaseyour Max Process Timesetting. WhensettingthevalueofMaxProcessTime,youshouldallowforclockdrift. Fordetails,seeClockSynchronizationonpage 60. Ifyouwanttoupdatethescheduleandsettingsofanotificationinacluster,all notificationinstancesintheclustermustbesuspendedordisabledforthechangesto besaved.Ifanynotificationinstanceintheclusterisenabled,theadapterwillnotsave theupdates. Ifallinstancesofanotificationintheclusterdonothavethesamesettings,the notificationthatbecameactivefirstwillhaveprecedence.
59
ClockSynchronization Todeterminewhetheranotificationhasfailed,notificationsusethesystemclocksofthe machinesthathosttheclusteredIntegrationServers.Synchronizingtheclocksofall machinesintheclusteriscriticalfortheproperexecutionofclusteredpolling notifications. However,intimetheseclocksmightbecomeunsynchronized.Thereforeyoushould anticipatetheeffectofclockdriftwhenyouestablishvaluesforthe keepAliveExpireTimeoutandMax Process Timesettings.Clockdriftisthetimedifference betweentheclocks.Asaguideline,addtothekeepAliveExpireTimeoutandMax Process Time settingstwotimesthemaximumclockdriftyouanticipate. Configuring JDBC Polling Notifications To enable JDBC polling notifications to operate in Distributed mode 1 2 3 Inthecluster,shutdowntheIntegrationServeryouareconfiguring. OpentheWmJDBCAdapter\config\clusterProperties.cnffile. Changeall<runtimeModeLimit>valuesto<distribute>.Thisenablesalltemplates tooperateinDistributedmode.ForanexampleclusterProperties.cnffile,see ExampleJDBCclusterProperties.cnfFileonpage 57.Alternatively,youmayupdate onlyspecifictemplateentries. SavethefileandrestarttheIntegrationServer. StarttheIntegrationServerAdministrator. FromtheAdaptersmenuinthenavigationareaoftheAdministrator,selectJDBC Adapter. Fromthenavigationarea,selectPolling Notifications. FromtheJDBC Adapter Polling Notifications table,usetheEnabledfieldtodisablethe notification,andthenclicktheEdit Scheduleicon. SettheCoordination ModetoDistributed.
4 5 6 7 8 9
10 UsetheEnabledfieldtoenablethenotification. Important! Tomaintainduplicatedetectionandordering,yourpollingnotification schedulesmustnotrunwiththeOverlapoptionselected.(ToaccesstheOverlapoption,click theEdit Scheduleicon.) Afteryouconfigureapollingnotification,youmaypropagatealltheaffectedcomponents acrossyourcluster.ChangingthepollingnotificationschedulefromtheIntegrationServer AdministratororchangingthepollingnotificationsettingsinthewebMethodsDeveloper willrequireyoutopropagatethepollingnotificationacrossthecluster.Ifyoumade
60
changestothesettingsinserver.cnfortothe WmJDBCAdapter\config\clusterProperties.cnffiles,youmustalsopropagatethese acrossthecluster.
Adapter Service Support in Clusters

Adapterservicesaresupportedinaclusteredenvironment.Inorderforaclusterto handlerequestsidentically,youshouldbesuretheidenticalserviceisineachserverinthe clustersothatifagivenserviceisnotavailable,therequestcanberedirectedandhandled byanotherserverinthecluster. SeeClusteringConsiderationsandRequirementsonpage 62formoredetailsabout adapterservicesinclusters.
Replicating Packages to webMethods Integration Servers

EverywebMethodsIntegrationServerintheclustershouldcontainanidenticalsetof packagesthatyoudefineusingtheJDBCAdapter;thatis,youshouldreplicatetheJDBC Adapterservicesandtheconnectionstheyuse.Youdonotreplicatethepolling notifications. Toensureconsistency,werecommendthatyoucreateallpackagesononeserver,and replicatethemtotheotherservers.Ifyouallowdifferentserverstocontaindifferent services,youmightnotderivethefullbenefitsofclustering.Forexample,ifaclient requestsaservicethatresidesinonlyoneserver,andthatserverisunavailable,the requestcannotbesuccessfullyredirectedtoanotherserver. Forinformationaboutreplicatingpackages,seethechapteronmanagingpackagesinthe webMethodsAdministratorsGuide.
Disabling the Redirection of Administrative Services

AsmentionedinWhatiswebMethodsIntegrationServerClustering?onpage 49,a serverthatcannothandleaclientsservicerequestcanautomaticallyredirecttherequest toanotherserverinthecluster.However,theJDBCAdapterusescertainpredefined administrativeservicesthatyoushouldnotallowtoberedirected.Theseservicesareused internallywhenyouconfiguretheadapter.Ifyouallowtheseservicestoberedirected, yourconfigurationspecificationsmightbesavedonmultipleservers,whichisan undesirableresult.Forexample,ifyoucreatetwoJDBCAdapterservices,onemightbe storedononeserver,whiletheotheronemightbestoredonanotherserver.Remember thatalladapterservicesmustresideonallwebMethodsIntegrationServersinthecluster.
61
To disable the redirection of administrative services 1 2 ShutdowntheAdministrator.SeethewebMethodsAdministratorsGuideforthe proceduretodothis. Editthefollowingfile: IntegrationServer_directory\config\redir.cnf 3 4 Addthefollowinglinetothefile:
<value name="wm.art">false</value>
SavethefileandrestartthewebMethodsIntegrationServer.
Clustering Considerations and Requirements

Note: ThefollowingsectionsassumethatyouhavealreadyconfiguredthewebMethods IntegrationServercluster.FordetailsaboutwebMethodsclustering,seethewebMethods IntegrationServerClusteringGuide. ThefollowingconsiderationsandrequirementsapplytotheJDBCAdapterinaclustered environment.
Requirements for Each Integration Server in a Cluster

ThefollowingtabledescribestherequirementsofeachIntegrationServerinagiven cluster: All Integration Servers in a given cluster must have identical... IntegrationServerversions Adapterpackages
For Example... AllIntegrationServersintheclustermustbethesame version,withthesameservicepacksandfixesapplied. AlladapterpackagesononeIntegrationServershould bereplicatedtoallotherIntegrationServersinthe cluster.
62
All Integration Servers in a given cluster must have identical... Adapterconnections
For Example... Ifyouconfigureaconnectiontothedatabase,this connectionmustappearonallserversintheclusterso thatanyIntegrationServerintheclustercanhandlea givenrequestidentically. Ifyouplantouseconnectionpoolsinaclustered environment,seeConsiderationsWhenConfiguring ConnectionswithConnectionPoolingEnabledon page 63.
Adapterservices
IfyouconfigureaspecificInsertSQLAdapterService, thissameadapterservicemustappearonallserversin theclustersothatanyIntegrationServerinthecluster canhandletherequestidentically. IfyouallowdifferentIntegrationServerstocontain differentservices,youmightnotderivethefullbenefits ofclustering.Forexample,ifaclientrequestsaservice thatresidesononlyoneserver,andthatserveris unavailable,therequestcannotbesuccessfully redirectedtoanotherserver.
SeeReplicatingPackagestowebMethodsIntegrationServersonpage 61for informationaboutreplicatingadapterpackages,connections,andadapterservicesacross multipleIntegrationServersinacluster.
Considerations When Installing JDBC Adapter Packages

ForeachIntegrationServerinthecluster,usethestandardJDBCAdapterinstallation proceduresforeachmachine,asdescribedinthewebMethodsJDBCAdapterInstallation Guide.
Considerations When Configuring Connections with Connection Pooling Enabled

Whenyouconfigureaconnectionthatusesconnectionpoolsinaclusteredenvironment, besurethatyoudonotexceedthetotalnumberofconnectionsthatcanbeopened simultaneouslyforthatdatabase. Forexample,ifyouhaveaclusteroftwoIntegrationServerswithaconnectionconfigured toadatabasethatsupportsamaximumof100connectionsopenedsimultaneously,the totalnumberofconnectionspossibleatonetimemustnotexceed100.Thismeansthat youcannotconfigureaconnectionwithaninitialpoolsizeof100andreplicatethe connectiontobothservers,becausetherecouldbepossiblyatotalof200connections openedsimultaneouslytothisdatabase.
63
Inanotherexample,consideraconnectionconfiguredwithaninitialpoolsizeof10anda maximumpoolsizeof100.Ifyoureplicatethisconnectionacrossaclusterwithtwo IntegrationServers,itispossiblefortheconnectionpoolsizeonbothserverstoexceedthe maximumnumberofdatabaseconnectionsthatcanbeopenatonetime. ForinformationaboutconfiguringconnectionsfortheJDBCAdapter,seeConfiguring JDBCAdapterConnectionsonpage 68. Formoregeneralinformationaboutconnectionpools,seethewebMethodsIntegration ServerAdministratorsGuide.
64
CHAPTER
JDBC Adapter Connections

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Before Configuring or Managing Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Setting the Environment Variable for Oracle JDBC OCI Drivers . . . . . . . . . . . . . . . . . . . . . . 67 Installing the JDBC Driver on the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Configuring JDBC Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Dynamically Changing a Services Connection at Runtime . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Viewing Adapter Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Editing Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Copying Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Deleting Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Enabling Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Disabling Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
65
CHAPTER 3 JDBC Adapter Connections
Overview
ThischapterdescribeshowtoconfigureandmanageJDBCAdapterconnections.For moreinformationabouthowadapterconnectionswork,seeAdapterConnectionson page 13.
Before Configuring or Managing Adapter Connections

To prepare to configure or manage adapter connections 1 2 InstallthewebMethodsIntegrationServerandtheJDBCAdapteronthesame machine.SeethewebMethodsJDBCAdapterInstallationGuidefordetails. InstallacompatibleJDBCdriver.SeeInstallingtheJDBCDriverontheIntegration Serveronpage 67forinstructions.SeethewebMethodsJDBCAdapterInstallation Guideforalistofsupporteddrivers. MakesureyouhavewebMethodsadministratorprivilegessothatyoucanaccessthe JDBCAdaptersadministrativescreens.SeethewebMethodsIntegrationServer AdministratorsGuideforinformationaboutsettinguserprivileges. BesuretoseeDatabaseDriverKnownLimitationsonpage 187foralistofknown driverlimitationssinceitmayaffecthowyouconfigureyourconnections. StartyourIntegrationServerandtheAdministrator,iftheyarenotalreadyrunning. UsingtheAdministrator,makesuretheWmJDBCAdapterpackageisenabled.See EnablingandDisablingPackagesonpage 48forinstructions. UsingtheDeveloper,createauserdefinedpackagetocontaintheconnection,ifyou havenotalreadydoneso.Formoreinformationaboutmanagingpackagesforthe adapter,seeJDBCAdapterPackageManagementonpage 46. IfyouuseOracleJDBCOCIdrivers,youmustsetanenvironmentvariablebeforeyou canconfiguretheconnection.SeeSettingtheEnvironmentVariableforOracleJDBC OCIDriversonpage 67.
4 5 6 7
66
Setting the Environment Variable for Oracle JDBC OCI Drivers
Setting the Environment Variable for Oracle JDBC OCI Drivers

ForOracleJDBCOCIdrivers,youmustsetthefollowingenvironmentvariablebeforeyou configuretheconnection.AlsocheckthattheOCIclientisconfiguredcorrectlybeforeyou proceed. Platform Solaris* HP* AIX* Linux Environment Variable Setting
LD_LIBRARY_PATH=/ORACLE_HOME/lib SHLIB_PATH=/ORACLE_HOME/lib LIBPATH=/ORACLE_HOME/lib LD_LIBRARY_PATH=/ORACLE_HOME/lib
Note: *IfyouareusingOracle920JDBCdriverfileswithanOracle920clienttoconnectto differentOracledatabaseversions,settheenvironmentvariableforyourplatformto /ORACLE_HOME/lib32.
Installing the JDBC Driver on the Integration Server

YoumustinstalltheJDBCdriverontheIntegrationServerbeforeyoucanspecify connections.TheIntegrationServerrequiresaccesstotheJavaclassesforeachJDBC driverthatitwillusetoconnecttoadatabase.YoumustplacetheJavaclassesinalocation thattheservercanaccess.Typically,youplacetheJavaclassesintheserversclasspath. Toplacetheclassesintheserversclasspath,placethe.zipor.jarfilecontainingtheclasses intheIntegrationServer/package/WmJDBCAdapter/code/jarsdirectory.Restartthe IntegrationServer.Theserverwillautomaticallyaddthe.zipor.jarlibrariestoits classpathafteryourestart. SeethewebMethodsJDBCAdapterInstallationGuideforalistofsupporteddrivers.
67
Configuring JDBC Adapter Connections

WhenyouconfigureJDBCAdapterconnections,youspecifyinformationthatthe IntegrationServerusestoconnecttoaJDBCsystem.YouconfigureJDBCAdapter connectionsusingtheAdministrator. Note: IfyouwillbeusingOracleJDBCOCIdriverswiththeJDBCAdapter,youmustadd anenvironmentvariablesettingbeforeyouconfigureadapterconnections.SeeSetting theEnvironmentVariableforOracleJDBCOCIDriversonpage 67fordetails.
To configure a connection 1 2 3 4 IntheAdaptersmenuintheAdministratorsnavigationarea,clickJDBC Adapter. OntheConnectionsscreen,clickConfigure New Connection. OntheConnectionTypesscreen,clickJDBC Adapter Connectiontodisplaythe ConfigureConnectionTypescreen. IntheJDBC Adapter Connectionsection,usethefollowingfields. Field Package Description/Action Thepackageinwhichtocreatetheconnection. YoumustcreatethepackageusingtheDeveloperbeforeyou canspecifyitusingthisparameter.Forgeneralinformation aboutcreatingpackages,seethewebMethodsDeveloperUsers Guide. Note: Configuretheconnectioninauserdefinedpackage ratherthanintheadapterspackage.SeeJDBCAdapter PackageManagementonpage 46forotherimportant considerationswhencreatingpackagesfortheJDBCAdapter. Folder Name Connection Name Thefolderinwhichtocreatetheconnection. Thenameyouwanttogivetheconnection.Connectionnames cannothavespacesorusespecialcharactersreservedbythe IntegrationServerorDeveloper.SeethewebMethodsDeveloper UsersGuideformoreinformationabouttheuseofspecial charactersinpackage,folder,andelementnames.
68
IntheConnection Propertiessection,usethefollowingfields: Note: Thefollowingtableshowssuggestedvaluesfortheseparametersasguidance only.SeeyourJDBCdriverdocumentationformoreinformationaboutwhatvaluesto assigntheseparameters. a SpecifytheTransaction TypeandDataSource Class Nameasfollows: Field Transaction Type Description/Action Thetypeoftransactionsupportthattheconnection provides.Selectoneofthefollowingtransactiontypes: NO_TRANSACTION:Theconnectionautomaticallycommits operations. LOCAL_TRANSACTION:Theconnectionuseslocal transactions. IfyouplantousetheconnectionwithBatchInsertSQLor BatchUpdateSQLadapterservices,youmustspecify LOCAL_TRANSACTIONtype. Note: IfyouareconfiguringaBasicNotificationandusing theExactly Once Notification and Delete selected records options,youmustconfigurethenotificationtousea LOCAL_TRANSACTIONconnection.Seestep11don page141forinformationaboutthesespecific configurationoptions. XA_TRANSACTION:TheconnectionusesXAtransactions. Note: DonotuseXA_TRANSACTIONconnectionswith Teradatadatabases. Note: TheJDBCAdapterdoessupporttheOracleRACTAF facility(whichprovidesfailoversupport)for Oraclev.9.2.xusinganOCIdriver.Underthese circumstancesyoumustuseLOCAL_TRANSACTION connections. Foramoredetaileddescriptionofthetransactionsupport providedbytheJDBCAdapter,seeTransaction ManagementofJDBCAdapterConnectionsonpage 15.
69
Field DataSource Class Name
Description/Action ThenameoftheJDBCdriversDataSourceor XADataSourceclass. TypeoneofthefollowingDataSourceorXADataSource classnames,dependingontheJDBCdriverand transactiontypethattheconnectionwilluse. Oracle JDBC OCI Driver ForNO_TRANSACTIONandLOCAL_TRANSACTION:
oracle.jdbc.pool.OracleDataSource
ForXA_TRANSACTION:
oracle.jdbc.xa.client.OracleXADataSource
Oracle JDBC Thin Driver ForNO_TRANSACTIONandLOCAL_TRANSACTION:

oracle.jdbc.pool.OracleDataSource
ForXA_TRANSACTION:
oracle.jdbc.xa.client.OracleXADataSource
DataDirect Connect for JDBC, edition 3.2 and 3.3 (for Microsoft SQL Server) Foralltransactiontypes:
com.ddtek.jdbcx.sqlserver.SQLServerDataSource
Microsoft SQL Server 2000 Driver for JDBC 2.2.0019 Foralltransactiontypes:

com.microsoft.jdbcx.sqlserver. SQLServerDataSource
Microsoft SQL Server 2005 Driver for JDBC 1.0.809.102 Foralltransactiontypes:

com.microsoft.sqlserver.jdbc. SQLServerDataSource
JTOpen v4.1 (for DB2 for AS/400 v4r5, v5r1, and v5r2) ForNO_TRANSACTIONandLOCAL_TRANSACTION:
com.ibm.as400.access.AS400JDBCDataSource
ForXA_TRANSACTION:
com.ibm.as400.access.AS400JDBCXADataSource
70
Field DataSource Class Name (continued)
Description/Action DB2 net type 3 (for OS/390 v6 and v7, and UDB 7.2 and 8.1) ForNO_TRANSACTIONandLOCAL_TRANSACTION:
COM.ibm.db2.jdbc.DB2DataSource
DataDirect Connect for JDBC 3.2 (for UDB 7.2) ForNO_TRANSACTIONandLOCAL_TRANSACTION:

com.ddtek.jdbcx.db2.DB2DataSource
DataDirect Connect for JDBC 3.2 (for UDB 8.1) Foralltransactiontypes:

com.ddtek.jdbcx.db2.DB2DataSource
DB2 app type 2 (for UDB 7.2 and 8.1) ForNO_TRANSACTIONandLOCAL_TRANSACTION:

COM.ibm.db2.jdbc.DB2DataSource
ForXA_TRANSACTION:
COM.ibm.db2.jdbc.DB2XADataSource
DB2 Universal type 4 ForNO_TRANSACTIONandLOCAL_TRANSACTION: com.ibm.db2.jcc.DB2SimpleDataSource jCONNECT 5.5 type 4 (For Sybase v. 11.x and 12.x) ForNO_TRANSACTIONandLOCAL_TRANSACTION:
com.sybase.jdbc2.jdbc.SybDataSource
ForXA_TRANSACTION:
com.sybase.jdbc2.jdbc.SybXADataSource
71
Field DataSource Class Name (continued)
Description/Action Informix JDBC 2.21 type 4 (For Informix 7.31 and 9.x) ForNO_TRANSACTIONandLOCAL_TRANSACTION:
com.informix.jdbcx.IfxDataSource
Note: Ifyouusethecom.informix.jdbcx.IfxDataSource DataSourceclasswithIntegrationServerversion6.0.1SP2, youmustdisabletheWmTomcatpackage.Beawarethat disablingtheWmTomcatpackagealsodisablessupport foranyJSPs.Forgeneralinformationaboutsetting dependencies,seeJDBCAdapterPackageManagement onpage 46.Formoredetailedinformation,seethe webMethodsDeveloperUsersGuide. ForXA_TRANSACTION:
com.informix.jdbcx.IfxXADataSource
Teradata type 4 (for Teradata v2r5) ForNO_TRANSACTIONandLOCAL_TRANSACTION:

com.ncr.teradata.TeraDataSource
Dependingonthedrivertype,someorallofthefollowingfieldsarerequired.To determinewhetheryourdrivertyperequiresyoutouseafield,seeRequired ConnectionPropertyFieldsonpage 80. Note: IfyouuseaDataDirectConnectforJDBCdriveryoumustcreatethe packageandportinformationyouenterfromthistab.SeeyourDataDirect Connectdocumentationfordetails. Field serverName user* password* Retype password databaseName Description/Action Thenameoftheserverthathoststhedatabase. Theusernamethattheconnectionwillusetoconnectto thedatabase. Thepasswordforthedatabaseusernamespecifiedinuser. Retypethepasswordyoujustentered. Thedatabasetowhichtheconnectionwillconnect.
72
Field portNumber
Description/Action Theportnumberthattheconnectionwillusetoconnectto thedatabase. Note: TheDB2nettype3driverpropertyportNumberis thesameastheDB2JDBCAppletserversportnumber. Thedefaultis6789.
networkProtocol
AstandardJDBCDataSourcepropertytoindicatethe nameofthenetworkprotocolthattheconnectionwilluse whenconnectingtothedatabase. UsethisfieldonlyifyouuseanOracleJDBCOCIdriver. Typetcp,whichisthenameofthenetworkprotocol.
Note: *ForMicrosoftSQLServerdatabases:Theusernameandpasswordyou configureforaconnectionmustbethesameasthoseusedtocreatethetablesyou usewithaspecificnotification;otherwise,anexceptionwillbegeneratedatrun time. 6 TherearetwotypesofpropertysettingsyoucanspecifyintheOther Properties field: Table filter property settings:limitwhichcatalogs,schemasandtablestolist.See step abelow. Driver-dependent property settings: enableyoutoprovideadditionalJDBCdriver DataSourceproperties.Seestep bbelow. Usea ;(semicolon)todelimittablefilteranddriverdependentpropertysettings.Do notenterspacesafterthesemicolon.Forexample:
TableFilter=<current catalog>.Accounting;driverType=oci
TableFilterPropertySettingslimitthelistofcatalogs,schemas,andtablesyou selectwhenyoucreateadapterservicesandnotifications.Thissettingisbeneficial ifyouworkwithlargedatabases. UsethefollowingformattoenterTableFilterPropertySettingsinthe Other Propertiesfield:

TableFilter=catalog1.schema1.table1, catalog2.schema2.table2,catalogN.schemaN
Example:
TableFilter=Payables.Accounting.Finance
73
Note: TheTableFiltersettingiscasesensitive.Besurethatthenamesyouenter matchthenamesinthedatabasetable.Ifyouuse<current catalog> or <current schema>describedbelow,besurethatyouusealllowercaseletters. WhenconfiguringtheTableFilterproperty: Youcanuse <current catalog>asthecatalog forthedefaultlogin catalog. Youcanuse<current schema>astheschemafortheloginuser. Thetablevariableisthetablenamepatternandisoptional.Ifyoudonot specifyatablevalue,theJDBCAdapterloadsallofthetablesforthe schema.ThefollowingexamplelistsallthetablesundertheAccounting schema:
TableFilter=<current catalog>.Accounting
Note: Informixdatabasesautomaticallyaccessthecurrentcatalogonly. Youcanusetheexacttablenameoranyofthefollowingspecial charactersinaString: Use %tomatchanysubstringofzeroormorecharacters.Thefollowing examplelistsallthetablesundertheAccountingschemanamedFinance, Finance1,FinanceDept,andsoforth:

TableFilter=<current catalog>.Accounting. Finance%
Use _tomatchanyonecharacter.Thefollowingexamplelistsallthe tablesundertheAccountingschemanamedFinance1,Finance2, Finance3,andsoforth.

TableFilter=<current catalog>.Accounting. Finance_
Use ,(commas)tolistmultipleTableFiltersettings.Donotenterspaces afterthecomma.Forexample:

TableFilter=<current catalog>.Accounting. Finance_,<current catalog>.Employee%
Use ;(semicolons)todelimitmultiplepropertysettings;thatis,both TableFiltersettingsanddriverdependentsettings.Donotenterspaces afterthesemicolon.Forexample:

TableFilter=<current catalog>.Accounting. Finance_,<current catalog>.Accounting;driverType=thin
74
YoualsousetheOther Propertiesfieldtosetdriverdependantpropertysettings, whichenableyoutoprovideadditionalJDBCdriverDataSourceproperties dependingonthedriveryouuse. Usethefollowingformat: propertyName=value Use ;(semicolons)todelimitmultiplepropertysettings;thatis,both TableFiltersettingsanddriverdependentsettings.Donotenterspacesafter thesemicolon.Forexample:
TableFilter=<current catalog>.Accounting. Finance;selectMethod=cursor
IntheOther Propertiesfield,typethefollowingsuggesteddriverdependent parametersbasedontheJDBCdriverandthetransactiontypetheconnectionis using: Field Other Properties (Driver-dependent Properties) Description/Action DataDirect Connect for JDBC 3.2 for DB2 UDB 7.2 and 8.1:
PackageName=value
wherevalue isthenameofthepackageyoucreated earlierinthedatabase.SeeyourDataDirectConnectfor JDBCdocumentationforinformationaboutcreating packages. DB2 Universal type 4:

driverType=4
Requiredsettingforthisdriver.IfthedriverTypeis notsetto4,thenType2connectivitywillbeselected bydefault.

readOnly=true
Createsareadonlyconnection.
currentSchema=YourSchemaName
Specifiesthedefaultschemanameusedtoqualify unqualifieddatabaseobjectsindynamically preparedSQLstatements.

loginTimeout=number
Themaximumtimeinsecondstowaitforthe DataSourceobjecttoconnecttoadatasource.
75
Field Other Properties (continued)
Description/Action
traceFile=fileName
Specifiesthenameofafileintowhichthisdriverwrites traceinformation.
traceFileAppend=true
Appends,insteadofoverwrites,thefilethatis specifiedbythetraceFileproperty.
traceLevel=number
Specifieswhatleveltotrace.Thispropertysdatais INTEGER.Setnumberto-1toTRACE_ALLor2to TRACE_STATEMENT_CALLS.Seeyourvendors driverdocumentationformoreinformation. DataDirect Connect for JDBC edition 3.2 and 3.3 for Microsoft SQL Server: ForXA_TRANSACTIONonly:
selectMethod=cursor
Microsoft SQL Server 2000 Driver for JDBC: ForXA_TRANSACTIONonly:

selectMethod=cursor
Microsoft SQL Server 2005 Driver for JDBC: ForXA_TRANSACTIONonly:

selectMethod=cursor
Oracle JDBC Thin Driver:

driverType=thin
Oracle JDBC OCI Driver version 8i:

driverType=oci8
Oracle JDBC OCI Driver version 9i:

driverType=oci
76
Field
Description/Action Teradata Type 4:

DSName=value
wherevalueistheTeradatadatabaseservername. Informix JDBC 2.21 type 4 (for NO_TRANSACTION. LOCAL_TRANSACTION, and XA_TRANSACTION):
IfxIFXHOST=hostname
wherehostnameisthemachinenameofthedatabase server. 7 IntheConnection Management Propertiessection,usethefollowingfields: Field Enable Connection Pooling Description/Action Enablestheconnectiontouseconnectionpooling. SeeAdapterConnectionsonpage 13formoreinformation aboutconnectionpooling. Note: Ifyouplantoenableconnectionpoolinginaclustered environment,considertheconnectionpoolsize.Fordetails, seeConsiderationsWhenConfiguringConnectionswith ConnectionPoolingEnabledonpage 63. Minimum Pool Size Ifconnectionpoolingisenabled,thisfieldspecifiesthe numberofconnectionstocreatewhentheconnectionis enabled.Theadapterwillkeepopenthenumberof connectionsyouconfigurehereregardlessofwhetherthese connectionsbecomeidle. Ifconnectionpoolingisenabled,thisfieldspecifiesthe maximumnumberofconnectionsthatcanexistatonetimein theconnectionpool. Ifconnectionpoolingisenabled,thisfieldspecifiesthe numberofconnectionsbywhichthepoolwillbeincremented ifconnectionsareneeded,uptothemaximumpoolsize.
Maximum Pool Size
Pool Increment Size
77
Field Block Timeout
Description/Action Ifconnectionpoolingisenabled,thisfieldspecifiesthe numberofmillisecondsthattheIntegrationServerwillwaitto obtainaconnectionwiththedatabasebeforeittimesoutand returnsanerror. Forexample,youhaveapoolwithMaximum Pool Sizeof20.If youreceive30simultaneousrequestsforaconnection,10 requestswillbewaitingforaconnectionfromthepool.Ifyou settheBlock Timeoutto5000,the10requestswillwaitfora connectionfor5secondsbeforetheytimeoutandreturnan error.Iftheservicesusingtheconnectionsrequire10seconds tocompleteandreturnconnectionstothepool,thepending requestswillfailandreturnanerrormessagestatingthatno connectionsareavailable. IfyousettheBlock Timeoutvaluetoohigh,youmayencounter problemsduringerrorconditions.Ifarequestcontainserrors thatdelaytheresponse,otherrequestswillnotbesent.This settingshouldbetunedinconjunctionwiththeMaximum Pool Sizetoaccommodatesuchburstsinprocessing.
Expire Timeout
Ifconnectionpoolingisenabled,thisfieldspecifiesthe numberofmillisecondsthataninactiveconnectioncanremain inthepoolbeforeitisclosedandremovedfromthepool. Theconnectionpoolwillremoveinactiveconnectionsuntilthe numberofconnectionsinthepoolisequaltotheMinimum Pool Size.Theinactivitytimerforaconnectionisresetwhenthe connectionisusedbytheadapter. IfyousettheExpire Timeout valuetoohigh,youmayhavea numberofunusedinactiveconnectionsinthepool.This consumeslocalmemoryandaconnectiononyourbackend resource.Thiscouldhaveanadverseeffectifyourresource hasalimitednumberofconnections. IfyousettheExpire Timeout valuetoolow,performancecould degradebecauseoftheincreasedactivityofcreatingand closingconnections.Thissettingshouldbetunedin conjunctionwiththeMinimum Pool Sizetoavoidexcessive opening/closingofconnectionsduringnormalprocessing.
78
Field Startup Retry Count
Description/Action (ThisfieldappliesonlytoIntegrationServerversions6.1and later.)Thenumberoftimesthatthesystemshouldattemptto initializetheconnectionpoolatstartupiftheinitialattempt fails.Thedefaultis0. (ThisfieldappliesonlytoIntegrationServerversions6.1and later.)Thenumberofsecondsthatthesystemshouldwait betweenattemptstoinitializetheconnectionpool.
Startup Backoff Timeout
ClickSave Connection. Iftheparametersfortheconnectionarevalid,theIntegrationServerenablesthe connection.Otherwise,theIntegrationServerdoesnotenabletheconnection. TheconnectionyoucreatedappearsontheadaptersConnectionsscreenandinthe DeveloperServiceBrowser.
79
Required Connection Property Fields ThefollowingtableliststherequiredConnection Propertiestabfieldsbydrivertype.For detailsaboutthefollowingfields,seestep 5bonpage72. Network Protocol No
Driver Name DB2 net type 3 (for OS/390 V6 and V7, and UDB V7.2 and V8.1) DB2 Universal type 4 Teradata Type 4 DataDirect Connect for JDBC 3.2 (for UDB 7.2 and 8.1) DB2 app type 2 (for UDB V7.2 and V8.1) Microsoft SQL Server 2000 (for JDBC 2.20019) Microsoft SQL Server 2005 (for JDBC 1.0.809.102) Microsoft SQL Server 7 with DataDirect Connect for JDBC Oracle Thin Oracle OCI JTOpen v4.1 (for DB2 for AS/400 v4r5, v5r1, and v5r2) Informix JDBC 2.21 type 4 (Informix v. 7.31 and 9.x) jCONNECT 5.5 type 4 (for Sybase v. 11.x and 12x)
serverName Yes
user Yes
password Yes
databaseName Yes
portNumber Yes
Yes No Yes
Yes Yes Yes
Yes Yes Yes
Yes No Yes
Yes No Yes
No No No
No Yes Yes Yes
Yes Yes Yes Yes
Yes Yes Yes Yes
Yes No No No
No Yes Yes Yes
No No No No
Yes Yes Yes
Yes Yes Yes
Yes Yes Yes
Yes Yes No
Yes Yes No
No Yes No
Yes Yes
Yes Yes
Yes Yes
Yes Yes
Yes Yes
No No
80
Dynamically Changing a Services Connection at Runtime
Dynamically Changing a Services Connection at Runtime

BeginningwithIntegrationServer6.5,youmayrunaserviceusingaconnectionother thanthedefaultconnectionthatwasassociatedwiththeservicewhentheservicewas created.Tooverridethedefault,youmustcodeyourflowtopassavaluethroughthe pipelineintoaservices$connectionNamefield. Forexample,youhaveaflowwhoseprimarypurposeistoupdateaproductiondatabase. However,youwanttheflowtohavethecapabilitytoupdateatestdatabasewiththe decisionofwhichdatabasetoupdatetobemadeprogrammaticallyatruntime.The outputsignatureoftheflowsfirstservicecontainsafieldcalledTarget.Theflowcould branchbasedonthevalueinTarget.IfTargetcontainsthevalueProduction,thesecond serviceintheflowwouldignore$connectionNamethususingitsdefaultconnectionto connectto(andthenupdate)theproductiondatabase.However,ifTargetcontainsthe valueTest,thesecondserviceintheflowwouldusethevalueinthe$connectionName fromthepipelineandconnectto(andthenupdate)thetestdatabase. Keepinmindtheserestrictionswhenusingdynamicconnections: Bothconnectionsthedefaultandoverridemustusethesamedatabaseschema. Theconnectionwithwhichyouoverridethedefault(thatis,thevalueprovidedfor $connectionName)mustbeconfiguredtousethesametransactiontypeasthedefault connection. The$connectionNamefieldispresentonlyinservices createdwithDeveloper6.5 createdwithDeveloper6.1(orearlier)andeditedwithDeveloper6.5 Formoreinformation,seeChangingtheConnectionAssociatedwithanAdapterService atRuntimeonpage 20.
81
Viewing Adapter Connection Parameters

YoucanviewaconnectionsparametersfromtheAdministratororfromtheDeveloper. To view the parameters for a connection using the Administrator 1 2 IntheAdaptersmenuintheAdministratorsnavigationarea,clickJDBC Adapter. OntheConnectionsscreen,clicktheViewicon fortheconnectionyouwanttosee.
TheViewConnectionscreendisplaystheparametersfortheconnection.For descriptionsoftheconnectionparameters,seeConfiguringJDBCAdapter Connectionsonpage 68. 3 ClickReturn to JDBC Adapter Connections toreturntothemainconnectionsscreen.
To view the parameters for a connection using the Developer 1 2 3 StarttheDeveloperifitisnotalreadyrunning. FromtheDevelopernavigationarea,openthepackageandfolderinwhichthe connectionislocated. Clicktheconnectionyouwanttoview. TheparametersfortheconnectionappearontheConnection Informationtab.For descriptionsoftheconnectionparameters,seeConfiguringJDBCAdapter Connectionsonpage 68.
Editing Adapter Connections

Ifthelogininformationforadatabasechanges,orifyouwanttoredefineparametersthat aconnectionuseswhenconnectingtoadatabase,youcanupdateaconnections parametersusingtheAdministrator. To edit a connection 1 2 IntheAdaptersmenuintheAdministratorsnavigationarea,clickJDBC Adapter. Makesurethattheconnectionisdisabledbeforeeditingit.SeeDisablingAdapter Connectionsonpage 85forinstructions.
82
Copying Adapter Connections
OntheConnectionsscreen,clicktheEditicon
fortheconnectionyouwanttoedit.
TheEditConnectionscreendisplaysthecurrentparametersfortheconnection. Updatetheconnectionsparametersbytypingorselectingthevaluesyouwantto specify. Fordescriptionsoftheconnectionparameters,seeConfiguringJDBCAdapter Connectionsonpage 68. 4 ClickSave Changes tosavetheconnectionandreturntotheConnectionsscreen.
Copying Adapter Connections

YoucancopyanexistingJDBCAdapterconnectiontoconfigureanewconnectionwith thesameorsimilarconnectionpropertieswithouthavingtoretypealloftheproperties fortheconnection.YoucopyadapterconnectionsusingtheAdministrator. To copy a connection 1 2 IntheAdaptersmenuintheAdministratorsnavigationarea,clickJDBC Adapter. OntheConnectionsscreen,clicktheCopyicon copy. fortheconnectionyouwantto
TheCopyConnectionscreendisplaysthecurrentparametersfortheconnectionyou wanttocopy.Namethenewconnection,specifyapackagenameandfoldername, andeditanyconnectionparametersasneededbytypingorselectingthevaluesyou wanttospecify. Note: Whenyoucopyaconnection,thenewconnectiondoesnotsavethepasswordof theoriginalconnection.Youmustenterandthenretypethepasswordbeforeyoucan savethenewconnection. Fordescriptionsoftheconnectionparameters,seeConfiguringJDBCAdapter Connectionsonpage 68. 3 ClickSave Connection tosavetheconnectionandreturntotheConnectionsscreen.
83
Deleting Adapter Connections

IfyounolongerwanttouseaparticularJDBCAdapterconnection,youcandeleteitby followingtheinstructionsinthissection.Youdeleteadapterconnectionsusingthe Administrator. IfyoudeleteaJDBCAdapterconnection,theadapterservicesornotificationsthatare definedtousetheconnectionwillnolongerwork.However,dependingonwhichversion oftheIntegrationServeryouuse,youmaybeabletoassignadifferentconnectiontoan adapterserviceandreusetheservice,asfollows: WhenusingversionsoftheIntegrationServerearlierthan6.1,youcannotchange whichconnectionanadapterserviceusesaftertheserviceisconfigured.(However, youcanchangetheparametersforanexistingconnection;seeEditingAdapter Connectionsonpage 82forinstructions.)Therefore,ifyoudeleteaJDBCAdapter connection,anyadapterservicesornotificationsthataredefinedtousethe connectionwillnolongerwork. WhenusingIntegrationServer6.1orlater,youcanchangewhichconnectionan adapterserviceuses.Therefore,ifyoudeleteaJDBCAdapterconnection,youcan assignadifferentconnectiontoanadapterserviceandreusetheservice.Todothis, youusethebuiltinwebMethodsfunctionsetAdapterServiceNodeConnection.For moreinformation,seeChangingtheConnectionAssociatedwithanAdapterService orNotificationatDesignTimeonpage 19. To delete a connection 1 2 IntheAdaptersmenuintheAdministratornavigationarea,clickJDBC Adapter. Makesurethattheconnectionisdisabledbeforedeleting.Todisabletheconnection, clickYesintheEnabledcolumnandclickOKtoconfirm.TheEnabledcolumnnow showsNo(Disabled)fortheconnection. OntheConnectionsscreen,click fortheconnectionyouwanttodelete.
TheIntegrationServerdeletestheadapterconnection.
84
Enabling Adapter Connections
Enabling Adapter Connections

AJDBCAdapterconnectionmustbeenabledbeforeyoucanconfigureanyadapter serviceusingtheconnection,orbeforeanadapterservicecanusetheconnectionatrun time.YouenableadapterconnectionsusingtheAdministrator. Note: Whenyoureloadapackagethatcontainsenabledconnections,theconnectionswill automaticallybeenabledwhenthepackagereloads.Ifthepackagecontainsconnections thataredisabled,theywillremaindisabledwhenthepackagereloads.
To enable a connection 1 2 IntheAdaptersmenuintheAdministratornavigationarea,clickJDBC Adapter. OntheConnectionsscreen,clickNointheEnabledcolumnfortheconnectionyouwant toenable. TheIntegrationServerAdministratorenablestheadapterconnectionanddisplays a andYesintheEnabledcolumn.
Disabling Adapter Connections

JDBCAdapterconnectionsmustbedisabledbeforeyoucaneditordeletethem.You disableadapterconnectionsusingtheAdministrator. To disable a connection 1 2 IntheAdaptersmenuintheAdministratornavigationarea,clickJDBC Adapter. OntheConnectionsscreen,clickYesintheEnabledcolumnfortheconnectionyou wanttodisable. TheadapterconnectionbecomesdisabledandyouseeaNointheEnabledcolumn.
85
86
CHAPTER
Adapter Services
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Before Configuring or Managing Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Configuring SelectSQL Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Configuring InsertSQL Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Configuring UpdateSQL Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Configuring BatchInsertSQL Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Configuring BatchUpdateSQL Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Configuring DeleteSQL Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Configuring CustomSQL Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Configuring DynamicSQL Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Configuring StoredProcedure Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115 Testing Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119 Viewing Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119 Editing Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 Deleting Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 Validating Adapter Service Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Reloading Adapter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
87
CHAPTER 4 Adapter Services
Overview
ThischapterdescribeshowtoconfigureandmanageJDBCAdapterservices.Fordetailed descriptionsoftheavailableJDBCAdapterservices,seeAdapterServicesonpage 17.
Before Configuring or Managing Adapter Services

To prepare to configure or manage JDBC Adapter services 1 2 StartyourIntegrationServerandtheAdministrator,iftheyarenotalreadyrunning. MakesureyouhaveIntegrationServerAdministratorprivilegessothatyoucan accesstheJDBCAdaptersadministrativescreens.SeethewebMethodsIntegration ServerAdministratorsGuideforinformationaboutsettinguserprivileges. BesuretocheckDatabaseDriverKnownLimitationsonpage 187foralistof knownlimitationsforyourdatabasedriversinceitmayaffecthowyouconfigure yourconnectionsandadapterservices. Ifyouhavemadechangestothetableschemaforagivenadapterservice,besureto updatetheadapterserviceaccordingly. UsingtheAdministrator,makesuretheWmJDBCAdapterpackageisenabled.See EnablingandDisablingPackagesonpage 48forinstructions. UsingtheAdministrator,configureanadapterconnectiontousewiththeadapter service.SeeConfiguringJDBCAdapterConnectionsonpage 68forinstructions. Note: WhenusingversionsoftheIntegrationServerearlierthan6.1,youmaynot assignadifferentconnectiontoanadapterserviceafteryouconfiguretheservice.You may,however,changetheparametersoftheconnection. Beginningwithversion6.1,theIntegrationServersolvesthislimitationbyproviding abuiltinserviceyoucanuseatdesigntimetochangetheconnectionassociatedwith anadapterservice.Formoreinformation,seeChangingtheConnectionAssociated withanAdapterServiceorNotificationatDesignTimeonpage 19. 7 8 StarttheDeveloperifitisnotalreadyrunning. IfyouareusingtheDeveloper6.1orlater,makesureyouareviewingthe webMethodsDeveloperintheEditperspective,asdescribedinViewingDifferent PerspectivesofthewebMethodsDeveloperonpage 43. UsingtheDeveloper,createauserdefinedpackagetocontaintheservice,ifyouhave notalreadydoneso.Whenyouconfigureadapterservices,youshouldalwaysdefine theminuserdefinedpackagesratherthanintheWmJDBCAdapterpackage.For
4 5 6
88
Configuring SelectSQL Services
moreinformationaboutmanagingpackagesfortheadapter,seeChapter 2,Package Managementonpage 45.

ASelectSQLserviceretrievesspecifiedinformationfromadatabasetable.Youconfigure JDBCadapterservicesusingtheDeveloper.Formoreinformationaboutadapterservices, seeUsingAdapterServicesonpage 19. BesuretoreviewthesectionBeforeConfiguringorManagingAdapterServiceson page 88beforeyouconfigureadapterservices.
To configure a SelectSQL service 1 2 3 4 5 6 FromtheDeveloperFilemenu,selectNew... SelectAdapter ServicefromthelistofelementsandclickNext. SelectJDBC AdapterastheadaptertypeandclickNext. SelecttheappropriateAdapter Connection NameandclickNext. SelecttheSelectSQLtemplateandclickNext. Typeauniquenamefortheserviceandselecttheappropriatefolder.ClickFinish. Theadapterserviceeditorfortheadapterserviceappears.YoucanselecttheAdapter SettingstabatanytimetoconfirmadapterservicepropertiessuchastheAdapter Name, Adapter Connection Name,andAdapter Service Template,asnecessary. 7 SelecttheTablestabtoconfigurethedatabasetable(ortables)theoperationaccesses, usingthefollowingfields: Field Table Alias Table Name Description/Action Thetablealiasisassignedautomaticallywhenyouselectmore thanonetableintheTable Namefield.Thedefaultist1. Selectatablename.Thedefaultfortheassociatedcatalog nameiscurrent catalog.Thedefaultfortheassociated schemanameiscurrent schema. Thetablenamemustnotcontainaperiod.Ifthetablename doescontainaperiod,DeveloperwillthrowaJavaexception. Note: Informixdatabasesdonotallowyoutospecifyacatalog anddatabasenamebecauseyoucanonlyaccessthecurrent catalog.
89
Field Type
Description/Action Thetypedisplaysautomaticallybasedonthetableyouselect.
Ifyouarenotjoiningtables,skipthisstep.SelecttheJoinstabtospecifythecolumns forjoiningthetablesyoujustconfigured. a b c d e SelecttheInsert Rowicon tocreatenewleftandrightcolumns.
SelectLeft Columnandselectthefirsttablesjoiningcolumn. SelecttheappropriateOperator. SelectRight Columnandselectthenexttablesjoiningcolumn. Repeatthisprocedureuntilyouhavedefinedallthejoins.
UsetheSELECTtabtodefinethecolumnsandfieldstobeselectedasfollows: a IntheALL/DISTINCTfield,selectALLtoincludeduplicaterowsorDISTINCTto suppressduplicaterows.SelectingALLcorrespondstotheSQLstatementSELECT ALL name from tablename.Thedefaultvalueisblank,whichcorrespondstothe SQLstatementSELECT name from tablename. UsetheInsert Rowicon rowsasneeded. (ortheFill in all rows to the tableicon )tocreatenew
b c
Asyouinsertadditionalrows,thecorrespondingColumn Type,JDBC Type,Output Field Type, and Output Field displayforeachcolumnyouselectintheExpression field. Note: YoucanusetheBigDecimaldatatypewiththeJDBCAdapter.However,the webMethodsDeveloperdoesnotsupporttheBigDecimaldatatype.Thismeans thattheDeveloperwillnotcorrectlydisplayaBigDecimaldatatyperesultand youcannotenteravalueofthisdatatype.However,theJDBCAdapterwill processtheBigDecimaldatatypecorrectly. Usethefollowingfields: Field Expression Column Type JDBC Type Description/Action Thecolumnnameinthedatabasetable. Thecolumndatatypedefinedinthedatabasetable. TheJDBCtypeofthecorrespondingOutput Field.
90
Field Output Field Type
Description/Action Thedatatypeoftheoutputfield.TheJDBCAdapter automaticallyconvertsdatabasespecifictypestoJavadata types. Thenameofthefieldcontainingtheoutputfromthe SELECToperation.Anoutputfieldnamedisplayswhen youselectanexpression. Youcanalsomodifytheoutputfieldnamesasrequired.
Output Field
Sort Order
Specifieshowrowsarereturnedasfollows: SelecteitherAscendorDescend.Leavethefieldblankif thereisnosortorder.
Maximum Row
Usethisfieldonlytospecifythemaximumnumberof recordstoretrievefromthedatabase.Thedefaultvalueof 0(nolimit)retrievesallrecords.
10 UsetheWHEREtabtospecifytheconditionsforselectinginformation: a b SelecttheInsert Rowicon todefinenewWHEREclausefields.
SelectalogicaloperatorfromtheAND/ORfield,anOperator,andseparators(theleft andrightparentheses)asneeded,andusethefollowingfields: Field AND/OR Column Operator Input Field* Description/Action Thelogicaloperator. ThenameofthecolumnyouwanttouseintheWHERE clause. TheoperatorusedwiththeColumnandInput Field. Thedefaultvalueis?,whichactsasaplaceholderforthe variablesothatyoucansettheinputvariableforthat columnatruntime,orgetinputexternaltothisadapter service. Youcanalsotypeafixedvalueinthisfieldnoworatrun time.Ifyoutypeafixedvalue,besurethatitisvalid,oran exceptionwillbegeneratedatruntime. JDBC Type Input Field Type TheJDBCtypeofthecorrespondingInput Field. ThecorrespondinginputfieldsJavatype. ForalistofJDBCtypetoJavatypemappings,seeJDBC DataTypetoJavaDataTypeMappingsonpage 170.
91
Field Input Field (second occurrence of this field)
Description/Action Typethenameoftheinputfield. Ifyouusethedefault?variableplaceholderastheInput FieldvalueintheWHEREclause,besuretoenterthe correspondingInput FieldanditsJDBC Field Typeinthe sameorderastheyappearonthetopportionofthe WHEREtab.
Note: * ForOracleusers,ifyouuseaCHARdatatypeandenteravalueintheInput Field,youmustpadthefieldwithspacesequaltothetotalcolumnwidth.For example,ifyouusethevalueSmithintheinputfieldanddefineitasaCHAR datatypeof50bytes,youmustpadthefieldwith45spaces.Analternativeisto useaDynamicSQLadapterservicebecauseyoudonotneedtopadthisfieldwhen youuseaSQLstatement.Usethe${value}toreplacethe?variableplaceholder, suchasWHERE char_col = ${value}.Thisvaluewillbeintheinputlistsothat atruntimeyoucansetthevaluetoaStringwithouthavingtopadthecolumn width.SeeConfiguringDynamicSQLServicesonpage 111foranexampleand configurationinstructions. c d Ifnecessary,usetheShift Up orShift Down iconstochangetheorderofthe WHEREclausetoensuretheparametersareparsedinthecorrectorder. RepeatthisprocedureuntilyouhavespecifiedallWHEREparameters.
11 ForinformationaboutusingtheInput/Output,Settings, Audit,Permissions,and Results tabs,seethewebMethodsDeveloperUsersGuide.Thesetabsapplytoallservicesthat youconfigureusingversionsoftheDeveloperearlierthan6.1. WhenusingDeveloper6.1orlater,theDeveloperonlycontainstheAdapter Settings andInput/Outputtabs.TheinformationfromtheAuditandPermissionstabsappearsin thePropertiespanel,andtheinformationfromtheResultstabappearsintheResults panel. 12 FromtheFilemenu,selectSave(or Save All). Torunortesttheservicedirectly,seeTestingAdapterServicesonpage 119.
Configuring InsertSQL Services

AnInsertSQLserviceinsertsnewinformationintoadatabasetable.YouconfigureJDBC adapterservicesusingtheDeveloper.Formoreinformationaboutadapterservices,see UsingAdapterServicesonpage 19. BesuretoreviewthesectionBeforeConfiguringorManagingAdapterServiceson page 88beforeyouconfigureadapterservices.
92
Configuring InsertSQL Services
To configure an InsertSQL service 1 2 3 4 5 6 FromtheDeveloperFilemenu,selectNew... SelectAdapter ServicefromthelistofelementsandclickNext. SelectJDBC AdapterastheadaptertypeandclickNext. SelecttheappropriateAdapter Connection NameandclickNext. SelecttheInsertSQLtemplateandclickNext. Typeauniquenamefortheserviceandselecttheappropriatefolder.ClickFinish. Theadapterserviceeditorfortheadapterserviceappears.YoucanselecttheAdapter SettingstabatanytimetoconfirmadapterservicepropertiessuchastheAdapter Name, Adapter Connection Name,andAdapter Service Template,asnecessary. 7 SelecttheTabletabtoconfigurethedatabasetabletobeupdatedandsetthefieldsas follows: Field Table Name Description/Action Selectatablename.Thedefaultfortheassociatedcatalog nameiscurrent catalog.Thedefaultfortheassociated schemanameiscurrent schema. Thetablenamemustnotcontainaperiod.Ifthetablename doescontainaperiod,DeveloperwillthrowaJavaexception. Note: Informixdatabasesdonotallowyoutospecifyacatalog anddatabasenamebecauseyoucanonlyaccessthecurrent catalog. Type Thetabletypedisplaysautomaticallybasedonthetableyou select.
SelecttheINSERTtabandusetheColumn,Column Type, JDBCTypeandExpressionfields onthetoprowofthetabtodefinethecolumnsandfieldstobeinsertedasdescribed inthefollowingtable. a UsetheInsert Rowicon rowsasneeded. Field Column Column Type (ortheFill in all rows to the tableicon )tocreatenew
Description/Action TheINSERTcolumnnameinthedatabasetable. TheINSERTcolumndatatypeinthedatabasetable.
93
Field JDBCType Expression
Description/Action TheJDBCtypefortheinputfield. Thedefaultvalueis?,whichactsasaplaceholderforthe variablesothatyoucansettheinputvariableforthat columnatruntime,orgetinputexternaltothisadapter service.Itaddsonerowwiththesamecolumnnametothe table. Youcanalsotypeafixedvalueinthisfieldnoworatrun time.Ifyoutypeafixedvalue,besurethatitisvalid,oran exceptionwillbegeneratedatruntime.
ForeachinsertedrowthatusesthedefaultExpressionvalueof?,the correspondingJDBCType,Input Field,andInput Field Typedisplayonthesecondrow oftheINSERTtab. Note: YoucanusetheBigDecimaldatatypewiththeJDBCAdapter.However,the webMethodsDeveloperdoesnotsupporttheBigDecimaldatatype.Thismeans thattheDeveloperwillnotcorrectlydisplayaBigDecimaldatatyperesultand youcannotenteravalueofthisdatatype.However,theJDBCAdapterwill processtheBigDecimaldatatypecorrectly. Usethefollowingfields: Field Column Column Type JDBCType Input Field* Input Field Type Description/Action TheINSERTcolumnnameinthedatabasetable. TheINSERTcolumndatatypeinthedatabasetable. TheJDBCtypefortheinputfield. Theinputfieldname.Youcanchangethisnameifneeded. Thedatatypeoftheinputfield.Youcanchangethistypeif needed.
94
Configuring UpdateSQL Services
Note: * ForOracleusers,ifyouuseaCHARdatatypeandenteravalueintheInput Field,youmustpadthefieldwithspacesequaltothetotalcolumnwidth.For example,ifyouusethevalueSmithintheinputfieldanddefineitasaCHAR datatypeof50bytes,youmustpadthefieldwith45spaces.Analternativeisto useaDynamicSQLadapterservicebecauseyoudonotneedtopadthisfieldwhen youuseaSQLstatement.Usethe${value}toreplacethe?variableplaceholder, suchasWHERE char_col = ${value}.Thisvaluewillbeintheinputlistsothat atruntimeyoucansetthevaluetoaStringwithouthavingtopadthecolumn width.SeeConfiguringDynamicSQLServicesonpage 111foranexampleand configurationinstructions. 9 UsetheResulttabsResult FieldandResult Field Typetospecifytheoutputfieldname andcorrespondingfieldtypesfortheresultingnumberofrowsthathavebeen inserted.
10 ForinformationaboutusingtheInput/Output,Settings, Audit,Permissions,and Results tabs,seethewebMethodsDeveloperUsersGuide.Thesetabsapplytoallservicesthat youconfigureusingversionsoftheDeveloperearlierthan6.1. WhenusingDeveloper6.1orlater,theDeveloperonlycontainstheAdapter Settings andInput/Outputtabs.TheinformationfromtheAuditandPermissionstabsappearsin thePropertiespanel,andtheinformationfromtheResultstabappearsintheResults panel. 11 FromtheFilemenu,selectSave(or Save All). Torunortesttheservicedirectly,seeTestingAdapterServicesonpage 119.

AnUpdateSQLserviceupdatesexistinginformationinadatabasetableandincludesa mappingforanoutputfieldthatstoresthenumberofrowsaffectedbytheupdate operation.YouconfigureJDBCadapterservicesusingtheDeveloper.Formore informationaboutadapterservices,seeUsingAdapterServicesonpage 19. BesuretoreviewthesectionBeforeConfiguringorManagingAdapterServiceson page 88beforeyouconfigureadapterservices. To configure an UpdateSQL service 1 2 3 4 FromtheDeveloperFilemenu,selectNew... SelectAdapter ServicefromthelistofelementsandclickNext. SelectJDBC AdapterastheadaptertypeandclickNext. SelecttheappropriateAdapter Connection NameandclickNext.
95
5 6
SelecttheUpdateSQLtemplateandclickNext. Typeauniquenamefortheserviceandselecttheappropriatefolder.ClickFinish. Theadapterserviceeditorfortheadapterserviceappears.YoucanselecttheAdapter SettingstabatanytimetoconfirmadapterservicepropertiessuchastheAdapter Name, Adapter Connection Name,andAdapter Service Template,asnecessary.
SelecttheTabletabtoconfigurethedatabasetabletobeupdatedandsetfieldsas follows: Field Table Name Description/Action Selectatablename.Thedefaultfortheassociatedcatalog nameiscurrent catalog.Thedefaultfortheassociated schemanameiscurrent schema. Thetablenamemustnotcontainaperiod.Ifthetablename doescontainaperiod,DeveloperwillthrowaJavaexception. Note: Informixdatabasesdonotallowyoutospecifyacatalog anddatabasenamebecauseyoucanonlyaccessthecurrent catalog. Type Thetabletypedisplaysautomaticallybasedonthetableyou select.
SelecttheUPDATEtabandusetheColumn,Column Type,JDBC Type andExpressionfields onthetoprowofthetabtodefinethecolumnsandfields,asfollows: a UsetheInsert Rowicon rowsasneeded. Field Column Column Type JDBC Type Expression (ortheFill in all rows to the tableicon )tocreatenew
Description/Action TheUPDATEcolumnnameinthedatabasetable. TheUPDATEcolumndatatypeinthedatabasetable. TheJDBCtypeofthecorrespondingInput Field. Thedefaultvalueis?,whichactsasaplaceholderforthe variablesothatyoucansettheinputvariableforthat columnatruntime,orgetinputexternaltothisadapter service.Itaddsonerowwiththesamecolumnnametothe table. Youcanalsotypeafixedvalueinthisfieldnoworatrun time.Ifyoutypeafixedvalue,besurethatitisvalid,oran exceptionwillbegeneratedatruntime.
96
IfyouinsertadditionalrowsusingthedefaultExpressionvalueof?,the correspondingJDBC Type,Input FieldandInput Field Typedisplayonthesecondrow oftheUPDATEtab: Field Column Column Type JDBC Type Input Field* Input Field Type Description/Action TheUPDATEcolumnnameinthedatabasetable. Thecolumndatatypedefinedinthedatabasetable. TheJDBCtypeoftheinputfield. Theinputfieldname.Youcanchangethisnameifneeded. Thedatatypeoftheinputfield.Youcanchangethistypeif needed.
Note: * ForOracleusers,ifyouuseaCHARdatatypeandenteravalueintheInput Field,youmustpadthefieldwithspacesequaltothetotalcolumnwidth.For example,ifyouusethevalueSmithintheinputfieldanddefineitasaCHAR datatypeof50bytes,youmustpadthefieldwith45spaces.Analternativeisto useaDynamicSQLadapterservicebecauseyoudonotneedtopadthisfieldwhen youuseaSQLstatement.Usethe${value}toreplacethe?variableplaceholder, suchasWHERE char_col = ${value}.Thisvaluewillbeintheinputlistsothat atruntimeyoucansetthevaluetoaStringwithouthavingtopadthecolumn width.SeeConfiguringDynamicSQLServicesonpage 111foranexampleand configurationinstructions. 9 UsetheWHEREtabtospecifytheconditionsforselectinginformation: a b SelecttheInsert Rowicon todefinenewWHEREclausefields.
SelectalogicaloperatorfromtheAND/ORfield,anOperator,andseparators(theleft andrightparentheses)asneeded. Note: YoucanusetheBigDecimaldatatypewiththeJDBCAdapter.However,the webMethodsDeveloperdoesnotsupporttheBigDecimaldatatype.Thismeans thattheDeveloperwillnotcorrectlydisplayaBigDecimaldatatyperesultand youcannotenteravalueofthisdatatype.However,theJDBCAdapterwill processtheBigDecimaldatatypecorrectly.
97
Usethefollowingfields: Field AND/OR Column Operator Input Field* Description/Action Thelogicaloperator. ThenameofthecolumnyouwanttouseintheWHERE clause. TheoperatorusedwiththeColumnandInput Field. Thedefaultvalueis?,whichactsasaplaceholderforthe variablesothatyoucansettheinputvariableforthat columnatruntime,orgetinputexternaltothisadapter service. Youcanalsotypeafixedvalueinthisfieldnoworatrun time.Ifyoutypeafixedvalue,besurethatitisvalid,oran exceptionwillbegeneratedatruntime. JDBC Type TheJDBCtypeofthecorrespondingInput Field.
Note: * ForOracleusers,ifyouuseaCHARdatatypeandenteravalueintheInput Field,youmustpadthefieldwithspacesequaltothetotalcolumnwidth.For example,ifyouusethevalueSmithintheinputfieldanddefineitasaCHAR datatypeof50bytes,youmustpadthefieldwith45spaces.Analternativeisto useaDynamicSQLadapterservicebecauseyoudonotneedtopadthisfieldwhen youuseaSQLstatement.Usethe${value}toreplacethe?variableplaceholder, suchasWHERE char_col = ${value}.Thisvaluewillbeintheinputlistsothat atruntimeyoucansetthevaluetoaStringwithouthavingtopadthecolumn width.SeeConfiguringDynamicSQLServicesonpage 111foranexampleand configurationinstructions. 10 UsetheResulttabsResult FieldandResult Field Typetospecifytheoutputfieldname andcorrespondingfieldtypesfortheresultingnumberofrowsthathavebeen inserted. 11 ForinformationaboutusingtheInput/Output,Settings, Audit,Permissions,and Results tabs,seethewebMethodsDeveloperUsersGuide.Thesetabsapplytoallservicesthat youconfigureusingversionsoftheDeveloperearlierthan6.1. WhenusingDeveloper6.1orlater,theDeveloperonlycontainstheAdapter Settings andInput/Outputtabs.TheinformationfromtheAuditandPermissionstabsappearsin thePropertiespanel,andtheinformationfromtheResultstabappearsintheResults panel. 12 FromtheFilemenu,selectSave(or Save All). Torunortesttheservicedirectly,seeTestingAdapterServicesonpage 119.
98
Configuring BatchInsertSQL Services

SimilartoanInsertSQLservice,aBatchInsertSQLservicealsoinsertsnewinformationintoa databasetable;howevertheBatchInsertSQLservicecaninsertalargevolumeofdataintoa tablemoreefficientlythananInsertSQLservice,improvingperformancewhenalargedata volumeisinvolved.YouconfigureJDBCadapterservicesusingtheDeveloper.Formore informationaboutadapterservices,seeUsingAdapterServicesonpage 19. BesuretoreviewthesectionBeforeConfiguringorManagingAdapterServiceson page 88beforeyouconfigureadapterservices. Note: BatchInsertSQLservicesdonotworkwithTeradatadatabases.
.
To configure a BatchInsertSQL Service 1 2 3 4 FromtheDeveloperFilemenu,selectNew... SelectAdapter ServicefromthelistofelementsandclickNext. SelectJDBC AdapterastheadaptertypeandclickNext. SelecttheappropriateAdapter Connection NameandclickNext. Note: ForBatchInsertSQLservices,youmustuseaLOCAL_TRANSACTIONconnection. IfyoudonotuseLOCAL_TRANSACTION,youwillnotseealistoftablesinthe Tablestab.Also,youmaynotseeanerrormessageuntilyoureloadmetadatavalues orchecktheerrorlog.SeeConfiguringJDBCAdapterConnectionsonpage 68for instructionsforcreatingaLOCAL_TRANSACTIONconnection.SeeReloading AdapterValuesonpage 121forinformationaboutreloadingmetadatavalues. 5 6 SelecttheBatchInsertSQLtemplateandclickNext. Typeauniquenamefortheserviceandselecttheappropriatefolder.ClickFinish. Theadapterserviceeditorfortheadapterserviceappears.YoucanselecttheAdapter SettingstabatanytimetoconfirmadapterservicepropertiessuchastheAdapter Name, Adapter Connection Name,andAdapter Service Template,asnecessary.
99
SelecttheTabletabtoconfigurethedatabasetabletobeupdatedandsetthefieldsas follows: Field Table Name Description/Action Selectatablename.Thedefaultfortheassociatedcatalog nameiscurrent catalog.Thedefaultfortheassociated schemanameiscurrent schema. Thetablenamemustnotcontainaperiod.Ifthetablename doescontainaperiod,DeveloperwillthrowaJavaexception. Note: Informixdatabasesdonotallowyoutospecifyacatalog anddatabasenamebecauseyoucanonlyaccessthecurrent catalog. Type Thetabletypedisplaysautomaticallybasedonthetableyou select.
SelecttheINSERTtabandusetheColumn,Column Type, JDBCTypeandExpressionfields onthetoprowofthetabtodefinethecolumnsandfieldstobeinsertedasdescribed inthefollowingtable. a UsetheInsert Rowicon rowsasneeded. Field Column Column Type JDBCType Expression (ortheFill in all rows to the tableicon )tocreatenew
Description/Action TheINSERTcolumnnameinthedatabasetable. TheINSERTcolumndatatypeinthedatabasetable. TheJDBCtypefortheinputfield. Thedefaultvalueis?,whichactsasaplaceholderforthe variablesothatyoucansettheinputvariableforthat columnatruntime,orgetinputexternaltothisadapter service.Itaddsonerowwiththesamecolumnnametothe table. Youcanalsotypeafixedvalueinthisfieldnoworatrun time.Ifyoutypeafixedvalue,besurethatitisvalid,oran exceptionwillbegeneratedatruntime.
100
ForeachinsertedrowthatusesthedefaultExpressionvalueof?,the correspondingInput Field,andInput Field Typedisplayonthesecondrowofthe INSERTtab.Usethefollowingfields: Note: YoucanusetheBigDecimaldatatypewiththeJDBCAdapter.However,the webMethodsDeveloperdoesnotsupporttheBigDecimaldatatype.Thismeans thattheDeveloperwillnotcorrectlydisplayaBigDecimaldatatyperesultand youcannotenteravalueofthisdatatype.However,theJDBCAdapterwill processtheBigDecimaldatatypecorrectly. Field Column Column Type Input Field* Input Field Type Description/Action TheINSERTcolumnnameinthedatabasetable. TheINSERTcolumndatatypeinthedatabasetable. Theinputfieldname.Youcanchangethisnameifneeded. Thedatatypeoftheinputfield.Youcanchangethistypeif needed. Note: IfyouuseWmFlatFileservicestogeneratethe documentlistasinput,theinputfieldtypemustbe java.lang.String.ThisisbecausefieldsfromWmFlatFile servicesgeneratedocumentsthathaveStringfields.
Note: * ForOracleusers,ifyouuseaCHARdatatypeandenteravalueintheInput Field,youmustpadthefieldwithspacesequaltothetotalcolumnwidth.For example,ifyouusethevalueSmithintheinputfieldanddefineitasaCHAR datatypeof50bytes,youmustpadthefieldwith45spaces.Analternativeisto useaDynamicSQLadapterservicebecauseyoudonotneedtopadthisfieldwhen youuseaSQLstatement.Usethe${value}toreplacethe?variableplaceholder, suchasWHERE char_col = ${value}.Thisvaluewillbeintheinputlistsothat atruntimeyoucansetthevaluetoaStringwithouthavingtopadthecolumn width.SeeConfiguringDynamicSQLServicesonpage 111foranexampleand configurationinstructions. 9 UsetheBatch ResulttabsBatchResult Output Nametospecifytheoutputfieldnamefor thebatchoperation.Theoutputofthebatchoperationisastringlist.Theelementsof thestringlistareorderedaccordingtotheorderinwhichcommandswereaddedto
101
thebatch.DependingontheJDBCdriveryouuse,theelementsinthestringlistmay beoneofthefollowing: Anumbergreaterthanorequaltozero.Thisindicatesthatthecommandwas successfullyexecutedandthenumberofrowsinthedatabaseaffected. AvalueofSUCCESS_NO_INFO.Thisindicatesthatthecommandwasprocessed successfullybutthenumberofrowsaffectedisunknown. 10 ForinformationaboutusingtheInput/Output,Settings, Audit,Permissions,and Results tabs,seethewebMethodsDeveloperUsersGuide.Thesetabsapplytoallservicesthat youconfigureusingversionsoftheDeveloperearlierthan6.1. WhenusingDeveloper6.1orlater,theDeveloperonlycontainstheAdapter Settings andInput/Outputtabs.TheinformationfromtheAuditandPermissionstabsappearsin thePropertiespanel,andtheinformationfromtheResultstabappearsintheResults panel. 11 FromtheFilemenu,selectSave(or Save All). Torunortesttheservicedirectly,seeTestingAdapterServicesonpage 119.
Configuring BatchUpdateSQL Services

SimilartoanUpdateSQLservice,aBatchUpdateSQLserviceupdatesinformationinadatabase table;however,theBatchUpdateSQLservicecanupdatealargevolumeofdatainatable moreefficientlythananUpdateSQLservice,improvingperformancewhenalargedata volumeisinvolved.YouconfigureJDBCadapterservicesusingtheDeveloper.Formore informationaboutadapterservices,seeUsingAdapterServicesonpage 19. Note: BatchUpdateSQLservicesdonotworkwithTeradatadatabases. BesuretoreviewthesectionBeforeConfiguringorManagingAdapterServiceson page 88beforeyouconfigureadapterservices. To configure a BatchUpdateSQL Service 1 2 3 4 FromtheDeveloperFilemenu,selectNew... SelectAdapter ServicefromthelistofelementsandclickNext. SelectJDBC AdapterastheadaptertypeandclickNext. SelecttheappropriateAdapter Connection NameandclickNext.
102
Note: ForBatchUpdateSQLservices,youmustuseaLOCAL_TRANSACTION connection.IfyoudonotuseLOCAL_TRANSACTION,youwillnotseealistof tablesintheTablestab.Also,youmaynotseeanerrormessageuntilyoureload metadatavaluesorchecktheerrorlog.SeeConfiguringJDBCAdapterConnections onpage 68forinstructionsforcreatingaLOCAL_TRANSACTIONconnection.See ReloadingAdapterValuesonpage 121forinformationaboutreloadingmetadata values. 5 6 SelecttheBatchUpdateSQLtemplateandclickNext. Typeauniquenamefortheserviceandselecttheappropriatefolder.ClickFinish. Theadapterserviceeditorfortheadapterserviceappears.YoucanselecttheAdapter SettingstabatanytimetoconfirmadapterservicepropertiessuchastheAdapter Name, Adapter Connection Name,andAdapter Service Template,asnecessary. 7 SelecttheTabletabtoconfigurethedatabasetabletobeupdatedandsetthefieldsas follows: Field Table Name Description/Action Selectatablename.Thedefaultfortheassociatedcatalog nameiscurrent catalog.Thedefaultfortheassociated schemanameiscurrent schema. Thetablenamemustnotcontainaperiod.Ifthetablename doescontainaperiod,DeveloperwillthrowaJavaexception. Note: Informixdatabasesdonotallowyoutospecifyacatalog anddatabasenamebecauseyoucanonlyaccessthecurrent catalog. Type Thetabletypedisplaysautomaticallybasedonthetableyou select.
SelecttheUPDATEtabandusetheColumn,Column Type, JDBC Type,andExpressionfields onthetoprowofthetabtodefinethecolumnsandfields,asfollows: a UsetheInsert Rowicon rowsasneeded. Field Column Column Type (ortheFill in all rows to the tableicon )tocreatenew
Description/Action TheUPDATEcolumnnameinthedatabasetable. TheUPDATEcolumndatatypeinthedatabasetable.
103
Field JDBC Type Expression
Description/Action TheJDBCtypeofthecorrespondingInput Field. Thedefaultvalueis?,whichactsasaplaceholderforthe variablesothatyoucansettheinputvariableforthat columnatruntime,orgetinputexternaltothisadapter service.Itaddsonerowwiththesamecolumnnametothe table. Youcanalsotypeafixedvalueinthisfieldnoworatrun time.Ifyoutypeafixedvalue,besurethatitisvalid,oran exceptionwillbegeneratedatruntime.
IfyouinsertadditionalrowsusingthedefaultExpressionvalueof?,the corresponding Input FieldandInput Field Typedisplayonthesecondrowofthe UPDATEtab: Note: YoucanusetheBigDecimaldatatypewiththeJDBCAdapter.However,the webMethodsDeveloperdoesnotsupporttheBigDecimaldatatype.Thismeans thattheDeveloperwillnotcorrectlydisplayaBigDecimaldatatyperesultand youcannotenteravalueofthisdatatype.However,theJDBCAdapterwill processtheBigDecimaldatatypecorrectly. Field Column Column Type Input Field* Input Field Type Description/Action TheUPDATEcolumnnameinthedatabasetable. Thecolumndatatypedefinedinthedatabasetable. Theinputfieldname.Youcanchangethisnameifneeded. Thedatatypeoftheinputfield.Youcanchangethistypeif needed. Note: IfyouuseWmFlatFileservicestogeneratethe documentlistasinput,theinputfieldtypemustbe java.lang.String.ThisisbecausefieldsfromWmFlatFile servicesgeneratedocumentsarehaveStringfields.
104
Note: * ForOracleusers,ifyouuseaCHARdatatypeandenteravalueintheInput Field,youmustpadthefieldwithspacesequaltothetotalcolumnwidth.For example,ifyouusethevalueSmithintheinputfieldanddefineitasaCHAR datatypeof50bytes,youmustpadthefieldwith45spaces.Analternativeisto useaDynamicSQLadapterservicebecauseyoudonotneedtopadthisfieldwhen youuseaSQLstatement.Usethe${value}toreplacethe?variableplaceholder, suchasWHERE char_col = ${value}.Thisvaluewillbeintheinputlistsothat atruntimeyoucansetthevaluetoaStringwithouthavingtopadthecolumn width.SeeConfiguringDynamicSQLServicesonpage 111foranexampleand configurationinstructions. 9 UsetheWHEREtabtospecifytheconditionsforselectinginformation: a b SelecttheInsert Rowicon todefinenewWHEREclausefields.
SelectalogicaloperatorfromtheAND/ORfield,anOperator,andseparators(theleft andrightparentheses)asneeded.Usethefollowingfields: Field AND/OR Column Operator Input Field Description/Action Thelogicaloperator. ThenameofthecolumnyouwanttouseintheWHERE clause. TheoperatorusedwiththeColumnandInput Field. Thedefaultvalueis?,whichactsasaplaceholderforthe variablesothatyoucansettheinputvariableforthat columnatruntime,orgetinputexternaltothisadapter service. Youcanalsotypeafixedvalueinthisfieldnoworatrun time.Ifyoutypeafixedvalue,besurethatitisvalid,oran exceptionwillbegeneratedatruntime. JDBC Type Input Field Type* TheJDBCtypeofthecorrespondingInput Field. ThecorrespondinginputfieldsJavatype. ForalistofJDBCtypetoJavatypemappings,seeJDBC DataTypetoJavaDataTypeMappingsonpage 170. Input Field (second occurrence of this field) Typethenameoftheinputfield. Ifyouusethedefault?variableplaceholderastheInput Fieldvalueinthewhereclause,besuretoenterthe correspondingInput FieldanditsJDBC Field Typeinthe sameorderastheyappearonthetopportionofthe WHEREtab.
105
10 UsetheBatch ResulttabsBatchResult Output Nametospecifytheoutputfieldnamefor thebatchoperation.Theoutputofthebatchoperationisastringlist.Theelementsof thestringlistareorderedaccordingtotheorderinwhichcommandswereaddedto thebatch.DependingontheJDBCdriveryouuse,theelementsinthestringlistmay beoneofthefollowing: Anumbergreaterthanorequaltozero.Thisindicatesthatthecommandwas successfullyexecutedandthenumberofrowsinthedatabaseaffected. AvalueofSUCCESS_NO_INFO.Thisindicatesthatthecommandwasprocessed successfullybutthenumberofrowsaffectedisunknown. 11 ForinformationaboutusingtheInput/Output,Settings, Audit,Permissions,and Results tabs,seethewebMethodsDeveloperUsersGuide.Thesetabsapplytoallservicesthat youconfigureusingversionsoftheDeveloperearlierthan6.1. WhenusingDeveloper6.1orlater,theDeveloperonlycontainstheAdapter Settings andInput/Outputtabs.TheinformationfromtheAuditandPermissionstabsappearsin thePropertiespanel,andtheinformationfromtheResultstabappearsintheResults panel. 12 FromtheFilemenu,selectSave(or Save All). Torunortesttheservicedirectly,seeTestingAdapterServicesonpage 119.
Configuring DeleteSQL Services

ADeleteSQLservicedeletesrowsfromatableandincludesamappingforanoutputfield thatstoresthenumberofaffectedrows.YouconfigureJDBCadapterservicesusingthe Developer.Formoreinformationaboutadapterservices,seeUsingAdapterServiceson page 19. BesuretoreviewthesectionBeforeConfiguringorManagingAdapterServiceson page 88beforeyouconfigureadapterservices. To configure a DeleteSQL service 1 2 3 4 5 FromtheDeveloperFilemenu,selectNew... SelectAdapter ServicefromthelistofelementsandclickNext. SelectJDBC AdapterastheadaptertypeandclickNext. SelecttheappropriateAdapter Connection NameandclickNext. SelecttheDeleteSQLtemplateandclickNext.
106
Configuring DeleteSQL Services
Typeauniquenamefortheserviceandselecttheappropriatefolder.ClickFinish. Theadapterserviceeditorfortheadapterserviceappears.YoucanselecttheAdapter SettingstabatanytimetoconfirmadapterservicepropertiessuchastheAdapter Name, Adapter Connection Name,andAdapter Service Template,asnecessary.
SelecttheTabletabtoconfigurethedatabasetabletobeupdatedandsetthefieldsas follows: Field Table Name Description/Action Selectatablename.Thedefaultfortheassociatedcatalog nameiscurrent catalog.Thedefaultfortheassociated schemanameiscurrent schema. Thetablenamemustnotcontainaperiod.Ifthetablename doescontainaperiod,DeveloperwillthrowaJavaexception. Note: Informixdatabasesdonotallowyoutospecifyacatalog anddatabasenamebecauseyoucanonlyaccessthecurrent catalog. Type Thetabletypedisplaysautomaticallybasedonthetableyou select.
UsetheWHEREtabtospecifytheconditionsforselectinginformation: a b SelecttheInsert Rowicon todefinenewWHEREclausefields.
SelectalogicaloperatorfromtheAND/ORfield,anOperator,andseparators(theleft andrightparentheses)asneeded. Note: YoucanusetheBigDecimaldatatypewiththeJDBCAdapter.However,the webMethodsDeveloperdoesnotsupporttheBigDecimaldatatype.Thismeans thattheDeveloperwillnotcorrectlydisplayaBigDecimaldatatyperesultand youcannotenteravalueofthisdatatype.However,theJDBCAdapterwill processtheBigDecimaldatatypecorrectly. Usethefollowingfields: Field AND/OR Column Operator Description/Action Thelogicaloperator. ThenameofthecolumnyouwanttouseintheWHERE clause. TheoperatorusedwiththeColumnandInput Field.
107
Field Input Field*
Description/Action Thedefaultvalueis?,whichactsasaplaceholderforthe variablesothatyoucansettheinputvariableforthat columnatruntime,orgetinputexternaltothisadapter service. Youcanalsotypeafixedvalueinthisfieldnoworatrun time.Ifyoutypeafixedvalue,besurethatitisvalid,oran exceptionwillbegeneratedatruntime.
JDBC Type Input Field Type
TheJDBCtypeofthecorrespondingInput Field. ThecorrespondinginputfieldsJavatype. ForalistofJDBCtypetoJavatypemappings,seeJDBC DataTypetoJavaDataTypeMappingsonpage 170.
Input Field (second occurrence of this field)
Typethenameoftheinputfield. Ifyouusethedefault?variableplaceholderastheInput Fieldvalueinthewhereclause,besuretoenterthe correspondingInput FieldanditsJDBC Field Typeinthe sameorderastheyappearonthetopportionofthe WHEREtab.
Note: * ForOracleusers,ifyouuseaCHARdatatypeandenteravalueintheInput Field,youmustpadthefieldwithspacesequaltothetotalcolumnwidth.For example,ifyouusethevalueSmithintheinputfieldanddefineitasaCHAR datatypeof50bytes,youmustpadthefieldwith45spaces.Analternativeisto useaDynamicSQLadapterservicebecauseyoudonotneedtopadthisfieldwhen youuseaSQLstatement.Usethe${value}toreplacethe?variableplaceholder, suchasWHERE char_col = ${value}.Thisvaluewillbeintheinputlistsothat atruntimeyoucansetthevaluetoaStringwithouthavingtopadthecolumn width.SeeConfiguringDynamicSQLServicesonpage 111foranexampleand configurationinstructions. 9 UsetheResulttabsResult FieldandResult Field Typetospecifytheoutputfieldname andcorrespondingfieldtypesfortheresultingnumberofrowsthathavebeen inserted.
10 Toverifyinputoroutputinformationforthisservice,usetheInput/Outputtabas needed. 11 ForinformationaboutusingtheInput/Output,Settings, Audit,Permissions,and Results tabs,seethewebMethodsDeveloperUsersGuide.Thesetabsapplytoallservicesthat youconfigureusingversionsoftheDeveloperearlierthan6.1. WhenusingDeveloper6.1orlater,theDeveloperonlycontainstheAdapter Settings andInput/Outputtabs.TheinformationfromtheAuditandPermissionstabsappearsin
108
Configuring CustomSQL Services
thePropertiespanel,andtheinformationfromtheResultstabappearsintheResults panel. 12 FromtheFilemenu,selectSave(or Save All). Torunortesttheservicedirectly,seeTestingAdapterServicesonpage 119.
Configuring CustomSQL Services

ACustomSQLservicedefinesandexecutescustomSQLtoperformdatabaseoperations. YoucanexecutealmostanySQLstatementrequiredbyintegrations,suchasdata managementstatements.YouconfigureJDBCadapterservicesusingtheDeveloper.For moreinformationaboutadapterservices,seeUsingAdapterServicesonpage 19. IfyouneedtowritecustomSQL,youcancreateaservicethatusescustomizedSQL statements.ThisallowsyoutheflexibilitytoexecutealmostanySQLstatementsrequired, suchasdatamanagementstatementsanddatadefinitionstatements,includinginsert, select,update,anddelete. BecauseanadapterservicethatusescustomSQLprovidesnoerrorchecking,besurethat yourSQLstatementworkscorrectly.YoucanverifySQLstatementaccuracyusingyour vendorsSQLutility.Seeyourvendordocumentationfordetails. BesuretoreviewthesectionBeforeConfiguringorManagingAdapterServiceson page 88beforeyouconfigureadapterservices. To create a CustomSQL service Note: YoucanuseaCustomSQLservicetocallastoredprocedureonlywhenthestored proceduredoesnothaveanyOUT/INOUTorreturnparameters.Ifyouneedtousethese parameters,usetheStoredProcedureservice.SeeConfiguringStoredProcedureServices onpage 115forinstructions. 1 2 3 4 5 6 FromtheDeveloperFilemenu,selectNew... SelectAdapter ServicefromthelistofelementsandclickNext. SelectJDBC AdapterastheadaptertypeandclickNext. SelecttheappropriateAdapter Connection NameandclickNext. SelecttheCustomSQLtemplateandclickNext. Typeauniquenamefortheserviceandselecttheappropriatefolder.ClickFinish. Theadapterserviceeditorfortheadapterserviceappears.YoucanselecttheAdapter SettingstabatanytimetoconfirmadapterservicepropertiessuchastheAdapter Name, Adapter Connection Name,andAdapter Service Template,asnecessary.
109
SelecttheSQLtabtospecifyaSQLstatementandtheassociatedinputandoutput parameters. UsetheInsert Rowicon table: andsettheSQLparametersasdescribedinthefollowing
Note: YoucanusetheBigDecimaldatatypewiththeJDBCAdapter.However,the webMethodsDeveloperdoesnotsupporttheBigDecimaldatatype.Thismeansthat theDeveloperwillnotcorrectlydisplayaBigDecimaldatatyperesultandyoucannot enteravalueofthisdatatype.However,theJDBCAdapterwillprocessthe BigDecimaldatatypecorrectly. Field SQL* Description/Action ASQLstatement. Ifyouneedmorespacetotypeyourstatement,usethelaunch icontotherighttoopenatexteditorwindow. Youcantypethestatementdirectlyinthisfield,forexample:
select short_col, int_col, float_col, double_col, date_col, date_time_col, varchar_col from ADAPTER-TEST
Forvariablenames,usethe?variableplaceholderforeach variable.Forexample:
select employee_name where StaffID = ? and Dept = ?
Note: DonotendyourSQLstatementwithasemicolon(;)or anexceptionwillbegeneratedatruntime. Note: Youmaypastetextintothisfieldfromthesystem clipboard.However,youmaynotcutorcopytextfromthis fieldtotheclipboardforpastingintoanotherapplication. Input JDBC Type Input Field Type TheJDBCtypeofthecorrespondingInput Field. TheJavatypethatcorrespondstotheinputJDBCtype. ForalistofJDBCtypetoJavatypemappings,seeJDBCData TypetoJavaDataTypeMappingsonpage 170. Input Field* Output JDBC Type Typethenameoftheinputfield. TheJDBCtypeofthecorrespondingOutput Field.
110
Configuring DynamicSQL Services
Field Output Field Type
Description/Action TheJavatypethatcorrespondstotheoutputJDBCtype. ForalistofJDBCtypetoJavatypemappings,seeJDBCData TypetoJavaDataTypeMappingsonpage 170.
Output Field Maximum Row
Theoutputfieldname. Themaximumnumberofrecordstoretrievefromthe database.Thedefaultvalueof0 (nolimit)retrievesall records. UsethisfieldonlywithSQLstatementsthatreturnaresultset.
Result Field Result Field Type
Nameoftheoutputfieldthatcontainsthetotalnumberof rowsaffectedbytheSQLstatement. ThedatatypeoftheResult Field.
Note: *Ifyouusethe?variableplaceholder(s)inyourSQLstatement,besuretoenter thecorrespondingInput Fieldandfieldtypeinformationinthesameorderasthey appearinyourSQLstatement.Forexample,usingtheSQLstatement:

select employee_name where StaffID = ? and Dept = ? StaffIDwouldbethefirstentryintheInput FieldandDeptwouldbethesecondentry.
ForinformationaboutusingtheInput/Output,Settings, Audit,Permissions,and Results tabs,seethewebMethodsDeveloperUsersGuide.Thesetabsapplytoallservicesthat youconfigureusingversionsoftheDeveloperearlierthan6.1. WhenusingDeveloper6.1orlater,theDeveloperonlycontainstheAdapter Settings andInput/Outputtabs.TheinformationfromtheAuditandPermissionstabsappearsin thePropertiespanel,andtheinformationfromtheResultstabappearsintheResults panel.
FromtheFilemenu,selectSave(or Save All).
Torunortesttheservicedirectly,seeTestingAdapterServicesonpage 119.

CreatingaDynamicSQLserviceallowsyoutoconfigureadynamicSQLstatement,partof whichyousetatruntimeusinginputfields.Atruntime,theservicewillcreatetheSQL statementbycombiningthecontentsoftheinputfieldsandthenexecutingit.Thisis usefulwhenyouneedtheflexibilitytosetallorpartofaSQLstatementatruntime, insteadofatdesigntime.
111
Using Input and Output Parameters

YoumustspecifytheinputandoutputparametersoftheDynamicSQLserviceatdesign time.Whenyouconfiguretheservice,theinputfieldsyouconfigurewillcontaintheinput fortheSQLstatement.Theoutputfieldsyouconfigurewillcontaintheresultsfromthe resultset.BesurethattheinputandoutputfieldscorrectlymatchthoseoftheSQL statement.Ifthereisanymismatch,theservicewillgenerateanexceptionatruntime. Note: YoucanusetheBigDecimaldatatypewiththeJDBCAdapter.However,the webMethodsDeveloperdoesnotsupporttheBigDecimaldatatype.Thismeansthatthe DeveloperwillnotcorrectlydisplayaBigDecimaldatatyperesultandyoucannotentera valueofthisdatatype.However,theJDBCAdapterwillprocesstheBigDecimaldata typecorrectly.
Configuring a DynamicSQL Statement

DynamicSQLuses${INPUT_FIELD_NAME}tomapapartoftheSQLstatementtotheinput field.Atdesigntime,theservicetemplategeneratesaninputfieldwith INPUT_FIELD_NAME.Atruntime,theserviceparsesthestatementandreplaces the${ INPUT_FIELD_NAME }withtheactualcontentsoftheinputfield. Forexample,considerthefollowingDynamicSQLstatement:
select * from table1 ${where}:
Inthisexample,theservicetemplatewillgenerateaninputfieldforthe{where}portion ofthestatement.Notethatyoudonottypeasemicolon(;)attheendoftheSQL statement.Doingsowillgenerateanexceptionatruntime. Atruntime,the{where}fieldissettowhere col1>100:
ThegeneratedSQLstatementwillbeSelect * from table1 where col1>100.
112
AmoreextremeexamplewouldbetosettheSQLfieldto${sql};inthiscase,theentire SQLstatementwillbesetthroughtheinputfieldsql.
Creating a DynamicSQL Service

UsethefollowinginstructionstocreateaDynamicSQLadapterservice.YouconfigureJDBC adapterservicesusingtheDeveloper. BesuretoreviewthesectionBeforeConfiguringorManagingAdapterServiceson page 88beforeyouconfigureadapterservices. To create a DynamicSQL service Note: YoucanuseaDynamicSQLservicetocallastoredprocedureonlywhenthestored proceduredoesnothaveanyOUT/INOUTorreturnparameters.Ifyouneedthese parameters,usetheStoredProcedureservice.SeeConfiguringStoredProcedureServices onpage 115forinstructions. 1 2 3 4 5 6 FromtheDeveloperFilemenu,selectNew... SelectAdapter ServicefromthelistofelementsandclickNext. SelectJDBC AdapterastheadaptertypeandclickNext. SelecttheappropriateAdapter Connection NameandclickNext. SelecttheDynamicSQLtemplateandclickNext. Typeauniquenamefortheserviceandselecttheappropriatefolder.ClickFinish. Theadapterserviceeditorfortheadapterserviceappears.YoucanselecttheAdapter SettingstabatanytimetoconfirmadapterservicepropertiessuchastheAdapter Name, Adapter Connection Name,andAdapter Service Template,asnecessary. 7 SelecttheDynamic SQLtabtospecifyaSQLstatementandtheassociatedinputand outputparameters. UsetheInsert Rowicon andsettheSQLparametersasdescribedinthetablebelow.
113
Field SQL*
Description/Action ASQLstatement. Ifyouneedmorespacetotypeyourstatement,usethelaunch icontotherighttoopenatexteditorwindow. Youcantypethestatementdirectlyinthisfield,forexample:

select short_col, int_col, float_col, double_col, date_col, date_time_col, varchar_col from ADAPTER-TEST
Forvariablenames,usethe?variableplaceholderforeach variable.Forexample:
select employee_name where StaffID = ? and Dept = ?
Note: DonotendyourSQLstatementwithasemicolon(;)or youwillgenerateanexception. Note: Youmaypastetextintothisfieldfromthesystem clipboard.However,youmaynotcutorcopytextfromthis fieldtotheclipboardforpastingintoanotherapplication. Input JDBC Type Input Field Type TheJDBCtypeofthecorrespondingInput Field. TheJavatypethatcorrespondstotheinputJDBCtype. ForalistofJDBCtypetoJavatypemappings,see JDBCDataTypetoJavaDataTypeMappingsonpage 170. Input Field* Output JDBC Type Output Field Type Typethenameoftheinputfield. TheJDBCtypeofthecorrespondingOutput Field. TheJavatypethatcorrespondstotheoutputJDBCtype. ForalistofJDBCtypetoJavatypemappings,see JDBCDataTypetoJavaDataTypeMappingsonpage 170. Output Field Maximum Row Theoutputfieldname. Themaximumnumberofrecordstoretrievefromthe database.Thedefaultvalueof0(no limit)retrievesall records. UsethisfieldonlywithSQLstatementsthatreturnaresultset. Result Field Nameoftheoutputfieldthatcontainsthetotalnumberof rowsaffectedbytheSQLstatement. DonotuseresultsasthevalueoftheResult Field.
114
Configuring StoredProcedure Services
Field Result Field Type
Description/Action ThedatatypeoftheResult Field.
Note: *Ifyouusethe?variableplaceholder(s)inyourSQLstatement,besuretoenter thecorrespondingInput Fieldandfieldtypeinformationinthesameorderasthey appearinyourSQLstatement.Forexample,usingtheSQLstatement: select employee_name where StaffID = ? and Dept = ?
StaffIDwouldbethefirstentryintheInput FieldandDeptwouldbethesecondentry.
ForinformationaboutusingtheInput/Output,Settings, Audit,Permissions,and Results tabs,seethewebMethodsDeveloperUsersGuide.Thesetabsapplytoallservicesthat youconfigureusingversionsoftheDeveloperearlierthan6.1. WhenusingDeveloper6.1orlater,theDeveloperonlycontainstheAdapter Settings andInput/Outputtabs.TheinformationfromtheAuditandPermissionstabsappearsin thePropertiespanel,andtheinformationfromtheResultstabappearsintheResults panel.
FromtheFilemenu,selectSave(or Save All).
Torunortesttheservicedirectly,seeTestingAdapterServicesonpage 119.

AStoredProcedureservicecallsastoredproceduretoperformdatabaseoperations.You configureJDBCadapterservicesusingtheDeveloper.Formoreinformationabout adapterservices,seeUsingAdapterServicesonpage 19. TheSQLstatementforanadapterservicecanalsobeastoredprocedurecall.Astored procedureisSQLcodethatisencapsulatedinastatementandcompiledintoexecutable code.Itisanobjectthatisstoredinthedatabaseandcalledwhentheadapterappliesthe SQLstatementtothedatabase. Storedproceduresprovidegreaterflexibilityinperformingdatabaseoperationsin responsetodocuments.Youcanconfigureoperationsforstoredprocedurecallswithor withoutparameters.Tolearnhowtocreateastoredprocedure,seethevendor documentationforyourdatabase. BesuretoreviewthesectionBeforeConfiguringorManagingAdapterServiceson page 88beforeyouconfigureadapterservices.
115
To configure a StoredProcedure service 1 2 3 4 5 6 FromtheDeveloperFilemenu,selectNew... SelectAdapter ServicefromthelistofelementsandclickNext. SelectJDBC AdapterastheadaptertypeandclickNext. SelecttheappropriateAdapter Connection NameandclickNext. SelecttheStoredProcedureSQLtemplateandclickNext. Typeauniquenamefortheserviceandselecttheappropriatefolder.ClickFinish. Theadapterserviceeditorfortheadapterserviceappears.YoucanselecttheAdapter SettingstabatanytimetoconfirmadapterservicepropertiessuchastheAdapter Name, Adapter Connection Name,andAdapter Service Template,asnecessary. 7 SelecttheCalltabtospecifythestoredproceduretocall.Usethefollowingfieldstoset theCall parameters: Note: YoucanusetheBigDecimaldatatypewiththeJDBCAdapter.However,the webMethodsDeveloperdoesnotsupporttheBigDecimaldatatype.Thismeansthat theDeveloperwillnotcorrectlydisplayaBigDecimaldatatyperesultandyoucannot enteravalueofthisdatatype.However,theJDBCAdapterwillprocessthe BigDecimaldatatypecorrectly. Field Catalog Name Schema Name Enable Procedure Name Lookup (Optional) Description/Action Thenameofthecatalog.Thedefaultforthecatalognameis current catalog. Thenameoftheschema.Thedefaultfortheschemanameis current schema. TotypeintheProcedure Name,setthisfieldtoFalse.Toselect theProcedure Namefromalist,setthisfieldtoTrue. ThedefaultisFalse. Tosaveyoutime,usethedefaultvalue(typingthename)if youknowthenameoftheprocedureandyouareworking withalargedatabasewhichmayhavealonglistof procedures. Procedure Name Typeorselectthestoredprocedurename,dependingonhow yousettheEnable Procedure Name Lookupfield.
116
Field JDBC Type
Description/Action UsetheInsert Rowicon (ortheFill in all rows to the tableicon
)andspecifytheJDBCtypeofthecorrespondingreturn fieldforthestoredprocedure. Return Field Name UsetheInsert Rowicon (ortheFill in all rows to the tableicon
)toaddreturnfieldnamesforthestoredprocedure. 8 9 UsetheParametertabtospecifythestoredproceduresparameters. UsetheInsert Rowicon (ortheFill in all rows to the tableicon procedureparametersasneeded. Field Param JDBC Type Param Name Param Type Expression Description/Action TheJDBCtypeofthestoredprocedureparameter. Thestoredprocedureparametername. DefinetheparametertypeasIN,INOUT,orOUT. Thedefaultvalueis?,whichactsasaplaceholderforthe variablesothatyoucansettheinputvariableforthatcolumn atruntime,orgetinputexternaltothisadapterservice.It addsonerowwiththesamecolumnnametothetable. Youcanalsotypeafixedvalueasinputnoworatruntime.If youchoosetotypeafixedvalue,youtypeastoredprocedure callstatementwithvaluesyousetusingthisfield. Input Name Input Type Thenameofanyinputparameters. TheinputparameterJavatype. ForalistofJDBCtypetoJavatypemappings,see JDBCDataTypetoJavaDataTypeMappingsonpage 170. Output Name Output Type Thenameofanyoutputparameters. TheoutputparameterJavatype. ForalistofJDBCtypetoJavatypemappings,see JDBCDataTypetoJavaDataTypeMappingsonpage 170. )tocreatenewstored
117
10 Iftheprocedurereturnsaresultset,selecttheResultSettabtospecifyresultset parametersusingthefieldsinthefollowingtable. StoredProcedureservicescansupportmultipleresultssets.UsetheInsert Rowicon createadditionalresultsetsasneeded.Usethefollowingfields: Field Result Set Index Result Set Name Result Set Name (from second row) Column Name JDBC Type Output Type Description/Action Anindexisautomaticallyassignedtoeachresultset.Thefirst rowdefaultvalueis1. Thenameoftheresultsetyouwanttocreate. Selectresultsetname. Thenameofthecolumnoftheresultset. TheJDBCtypeoftheresultcolumn. TheJavatypeoftheresultcolumn. ForalistofJDBCtypetoJavatypemappings,see JDBCDataTypetoJavaDataTypeMappingsonpage 170. 11 ForinformationaboutusingtheInput/Output,Settings, Audit,Permissions,and Results tabs,seethewebMethodsDeveloperUsersGuide.Thesetabsapplytoallservicesthat youconfigureusingversionsoftheDeveloperearlierthan6.1. WhenusingDeveloper6.1orlater,theDeveloperonlycontainstheAdapter Settings andInput/Outputtabs.TheinformationfromtheAuditandPermissionstabsappearsin thePropertiespanel,andtheinformationfromtheResultstabappearsintheResults panel. 12 FromtheFilemenu,selectSave(or Save All). Torunortesttheservicedirectly,seeTestingAdapterServicesonpage 119. to
118
Testing Adapter Services
Testing Adapter Services

YouusetheDevelopertotestadapterservices. IfyouareusingIntegrationServer6.1orlater,makesureyouareviewingthe webMethodsDeveloperintheTestperspective,asdescribedinViewingDifferent PerspectivesofthewebMethodsDeveloperonpage 43. To test adapter services in the Developer Adapter Service Editor 1 2 IntheDeveloperServiceBrowser,expandthepackageandfolderthatcontainthe serviceyouwanttotest. Selecttheserviceyouwanttotest. TheDeveloperdisplaystheconfiguredadapterserviceintheservicetemplates AdapterServiceEditor. 3 4 5 ClicktheRunicon .
Foreveryserviceinputfield,youwillbepromptedtoenteraninputvalue.Entera valueforeachinputfieldandthenclickOK. IfyouuseaversionoftheDeveloperearlierthan6.1,clicktheResultstabtoviewthe outputfromthisservice.IfyouuseDeveloper6.1orlater,viewtheResultspanel.
Formoreinformationabouttestinganddebuggingservices,seethewebMethodsDeveloper UsersGuide.
Viewing Adapter Services

YouusetheDevelopertoviewadapterservices.IfyouareusingDeveloper6.1orlater, makesureyouareviewingthewebMethodsDeveloperintheEditperspective,as describedinViewingDifferentPerspectivesofthewebMethodsDeveloperonpage 43. To view a service 1 2 IntheDeveloperServiceBrowser,expandthepackageandfolderthatcontainthe serviceyouwanttoview. Selecttheserviceyouwanttoview. TheDeveloperdisplaystheconfiguredadapterserviceintheservicetemplates AdapterServiceEditor.
119
Editing Adapter Services

YouusetheDevelopertoeditadapterservices.IfyouareusingDeveloper6.1orlater, makesureyouareviewingthewebMethodsDeveloperintheEditperspective,as describedinViewingDifferentPerspectivesofthewebMethodsDeveloperonpage 43. DependingonwhichversionoftheIntegrationServeryouuse,youmaybeabletochange theconnectionassociatedwithanadapterservice,asfollows: WhenusingversionsoftheIntegrationServerearlierthan6.1,youcannotchange whichconnectionanadapterserviceusesaftertheserviceisconfigured. WhenusingIntegrationServer6.1orlater,youcanchangewhichconnectionan adapterserviceuses.Todothis,youusethebuiltinservice setAdapterServiceNodeConnection.Formoreinformation,seeChangingtheConnection AssociatedwithanAdapterServiceorNotificationatDesignTimeonpage 19. To edit a service 1 2 IntheDeveloperServiceBrowser,expandthepackageandfolderthatcontainthe serviceyouwanttoview. Selecttheserviceyouwanttoedit. TheDeveloperdisplaystheconfiguredadapterserviceintheservicetemplates AdapterServiceEditor. 3 Modifythevaluesforservicesparametersasneeded.Fordetaileddescriptionsofthe servicesparameters,seethesectiononconfiguringaserviceforthespecifictypeof serviceyouwanttoedit.
Note: Becauseadapterservicesinherentlydependonconnections,youcannotchangean adapterconnectionforanadapterserviceafteryouconfigureit.
Deleting Adapter Services

YouusetheDevelopertodeleteadapterservices.IfyouareusingDeveloper6.1orlater, makesureyouareviewingthewebMethodsDeveloperintheEditperspective,as describedinViewingDifferentPerspectivesofthewebMethodsDeveloperonpage 43. To delete a service 1 2 IntheDeveloperServiceBrowser,expandthepackageandfolderthatcontainthe serviceyouwanttodelete. RightclicktheadapterserviceandthenclickDelete.
120
Validating Adapter Service Values
Validating Adapter Service Values

TheDeveloperenablestheJDBCAdaptertovalidateuserdefineddataforadapter servicesatdesigntime.Youcanvalidatethevaluesforasingleadapterserviceoryoucan configuretheDevelopertoalwaysvalidatethevaluesforadapterservices. Note: Ifyouselecttheoptiontoalwaysvalidatevaluesforadapterservices,itwilldosofor allwebMethods6.xadaptersinstalledontheIntegrationServer,whichcouldpotentially slowyourdesigntimeoperations. Tovalidateallvaluessetfortheadapterservice,selectfromtheDevelopertheTools > Options... >Integration Server >Adapter Service/Notification EditoritemandenabletheAutomatic data validationoption. ThisoptionisalsoavailableasaniconontheDeveloper,theValidate service/notification value icon .ThisiconisavailableonlywhentheAutomatic data validationoptioniscurrently disabled.WithversionsoftheIntegrationServerearlierthan6.1,theiconislocatedonthe Developertoolbar.WiththeIntegrationServer6.1orlater,theiconislocatedontheeditor panel. TheAutomatic data validationoptionenablesdatavalidationfortheselectedadapterservice only.Itcomparestheservicevaluesagainsttheresourcedatathathasalreadybeen fetchedfromtheadapter.Notethatthisoptioncanslowoperations. SeethewebMethodsDeveloperUsersGuideformoreinformationabouttheAdapter Service/Notification Editor andotherDevelopermenuoptionsandtoolbaricons.
Reloading Adapter Values

TheDeveloperenablestheJDBCAdaptertoreloadandvalidateuserdefineddatafor adapterservicesatdesigntime.Youcanreloadvaluesforasingleadapterserviceoryou canconfiguretheDevelopersoitautomaticallyreloadsthevaluesforadapterservices. Note: Ifyouselecttheoptiontoautomaticallyreloadvaluesforadapterservices,itwilldo soforallwebMethods6.xadaptersinstalledontheIntegrationServer,whichcould potentiallyslowyourdesigntimeoperations. Toreloadtheadaptervaluesandrevalidatealluservaluesasneededfortheadapter service,selectfromtheDevelopertheTools >Options... >Integration Server >Adapter Service/Notification Editoritemandenablethe Automatic polling of adapter metadataoption. ThisoptionisalsoavailableasaniconontheDevelopertoolbar.Withversionsofthe IntegrationServerearlierthan6.1,thisicon(theRefreshicon )islocatedonthe
121
Developertoolbar.WiththeIntegrationServer6.1orlater,theicon(Reload Values from the Adapter icon )islocatedontheeditorpanel.
Thisoptionenablesdatavalidationfortheselectedadapterserviceonly.Itcomparesthe servicevaluesagainsttheresourcedatathathasalreadybeenfetchedfromtheadapter. SeethewebMethodsDeveloperUsersGuideformoreinformationabouttheAdapter Service/Notification Editor andotherDevelopermenuoptionsandtoolbaricons.
122
CHAPTER
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 Before Configuring or Managing Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 Configuring InsertNotifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Configuring UpdateNotifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 Configuring DeleteNotifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 Configuring BasicNotifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Configuring StoredProcedureNotifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Configuring OrderedNotifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 Managing Polling Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 Using the Exactly Once Notification Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 Exporting Configured Adapter Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 Viewing Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 Editing Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 Deleting Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 Validating Adapter Notification Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Reloading Adapter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
123
CHAPTER 5 Adapter Notifications
Overview
ThischapterdescribeshowtoconfigureandmanageJDBCAdapternotifications.For detaileddescriptionsoftheavailableJDBCAdapternotifications,seeAdapter Notificationsonpage 22.
Before Configuring or Managing Notifications

To prepare to configure or manage JDBC Adapter notifications 1 2 StartyourIntegrationServerandtheAdministrator,iftheyarenotalreadyrunning. MakesureyouhaveIntegrationServerAdministratorDeveloperprivilegessothat youcanaccesstheJDBCAdaptersadministrativescreens.SeethewebMethods IntegrationServerAdministratorsGuideforinformationaboutsettinguserprivileges. BesuretocheckDatabaseDriverKnownLimitationsonpage 187foralistof knownlimitationsforyourdatabasedriversinceitmayaffecthowyouconfigure yourconnectionsandnotifications. Ifyouhavemadechangestothetableschemaforagivenadapternotification,besure toupdatetheadapternotificationaccordingly. IfyouplantousetheOnlyOncenotificationfeature,seeUsingtheExactlyOnce NotificationFeatureonpage 152fordetails. UsingtheAdministrator,makesuretheWmJDBCAdapterpackageisenabled.See EnablingandDisablingPackagesonpage 48forinstructions. UsingtheAdministrator,configureanadapterconnectiontousewiththenotification. SeeConfiguringJDBCAdapterConnectionsonpage 68forinstructions. Note: WhenusingversionsoftheIntegrationServerearlierthan6.1,youmaynot assignadifferentconnectiontoapollingnotificationafteryouconfigurethe notification.Youmay,however,changetheparametersoftheconnection. Beginningwithversion6.1,theIntegrationServersolvesthislimitationbyproviding abuiltinserviceyoucanuseatdesigntimetochangetheconnectionassociatedwith apollingnotification.Formoreinformation,seeChangingtheConnection AssociatedwithanAdapterServiceorNotificationatDesignTimeonpage 19. 8 9 StarttheDeveloperifitisnotalreadyrunning. IfyouareusingtheDeveloper6.1orlater,makesureyouareviewingthe webMethodsDeveloperintheEditperspective,asdescribedinViewingDifferent PerspectivesofthewebMethodsDeveloperonpage 43.
4 5 6 7
124
Configuring InsertNotifications
10 UsingtheDeveloper,createauserdefinedpackagetocontainthenotification,ifyou havenotalreadydoneso.Whenyouconfigurenotifications,youshouldalways definetheminuserdefinedpackagesratherthanintheWmJDBCAdapterpackage. Formoreinformationaboutmanagingpackagesfortheadapter,seeChapter 2, PackageManagementonpage 45. 11 Youmustscheduleanotificationandthenenableitbeforeyoucanusethe notification.SeeManagingPollingNotificationsonpage 149forinstructions.
AnInsertNotificationpublishesnotificationofinsertoperationsonadatabasetable.You configurenotificationsusingtheDeveloper.Formoreinformationaboutnotifications,see AdapterNotificationsonpage 22. BesuretoreviewthesectionBeforeConfiguringorManagingNotificationsonpage 124 beforeyouconfigurenotifications. Note: InsertNotificationsarenotsupportedusingTeradatadatabases.
To configure an InsertNotification 1 2 3 4 5 6 7 FromtheDeveloperFilemenu,selectNew... SelectAdapter NotificationfromthelistofelementsandclickNext. SelectJDBC AdapterastheadaptertypeandclickNext. SelecttheappropriateAdapter Connection NameandclickNext. SelecttheInsertNotificatontemplateandclickNext. Typeauniquenameforthenotificationandselecttheappropriatefolder.ClickNext. Thenameofthepublishabledocumentassociatedwiththisnotificationdisplays. ClickFinish. Formoreinformationaboutadapternotificationsandpublishabledocuments,see AdapterNotificationsonpage 22.FormoredetailsabouttheIntegrationServer publishabledocuments,whenusingversionsoftheIntegrationServerearlierthan6.1, seetheBuildingIntegrationSolutionsUsingPublicationdocument,andwhenusing IntegrationServer6.1orlater,seethePublishSubscribeDevelopersGuide. 8 Theeditorfortheadapternotificationappears.YoucanselecttheAdapter Settingstab atanytimetoconfirmadapternotificationpropertiessuchastheAdapter Name,Adapter Connection Name,andAdapter Notification Template,asnecessary.
125
SelecttheNotification Configuretabandusethefollowingfields: Field Base Name Description/Action ThebasenameusedtogeneratetheResource Namecreatedby theJDBCAdapter. Note: ForOS/390DB27.2,theBase Name youcreatebelowmust benomorethan5charactersbecausetriggersonOS/390name cannotbemorethan8characters. Resource Type Typesarebuffertable,trigger,andsequence. Thebasenameandresourcetypedeterminethefollowing Resource Name. Resource Name Toensureuniqueness,theresourcenamecombinesthe followingelements.Youdonoteditthisname. Resourceprefix(WMB,WMT,andWMSforbuffertable, trigger,andsequencerespectively) ThenameyoutypedintheBase Name field Asuffix,basedonasystemtimestamp File Record Format Theformatofthefilerecord. OptionalfieldusedbyDB2forAS/400V4R5only. Database Name Thenameofthedatabasewherethebuffertableswillbe created. OptionalfieldusedbyDB2forOS/390only. Table Space Name Thetablespacewherethebuffertableswillbecreated. OptionalfieldusedbyDB2forOS/390only.
10 SelecttheTablestabandusethefollowingfields: Note: ForAS/400DB2V4R5usingajt400.jarfile,thetablenameforthenotification cannotexceed10characters;otherwise,anexceptionwillbegeneratedwhenyoutry toenablethenotification.
126
Field Table Alias Table Name
Description/Action Thetablealiasisautomaticallyassignedwhenyouselectmore thanonetableintheTable Namefield.Thedefaultist1. Selectatablename.Thedefaultfortheassociatedcatalog nameiscurrent catalog.Thedefaultfortheassociated schemanameiscurrent schema. Thetablenamemustnotcontainaperiod.Ifthetablename doescontainaperiod,DeveloperwillthrowaJavaexception. Note: Informixdatabasesdonotallowyoutospecifyacatalog anddatabasenamebecauseyoucanonlyaccessthecurrent catalog.
Type
Thetabletypedisplaysautomaticallybasedonthetableyou select.
11 Ifyouarenotjoiningtables,skipthisstep.SelecttheJoinstabtospecifythecolumns forjoiningthetablesyoujustconfigured. a b c d e SelecttheInsert Rowicon tocreatenewleftandrightcolumns.
SelectLeft Columnandselectthefirsttablesjoiningcolumn. SelecttheappropriateOperator. SelectRight Columnandselectthenexttablesjoiningcolumn. Repeatuntilyouhavedefinedallthejoins.
12 UsetheSELECTtabtodefinethecolumnsandfieldstobeselectedusingthefollowing fields: a IntheALL/DISTINCTfield,selectALLtoincludeduplicaterowsorDISTINCTto suppressduplicaterows.SelectingALLcorrespondstotheSQLstatementSELECT ALL name from tablename.Thedefaultvalueisblank,whichcorrespondstothe SQLstatementSELECT name from tablename. SelecttheInsert Rowicon fieldsasneeded. (ortheFill in all rows to the tableicon )tocreatenew
127
IntheExpressionfield,selectacolumnortypeanyvalidSQLexpression.The correspondingColumn Type,JDBC Type,Output Field Type,andOutput Field display foreachcolumnyouselectintheExpressionfield.Usethefollowingfields: Note: YoucanusetheBigDecimaldatatypewiththeJDBCAdapter.However,the webMethodsDeveloperdoesnotsupporttheBigDecimaldatatype.Thismeans thattheDeveloperwillnotcorrectlydisplayaBigDecimaldatatyperesultand youcannotenteravalueofthisdatatype.However,theJDBCAdapterwill processtheBigDecimaldatatypecorrectly. Field Expression Column Type JDBC Type Output Field Type Description/Action ThecolumnnameorSQLexpression. Thecolumndatatypedefinedinthedatabasetable. TheJDBCtypeofthecorrespondingOutput Field. Thedatatypeoftheoutputfield.TheJDBCAdapter automaticallyconvertsdatabasespecifictypestoJavadata types. ForalistofJDBCtypetoJavatypemappings,see JDBCDataTypetoJavaDataTypeMappingson page 170. Output Field Thenameofthefieldcontainingtheoutputfromthe SELECToperation.Anoutputfieldnamedisplayswhen youselectanexpression. Youcanalsomodifytheoutputfieldnamesasrequired. Maximum Row Specifiesthenumberofrowstoberetrievedfromthe buffertable.Thisfieldisusefulwhenyouareworking withalargenumberofrecordsandyouwanttolimitthe numberofdocumentssenteachtimethenotificationpolls. Useavalueof0toindicatenolimitonthenumberofrows retrieved.
13 UsetheWHENtabtospecifytheconditionsforselectinginformationusingthe followingtable. Note: IfyouuseMicrosoftSQLServer,Sybase,orV4AS/400DB2,donotusetheWHEN tabbecausethisfeatureisnotsupported.Anexceptionwillbegeneratedifyoutryto usethistab.
128
Configuring UpdateNotifications
a b c d
SelecttheInsert Rowicon
todefinenewWHENclausefields.
SelecttheColumnfieldandchooseacolumnfromthelist. SelectalogicaloperatorfromtheAND/ORfield,anOperator,andseparators(theleft andrightparentheses)asneeded. TypeafixedvalueintheValuefield.Besurethatitisavalidvalue,oranexception willbegeneratedatruntime. Ifnecessary,usetheShift Up orShift Down iconstochangetheorderofthe WHENclausetoensuretheparametersareparsedinthecorrectorder. RepeatuntilyouhavespecifiedallWHENparameters.
e f
14 ForinformationaboutusingthePermissionstabtoassignanaccesscontrollist(ACL) toanelementusingversionsoftheDeveloperearlierthan6.1,seethewebMethods DeveloperUsersGuide. WhenusingDeveloper6.1orlater,theinformationfromthePermissionstabnow appearsinthePropertiespanel. 15 FromtheFilemenu,selectSave(or Save All). 16 YoumustscheduleandenablethenotificationusingtheServerAdministratorbefore youcanuseit.SeeManagingPollingNotificationsonpage 149fordetails.
AnUpdateNotificationpublishesnotificationofupdateoperationsonadatabasetable. YouconfigurenotificationsusingtheDeveloper.Formoreinformationabout notifications,seeAdapterNotificationsonpage 22. BesuretoreviewthesectionBeforeConfiguringorManagingNotificationsonpage 124 beforeyouconfigurenotifications. Note: UpdateNotificationsarenotsupportedusingTeradatadatabases.
To configure an UpdateNotification 1 2 3 4 5 FromtheDeveloperFilemenu,selectNew... SelectAdapter NotificationfromthelistofelementsandclickNext. SelectJDBC AdapterastheadaptertypeandclickNext. SelecttheappropriateAdapter Connection NameandclickNext. SelecttheUpdateNotificatontemplateandclickNext.
129
6 7
Typeauniquenameforthenotificationandselecttheappropriatefolder.ClickNext. Thenameofthepublishabledocumentassociatedwiththisnotificationdisplays. ClickFinish. Formoreinformationaboutadapternotificationsandpublishabledocuments,see AdapterNotificationsonpage 22.FormoredetailsabouttheIntegrationServer publishabledocuments,whenusingversionsoftheIntegrationServerearlierthan6.1, seetheBuildingIntegrationSolutionsUsingPublicationdocument,andwhenusing IntegrationServer6.1orlater,seethePublishSubscribeDevelopersGuide.
Theeditorfortheadapternotificationappears.YoucanselecttheAdapter Settingstab atanytimetoconfirmadapternotificationpropertiessuchastheAdapter Name,Adapter Connection Name,andAdapter Notification Template,asnecessary. SelecttheNotification Configuretabandusethefollowingfields: Field Base Name Description/Action ThebasenameusedtogeneratetheResource Namecreatedby theJDBCAdapter. Note: ForOS/390DB2V7.2,theBase Name youcreatebelow mustbenomorethan5charactersbecausetriggersonOS/390 namecannotbemorethan8characters. Resource Type Typesarebuffertable,trigger,andsequence. Thebasenameandresourcetypedeterminethefollowing Resource Name. Resource Name Toensureuniqueness,theresourcenamecombinesthe followingelements.Youdonoteditthisname. Resourceprefix(WMB,WMT,andWMSforbuffertable, trigger,andsequencerespectively) ThenameyoutypedintheBase Name field Asuffix,basedonasystemtimestamp File Record Format Theformatofthefilerecord. OptionalfieldusedbyDB2forAS/400V4R5only. Database Name Thenameofthedatabasewherethebuffertableswillbe created. OptionalfieldusedbyDB2forOS/390only. Table Space Name Thetablespacewherethebuffertableswillbecreated. OptionalfieldusedbyDB2forOS/390only.
130
10 SelecttheTablestabandusethefollowingfields: Note: ForAS/400DB2V4R5usingajt400.jarfile,thetablenameforthenotification cannotexceed10characters;otherwise,anexceptionwillbegeneratedwhenyoutry toenablethenotification. Field Table Alias Table Name Description/Action Thetablealiasisautomaticallyassignedwhenyouselectmore thanonetableintheTable Namefield.Thedefaultist1. Selectatable.Thedefaultfortheassociatedcatalognameis current catalog.Thedefaultfortheassociatedschema nameiscurrent schema. Thetablenamemustnotcontainaperiod.Ifthetablename doescontainaperiod,DeveloperwillthrowaJavaexception. Note: Informixdatabasesdonotallowyoutospecifyacatalog anddatabasenamebecauseyoucanonlyaccessthecurrent catalog. Type Thetabletypedisplaysautomaticallybasedonthetableyou select.
12 UsetheSELECTtabtodefinethecolumnsandfieldstobeselectedasfollows: a IntheALL/DISTINCTfield,selectALLtoincludeduplicaterowsorDISTINCTto suppressduplicaterows.SelectingALLcorrespondstotheSQLstatementSELECT ALL name from tablename.Thedefaultvalueisblank,whichcorrespondstothe SQLstatementSELECT name from tablename. SelecttheInsert Rowicon fieldsasneeded. (ortheFill in all rows to the tableicon )tocreatenew
131
IntheExpressionfield,selectacolumnortypeanyvalidSQLexpression.The correspondingColumn Type,JDBC Type,Output Field Type,andOutput Field display foreachcolumnyouselectintheExpressionfield.Usethefollowingfields: Note: YoucanusetheBigDecimaldatatypewiththeJDBCAdapter.However,the webMethodsDeveloperdoesnotsupporttheBigDecimaldatatype.Thismeans thattheDeveloperwillnotcorrectlydisplayaBigDecimaldatatyperesultand youcannotenteravalueofthisdatatype.However,theJDBCAdapterwill processtheBigDecimaldatatypecorrectly. Field Expression Column Type JDBC Type Output Field Type Description/Action ThecolumnnameorSQLexpression. Thecolumndatatypedefinedinthedatabasetable. TheJDBCtypeofthecorrespondingOutput Field. Thedatatypeoftheoutputfield.TheJDBCAdapter automaticallyconvertsdatabasespecifictypestoJavadata types. ForalistofJDBCtypetoJavatypemappings,see JDBCDataTypetoJavaDataTypeMappingson page 170. Output Field Thenameofthefieldcontainingtheoutputfromthe SELECToperation.Anoutputfieldnamedisplayswhen youselectanexpression. Youcanalsomodifytheoutputfieldnamesasrequired. Notify On Update Enablethisoptiontoindicatewhichofthecolumns specifiedintheSELECTtabyouwantnotificationif updated.Select: Yes:youwantnotificationifthiscolumnofdatahas beenupdated No:youdonotwantnotificationifthiscolumnofdata hasbeenupdated Forexample,youconfigurethefollowingthreeoutput fields:MyName,MyNumber,andMyLocation. Youwant notificationonlyifthe MyLocation outputfieldis updated.Inthiscase,youwouldselectYes forthe MyLocationoutputfield,andselectNofortheMyName andMyNumberoutputfields.
132
Field Maximum Row
Description/Action Specifiesthenumberofrowstoberetrievedfromthe buffertable.Thisfieldisusefulwhenyouareworking withalargenumberofrecordsandyouwanttolimitthe numberofdocumentssenteachtimethenotificationpolls. Useavalueof0toindicatenolimitonthenumberofrows retrieved.
13 UsetheWHENtabtospecifytheconditionsforselectinginformation: Note: IfyouuseMicrosoftSQLServer,Sybase,orV4AS/400DB2,donotusetheWHEN tabbecausethisfeatureisnotsupported.Anexceptionwillbegeneratedifyoutryto usethistab. a b c d SelecttheInsert Rowicon todefinenewWHENclausefields.
SelecttheColumnfieldandchooseacolumnfromthelist. SelectalogicaloperatorfromtheAND/ORfield,anOperator,andseparators(theleft andrightparentheses)asneeded. TypeafixedvalueintheValuefield.Besurethatitisavalidvalue,oranexception willbegeneratedatruntime. Ifnecessary,usetheShift Up orShift Down iconstochangetheorderofthe WHENclausetoensuretheparametersareparsedinthecorrectorder. RepeatuntilyouhavespecifiedallWHENparameters.
e f
14 ForinformationaboutusingthePermissionstabtoassignanaccesscontrollist(ACL) toanelementusingversionsoftheDeveloperearlierthan6.1,seethewebMethods DeveloperUsersGuide. WhenusingDeveloper6.1orlater,theinformationfromthePermissionstabappears inthePropertiespanel. 15 FromtheFilemenu,selectSave(or Save All). 16 YoumustscheduleandenablethenotificationusingtheServerAdministratorbefore youcanuseit.SeeManagingPollingNotificationsonpage 149fordetails.
133
Configuring DeleteNotifications
ADeleteNotificationpublishesnotificationofdeleteoperationsonadatabasetable.You configurenotificationsusingtheDeveloper.Formoreinformationaboutnotifications,see AdapterNotificationsonpage 22. BesuretoreviewthesectionBeforeConfiguringorManagingNotificationsonpage 124 beforeyouconfigurenotifications. Note: DeleteNotificationsarenotsupportedusingTeradatadatabases.
To configure a DeleteNotification 1 2 3 4 5 6 7 FromtheDeveloperFilemenu,selectNew... SelectAdapter NotificationfromthelistofelementsandclickNext. SelectJDBC AdapterastheadaptertypeandclickNext. SelecttheappropriateAdapter Connection NameandclickNext. SelecttheDeleteNotificatontemplateandclickNext. Typeauniquenameforthenotificationandselecttheappropriatefolder.ClickNext. Thenameofthepublishabledocumentassociatedwiththisnotificationdisplays. ClickFinish. Formoreinformationaboutadapternotificationsandpublishabledocuments,see AdapterNotificationsonpage 22.FormoredetailsabouttheIntegrationServer publishabledocuments,whenusingversionsoftheIntegrationServerearlierthan6.1, seetheBuildingIntegrationSolutionsUsingPublicationdocument,andwhenusing IntegrationServer6.1orlater,seethePublishSubscribeDevelopersGuide. 8 Theeditorfortheadapternotificationappears.YoucanselecttheAdapter Settingstab atanytimetoconfirmadapternotificationpropertiessuchastheAdapter Name,Adapter Connection Name,andAdapter Notification Template,asnecessary.
134
SelecttheNotification Configuretabandusethefollowingfields: Field Base Name Description/Action ThebasenameusedtogeneratetheResource Namecreatedby theJDBCAdapter. Note: ForOS/390DB2V7.2,theBase Name youcreatebelow mustbenomorethan5charactersbecausetriggersonOS/390 namecannotbemorethan8characters. Resource Type Typesarebuffertable,trigger,andsequence. Thebasenameandresourcetypedeterminethefollowing Resource Name. Resource Name Toensureuniqueness,theresourcenamecombinesthe followingelements.Youdonoteditthisname. Resourcetypeprefix(WMB,WMT,andWMSforbuffer table,trigger,andsequencerespectively) ThenameyoutypedintheBase Name field Asuffix,basedonasystemtimestamp File Record Format Theformatofthefilerecord. OptionalfieldusedbyDB2forAS/400V4R5only. Database Name Thenameofthedatabasewherethebuffertableswillbe created. OptionalfieldusedbyDB2forOS/390only. Table Space Name Thetablespacewherethebuffertableswillbecreated. OptionalfieldusedbyDB2forOS/390only.
135
10 SelecttheTablestabandusethefollowingfields: Note: ForAS/400DB2V4R5usingajt400.jarfile,thetablenameforthenotification cannotexceed10characters;otherwise,anexceptionwillbegeneratedwhenyoutry toenablethenotification. Field Table Alias Table Name Description/Action Thetablealiasisautomaticallyassignedwhenyouselectmore thanonetableintheTable Namefield.Thedefaultist1. Selectatablename.Thedefaultfortheassociatedcatalog nameiscurrent catalog.Thedefaultfortheassociated schemanameiscurrent schema. Thetablenamemustnotcontainaperiod.Ifthetablename doescontainaperiod,DeveloperwillthrowaJavaexception. Note: Informixdatabasesdonotallowyoutospecifyacatalog anddatabasenamebecauseyoucanonlyaccessthecurrent catalog. Type Thetabletypedisplaysautomaticallybasedonthetableyou select.
12 UsetheSELECTtabtodefinethecolumnsandfieldstobeselected. a IntheALL/DISTINCTfield,selectALLtoincludeduplicaterowsorDISTINCTto suppressduplicaterows.SelectingALLcorrespondstotheSQLstatementSELECT ALL name from tablename.Thedefaultvalueisblank,whichcorrespondstothe SQLstatementSELECT name from tablename. SelecttheInsert Rowicon fieldsasneeded. (ortheFill in all rows to the tableicon )tocreatenew
136
IntheExpressionfield,selectacolumnortypeanyvalidSQLexpression.The correspondingColumn Type,JDBC Type,Output Field Type,andOutput Field display foreachcolumnyouselectintheExpressionfield.Usethefollowingfields: Note: YoucanusetheBigDecimaldatatypewiththeJDBCAdapter.However,the webMethodsDeveloperdoesnotsupporttheBigDecimaldatatype.Thismeans thattheDeveloperwillnotcorrectlydisplayaBigDecimaldatatyperesultand youcannotenteravalueofthisdatatype.However,theJDBCAdapterwill processtheBigDecimaldatatypecorrectly. Field Expression Column Type JDBC Type Output Field Type Description/Action ThecolumnnameorSQLexpression. Thecolumndatatypedefinedinthedatabasetable. TheJDBCtypeofthecorrespondingOutput Field. Thedatatypeoftheoutputfield.TheJDBCAdapter automaticallyconvertsdatabasespecifictypestoJavadata types. ForalistofJDBCtypetoJavatypemappings,see JDBCDataTypetoJavaDataTypeMappingson page 170. Output Field Thenameofthefieldcontainingtheoutputfromtheselect operation.Anoutputfieldnamedisplayswhenyouselect anexpression. Youcanalsomodifytheoutputfieldnamesasrequired. Maximum Row Specifiesthenumberofrowstoberetrievedfromthe buffertable.Thisfieldisusefulwhenyouareworking withalargenumberofrecordsandyouwanttolimitthe numberofdocumentssenteachtimethenotificationpolls. Useavalueof0toindicatenolimitonthenumberofrows retrieved.
13 UsetheWHENtabtospecifytheconditionsforselectinginformation: Note: IfyouuseMicrosoftSQLServer,Sybase,orV4AS/400DB2,donotusetheWHEN tabbecausethisfeatureisnotsupported.Anexceptionwillbegeneratedifyoutryto usethistab. a b SelecttheInsert RowicontodefinenewWHENclausefields. SelecttheColumnfieldandchooseacolumnfromthelist.
137
c d
SelectalogicaloperatorfromtheAND/ORfield,anOperator,andseparators(theleft andrightparentheses)asneeded. TypeafixedvalueintheValuefield.Besurethatitisavalidvalue,oranexception willbegeneratedatruntime. Ifnecessary,usetheShift Up orShift Down iconstochangetheorderofthe WHENclausetoensuretheparametersareparsedinthecorrectorder. RepeatuntilyouhavespecifiedallWHENparameters.
e f
14 ForinformationaboutusingthePermissionstabtoassignanaccesscontrollist(ACL) toanelementusingversionsoftheDeveloperearlierthan6.1,seethewebMethods DeveloperUsersGuide. WhenusingDeveloper6.1orlater,theinformationfromthePermissionstabappears inthePropertiespanel. 15 FromtheFilemenu,selectSave(orSave All). 16 YoumustscheduleandenablethenotificationusingtheServerAdministratorbefore youcanuseit.SeeManagingPollingNotificationsonpage 149fordetails.
Configuring BasicNotifications
ABasicNotificationpollsadatabasetablefordatausingaSQLSelectoperation.You configurenotificationsusingtheDeveloper.Formoreinformationaboutnotifications,see AdapterNotificationsonpage 22. BesuretoreviewthesectionBeforeConfiguringorManagingNotificationsonpage 124 beforeyouconfigurenotifications. Note: RunningaBasicNotificationmaygenerateaduplicatemessageerror;theIntegration Serverwillignoretheduplicatenotificationdocument.Inthiscase,youshouldcheckthe Delete selected recordsoptionontheSELECTtab(describedinstep 11below)andchoosea columnwithsequentiallyuniquevaluesastheRecord ID Columnvalue.
To configure a BasicNotification 1 2 3 4 5 FromtheDeveloperFilemenu,selectNew... SelectAdapter NotificationfromthelistofelementsandclickNext. SelectJDBC AdapterastheadaptertypeandclickNext. SelecttheappropriateAdapter Connection NameandclickNext. SelecttheBasicNotificatontemplateandclickNext.
138
6 7
Typeauniquenameforthenotificationandselecttheappropriatefolder.ClickNext. Thenameofthepublishabledocumentassociatedwiththisnotificationdisplays. ClickFinish. Formoreinformationaboutadapternotificationsandpublishabledocuments,see AdapterNotificationsonpage 22.FormoredetailsabouttheIntegrationServer publishabledocuments,whenusingversionsoftheIntegrationServerearlierthan6.1, seetheBuildingIntegrationSolutionsUsingPublicationdocument,andwhenusing IntegrationServer6.1orlater,seethePublishSubscribeDevelopersGuide.
Theeditorfortheadapternotificationappears.YoucanselecttheAdapter Settingstab atanytimetoconfirmadapternotificationpropertiessuchastheAdapter Name,Adapter Connection Name,andAdapter Notification Template,asnecessary. SelecttheTablestabandusethefollowingfields: Note: ForAS/400DB2V4R5usingajt400.jarfile,thetablenameforthenotification cannotexceed10characters;otherwise,anexceptionwillbegeneratedwhenyoutry toenablethenotification. Field Table Alias Table Name Description/Action Thetablealiasisautomaticallyassignedwhenyouselectmore thanonetableintheTable Namefield.Thedefaultist1. Selectatablename.Thedefaultfortheassociatedcatalog nameiscurrent catalog.Thedefaultfortheassociated schemanameiscurrent schema. Thetablenamemustnotcontainaperiod.Ifthetablename doescontainaperiod,DeveloperwillthrowaJavaexception. Note: Informixdatabasesdonotallowyoutospecifyacatalog anddatabasenamebecauseyoucanonlyaccessthecurrent catalog. Type Thetabletypedisplaysautomaticallybasedonthetableyou select.
10 Ifyouarenotjoiningtables,skipthisstep.SelecttheJoinstabtospecifythecolumns forjoiningthetablesyoujustconfigured. a b c SelecttheInsert Rowicon leftandrightcolumns. (ortheFill in all rows to the tableicon )tocreatenew
SelectLeft Columnandselectthefirsttablesjoiningcolumn. SelecttheappropriateOperator.
139
d e
SelectRight Columnandselectthenexttablesjoiningcolumn. Repeatuntilyouhavedefinedallthejoins.
11 UsetheSELECTtabtodefinethecolumnsandfieldstobeselected. a IntheALL/DISTINCTfield,selectALLtoincludeduplicaterowsorDISTINCTto suppressduplicaterows.SelectingALLcorrespondstotheSQLstatementSELECT ALL name from tablename.Thedefaultvalueisblank,whichcorrespondstothe SQLstatementSELECT name from tablename. SelecttheInsert Rowicon fieldsasneeded. (ortheFill in all rows to the tableicon )tocreatenew
b c
IntheExpressionfield,selectacolumnortypeanyvalidSQLexpression.The correspondingColumn Type,JDBC Type, Output Field Type, and Output Field display for each column you select in theExpressionfield.Usethefollowingfields: Note: YoucanusetheBigDecimaldatatypewiththeJDBCAdapter.However,the webMethodsDeveloperdoesnotsupporttheBigDecimaldatatype.Thismeans thattheDeveloperwillnotcorrectlydisplayaBigDecimaldatatyperesultand youcannotenteravalueofthisdatatype.However,theJDBCAdapterwill processtheBigDecimaldatatypecorrectly. Field Expression Column Type JDBC Type Output Field Type Description/Action ThecolumnnameorSQLexpression. Thecolumndatatypedefinedinthedatabasetable. TheJDBCtypeofthecorrespondingOutput Field. Thedatatypeoftheoutputfield.TheJDBCAdapter automaticallyconvertsdatabasespecifictypestoJavadata types. ForalistofJDBCtypetoJavatypemappings,see JDBCDataTypetoJavaDataTypeMappingson page 170. Output Field Thenameofthefieldcontainingtheoutputfromthe SELECToperation.Anoutputfieldnamedisplayswhen youselectanexpression. Youcanalsomodifytheoutputfieldnamesasrequired.
140
Field Sort Order
Description/Action Specifiesorderingofpublishabledocumentspereach polling.Usethisfieldtoensurethatthenotifications publishabledocuments,foreachpolling,areinthecorrect ascendingordescendingorderbasedononeormoretable columns. SelecteitherAscendorDescend.Leavethefieldblankif thereisnosortorder.
IfyouwanttousetheExactlyOncenotificationfeature,youmustenablethe Exactly Once Notificationoption.SeeConfiguringInsertNotificationsonpage 125 formoreinformation. Setthe Delete selected records flagtoautomaticallydeletetheselectedrecordsfrom thebuffertable(basedontheirRecord ID Columnvalueasenteredinstep f)after thenotification.Usethisoptiontopreventpublishingthesamedocumentstothe IntegrationServereachtimepollingoccurs. YoumustenabletheDelete selected records optiontousetheExactlyOnce notificationfeature.SeeConfiguringInsertNotificationsonpage 125formore information. Note: RunningaBasicNotificationmaygenerateaduplicatemessageerror;the IntegrationServerwillignoretheduplicatenotificationdocument.Inthiscase, youshouldchecktheDelete selected recordsoptionandchooseacolumnwith sequentiallyuniquevaluesastheRecord ID Columnvalueinstep fbelow.
Youmustusethe Record ID Column fieldtousetheExactlyOncenotification feature.Selectthecolumnfromthebuffertablethatyouwanttouseastheunique IDforthepublishabledocumentforthisnotification.SeeConfiguring InsertNotificationsonpage 125formoredetails. Toensurethatallvalueswillbeunique,chooseatablecolumnintheRecord ID Columnfieldwhosevaluesaresequentialnumbers.
UsetheMaximum Rowfieldtospecifythemaximumnumberofrecordstoretrieve fromthedatabase.Thisfieldisusefulwhenyouareworkingwithalargenumber ofrecordsandyouwanttolimitthenumberofdocumentssenteachtimethe notificationpolls. Thedefaultvalueof0(nolimit)retrievesallrecords.
141
Configuring StoredProcedureNotifications
AStoredProcedureNotificationpublishesnotificationdatabycallingastoredprocedureinside ofadatabase.YouconfigurenotificationsusingtheDeveloper.Formoreinformation aboutnotifications,seeAdapterNotificationsonpage 22. BesuretoreviewthesectionBeforeConfiguringorManagingNotificationsonpage 124 beforeyouconfigurenotifications. FordetailsandimportantconsiderationswhenusingaStoredProcedureNotification,see StoredProcedureNotificationsonpage 31. To configure a StoredProcedureNotification 1 2 3 4 5 6 7 FromtheDeveloperFilemenu,selectNew... SelectAdapter NotificationfromthelistofelementsandclickNext. SelectJDBC AdapterastheadaptertypeandclickNext. SelecttheappropriateAdapter Connection NameandclickNext. SelecttheStoredProcedureNotificatontemplateandclickNext. Typeauniquenameforthenotificationandselecttheappropriatefolder.ClickNext. Thenameofthepublishabledocumentassociatedwiththisnotificationdisplays. ClickFinish. Formoreinformationaboutadapternotificationsandpublishabledocuments,see AdapterNotificationsonpage 22.FormoredetailsabouttheIntegrationServer publishabledocuments,whenusingversionsoftheIntegrationServerearlierthan6.1, seetheBuildingIntegrationSolutionsUsingPublicationdocument,andwhenusing IntegrationServer6.1orlater,seethePublishSubscribeDevelopersGuide. 8 Theeditorfortheadapternotificationappears.YoucanselecttheAdapter Settingstab atanytimetoconfirmadapternotificationpropertiessuchastheAdapter Name,Adapter Connection Name,andAdapter Notification Template,asnecessary.
142
Configuring StoredProcedureNotifications
SelecttheCalltabtospecifywhichstoredproceduretousewiththenotification.Use theInsert Rowicon Field Catalog Name Schema Name Enable Procedure Lookup (Optional) andsettheCallparametersasfollows: Description/Action Thenameofthecatalog.Thedefaultforthecatalognameis current catalog. Thenameoftheschema.Thedefaultfortheschemanameis current schema. TotypeintheProcedure Name,setthisfieldtoFalse.Toselect theProcedure Namefromalist,setthisfieldtoTrue. ThedefaultisFalse. SetthisvaluetoFalse ifyouknowthenameoftheprocedure andyouareworkingwithalargedatabasethathasalonglist ofprocedures. Procedure Name JDBC Type Return Field Name Typeorselectthestoredprocedurename,dependingonhow yousettheEnable Procedure Lookupfield. TheJDBCtypeofthecorrespondingReturn Field Name. Nameofthereturnfieldofthestoredprocedure.
10 UsetheParametertabtospecifystoredprocedureparameters.UsetheInsert Row icon (ortheFill in all rows to the tableicon storedprocedure. )tocreatenewparametersforthe
Note: YoucanusetheBigDecimaldatatypewiththeJDBCAdapter.However,the webMethodsDeveloperdoesnotsupporttheBigDecimaldatatype.Thismeansthat theDeveloperwillnotcorrectlydisplayaBigDecimaldatatyperesultandyoucannot enteravalueofthisdatatype.However,theJDBCAdapterwillprocessthe BigDecimaldatatypecorrectly.
Field ParamJDBCType
Description/Action TheJDBCtypeofthestoredprocedureparameter. ForalistofJDBCtypetoJavatypemappings,see JDBCDataTypetoJavaDataTypeMappingsonpage 170.
ParamName ParamType
Storedprocedureparametername. SelectOUTastheparametertypebecauseStoredProcedure Notificationsdonotacceptinputparameters.
143
Field Expression Output Name
Description/Action Keepthedefaultvalueof?becauseStoredProcedure Notificationsdonotacceptinputparameters. Nameofanyoutputparametersofthestoredprocedure,if any. SeeStoredProcedureNotificationsonpage 31for informationaboutoutputfieldsforstoredprocedures.
Output Type
OutputparameterJavatype. ForalistofJDBCtypetoJavatypemappings,see JDBCDataTypetoJavaDataTypeMappingsonpage 170.
11 StoredProcedurenotificationscansupportoneresultset(oroneOracleREFCURSOR).If theprocedurereturnsaresultset,selecttheResultSettabtospecifyresultset parametersusingthefieldsinthefollowingtable: Field Result Set Index Result Set Name Description/Action Anindexisautomaticallyassignedtoeachresultset.Thefirst rowdefaultvalueis1. Typethenameoftheresultsetyouwanttocreate. SeeStoredProcedureNotificationsonpage 31for informationaboutresultsets. Result Set Name (from second row) Column Name JDBC Type Output Type Selectavalidresultsetname. Nameofcolumnoftheresultset. TheJDBCtypeoftheresultsetcolumn. TheJavatypeoftheresultcolumn. ForalistofJDBCtypetoJavatypemappings,see JDBCDataTypetoJavaDataTypeMappingsonpage 170. 12 ForinformationaboutusingthePermissionstabtoassignanaccesscontrollist(ACL) toanelementusingversionsoftheDeveloperearlierthan6.1,seethewebMethods DeveloperUsersGuide. WhenusingDeveloper6.1orlater,theinformationfromthePermissionstabappears inthePropertiespanel. 13 FromtheFilemenu,selectSave(or Save All). 14 YoumustscheduleandenablethenotificationusingtheServerAdministratorbefore youcanuseit.SeeManagingPollingNotificationsonpage 149fordetails.
144
Configuring OrderedNotifications
AnOrderedNotificationpublishesnotificationdataformultipleinsert,update,ordelete operationsonmultipletables.YouconfigurenotificationsusingtheDeveloper.Formore informationaboutnotifications,seeAdapterNotificationsonpage 22. BesuretoreviewthesectionBeforeConfiguringorManagingNotificationsonpage 124 beforeyouconfigurenotifications. Note: OrderedNotificationsarenotsupportedusingTeradataV2R5databases. WithOrderedNotifications,typicallyyouconfigureanIntegrationServertriggerto subscribetothenotificationspublishabledocumentandaflowservicethatthetrigger invokes.BecausetheprimaryreasontouseOrderedNotificationsistopreservetheorder inwhichtheoperationsoccur,besuretousetheProcess Document Seriallyoptiononthe SettingstabinDeveloperwhenyoucreatethetriggerandflowservice.Formore informationaboutusingconfiguringIntegrationServerstriggersandflowservices,see thewebMethodsDeveloperUsersGuide. To configure an OrderedNotification 1 2 3 4 5 6 7 FromtheDeveloperFilemenu,selectNew... SelectAdapter NotificationfromthelistofelementsandclickNext. SelectJDBC AdapterastheadaptertypeandclickNext. SelecttheappropriateAdapter Connection NameandclickNext. SelecttheStoredProcedureNotificatontemplateandclickNext. Typeauniquenameforthenotificationandselecttheappropriatefolder.ClickNext. Thenameofthepublishabledocumentassociatedwiththisnotificationdisplays. ClickFinish. Formoreinformationaboutadapternotificationsandpublishabledocuments,see AdapterNotificationsonpage 22.FormoredetailsabouttheIntegrationServer publishabledocuments,whenusingversionsoftheIntegrationServerearlierthan6.1, seetheBuildingIntegrationSolutionsUsingPublicationdocument,andwhenusing IntegrationServer6.1orlater,seethePublishSubscribeDevelopersGuide. 8 Theeditorfortheadapternotificationappears.YoucanselecttheAdapter Settingstab atanytimetoconfirmnotificationpropertiessuchastheAdapter Name,Adapter Connection Name,andAdapter Notification Template,asnecessary.
145
SelecttheNotification Configuretabandusethefollowingfields: Field Base Name Description/Action ThebasenameusedtogeneratetheResource Namecreatedby theJDBCAdapter. Note: ForOS/390DB2V7.2,theBase Name youcreatebelow mustbenomorethan5charactersbecausetriggersonOS/390 namecannotbemorethan8characters. Resource Type Typesarebuffertable,trigger,andsequence. Thebasenameandresourcetypedeterminethefollowing Resource Name. Resource Name Toensureuniqueness,theresourcenamecombinesthe followingelements.Youdonoteditthisname. Resourceprefix(WMB,WMT,andWMSforbuffertable, trigger,andsequencerespectively) ThenameyoutypedintheBase Name field Asuffix,basedonasystemtimestamp File Record Format Theformatofthefilerecord. OptionalfieldusedbyDB2forAS/400V4R5only. Database Name Thenameofthedatabasewherethebuffertableswillbe created. OptionalfieldusedbyDB2forOS/390only. Table Space Name Thetablespacewherethebuffertableswillbecreated. OptionalfieldusedbyDB2forOS/390only.
146
10 SelecttheSource Tablestabandusethefollowingfields: Note: ForAS/400DB2V4R5usingajt400.jarfile,thetablenameforthenotification cannotexceed10characters;otherwise,anexceptionwillbegeneratedwhenyoutry toenablethenotification. Field Table Alias Table Name Description/Action Thetablealiasisautomaticallyassignedwhenyouselectmore thanonetableintheTable Namefield.Thedefaultist1. Selectatablename.Thedefaultfortheassociatedcatalog nameiscurrent catalog.Thedefaultfortheassociated schemanameiscurrent schema. Thetablenamemustnotcontainaperiod.Ifthetablename doescontainaperiod,DeveloperwillthrowaJavaexception. Note: Informixdatabasesdonotallowyoutospecifyacatalog anddatabasenamebecauseyoucanonlyaccessthecurrent catalog. Type Operation Type Operation ID Thetabletypedisplaysautomaticallybasedonthetableyou select. SelectINSERT,UPDATE,orDELETEoperation. AssignanIDtouniquelyidentifythegivenoperationforthe notification.
11 UsetheSELECTtabtodefinethecolumnsandfieldstobeselectedusingthefollowing fields: a IntheALL/DISTINCTfield,selectALLtoincludeduplicaterowsorDISTINCTto suppressduplicaterows.SelectingALLcorrespondstotheSQLstatementSELECT ALL name from tablename.Thedefaultvalueisblank,whichcorrespondstothe SQLstatementSELECT name from tablename. SelecttheInsert Rowicon (ortheFill in all rows to the tableicon )tocreatenew fieldsasneeded.ForeachExpressioncolumnyouselect,thecorresponding Operation ID,Column Type,JDBC Type,Output Field Type,andOutput Field display. Note: YoucanusetheBigDecimaldatatypewiththeJDBCAdapter.However,the webMethodsDeveloperdoesnotsupporttheBigDecimaldatatype.Thismeans thattheDeveloperwillnotcorrectlydisplayaBigDecimaldatatyperesultand youcannotenteravalueofthisdatatype.However,theJDBCAdapterwill processtheBigDecimaldatatypecorrectly.
147
Usethefollowingfields: Field Expression Operation ID Column Type JDBC Type Output Field Type Description/Action Thecolumnname. ThecorrespondingoperationIDfortheexpression. Thecolumndatatypedefinedinthedatabasetable. TheJDBCtypeofthecorrespondingOutput Field. Thedatatypeoftheoutputfield.TheJDBCAdapter automaticallyconvertsdatabasespecifictypestoJavadata types. ForalistofJDBCtypetoJavatypemappings,see JDBCDataTypetoJavaDataTypeMappingson page 170. Output Field Thenameofthefieldcontainingtheoutputfromthe SELECToperation.Anoutputfieldnamedisplayswhen youselectanexpression. Youcanalsomodifytheoutputfieldnamesasrequired. Notify On Update UsedforUpdateoperationsonly.Enablethisoptionto indicatewhichofthecolumnsspecifiedintheSELECTtab youwantnotificationifupdated.Select: Yes:youwantnotificationifthiscolumnofdatahas beenupdated No:youdonotwantnotificationifthiscolumnofdata hasbeenupdated Forexample,youconfigurethefollowingthreeoutput fields:MyName,MyNumber,andMyLocation. Youwant notificationonlyifthe MyLocation outputfieldis updated.Inthiscase,youwouldselectYes forthe MyLocationoutputfield,andselectNofortheMyName andMyNumberoutputfields. 12 UsetheWHENtabtospecifytheconditionsforselectinginformationusingthe followingtable. Note: IfyouuseMicrosoftSQLServerorSybase,donotusetheWHENtabbecausethis featureisnotsupported.Anexceptionwillbegeneratedifyoutrytousethistab.
148
Managing Polling Notifications
a b c d
SelecttheInsert Rowicon
todefinenewWHENclausefields.
SelecttheColumnfieldandchooseacolumnfromthelist.TheOperation IDwill displayafteryoumakeyourselection. SelectalogicaloperatorfromtheAND/ORfield,anOperator,andseparators(theleft andrightparentheses)asneeded. TypeafixedvalueintheValuefield.Besurethatitisavalidvalue,oranexception willbegeneratedatruntime. Ifnecessary,usetheShift Up orShift Down iconstochangetheorderofthe WHENclausetoensuretheparametersareparsedinthecorrectorder. RepeatuntilyouhavespecifiedallWHENparameters.
e f

Youmustscheduleanotificationandthenenableitbeforeyoucanusethenotification. UsetheIntegrationServerAdministratoralongwiththefollowingprocedurestodoso. Note: YoumusthavewebMethodsadministratorprivilegestoaccesstheJDBCAdapters administrativescreens.SeethewebMethodsIntegrationServerAdministratorsGuidefor informationaboutsettinguserprivileges.
To manage polling notifications
1 2 3
StarttheIntegrationServerAdministrator. FromtheAdaptersmenuinthenavigationareaoftheAdministrator,selectJDBC Adapter. Fromthenavigationarea,selectPolling Notifications.
149
FromtheJDBC Adapter Polling Notifications table,usethefieldsinthefollowingtableto manageeachadapternotification: Note: ForAS/400DB2V4R5usingajt400.jarfile,thetablenameforthenotification cannotexceed10characters;otherwise,anexceptionwillbegeneratedwhenyoutry toenablethenotification. Note: IfyouuseanXATransactionconnection,youcannotenableanotification. Field Notification Name Package Name Enabled Description/Action Thenameofthenotification. Thenameofthepackageforthenotification. ThisfieldappliesonlytoIntegrationServerversionsearlierthan6.5. Note: Youmustscheduleapollingnotificationbeforeyoucan enableit.Toscheduleapollingnotification,usetheEdit Schedule icondescribedintheseprocedures.
Afteryouscheduleapollingnotification,youcanusethis optiontoenable(Yes)ordisable(No)apollingnotification. Clickonthecurrentvalueinthisfieldtochangeitsvalue. Enablinganddisablinganotificationaffectshowitstrigger andbuffertablesarecreatedanddropped.Fordetails,see PollingNotificationsandStatesonpage 41. Ifthereisnopollingnotificationscheduledforagivenadapter notification,Not Scheduled appearsinthisfield.UsetheEdit Schedule instep 5. icontocreateapollingnotificationasdescribed
150
Field State
Description/Action ThisfieldappliesonlytoIntegrationServerversion6.5. Note: Youmustscheduleapollingnotificationbeforeyoucan enableit.Toscheduleapollingnotification,usetheEdit Schedule icondescribedintheseprocedures.
Afteryouscheduleapollingnotification,youcanusethis optionsdropdownlisttosetthepollingnotificationsstate: Enabled:Thepollingnotificationperformsasscheduled. Suspended:Thepollingnotificationisremovedfromthe schedulerbutthedatabasetriggerandbuffertablearenot dropped. Disabled:Thepollingnotificationisremovedfromthe schedulerandthedatabasetriggerandbuffertableare dropped. TheSuspend all enabledandResume all suspendedlinkshelpyou changestatesquicklyformultiplepollingnotifications. Enabling,suspending,anddisablinganotificationaffectshow itstriggerandbuffertablesarecreatedanddropped.For details,seePollingNotificationsandStatesonpage 41. Ifthereisnopollingnotificationscheduledforagivenadapter notification,controlforthisfieldisdisabled.UsetheEdit Schedule instep 5. Edit Schedule icontocreateapollingnotificationasdescribed
ClickontheEdit Schedule notificationparameters.
icontocreateormodifypolling
Note: Youmustdisableapollingnotificationbeforeyoucan editit. Continuetostep 5. View Schedule ClickontheView Scheduleicontoreviewtheparametersforthe selectedpollingnotification.ClickReturn to JDBC Adapter Notificationstogobacktothemainpollingnotificationpage.
151
Tocreateormodifyscheduleparametersfortheselectedadapternotification,clickon theEdit Schedule Field Interval (seconds) Overlap iconandusethefollowingfields: Description/Action Typethepollingintervaltimeinseconds. Note: Donotusethisoption;otherwise,whenyouenablethis notification,itmaylockuptablesandcausetheIntegration Servertofail. Enablethisoptiontostartpollingimmediately.
Immediate 6 7 ClickSave Schedule.
Afteryoucreateapollingnotification,youcanenableit.UsetheStatefielddescribed instep 4toenableapollingnotification.
Using the Exactly Once Notification Feature

AdapternotificationscanusetheExactlyOncenotificationfeature.Thisfeatureensures thatnotificationdatawillnotbeduplicatedevenifafailureoccursduringprocessing. ThisisachievedbyassigninguniqueIDsforeachpublishabledocument.Aftera processingfailure,theIntegrationServerchecksforduplicaterecordsinstorageand ignoresanyduplicateIDs. Becausethisfeatureensuresthattherowsofthedatainthebuffertablewillnotbe duplicatedevenafteraprocessingfailure,youshouldnotrecreateanotificationinthe eventofaprocessingfailure.TheExactlyOncefeaturewillautomaticallymakethe appropriatecorrectionsasneeded. Note: StoredProcedureNotificationsdonotsupporttheExactlyOncenotificationfeature becausetheydonotusepublishabledocumentuniqueIDs.
Enabling Exactly Once Notification

TousetheExactlyOncefeature,youmustenableclientsidequeuingintheIntegration Server.Fordetails,seethewebMethodsIntegrationServerAdministratorsGuide.
152
Exporting Configured Adapter Notifications
Exporting Configured Adapter Notifications

YoucanexportnotificationsfromoneIntegrationServertoanotherIntegrationServer. Youdonotneedtodisablenotificationsinordertoexportthem.Inmostcases,thecurrent stateofthenotificationsinthepackagethatyouexportisretained.However,ifyou deploytoadifferentIntegrationServerandconnecttoadifferentdatabase,thenyou shouldfirstdisablethenotification. Note: AgivennotificationcanonlyrunononeIntegrationServeratatime. WithInsertNotifications,UpdateNotifications,andDeleteNotifications,thebuffertable andtriggerremaininthedatabase.WhentheIntegrationServerwiththeexported notificationsstarts,eachconfigurednotificationstartstopollthedatafromthebuffer table. IfyouwanttoexportconfigurednotificationsinaDisabledstate,youneedtodisablethe notificationsbeforeyouexportthepackagecontainingthem.WithInsertNotifications, UpdateNotifications,andDeleteNotifications,thebuffertableandtriggerwillbe droppedwhenyoudisablethenotification.Whenyouenabletheexportednotification, thebuffertableandtriggerwillbecreated. YoumayexportconfigurednotificationsinaSuspendedstate.Thetriggerandbuffertable willnotbedropped. SeeInsertNotifications,UpdateNotifications,andDeleteNotificationsonpage 24for moredetails. Formoreinformationaboutexportingpackages,seethewebMethodsIntegrationServer AdministratorsGuide.
Viewing Notifications
YouusetheDevelopertoviewnotifications.IfyouareusingtheDeveloper6.1orlater, makesureyouareviewingthewebMethodsDeveloperintheEditperspective,as describedinViewingDifferentPerspectivesofthewebMethodsDeveloperonpage 43. To view a notification 1 2 IntheDeveloperServiceBrowser,expandthepackageandfolderthatcontainthe notificationyouwanttoview. Selectthenotificationyouwanttoview. TheDeveloperdisplaysthenotificationinthenotificationtemplatesAdapter NotificationEditor.
153
Editing Notifications
YouusetheDevelopertoeditnotifications.IfyouareusingtheDeveloper6.1orlater, makesureyouareviewingthewebMethodsDeveloperintheEditperspective,as describedinViewingDifferentPerspectivesofthewebMethodsDeveloperonpage 43. DependingonwhichversionoftheIntegrationServeryouuse,youmaybeabletochange theconnectionassociatedwithanadapternotification,asfollows: WhenusingversionsoftheIntegrationServerearlierthan6.1,youcannotchange whichconnectionanadapternotificationusesafterthenotificationisconfigured. WhenusingIntegrationServer6.1orlater,youcanchangewhichconnectionan adapternotificationuses.Todothis,youusethebuiltinservice pub.art.notification:setPollingNotificationNodeConnection.Formoreinformation,seeChanging theConnectionAssociatedwithanAdapterServiceorNotificationatDesignTime onpage 19. To edit a notification 1 2 IntheDeveloperServiceBrowser,expandthepackageandfolderthatcontainthe notificationyouwanttoview. Selectthenotificationyouwanttoedit. TheDeveloperdisplaysthenotificationinthenotificationtemplatesAdapter NotificationEditor. 3 Modifythevaluesfornotificationsparametersasneeded.Fordetaileddescriptionsof thenotificationsparameters,seethesectiononconfiguringanotificationforthe specifictypeofnotificationyouwanttoedit.
Note: Becauseadapternotificationinherentlydependonconnections,youcannoteditor changetheadapterconnectionforanotificationafteryouconfigureit.
Deleting Notifications
YouusetheDevelopertodeleteadapternotifications.IfyouareusingtheDeveloper6.1 orlater,makesureyouareviewingtheDeveloperintheEditperspective,asdescribedin ViewingDifferentPerspectivesofthewebMethodsDeveloperonpage 43. Note: Beforeyoudeletethenotification,besurethatyoufirstdisableit.Otherwise,the triggerandbuffertablecreatedbythenotificationwillremaininthedatabase.Todisable anotification,seeManagingPollingNotificationsonpage 149.
154
Validating Adapter Notification Values
To delete a notification 1 IntheDeveloperServiceBrowser,expandthepackageandfolderthatcontainthe notificationyouwanttodelete. RightclickthenotificationandthenclickDelete.
Validating Adapter Notification Values

TheDeveloperenablestheJDBCAdaptertovalidateuserdefineddataforadapter notificationsatdesigntime.Youcanvalidatethevaluesforasinglenotificationoryoucan configuretheDevelopertoalwaysvalidatethevaluesfornotifications. Note: Ifyouselecttheoptiontoalwaysvalidatevaluesforadapternotifications,itwilldo soforallwebMethods6.xadaptersinstalledontheIntegrationServer,whichcould potentiallyslowyourdesigntimeoperations. Tovalidateallvalues,selectfromtheDevelopertheTools > Options... >Integration Server> Adapter Service/Notification EditoritemandenabletheAutomatic data validationoption. WhenusingversionsoftheIntegrationServerearlierthan6.1,thisoptionisalsoavailable asaniconontheDeveloper,theValidate service/notification valueicon .Thisiconis availableonlywhentheAutomatic data validationoptioniscurrentlydisabled. TheAutomatic data validationoptionenablesdatavalidationfortheselectedadapter notificationonly.Itcomparestheservicevaluesagainsttheresourcedatathathasalready beenfetchedfromtheadapter.Notethatthisoptioncanslowoperations. SeethewebMethodsDeveloperUsersGuideformoreinformationabouttheAdapter Service/Notification Editor andotherDevelopermenuoptionsandtoolbaricons.
Reloading Adapter Values

TheDeveloperenablestheJDBCAdaptertoreloadandvalidateuserdefineddatafor notificationsatdesigntime.Youcanreloadvaluesforasinglenotificationoryoucan configuretheDevelopersoitautomaticallyreloadsthevaluesforadapternotifications. Note: Ifyouselecttheoptiontoautomaticallyreloadvaluesfornotifications,itwilldoso forallwebMethods6.xadaptersinstalledontheIntegrationServer,whichcould potentiallyslowyourdesigntimeoperations. Toreloadtheadaptervaluesandrevalidatealluservaluesasneededfortheadapter service,selectfromtheDevelopertheTools >Options... >Integration Server>Adapter Service/Notification Editoritemandenablethe Automatic polling of adapter metadataoption.
155
WhenusingversionsoftheIntegrationServerearlierthan6.1,thisoptionisalsoavailable asaniconontheDeveloper,theRefreshicon .
Thisoptionenablesdatavalidationfortheselectedadapterserviceonly.Itcomparesthe servicevaluesagainsttheresourcedatathathasalreadybeenfetchedfromtheadapter. SeethewebMethodsDeveloperUsersGuideformoreinformationaboutthe Adapter Service/Notification Editor andotherDevelopermenuoptionsandtoolbaricons.
156
CHAPTER
Logging and Exception Handling

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 JDBC Adapter Message Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 JDBC Adapter Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Customizing the Adapters List of Fatal Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 JDBC Adapter Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
157
CHAPTER 6 Logging and Exception Handling
Overview
Thefollowingsectionsdescribemessagelogging,JDBCAdapterexceptionhandling,and customizingtheJDBCAdapterslistoffatalerrorcodes.Alistoferrorcodesand supportinginformationappearsattheendofthischapter. Foralistofknowndatabasedriverlimitations,seeDatabaseDriverKnownLimitations onpage 187.
JDBC Adapter Message Logging

TheJDBCAdapterusestheIntegrationServerloggingmechanismtologmessages.You canconfigureandviewtheIntegrationServerlogstomonitorandtroubleshoottheJDBC Adapter.SeethewebMethodsIntegrationServerAdministratorsGuidefordetailed informationaboutloggingintheIntegrationServer,includinginstructionsforconfiguring andviewingthedifferentkindsoflogssupportedbytheserver. TheIntegrationServermaintainsseveraltypesoflogs;however,theJDBCAdapteronly logsmessagestotheAudit,ErrorandServerlogs,asdescribedinthetablebelow: Log AuditLog Description Youcanmonitorindividualadapterservicesusingtheauditlogas youwouldauditanyserviceintheIntegrationServer.Theaudit propertiesforanadapterserviceareavailableineachJDBC AdapterservicetemplateontheAudittab. TheJDBCAdapterautomaticallypostscriticallevelanderror levellogmessagestotheserversErrorlog.Theselogmessages willappearasAdapterRuntimemessages. TheJDBCAdapterpostsmessagestotheServerlog,dependingon howtheserverlogisconfigured.Criticallevelthroughdebug levellogmessagesappearasAdapterRuntimelogmessages.V1 Verbose1orV4Verbose4logmessagesappearasJDBCAdapter logmessages.
ErrorLog
ServerLog
TheJDBCAdapterslogmessagesappearinthefollowingformat:ADA.1.nnnnc,where thefacilitycodeADAindicatesthatthemessageisfromanadapter,1indicatesthatitis theJDBCAdapter,nnnnrepresentstheerrorsminorcode,and(optionally)crepresents themessagesseveritylevel.FordetaileddescriptionsoftheJDBCAdaptersminorcodes, seeJDBCAdapterErrorCodesonpage 161. BecausetheJDBCAdapterworksinconjunctionwiththeWmARTpackage,theadapters messagesandexceptionstypicallyappearwithinlogmessagesfortheWmARTpackage, althoughthatisnotnecessarilytrueforverboselevelmessages.
158
JDBC Adapter Exception Handling
TomonitortheJDBCAdapterslogmessagesintheServerlog,ensurethatyourserver logsloggingsettingsareconfiguredtomonitorthefollowingfacilities: 0113AdapterRuntime(ManagedObject) 0114AdapterRuntime 0115AdapterRuntime(Listener) 0116AdapterRuntime(Notification) 0117AdapterRuntime(AdapterService) 0118AdapterRuntime(Connection) 0121AdapterRuntime(SCCTransactionManager) 0126AdapterRuntime(SCCConnectionManager)
JDBC Adapter Exception Handling

TheJDBCAdapterthrowstwokindsofexceptionsthatyoushouldbeawareofasyou buildintegrationsusingtheadapter:AdapterExceptionand AdapterConnectionException.WhencreatingafloworJavaservicethatincorporatesan adapterserviceornotification,youmightwanttobuildlogicintothewrappingserviceto catchandhandlethesetypesofexceptions.
AdapterException
TheJDBCAdapterthrowsanAdapterExceptionfortworeasons: 1 2 Toreportanerrorrelatedtotheadapterslogic,suchasaconfigurationerrorora connectioncreationerror. TowrapanSQLExceptioniftheadapterdoesnotconsidertheSQLExceptions SQLCODEtobeafatalerror.Inthiscase,WmARTwrapstheAdapterExceptionina com.wm.pkg.art.error.DetailedServiceExceptionandthrowsittotheIntegration Server.AdapterExceptionscontaininganerrorcodeof316areSQLExceptions.
TomanagetheAdapterException,youcancatchtheDetailedServiceExceptioninaflowor JavaserviceandthennavigatethroughthenestedexceptionstotheAdapterException, whichwillcontaintheerrorcodeidentifyingtheerror.
159
AdapterConnectionException
TheJDBCAdapterthrowsanAdapterConnectionExceptiontowrapanSQLExceptionif theadapterinterpretstheSQLCODEasafatalerror. Inthiscase: WmART6.5andlaterresetstheentireconnectionpool. WmARTearlierthan6.5dropstheconnectionfromtheconnectionpool. WmARTthenwrapstheexceptionincom.wm.pkg.art.error.DetailedSystemException andthrowsittotheIntegrationServer.
SQLException
WhenanadapterconnectionsassociatedJDBCdriverfailstoexecuteaSQLcommand againstadatabase,thedriverthrowsaSQLException.SQLExceptionsincludeaSQL STATE,aSQLCODE,andanerrormessage. TheJDBCAdaptercatchestheSQLExceptionfromtheJDBCdriverand,dependingonthe SQLCODE,wrapstheSQLExceptionineitheranAdapterExceptionoran AdapterConnectionException.IfaSQLCODEisintheadapterslistoffatalerrorsforthe database,theadapterwrapstheexceptioninanAdapterConnectionException;otherwise, itwrapsitinanAdapterException.EachAdapterExceptionand AdapterConnectionExceptioncontainsanadaptererrorcode.Iftheerrorcodeis316,then theexceptionwrapsanSQLException.
Customizing the Adapter s List of Fatal Error Codes

Youcanaddaspecificerrorcodetothelistoffatalerrorcodes.ThisallowstheJDBC AdaptertoautomaticallyrefreshJDBCAdapterconnectionswhenaspecificerroroccurs. Besurethatthereisnootheruseforthiserrorcodebeforeyouaddittothelist. To customize the fatal error list 1 2 3 StarttheIntegrationServerAdministratorifitisnotalreadyrunning. UnderSettingsintheleftpanel,selectExtended. SelectEdit Extended Settings. Intheeditbox,type:
watt.adapter.JDBC.database driver.fatalErrors=+ErrorCode_1, ErrorCode_2, ErrorCode_n
Example:ToallowtheJDBCAdaptertorefreshconnectionswhenencountering Oracleerrorcodes17002and17003usinganOracleJDBCdriver,type:
watt.adapter.JDBC.Oracle.fatalErrors=+17002, 17003
160
JDBC Adapter Error Codes
Thefollowingisalistofothersupporteddriversettings(for watt.adapter.JDBC.databasedriver.fatalErrors): Driver MicrosoftSQLServer OracleJDBC IBMDB2Net IBMDB2App JTOpen DataDirectConnect forJDBCdriverfor DB2 TeradataType4 JDBC2.21type4for Informix jCONNECT5.5type 4forSybase DB2Universaltype4 Otherdrivertypes 4 5 ClickSave Changes. RestarttheJDBCAdapter. Setting watt.adapter.JDBC.MsMssql.fatalErrors watt.adapter.JDBC.Oracle.fatalErrors watt.adapter.JDBC.DB2NET.fatalErrors watt.adapter.JDBC.DB2APP.fatalErrors watt.adapter.JDBC.DB2JTOPEN.fatalErrors watt.adapter.JDBC.CJDBCDB2.fatalErrors
watt.adapter.JDBC.TeraData.fatalErrors watt.adapter.JDBC.INFORMIX.fatalErrors watt.adapter.JDBC.SYBASE.fatalErrors

watt.adapter.JDBC.DB2UNIVERSAL.fatalErrors
watt.adapter.JDBC.Generic.fatalErrors

ThefollowingtableliststheJDBCAdaptersminorcodesandprovidesinformationonthe errormessage,reason,andpossibleactionforeacherror. 200 The JDBC DataSource class ClassName cannot be located. ADataSourceclassnamewasspecifiedintheadapterConnectionPropertiesDataSource Classfield,buttheclasscannotbelocated. Cause: Eithertheclassdoesnotexistorthenamewasmisspelled. Response: CheckthespellingandmakesuretheJDBCdriverfileisintheCLASSPATHor intheIntegrationServer/package/WmJDBCAdapter/code/jarsdirectory.
161
201 The JDBC DataSource class ClassName cannot be instantiated. Cause: TheinstantiationoftheJDBCdriversDataSourceclassfailed. Response: UseasupportedJDBCdriver. 202 Cannot set properties for JDBC DataSource class ClassName. Cause: PropertiescannotbesetthroughtheDataSourceclassbecausethedriverdoesnot supportthespecifiedproperty. Response: SeeConfiguringJDBCAdapterConnections,step 5onpage69forsupported driversandtheirsettings. 203 The JDBC DataSource class ClassName does not have some of the configured property settings. Cause: Somepropertiesspecifiedintheconnectionspropertiesarenotcorrect. Response: SeeConfiguringJDBCAdapterConnections,step 5onpage69forsupported driversandtheirsettings. 204 Cannot connect to the database with DataSource class ClassName. Cause: Theconnectionbetweentheadapterandthedatabasefailed. Response: ChecktheSQLexceptionintheIntegrationServererrorlog,andcheckthe databaseerrormessages. 205 Cannot retrieve the database metadata MetadataElement. Cause: Anerroroccurredwhentheadaptertriedtoretrievedatabasemetadata information. Response: ChecktheSQLexceptionintheIntegrationServererrorlog,andcheckthe databaseerrormessages. 206 The JDBC DataSource class ClassName is not XADataSource. Cause: TheDataSourceclassnameyouspecifiedintheConnectionPropertiesDataSource NamefieldisnotanXADataSource. Response: SeeyourJDBCAdapterdocumentationforsupporteddriversandDataSource classnames. 207 The JDBC DataSource class ClassName does not support LOCAL_TRANSACTION. Cause: TheLOCAL_TRANSACTIONtransactiontypeisnotsupportedbythisdatabase. Response: UseNO_TRANSACTIONinstead.
162
208 Cannot disconnect from the database DataBaseName. Cause: Theconnectionbetweentheadapteranddatabasecannotbeclosed. Response: ChecktheSQLexceptionintheIntegrationServererrorlogsanddatabaseerror messagesfordetails. 209 Cannot create writer with file path FilePathName or JDBC Log. Cause: JDBClogfilecreationfailed. Response: Checkthatthelogfilepathhasthecorrectwatt.adapter.JDBC.JDBCLogFile setting. 210 Cannot unlock webMethods OEM JDBC driver license. Cause: TheOEMversionoftheDataDirectConnectforJDBCdrivercannotbeunlocked withthekeywebMethods. Response: CheckthatthedriveristheOEMversionandthatthekeyiswebMethods. 306 The adapter does not support Ordered Notification for this database DataBaseName. Please select another service or notification template. Cause: OrderedNotificationsarenotsupportedonthisdatabase. Response: UseaBasicNotificationorStoredProcedureNotificationinsteadof OrderedNotification. 307 The adapter does not support Automatic Notification for this DataBaseName. Please select another operation template. Cause: TheAutomaticNotification(InsertNotification,UpdateNotification,or DeleteNotification)isnotsupportedforthisdatabase. Response: UseaBasicNotificationorStoredProcedureNotificationinsteadof InsertNotification,UpdateNotification,orDeleteNotification. 308 There must be at least one expression for the SELECT statement. Cause: YoudidnotspecifyanyrowsusingtheSELECTtabfortheconfiguredservice. Response: AddrowstotheSELECTtab. 309 Select at least one column from the main table. Cause: Thereisnocolumnspecifiedfromthetable. Response: AddatleastonecolumnofthemaintableundertheSELECTtab.
163
310 The database vendor VendorName does not support the database trigger condition. Cause: TheWHENtriggerconditiondoesnotapplytothisdatabase. Response: DonotusetheWHENtabwiththenotification. 311 The connection is not available for NotificationCallbackName. Cause: Thereisnoconnectionavailableintheconnectionpool. Response: Checktheadapterconnectionandcontactyouradministratortoincreasethe numberofconnections. 312 Cannot commit the transaction to the database. DataBaseName. Cause: Thetransactioncommitfailed. Response: ChecktheSQLexceptionintheIntegrationServererrorlogsanddatabaseerror messagesfordetails. 313 Cannot read data for the output field OutputFieldName. Cause: I/Oerroroccurredwhentryingtoreadbytesequencedata. Response: CallCustomerCareforassistance. 314 Cannot set data for the input field InputFieldName. Cause: Theinputfieldvalueisnotnumeric. Response: Changetoanumericinputvalue. 316 Cannot execute the SQL statement SQLStatement. Cause: SQLstatementsfailedtoexecute. Response: ChecktheSQLexceptionintheIntegrationServererrorlogsanddatabaseerror messagesfordetails. 318 Cannot get the list of catalogs. Cause: Cataloginformationforthedatabasecannotberetrieved. Response: ChecktheSQLexceptionintheIntegrationServererrorlogsanddatabaseerror messagesfordetails.
164
319 Cannot get the list of table columns. Cause: Columninformationforthedatabaseobjectcannotberetrieved. Response: ChecktheSQLexceptionintheIntegrationServererrorlogsanddatabaseerror messagesfordetails. 320 Cannot get the list of stored procedures. Cause: Storedprocedureinformationforthedatabasecannotberetrieved. Response: ChecktheSQLexceptionintheIntegrationServererrorlogsanddatabaseerror messagesfordetails. 321 Cannot get the list of schemas. Cause: Schemainformationforthedatabasecannotberetrieved. Response: ChecktheSQLexceptionintheIntegrationServererrorlogsanddatabaseerror messagesfordetails. 322 Cannot get the list of tables. Cause: Tableinformationforthedatabasecannotberetrieved. Response: ChecktheSQLexceptionintheIntegrationServererrorlogsanddatabaseerror messagesfordetails. 326 This database does not support stored procedure calls using JDBC stored procedure escape syntax. Cause: Storedprocedurecallsarenotsupportedbythisdatabase. Response: Donotusestoredprocedureservices. 327 This notification is not ready to be enabled. Cause: Configurationofthenotificationisnotcomplete. Response: SeeChapter 5,AdapterNotificationsonpagepage 157forcomplete instructionsforconfiguringnotifications. 331 The String for the input field InputFieldName does not contain a parsable number. Cause: TheinputStringvalueisnotnumeric. Response: ChangetoanumericinputStringvalue.
165
333 You must have the Record ID column listed under the SELECT tab. Cause: YoudidnotconfiguretheRecordIDcolumn. Response: AddtheRecordIDcolumnusingtheSELECTtabfortheBasicNotification. 334 A notification procedure can only have a single result set. Cause: YouconfiguredmorethanoneresultsetfortheStoredProcedureNotification. Response: Rewritethestoredprocedureandconfigureonlyoneresultset. 335 A notification procedure can only have a single Oracle REF Cursor. Cause: YouconfiguredmorethanoneOracleREFCursorfortheStoredProcedure Notification. Response: RewritethestoredprocedureandconfigureonlyoneOracleREFCursor. 336 If you choose Only Once Notification, you must also check the Delete Selected Records box to avoid duplicate document warning messages. Cause: TheDelete Selected Recordsboxisnotchecked. Response: ChecktheDelete Selected Recordsbox. 337 The notification should not be configured on a connection with TransactionType. Cause: Notificationisconfiguredwithconnectionoftransactiontypeotherthan LOCAL_TRANSACTION. Response: ReconfigurethenotificationusingLOCAL_TRANSACTION. 338 The data mapping for field FieldName is not supported. Cause: Thedatamappingisnotcorrect. Response: Foralistofsupporteddatatypemappings,seeDataTypeMappingon page 169. 339 The number of Base Name characters used in Notification Configure tab must not exceed MaximumCharacterLength. Cause: TheBase Nameistoolong. Response: RefertothemessageitselfandshortentheBase NameusingtheNotification Configure tab.
166
401 Cannot execute AS/400 command CommandName. Cause: TheAS/400environmentmaynotbecorrect. Response: Checkthecommandanderrormessage. 402 Cannot create file on AS/400. Cause: AnerroroccurswhentheadaptercreatesthefileontheAS/400system. Response: CheckthefilenameandAS/400filesystem. 403 Cannot create trigger on AS/400. Cause: AnerroroccurswhentheadaptercreatesatriggerontheAS/400system. Response: Checkwhetherthereisalreadyatriggerwiththisname.Alsocheckwhetherthe userhasrightstocreatethetrigger. 404 Cannot drop trigger on AS/400. Cause: ErrorsoccurwhentheadapterdropsatriggerfromtheAS/400system. Response: Checkwhetherthetriggerexists. 501 BaseName is not a valid name. For the notification on AS/400, the name of the source table, buffer table and trigger should not exceed 10 characters. Cause: Thenamesarelongerthan10characters. Response: Changethebasenamesothatthenamesofbuffertableandtriggerare10 charactersorless.
167
168
APPENDIX
Data Type Mapping

JDBC Data Type to Java Data Type Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 SQL Data Type to JDBC Data Type Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
169
A P P E N D I X A D a t a Ty p e M a p p i n g
JDBC Data Type to Java Data Type Mappings

EachcolumninthedatabasetableisassignedaSQLtype.TheJDBCdrivermapseach SQLdatatypetoaJDBCdatatype.TheJDBCAdapterthenmapseachJDBCdatatypeto oneormoreJavadatatypesthatareusedastheinputoroutputoftheadapterserviceor notification. ThefollowingtableshowstheJDBCdatatypetoJavadatatypemappings.Youcanmap eachJDBCdatatypetoasetofJavadatatypesbychoosingonefromtheset.TheJDBC datatypeyouselectduringconfigurationwillthenmaptotheinputoroutputofthe adapterserviceornotification. SeeJDBCDataTypetoJavaDataTypeMappingsonpage 170foralistofdatatypesfor whichtheIntegrationServerhassomeconstraints. Note: TheJDBCAdapterdoesnotsupportthedatalinkDB2datatypewhenusingthe adapterwithDB2forAS/400orDB2forOS/390. Note: TheJDBCAdapterdoesnotsupportuserdefineddatatypes,OraclePL/SQL collections,orOraclePL/SQLrecords. Note: YoucanusetheBigDecimaldatatypewiththeJDBCAdapter.However,the webMethodsDeveloperdoesnotsupporttheBigDecimaldatatype.Thismeansthatthe DeveloperwillnotcorrectlydisplayaBigDecimaldatatyperesultandyoucannotentera valueofthisdatatype.However,theJDBCAdapterwillprocesstheBigDecimaldatatype correctly. JDBC Data Type BIT TINYINT Java Data Type java.lang.Boolean java.lang.String java.lang.Byte java.lang.Integer java.lang.String java.lang.Short java.lang.Integer java.lang.String java.lang.Integer java.lang.String java.lang.Long java.lang.String
SMALLINT
INTEGER BIGINT
170
JDBC Data Type to Java Data Type Mappings
JDBC Data Type FLOAT REAL BOOLEAN DOUBLE NUMERIC DECIMAL CHAR VARCHAR LONGVARCHAR DATE TIME
Java Data Type java.lang.Double java.lang.String java.lang.Float java.lang.String java.lang.Boolean java.lang.String java.lang.Double java.lang.String java.math.BigDecimal java.lang.String java.math.BigDecimal java.lang.String java.lang.String java.lang.Character java.lang.String java.lang.String java.sql.Date java.util.Date java.sql.Time java.util.Date java.lang.String java.sql.Timestamp java.util.Date java.lang.String bytearray(byte[]) bytearray(byte[]) bytearray(byte[]) java.sql.CLOB java.lang.String java.sql.BLOB bytearray java.lang.Object java.lang.String
TIMESTAMP
BINARY VARBINARY LONGVARBINARY *CLOB *BLOB OTHER
171
A P P E N D I X A D a t a Ty p e M a p p i n g
Note: IfyouplantouseCLOBsorBLOBsthatexceed4KB,besuretouseanOracleOCI driverorOracle10gThindriver.
JDBC Data Type to Java Data Type Mapping Constraints

TheIntegrationServerhassomeconstraintswhenmappingJDBCdatatypestoJavadata types. IfyouselectoneofthefollowingJavadatatypes,thedatatypewillmapexactlytothe Input/OutputtabintheDeveloper: java.lang.String java.lang.Byte java.lang.Boolean java.lang.Character java.lang.Double java.lang.Float java.lang.Integer java.lang.Long java.lang.Short java.util.Date java.math.BigDecimal java.math.BigInteger java.lang.Object Thosedatatypesnotincludedinthislistwillmaptojava.lang.Object.Inthesecases,ifthe JDBCdatatypeyouspecifyisforinput,youwillneedtopassintheobjectwiththe selectedJavadatatype.IftheJDBCtypeisforoutput,youcancasttheobjecttothe selectedJavadatatype.
SQL Data Type to JDBC Data Type Mappings

ForthemappingsfromSQLdatatypestoJDBCdatatypes,seeyourvendors specifications.
172
APPENDIX
Built-In Transaction Management Services

Transaction Management Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 pub.art.transaction:commitTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 pub.art.transaction:rollbackTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 pub.art.transaction:setTransactionTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 pub.art.transaction:startTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 Changing the Integration Server Transaction Timeout Interval . . . . . . . . . . . . . . . . . . . . . . 186
173
A P P E N D I X B B u i l t - I n Tr a n s a c t i o n M a n a g e m e n t S e r v i c e s
Transaction Management Overview

Thisappendixprovidesanoverviewandexamplesofusingtransactions.Itdescribeshow theIntegrationServersupportsthebuiltinservicesusedtomanageexplicittransactions foryourJDBCAdapterservicesintheWmARTpackage.SeeBuiltInTransaction ManagementServicesonpage 183fordescriptionsofeachofthespecificbuiltin transactionmanagementservicesthatcanbeusedwiththeWmARTpackage. ForinformationaboutotherbuiltinservicesavailablewiththeJDBCAdapter,seethe webMethodsIntegrationServerBuiltInServicesReference,whichisavailablefromtheHelp menuofthewebMethodsDeveloper.
Transactions
TheIntegrationServerconsidersatransactiontobeoneormoreinteractionswithoneor moreresourcesthataretreatedasasinglelogicalunitofwork.Theinteractionswithina transactionareeitherallcommittedorallrolledback.Forexample,ifatransaction includesmultipledatabaseinserts,andoneormoreinsertsfail,allinsertsarerolledback.
Transaction Types
TheIntegrationServersupportsthefollowingkindsoftransactions: Alocaltransaction(LOCAL_TRANSACTION)whichisatransactiontoaresources localtransactionmechanism AnXAResourcetransaction(XA_TRANSACTION)whichisatransactiontoa resourcesXAResourcetransactionmechanism TheIntegrationServercanautomaticallymanagebothkindsoftransactions,without requiringtheadapterusertodoanything.TheIntegrationServerusesacontainer managed(implicit)transactionmanagementapproachbasedontheJ2EECA specification,andalsoperformssomeadditionalconnectionmanagement.Thisisbecause adapterservicesuseconnectionstocreatetransactions.Formoreinformationabout implicittransactions,seeImplicitandExplicitTransactionsonpage 175. However,therearecaseswhereadapterusersneedtoexplicitlycontrolthetransactional unitsofwork.ExamplesofthesecasesareprovidedinImplicitandExplicit Transactionsonpage 175. Tosupporttransactions,theIntegrationServerreliesonabuiltinJ2EEbasedTransaction Manager.TheTransactionManagerisresponsibleforbeginningandendingtransactions, maintainingatransactioncontext,enlistingnewlyconnectedresourcesintoexisting transactions,andensuringthatlocalandXAResourcetransactionsarenotcombinedin illegalways.
174
Note: TheTransactionManageronlymanagesoperationsperformedbyadapterservices. Otherkindsofservicesarebeyonditscontrol. Important! Youcannotsteportraceaflowthatcontainsatransactedadapterservice.
XA Transactions
IfanXAtransactionalconnectionthrowsanexceptionduringaservicetransactionand theexceptionresultsinaninconsistentstate,youmayneedtoresolvethetransaction usingthetoolsprovidedwiththedatabase. ForinformationaboutusingtheIntegrationServertomanageXAtransactions,seethe webMethodsIntegrationServerAdministratorsGuide.
Implicit and Explicit Transactions

ImplicittransactionsareautomaticallyhandledbytheIntegrationServertransaction manager.Whenyoudefineanexplicittransaction,youdefinethestartoncompletion boundariesofthetransaction.Assuch,implicitandexplicittransactionsneedtobe createdandmanageddifferently. Thefollowingsectionsdescribeimplicitandexplicittransactionsandhowtomanage them.
Implicit Transactions
Withimplicittransactions,theIntegrationServerautomaticallymanagesbothlocaland XAResourcetransactionswithoutrequiringyoutoexplicitlydoanything.Thatis,the IntegrationServerstartsandcompletesanimplicittransactionwithnoadditionalservice callsrequiredbytheadapteruser. Atransactioncontext,whichthetransactionmanagerusestodefineaunitofwork,starts whenanadapterserviceisencounteredinaflowexecution.Theconnectionrequiredby theadapterserviceisregisteredwiththenewlycreatedcontextandusedbytheadapter service.Ifanotheradapterserviceisencountered,thetransactioncontextissearchedto seeiftheconnectionisalreadyregistered.Iftheconnectionisalreadyregistered,the adapterserviceusesthisconnection.Iftheconnectionisnotregistered,anewconnection instanceisretrievedandregisteredwiththetransaction. Notethatifthetoplevelflowinvokesanotherflow,adapterservicesinthechildflowuse thesametransactioncontext. Whenthetoplevelflowcompletes,thetransactioniscompletedandiseithercommitted orrolledback,dependingonthestatus(successorfailure)ofthetoplevelflow. AsingletransactioncontextcancontainanynumberofXA_TRANSACTIONconnections butnomorethanoneLOCAL_TRANSACTIONconnection.Ifyourflowcontainsadapter
175
servicesthatusemorethenoneLOCAL_TRANSACTIONconnection,youmustuse explicittransactions,whicharedescribedinthenextsection. SeeImplicitandExplicitTransactionExamplesonpage 177forimplicittransaction examples. Formoreinformationaboutdesigningandusingflows,seethewebMethodsDeveloper UsersGuide. Formoreinformationabouttransactiontypes,seeTransactionManagementofJDBC AdapterConnectionsonpage 15.
Explicit Transactions
Youuseexplicittransactionswhenyouneedtoexplicitlycontrolthetransactionalunitsof work.Todothis,youuseadditionalservices,knownasbuiltinservices,inyourflow. Atransactioncontextstartswhenthepub.art.transaction.startTransaction()serviceisexecuted. Thetransactioncontextiscompletedwheneitherthepub.art.transaction.commitTransaction()or pub.art.transaction.rollbackTransaction()serviceisexecuted.Aswithimplicittransactions,a singletransactioncontextcancontainanynumberofXA_TRANSACTIONconnections butnomorethanoneLOCAL_TRANSACTIONconnection. Note: Withexplicittransactions,youmustbesuretocalleitheracommitTransaction()or rollbackTransaction()foreachstartTransaction();otherwiseyouwillhavedangling transactionsthatwillrequireyoutoreboottheIntegrationServer. Anewexplicittransactioncontextcanbestartedwithinatransactioncontext,provided thatyouensurethatthetransactionswithinthetransactioncontextarecompletedinthe reverseordertheywerestartedthatis,thelasttransactiontostartshouldbethefirst transactiontocomplete,andsoforth. Forexample,considerthefollowingisavalidconstruct:
pub.art.transaction.startTransaction() pub.art.transaction.startTransaction() pub.art.transaction.startTransaction() pub.art.transaction.commitTransaction() pub.art.transaction.commitTransaction() pub.art.transaction.commitTransaction()
Thefollowingexampleshowsaninvalidconstruct:
pub.art.transaction.startTransaction() pub.art.transaction.startTransaction() pub.art.transaction.commitTransaction() pub.art.transaction.commitTransaction()
SeeImplicitandExplicitTransactionExamplesonpage 177forexplicittransaction examples.
176
Formoreinformationaboutdesigningandusingflows,seethewebMethodsDeveloper UsersGuide. Formoreinformationabouttransactiontypes,seeTransactionManagementofJDBC AdapterConnectionsonpage 15.
Implicit and Explicit Transaction Examples

Theexamplesinthissectionusetheconnections,services,andflowsshownbelowand describedinthetablethatfollows.
177
Step
1
Description Youconfiguredthreeconnections: localConn1:LOCAL_TRANSACTIONtype localConn2:LOCAL_TRANSACTIONtype xaConn1:XA_TRANSACTION
Youconfiguredthefollowingadapterserviceswhichusethe LOCAL_TRANSACTIONconnectionslistedinstep1above. InsertLocal1:configuredtouseLocalConn1connection SelectLocal1:configuredtouselocalConn1connection SelectLocal2:configuredtouselocalConn2connection
Youconfiguredthefollowingadapterserviceswhichusethe XA_TRANSACTIONconnectionlistedinstep1above. InsertXA1:usesxaConn1connection SelectXA1:usesxaConn1connection
Youcreatethefollowingflowexamples(describedinthissection)using LOCAL_TRANSACTIONs: SingleLocalInsert(explicittransaction).Seepage 180. ValidDoubleLocal(explicittransaction).Seepage 182.
Youcreatethefollowingflowexamples(describedinthissection)using bothXA_TRANSACTIONsandLOCAL_TRANSACTIONs: ValidMixed(implicittransaction).Seepage 179. ValidMixed2(implicit/explicittransaction).Seepage 181.
178
Flow Example: ValidMixed

ThisexamplesshowsanImplicitTransaction. Thisflowcalls: OneserviceusinganXA_TRANSACTIONconnection(InsertXA1service) OneserviceusingaLOCAL_TRANSACTIONconnection(SelectLocal2service)
Adapter service using an XA_TRANSACTION connection Adapter service using a LOCAL_TRANSACTION connection
179
Flow Example: SingleLocalInsert

ThisexamplesshowsanExplicitTransaction. Thisflowcallsoneadapterservice(InsertLocal1)usingaLOCAL_TRANSACTION connection. Thisexampledemonstratesthecorrectwaytosetupyourflowtouseanexplicit transaction.YouusethefollowingconstructofthreeSEQUENCEs,whichisrequiredto insurethattheexplicittransactioniseithercommitted(onsuccess)orrolledback(on failure).
1 2
Step
1 2 3
Description ThetoplevelSEQUENCEwillexitonsuccess. Thetransactionwillbecommittedifsuccessful,andthetoplevel SEQUENCEwillcomplete. ThisSEQUENCEisenteredonlyifthepreviousSEQUENCEis unsuccessful.Thetransactionisrolledbackandtheflowexitswithastatus offailure.
Notethatwiththisconstruct,youwillnotgettriggerretriesoraretryableexception.The EXITstatementwillresultingeneratingaFlowexceptionwhichisnotretryable.Toget retries,youwillneedtouseaREPEATstepstatementinyourflow.Forinformationabout usingtheREPEATstatement,seethewebMethodsDeveloperUsersGuide.
180
Flow Example: ValidMixed2

ThisexamplesshowsbothanImplicitandExplicitTransaction. Thisflowcalls: Oneadapterservice(InsertXA1)usinganXA_TRANSACTIONconnection Oneflow(SingleLocalInsertshowninthelastexampleonpage 180)which containsitsownexplicittransactionsandusingaLOCAL_TRANSACTION connection(localConn2) Oneadapterservice(SelectLocal2)usingthesameLOCAL_TRANSACTION connection(localConn2)astheSingleLocalInsertflow Inthisexample,InsertXA1andSelectLocal2areregisteredaspartoftheimplicit transaction.SingleLocalInsertispartofitsownexplicittransaction.Theexplicit transactionisrequiredsinceyouareusingtwodifferentlocaltransactionconnections (localConn1andlocalConn2).
Adapter service using the XA_TRANSACTION connection xaCONN1 Flow using the LOCAL_TRANSACTION connection localConn1 Adapter service using the LOCAL_TRANSACTION connection localConn2
181
Flow Example: ValidDoubleLocal

ThisexampleshowsanExplicittransaction. Thisflowcalls: Aflow(SingleLocalInsert)whichusestheLOCAL_TRANSACTIONconnection localConn1 Anadapterservice(SelectLocal2)whichusestheLOCAL_TRANSACTION connectionlocalConn2 Thisflowshowsanexplicittransactionresidingwithinanotherexplicittransaction.The flowcallsaflowandanadapterservicewhichusedifferentLOCAL_TRANSACTION connections.Recallthatyoumustuseanexplicittransactionifyouhavemorethanone LOCAL_TRANSACTIONconnection. NoticethattheflowissimilartotheSingleLocalInsertflowexampleonpage 180,which usesaflowconstructinvolvingthreeSEQUENCEstoinsurethattheexplicittransactionis eithercommitted(onsuccess)orrolledback(onfailure).
1 2
Step
1 2 3
Description ThetoplevelSEQUENCEwillexitonsuccess. Thetransactionwillbecommittedifsuccessful,andthetoplevel SEQUENCEwillcomplete. ThisSEQUENCEisenteredonlyifthepreviousSEQUENCEis unsuccessful.Thetransactionisrolledbackandtheflowexitswithastatus offailure.
182

ThefollowingsectionsdescribeeachofthebuiltinservicesyoucanusewiththewmART package.
pub.art.transaction:commitTransaction
Thisservicecommitsanexplicittransaction.Itmustbeusedinconjunctionwiththe pub.art.transaction:startTransactionservice.Ifitdoesnothaveacorresponding pub.art.transaction:startTransactionservice,yourflowservicewillreceivearuntimeerror. SeeTransactionManagementOverviewonpage 174formoreinformationabout implicitandexplicittransactions. Input Parameters commitTransactionInput transactionName Document. Adocumentthatcontainsthevariable transactionName,describedbelow. String. Usedtoassociateanamewithanexplicittransaction. ThetransactionNamemustcorrespondtothetransactionName inanypub.art.transaction:startTransactionor pub.art.transaction:rollbackTransactionservicesassociatedwiththe explicittransaction. Thisvaluemustbemappedfromthemostrecent pub.art.transaction:startTransactionthathasnotpreviouslybeen committedorrolledback. Output Parameters None.
183
pub.art.transaction:rollbackTransaction
Thisservicerollsbackanexplicittransaction.Itmustbeusedinconjunctionwiththe pub.art.transaction:startTransactionservice.Ifitdoesnothaveacorresponding pub.art.transaction:startTransactionservice,yourflowservicewillreceivearuntimeerror. SeeTransactionManagementOverviewonpage 174formoreinformationabout implicitandexplicittransactions. Input Parameters rollbackTransactionInput transactionName Document.Adocumentthatcontainsthevariable transactionName,describedbelow. String.Usedtoassociateanamewithanexplicittransaction. ThetransactionNamemustcorrespondtothetransactionName inanypub.art.transaction:startTransactionor pub.art.transaction:commitTransactionservicesassociatedwiththe explicittransaction. Thisvaluemustbemappedfromthemostrecent pub.art.transaction:startTransactionthathasnotpreviouslybeen committedorrolledback. Output Parameters None.
pub.art.transaction:setTransactionTimeout
Thisserviceenablesyoutomanuallysetatransactiontimeoutintervalforimplicitand explicittransactions.Whenyouusethisservice,youaretemporarilyoverridingthe IntegrationServertransactiontimeoutinterval.SeeChangingtheIntegrationServer TransactionTimeoutIntervalonpage 186tochangetheserversdefaulttransaction timeout. Youmustcallthisservicewithinaflowbeforethestartofanyimplicitorexplicit transactions.Implicittransactionsstartwhenyoucallanadapterserviceinaflow.Explicit transactionsstartwhenyoucallthepub.art.transaction:startTransactionservice. Iftheexecutionofatransactiontakeslongerthanthetransactiontimeoutinterval,all transactedoperationsarerolledback. Thisserviceonlyoverridesthetransactiontimeoutintervalfortheflowserviceinwhich youcallit.
184
Input Parameters timeoutSeconds IntegerThenumberofsecondsthattheimplicitorexplicit transactionstaysopenbeforethetransactionmanagermarksitfor rollback.
Output Parameters None.
pub.art.transaction:startTransaction
Thisservicestartsanexplicittransaction.Itmustbeusedinconjunctionwitheithera pub.art.transaction:commitTransactionserviceorpub.art.transaction:rollbackTransactionservice.Ifit doesnothaveacorrespondingpub.art.transaction:commitTransactionserviceor pub.art.transaction:rollbackTransactionservice,yourflowservicewillreceivearuntimeerror. SeeTransactionManagementOverviewonpage 174formoreinformationabout implicitandexplicittransactions. Input Parameters startTransactionInput transactionName Document.Adocumentthatcontainsthevariable transactionName,describedbelow. String.Specifiesthenameofthetransactiontobestarted.This parameterisoptional.Ifyouleavethisparameterblank,the IntegrationServerwillgenerateanameforyou.Inmost implementations,itisnotnecessarytoprovideyourown transactionnameasinput.
Output Parameters startTransactionOutput transactionName Document.Adocumentthatcontainsthevariable transactionName,describedbelow. String.Thenameofthetransactiontheservicejuststarted.
185
Changing the Integration Server Transaction Timeout Interval

TheIntegrationServerdefaulttransactiontimeoutisnotimeout(NO_TIMEOUT).To changetheserverstransactiontimeoutinterval,useatexteditortomodifytheserver.cnf fileandaddtheparameterbelow.Notethatthisparameterdoesnotexistbydefaultinthe server.cnffile;youmustaddittothefileasdescribedbelow. BesuretoshutdowntheIntegrationServerbeforeyoueditthisfile.Afteryoumake changes,restarttheserver. Addthefollowingparametertotheserver.cnffile:
watt.art.tmgr.timeout=TransactionTimeout
whereTransactionTimeoutisthenumberofsecondsbeforetransactiontimeout. Thistransactiontimeoutparameterdoesnothalttheexecutionofaflow;itisthe maximumnumberofsecondsthatatransactioncanremainopenandstillbeconsidered valid.Forexample,ifyourcurrenttransactionhasatimeoutvalueof60secondsandyour flowtakes120secondstocomplete,thetransactionmanagerwillrollbackallregistered operationsregardlessoftheexecutionstatus. SeethewebMethodsIntegrationServerAdministratorsGuideformoreinformationabout addingparameterstotheserver.cnffile.
186
APPENDIX
Database Driver Known Limitations

Driver Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
187
APPENDIX C Database Driver Known Limitations
Driver Limitations
Thisappendixprovidesahighlevellistoflimitationsandissues.Foradditionaldetails, refertoyourvendordocumentation. Database/Adapter IS Operating System/Platform Affected UDB7.2
Driver DataDirect Connectfor JDBC3.2
Limitation Description ThisdriverversiondoesnotsupporttheBLOBdata types.Ifyoutrytoselectdatafromatablethathas BLOBdatatypes,youwillreceivethefollowing message:

[DataDirect][DB2 JDBC Driver][DB2]AN UNSUPPORTED SQLTYPE WAS ENCOUNTERED IN POSITION 2 ON A PREPARE OR DESCRIBE OPERATION
NotethatthisdriverdoessupportBLOBdatatypes usingOS/390orDB2iSeriesV5R2. UDB7.2 UDB7.2 DriverdoesnotsupportXA_TRANSACTIONSusing JavaTransactionAPI(JTA).Instead,useUDB8.1. CannotinsertintoaBLOBcolumntypeifyouusebyte arrayastheInputFieldType.Theworkaroundistouse theIBMdrivers(DB2apptype2orDB2nettype3). CannotusetheCLOBdatatypeintheOUTparameterin StoredProcedureservices.Doingsothrows [DataDirect][DB2JDBCDriver][DB2]DATA TYPE/LENGTH/VALUEOFARGUMENT1OF CLOBSP1ISINVALID. TheCallableStatement.getClob()doesnotwork;instead, usetheIBMdriverversions(DB2apptype2orDB2net type3). UDB7.2andUDB8.1 CannotrunaStoredProcedureserviceusingBLOBand CLOBdatatypes(java.sql.Bloborjava.sql.Clob)asthe INparameter.Instead,useanIBMdriver(DB2apptype 2orDB2nettype3)withUDB8.1toworkwithIN, OUT LOBparameters.
UDB7.2andUDB8.1
188
Driver Limitations
Driver DB2JDBCapp (type2)
Database/Adapter IS Operating System/Platform Affected AIX5.1 Linux UDBDB28.1/SunSolaris
Limitation Description CannotenableXA_TRANSACTIONconnections. CannotcreateXA_TRANSACTIONconnections. CannotrunaSelectSQLadapterservicewithtablenames thatusespecialcharacters.Notethatyoucandosoif youuseaMicroSoftWindowsNToperatingsystemand aJDBCapp(type2)driver. IfaStoredProcedureNotificationhasbeenenabledfor longperiodsoftime,thefollowingmessageisposted:
[IBM][CLI Driver][DB2/SUN] SQL1131N DARI (Stored Procedure) process has been terminated abnormally is posted. SQLSTATE=38503
UDBDB27.2
UDB8.1
Noerrormessageisissuedwheninsertingastringthat islargerthanthesizeofthecolumndefinedfor CHAR(N)orVARCHAR(N). TheIntegrationServercrashesifthedatabaseisshut downwhileexecutinganInsertSQLadapterserviceusing anXA_TRANSACTIONconnection. ThisdriverdoesnotsupportXA_TRANSACTION.Use theUniversalType2driverifyouneed XA_TRANSACTIONsupport. WhitespacecharactersarenotremovedfromSQL StatementsenteredintheSQLtextboxforCustomSQL orDynamicSQLservices.ThisdriverpassestheSQL statementstotheserverexactlyasentered.Besurethe SQLyouenterhasnoextraneouswhitespacecharacters, suchasnewlinesortabs.
UDB8.1onAIX5.1
DB2Universal type4
UDB8.1
DB2onOS/3906and7
Insert,Delete,Update,Basic,andOrderedNotifications cannotbeenabledifthesourcetablecontainsCHAR, VARCHAR,orLONGVARCHARcolumns.
189
Driver DB2JDBCnet (Type3)
Database/Adapter IS Operating System/Platform Affected DB27onOS/390 DB27.2onOS/390
Limitation Description Ifyouattempttoinsert20kormorerecords,eitherthe systemwilldeadlockoryouwillreceiveatimeouterror. WhenconfiguringaJDBCAdapternotificationin Developer(File>New>Adapter Notification),theBase Name youspecifyontheNotification Configuretabmustbeno morethan5charactersbecausetriggersonOS/390name cannotbemorethan8characters. UsingaSelectSQLservice,youcannotselectalarge volumeofdata(20k)usingtheCLOBdatatype. ThedriverdoesnotwritetotheJDBClog,evenwhen thelogoptionisenabled.Theworkaroundistocreatean emptylogfile.Todothis,usetheIntegrationServer AdministratorandselectSettings>Extended>Edit Extended Settingsandtype:
watt.adapter.JDBC.JDBCLogFile= c:\log.txt
DB2onOS/390 UDB7.2
UDB7.2
IfyourunaBatchUpdateSQLservicethathasnorecords thatmatchyoursearchcriteria,youwillreceivean error;youmusthaveatleastonerecordthatmatchesthe criteriatoexecutesuccessfully. Noerrormessageisissuedwheninsertingastringthat islargerthanthesizeofthecolumndefinedfor CHAR(N)orVARCHAR(N). Thisdriverdoesnotsupportmultipleresultssets.Ifyou configuretheadaptertousemultipleresultsets,all resultrowswillbestoredinthefirstResultSetyou specifiedwhenyouconfiguredtheadapter. WithInformix9.3and9.4usingXA_TRANSACTION, youcannotupdateLONGVARCHARdatatypecolumns withanullvalue. WithInformix9.3and9.4usingXA_TRANSACTION, youcannotupdateBOOLEANdatatypecolumnswitha NOTNULLvalue.
UDB8.1
InformixDriver forJDBCVersion 2.21type4
Informix7.31and9.x
Informix7.31and9.x
Informix7.31and9.x
190
Driver Limitations
Driver jCONNECT5.5 type4
Database/Adapter IS Operating System/Platform Affected Sybase11.xand12.x
Limitation Description ASybasecolumnusingaBITdatatypedoesnotallow NULLvaluesduetodriverbehavior.Thismeansthatif youinsertaNULLor?(variable)valuewhenyourunan InsertSQLservice,thedriverconvertsthiscolumnvalue tofalseandinsertstheNULLvalueforthecolumninto thedatabase. Storedproceduressupportonlyoneresultset.
OracleJDBC Drivers(Oracle JDBCThinand Oracle JDBC/OCI)
AllsupportedOracle databases Oracle8.0.5
TheNUMBERandNUMBER(n,m)Oracledatatypes maptojava.math.BigDecimalinallJDBCAdapter servicesbydefault. Whenmappingadatedatatypetojava.util.Dateusing theInsertSQLadapterservice,youreceiveanORA1024 InvaliddatatypeinOCIcallexception.Asa workaround,mapthedatetojava.sql.Timestamp. BesuretoapplytheHPUX11iQualityPack(June2002) andthePHSS_26138onHPUX11ibeforeconfiguring theJDBCAdapterconnectionusinganOCIdriver; otherwise,itthrowsanUnresolvedsymbol:gethrtime (code)error. WhenconnectingtoanOracle8.0.5serverusingtheOCI driverandtryingtoInsertBLOBandCLOBdatatypes, youreceiveaORA01461:canbindaLONGvalueonly forinsertintoaLONGcolumn.error. Ifalladapternotificationsareenabledformorethan 18 hours,youreceivetheerror:
OCI-21503: program terminated by fatal error OCI-04030: out of process memory when trying to allocate 20056 bytes.
HPUX11i
Oracle8.0.5
HPUX
Allsupporteddatabases
BLOBandCLOBdatatypescannotbeusedinatable definitionwhenconfiguringJDBCAdapter notifications. Youmustsetanenvironmentvariablebeforeyoucan configureconnections.SeeSettingtheEnvironment VariableforOracleJDBCOCIDriversonpage 67for details. BLOB/CLOBdatatypeobjectsarelimitedto4KB.For largerBLOB/CLOBobjects,usetheOracleJDBC/OCI driverorOracle10gThindriver.
OracleJDBCOCI Driver
OracleJDBC ThinDriver
191
Driver SQLServer2000 DriverforJDBC Version2.2.0019
Database/Adapter IS Operating System/Platform Affected MicrosoftSQLServer2000
Limitation Description WhenrunningtheSelectSQLadapterserviceusing thenotnullrealtype,theValuecannotbe convertedtorequestedtypeerroristhrown.Thisis adriverissueforboththeDataDirectConnectfor JDBCandtheMicrosoftSQLServer2000Driverfor JDBC. Thisdriverdoesnotsupportretrievingtablenames fromadatabasewhenthedatabasesnamecontains specialcharacters. ThisdrivermusthaveSunsJDK1.3package javax.sql.*intheIntegrationServerCLASSPATH beforeyoucanenabletheadapterconnection.Ifthis packageismissing,theadapterthrowstheerror messageunabletoconfigureconnectionmanger javax/sql/DataSource.Onesolutionistocopythe adaptersjdbcxsql.zipfile,whichislocatedinthe IntegrationServer_directory\packages\ WmJDBCAdapter\code\jarsdirectory,tothe IntegrationServer_directory\lib\jarsdirectory,placing therequiredfilesinalocationwheretheIntegration ServercanincludetheminitsCLASSPATH.
SQLServer2005 DriverforJDBC Version 1.0.809.102
MicrosoftSQLServer2005
ThisdriverreturnsincorrectdatatypeTEXT, IMAGE,andNTEXTforMSSQLdatatypes VARCHAR(max),VARBINARY(max)and NVARCHAR(max)respectively. ThisdriverreturnsinvalidJDBCdatatypeforMS SQLUNIQUEIDENTIFIERdatatype.
TeradataV2R5 (Type4)
Allsupporteddatabases.
Thisdriverdoesnotsupportthefollowingservicesand notifications: BatchInsertSQLorBatchUpdateSQLservices InsertNotifications,UpdateNotifications,DeleteNotifications, andOrderedNotifications
Ifyouusethe@characterinatableorcolumnname, youwillreceivethefollowingsyntaxerror:
Expected something between the word 'SP$CHAR#TABLE' and '@'." while using in Insert service on Teradata.
192
APPENDIX
Determining Whether to Use the WmDB Package or the JDBC Adapter

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 When to Use the WmDB Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 When to Use the webMethods JDBC Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
193
APPENDIX D Determining Whether to Use the WmDB Package or the JDBC Adapter
Overview
webMethodsprovidestwomethodsforaccessingdatabases: WmDB packagetouseforprototyping,design,ortemporarydatabaseaccess. webMethods JDBC Adaptertouseforallenterprise,missioncriticalapplications. ThisappendixdescribesusecasestohelpyoudeterminewhentousetheWmDBpackage andwhentousethewebMethodsJDBCAdapter.
When to Use the WmDB Package

ThefollowinglistsusecaseswhereitwouldbebettertousetheWmDBpackagerather thantheJDBCAdapter.UsetheWmDBpackagewhen: YouneedimmediateresultsfromtheexecutionofaSQLquery.TheWmDBpackage allowsyoutorunquickSQLqueriesdirectlyfromtheIntegrationServer AdministratororDSPpages. Youhaveaneedforadhocintrospectionofdatabaseobjects,suchastables,views, aliases,synonyms,orstoredprocedures. Youwanttocustomizemanagementofthedatabaseconnectionpool. Youhavealimitednumberoftasksthatneedtoaccessadatabase. Youarerequiredtointegratewithaproprietaryoranonmainstreamdatabase,and youwanttoperformaquick,easycompatibilitytestbeforeexploringan implementationthatusestheJDBCAdapter.TheJDBCAdaptersupportsallJDBC compliantdatabaseimplementationsandiscertifiedonspecificmainstream databases. Youaredevelopingathrowawaytestscenario.
When to Use the webMethods JDBC Adapter

YouwillwanttousetheJDBCAdapterinmostcases.Thefollowinglistsusecasesthat describethetypesofsituationswhenyoushouldusetheJDBCAdapterratherthanthe WmDBpackage: Yoursystemislikelytobeexpandedandmodernized.Thisistypicalforenterprise, missioncriticalapplications. Yourequirebetterdatabaseperformance.TheperformanceoftheJDBCAdapteris superiortothatoftheWmDBpackage,particularlyforbatchoperations.Forexample, toinsertdataintoadatabaseusingtheWmDBpackageyouusethepub.db:insert service;yousupplytheitemstoinsertusingadocumentlistasinput,andthe
194
When to Use the webMethods JDBC Adapter
pub.db:insertserviceprocesseseachiteminthedocumentlistsequentiallywithout usingJDBCstandardfacilities. Yourequireorplantousenotificationfeatures. Youneedautomaticandefficientdatabaseconnectionpoolmanagement. YourequireXAtransactionality. YouneedtouseJDBCstandarddatatypes,includingBLOBandCLOB. Youneedtobeabletoconfigureservicesratherthanhardcodethem. Youneedtouserolebasedsecurity.TheJDBCAdapterallowstheseparationofthe databaseadministratoranddevelopmentenvironmentsasneeded.TheWmDB packagerequiresAdministratorprivileges. Youwantaconfigurableandstructureduserinterface.TheJDBCAdapteruses templatebasedconfigurationthatismorestructuredandeasiertouse.TheJDBC Adapterusesmetadatathathelpsprotecttheusersinvestmenteveniftechnology changes. YouwanttomanageyourdatabaseconnectionusingwebMethodsManager.
195
APPENDIX D Determining Whether to Use the WmDB Package or the JDBC Adapter
196
Index
Index
Symbols
$connectionName (service input field) 81 pub.art.transaction:rollbackTransaction 184 pub.art.transaction:setTransactionTimeout 184 pub.art.transaction:startTransaction 185
A
Access Control Lists (ACLs), assigning 49 adapter connections. See connections. adapter notifications. See notifications. adapter services built-in service for 19 testing changing Developer to the Test perspective 43 validating data, setting option 121, 155 adapter services. See services. AdapterConnectionException 160 AdapterException 159 architectural overview 11 Automatic data validation icon 121, 155 Automatic polling of adapter metadata option 121, 155
C
classes (Java), providing access to Integration Server 67 CLOB/BLOB OCI driver usage requirement 14, 172 Oracle 10g driver usage requirement 14, 172 clock drift 60 clustering benefits 49 cluster store 49 connection pooling enabled 63 defined 49 description 49 failover support 50 load balancing 50 notification support 50 polling notifications 54 replicating packages in clustered environment 61 requirements 62 scalability 50 clusterProperties.cnf file 56, 57 commit transaction service 183 connections built-in services for 16 changing at design time 19 changing at runtime 20, 81 copying 83 defined 13 deleting 84 preventing use of 84 transaction management overview 15 conventions used in this document 7 CustomSQL adapter service, configuring 109
B
BasicNotifications configuring 138 defined 28 BatchInsertSQL adapter service, configuring 99 BatchUpdateSQL adapter service, configuring 102 BigDecimal data type, use in Developer 128, 132, 137, 140, 143, 147, 170 BLOB/CLOB OCI driver usage requirement 14, 172 Oracle 10 driver usage 14, 172 buffer tables and exported notifications 153 retrieving data from 128, 133, 137 used by notifications 24, 28, 35 built-in services for adapter services 19 for connections 16 pub.art.transaction:commitTransaction 183
D
data type mappings
197
Index
constraints (JDBC Type to Java Type) 172 JDBC data type to Java data type 170 SQL data type to JDBC data type 172 database TableFilter property setting 73 databases supported DB2 for AS/400 10 DB2 for OS/390 10 DB2 Universal Database (UDB) 10 IBM Informix 10 Microsoft SQL Server 10 Oracle 10 Sybase 10 Teradata 10 DataSource class, when to use 14 DB2 for AS/400 10 DB2 for OS/390 10 DB2 Universal Database (UDB) 10 DeleteNotification, configuring 134 DeleteSQL adapter service, configuring 106 deleting connections 84 notifications 154 services 120 dependencies, package 47 disabling insert, update, or delete notifications 154 redirection of administrative services in clustered environment 62 Distributed mode 55 documentation additional 8 conventions used 7 feedback 8 drivers database connection management 14 DataSource or XADataSource class 70 defined 17 installing on the Integration Server 67 limitations 188 requirements 11 dynamic connections and services 20, 81 DynamicSQL adapter service, configuring 111, 115
E
enabling packages 48 environment variable for Oracle JDBC OCI drivers 67 error code list, customizing 160 Exactly Once notification feature 24, 152 exceptions for JDBC Adapter AdapterConnectionException 160 AdapterException 159, 160 explicit transaction management services 176 exporting configured adapter notifications 153 packages, renaming disallowed 49
F
fatal error code list, customizing 160 files (specific) clusterProperties.cnf 56, 57 flat files, specifying the input field types 101, 104
G
group access control, assigning 49
I
IBM Informix database support 10 implicit transaction management services 175 InsertNotification, configuring 125 InsertSQL adapter service, configuring 89, 92
J
Java classes, providing access to Integration Server 67 JDBC data type to Java data type data type mappings 170 JDBC OCI driver for Oracle, setting environment variables 67 jdbcxsql.zip file 192
L
limitations drivers 188 Suspended state 42 LOCAL_TRANSACTION transaction type defined 15
198
Index
support for notifications 15 logging messages for JDBC Adapter 158
M
Manager (webMethods), using with JDBC Adapter 43 mapping data types constraints 172 JDBC data type to Java data type 170 SQL data type to JDBC data type 172 message logging for JDBC Adapter 158 Microsoft SQL Server 10 modes for polling notifications 55
N
namespace node packages package dependencies 47 NO_TRANSACTION transaction type, defined 15 notifications BasicNotification 138 cluster support 50 clustering supported 54 defined 22 DeleteNotification 134 InsertNotification 125 OrderedNotification 145 states, setting 151 StoredProcedureNotification 142 templates, defined 23 UpdateNotification 129
enabling and disabling 48 renaming when exporting (disallowed) 49 replicating in clustered environment 61 perspectives, in Developer Details 43 Edit 43 Test 43 polling notifications clusters, executing within 54 managing 149 scheduling 151 states 41 preventing use of connections 84 program code conventions in this document 7 pub.art.transaction:commitTransaction 183 pub.art.transaction:rollbackTransaction 184 pub.art.transaction:setTransactionTimeout 184 pub.art.transaction:startTransaction 185
R
Reload values from the adapter icon 121 replicating packages in a clustered environment 61 rollback transaction service 184
S
scheduling polling notifications 151 services BatchInsertSQL 99 BatchUpdateSQL 102 commitTransaction 183 CustomSQL 109 defined 17 DeleteSQL 106 dynamic connections 20, 81 DynamicSQL 111, 115 InsertSQL 92 Reload values from the adapter 121 Reload values from the adapter icon 121 rollbackTransaction 184 SelectSQL 89 SetTransactionTimeout 184 startTransaction 185
O
OCI driver requirements with CLOB/BLOB 14, 172 setting environment variables 67 Oracle 10g driver requirements with CLOB/BLOB 14, 172 Oracle database supported 10 Oracle RAC TAF facility, local transaction support 69 OrderedNotification, configuring 145
P
packages
199
Index
StoredProcedure 115 templates, define 17 UpdateSQL 95 services, built-in see built-in services set transaction timeout service 184 setAdapterServiceNodeConnection service 19 SQL data type to JDBC data type mappings 172 SQLException 160 Standby mode 55 start transaction service 185 states and polling notifications 41 StoredProcedure service, configuring 115 StoredProcedureNotification configuring 142 defined 31 Suspended state limitations 42 overview 41 Sybase database support 10
avoiding loss of 49 Stored Procedure Notification 32 used by notifications 24, 28, 35 troubleshooting information 8 typographical conventions in this document 7
U
UpdateNotification, configuring 129 updates applied to the adapter 44 UpdateSQL adapter service, configuring 95 user-defined data types 170
V
Validate service/notification values icon 121, 155 viewing notifications 153 services 119
W
webMethods Manager, using with JDBC Adapter 43 WmDB package 194
T
TableFilter property setting 73 Teradata database support 10 testing adapter services changing Developer to the Test perspective, in Developer 43 testing services 119 transaction management services examples 177 explicit 176 implicit 175 transaction support implicit transaction usage cases 174 local transactions 174 XAResource transactions 174 transaction timeouts, setting 184 transaction types LOCAL_TRANSACTION 15 NO_TRANSACTION 15 XA_TRANSACTION 15 triggers and exported noticiations 153
X
XA transactions 175 XA_TRANSACTION transaction type, defined 15 XAResource transactions see transaction support
200

Web Methods JDBC Adapter User&#39;s Guide 6.0.3

Загружено:

Сведения о документе

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Web Methods JDBC Adapter User&#39;s Guide 6.0.3

Загружено:

Авторское право:

Доступные форматы

webMethods JDBC Adapter

Document ID: ADAPTER-JDBC-UG-603-20060704

Chapter 1. Overview of the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 2. Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods JDBC Adapter Users Guide Version 6.0.3

Chapter 3. JDBC Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Chapter 4. Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

webMethods JDBC Adapter Users Guide Version 6.0.3

Chapter 5. Adapter Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Chapter 6. Logging and Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

webMethods JDBC Adapter Users Guide Version 6.0.3

Appendix A. Data Type Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Appendix B. Built-In Transaction Management Services . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Appendix C. Database Driver Known Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

webMethods JDBC Adapter Users Guide Version 6.0.3

About This Guide

About This Guide

webMethods JDBC Adapter Users Guide Version 6.0.3

About This Guide

webMethods JDBC Adapter Users Guide Version 6.0.3

Overview of the Adapter

webMethods JDBC Adapter Users Guide Version 6.0.3

CHAPTER 1 Overview of the Adapter

About the JDBC Adapter

webMethods JDBC Adapter Users Guide Version 6.0.3

webMethods JDBC Adapter Users Guide Version 6.0.3

CHAPTER 1 Overview of the Adapter

Thenextdiagramshowsabusinessintegrationwhereanadapterserviceisusedtoupdate adatabasewithemployeedata.Theemployeedatacouldbeprovidedbyseveraldifferent typesofexternalIntegrationServer(IS)clients.

Java, C/C++, VB webMethods Client

Employee ___ ____ ___ I N T E R N E T

webMethods Integration Server ERP System Services

Employee ___ ____ ___

Web browser or webMethods Client

Employee ___ ____ ___

webMethods JDBC Adapter Users Guide Version 6.0.3

webMethods JDBC Adapter Users Guide Version 6.0.3

CHAPTER 1 Overview of the Adapter

Using JDBC Drivers to Connect to Databases

webMethods JDBC Adapter Users Guide Version 6.0.3

Transaction Management of JDBC Adapter Connections

webMethods JDBC Adapter Users Guide Version 6.0.3

CHAPTER 1 Overview of the Adapter

Runtime Behavior of Connection Pools

Built-In Services For Connections

webMethods JDBC Adapter Users Guide Version 6.0.3

Description Retrievesspecifiedinformationfroma databasetable. SeeConfiguringSelectSQLServiceson page 89forinstructions.

Insertsnewinformationintoadatabasetable. SeeConfiguringInsertSQLServiceson page 92forinstructions.

Updatesexistinginformationinadatabase tableandincludesamappingforanoutput fieldthatstoresthenumberofaffectedrows. SeeConfiguringUpdateSQLServiceson page 95forinstructions.

webMethods JDBC Adapter Users Guide Version 6.0.3

CHAPTER 1 Overview of the Adapter

Adapter Service Type BatchInsertSQL

Adapter Service Template BatchInsertSQL

Deletesrowsfromatableandincludesa mappingforanoutputfieldthatstoresthe numberofaffectedrows. SeeConfiguringDeleteSQLServiceson page 106forinstructions.

DefinesandexecutescustomSQLtoperform databaseoperations.Youcanexecutealmost anySQLstatementrequiredbyintegrations, suchasdatamanagementstatements. SeeConfiguringCustomSQLServiceson page 109forinstructions.

DefinesandexecutesaSQLstatement,partof whichyousetatruntimethroughtheinput field. SeeConfiguringDynamicSQLServiceson page 111forinstructions.

Callsastoredproceduretoperformdatabase operations. SeeConfiguringStoredProcedureServices onpage 115forinstructions.

webMethods JDBC Adapter Users Guide Version 6.0.3

Using Adapter Services

Developerand IntegrationServer Administrator

webMethods JDBC Adapter Users Guide Version 6.0.3

CHAPTER 1 Overview of the Adapter

Changing the Connection Associated with an Adapter Service at Runtime

webMethods JDBC Adapter Users Guide Version 6.0.3

Adapter Service Transaction Processing

Web Methods JDBC Adapter User's Guide 6.0.3

Web Methods JDBC Adapter User's Guide 6.0.3

Employee _ _ I N T E R N E T

Employee _ _

Employee _ _