7-1-1 WmDB Users Guide

8/8/2019 7-1-1 WmDB Users Guide

1/38

WmDB User s Guide

Version 7.1.1

January 2008

webMethods

Page


2/38

ThisdocumentappliestowebMethodsIntegrationServerVersion 7.1.1andwebMethodsDeveloperVersion 7.1.1 andtoallsubsequentreleases.

Specificationscontainedhereinaresubjecttochangeandthesechangeswillbereportedinsubsequentreleasenotesorneweditions.

CopyrightSoftwareAG2008.

Allrightsreserved.

ThenameSoftwareAGand/orallSoftwareAGproductnamesareeithertrademarksorregisteredtrademarksofSoftwareAG.Othercompanyandproductnamesmentionedhereinmaybetrademarksoftheirrespectiveowners.

Document ID: IS-WMDB-UG-711-20080128

yrightDocu

tID


3/38

WmDB Users Guide Version 7.1.1 3

Table of Contents

About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Supported Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Database Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1. Configur ing Access to Database Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Supported Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Database Connection Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

About the Server Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Preloading JDBC Drivers at Server Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Making the Java Classes for JDBC Drivers Accessible . . . . . . . . . . . . . . . . . . . . . . . . 10

Identifying Database Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Enabling Database Connection Pooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Updating Information for Database Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Deleting Database Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

2. Accessing Databases with Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Deciding Which Type of Service to Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Creating Database Flow Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Generating a Database Flow Service from a SQL Statement . . . . . . . . . . . . . . . . . . . 20Specifying a Dynamic SQL Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Steps for Generating a Flow Service from a SQL Statement . . . . . . . . . . . . . . . . 22

Generating a Database Flow Service from a Table . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Restricting the List of Database Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Steps for Generating the Flow Service from a Table . . . . . . . . . . . . . . . . . . . . . . 24

Output from the Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Creating Database Services with Java, C/C++, or Visual Basic . . . . . . . . . . . . . . . . . . . . . 26

Built-in Database Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Testing SQL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Creating Clients that Access Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Invoking a Database Service from a Browser-based Client . . . . . . . . . . . . . . . . . . . . . 28

Invoking a Built-in Service from a Java, C/C++, or VB Client . . . . . . . . . . . . . . . . . . . . 29

Sample Code - IData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29


4/38

Table of Contents

4 WmDB Users Guide Version 7.1.1

A. Determin ing Whether to Use the WmDB Package or the JDBC Adapter . . . . . . . . . . . 33

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

When to Use the WmDB Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

When to Use the webMethods JDBC Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37


5/38


About This Guide

ThisguidedescribeshowtousetheWmDBpackagetoaccessadatabase.TheWmDB

packagecontainsservicesandDynamicServerPages(DSPs)thatyoucanusetobuildservicesthatconnecttodatabases.ThewebMethodsIntegrationServercanconnecttodatabasesthroughWmDBflowservices;theseWmDBservicescanthenbeinvokedthroughJava,C/C++,andVisualBasicclients.Thisguideisforuserswhowanttoconnecttodatabasesinthismanner.

Thisguidedescribeshowto:

Configureaccesstodatabasesystemsbysupplyingdatabaseconnectioninformation.

AccessdatabaseswithflowservicesorthroughJava,C/C++,orVisualBasicclients.

Suppor ted DatabasesListedbelowarethedatabasestowhichthewebMethodsIntegrationServercanconnectusingWmDBflowservices.TheIntegrationServersupportsthesedatabasesonallplatformsonwhichthedatabasevendorsupportsthedatabases.

Oracle8iand9.i

SQLServer2000

MSACCESS

MYSQL

DB2

UDB

8.1

Database Drivers

TousetheWmDBpackage,youmustuseavalidtype2JDBCdriveronanoperatingsystemsupportedbythewebMethodsIntegrationServer.

Note: TheWmDBpackageisnotincludedinthemainProgramcomponentof

webMethodsIntegration

Server.

If

you

need

this

package,

be

sure

to

select

WmDB

on

thelistofinstallablecomponentsduringinstallation.

Important! TheWmDBpackagehasbeendeprecated.Whendevelopingnewapplications,usethewebMethodsJDBCAdapterinsteadoftheWmDBpackage.TheJDBCAdapterprovidesmorefunctionality,mayimproveperformance,andsupportsadapternotifications.FormoreinformationabouttheJDBCAdapter,seethewebMethodsJDBCAdapterUsersGuide.

Important! TheWmDBpackagedoesnotsupportSybaseASE12.5.


6/38

About This Guide


Document Conventions

Additional Information

ThewebMethodsAdvantageWebsiteathttp://advantage.webmethods.comprovides

youwith

important

sources

of

information

about

webMethods

products:

Troubleshooting Information.ThewebMethodsKnowledgeBaseprovidestroubleshootinginformationformanywebMethodsproducts.

Documentation Feedback.ToprovidefeedbackonwebMethodsdocumentation,gototheDocumentationFeedbackFormonthewebMethodsBookshelf.

Additional Documentation. Startingwith7.0,youhavetheoptionofdownloadingthedocumentationduringproductinstallationtoasingledirectorycalled_documentation,locatedbydefaultunderthewebMethodsinstallationdirectory.Inaddition,youcanfinddocumentationforallwebMethodsproductsonthewebMethodsBookshelf.

Convention Description

Bold Identifieselementsonascreen.

Italic Identifiesvariableinformationthatyoumustsupplyorchangebasedonyourspecificsituationorenvironment.Identifiestermsthefirsttimetheyaredefinedintext.Alsoidentifiesserviceinputandoutputvariables.

Narrow font IdentifiesstoragelocationsforservicesonthewebMethodsIntegrationServerusingtheconventionfolder.subfolder:service.

Typewriter

fontIdentifiescharactersandvaluesthatyoumusttypeexactlyormessagesthatthesystemdisplaysontheconsole.

UPPERCASE Identifieskeyboardkeys.Keysthatyoumustpresssimultaneously

arejoinedwiththe+symbol.

\ Directorypathsusethe\directorydelimiterunlessthesubjectisUNIXspecific.

[] Optionalkeywordsorvaluesareenclosedin[].Donottypethe[]symbolsinyourowncode.
http://advantage.webmethods.com/http://advantage.webmethods.com/kb_tophttp://advantage.webmethods.com/kb_tophttp://advantage.webmethods.com/kb_tophttp://advantage.webmethods.com/kb_tophttp://advantage.webmethods.com/kb_tophttp://advantage.webmethods.com/kb_tophttp://advantage.webmethods.com/docfeedbackhttp://advantage.webmethods.com/docfeedbackhttp://advantage.webmethods.com/docfeedbackhttp://advantage.webmethods.com/docfeedbackhttp://advantage.webmethods.com/docfeedbackhttp://advantage.webmethods.com/Bookshelfhttp://advantage.webmethods.com/Bookshelfhttp://advantage.webmethods.com/Bookshelfhttp://advantage.webmethods.com/Bookshelfhttp://advantage.webmethods.com/Bookshelfhttp://advantage.webmethods.com/Bookshelfhttp://advantage.webmethods.com/Bookshelfhttp://advantage.webmethods.com/Bookshelfhttp://advantage.webmethods.com/Bookshelfhttp://advantage.webmethods.com/docfeedbackhttp://advantage.webmethods.com/kb_tophttp://advantage.webmethods.com/


7/38


1 Configuring Access to Database Systems

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Database Connection Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

About the Server Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Identifying Database Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Enabling Database Connection Pooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Updating Information for Database Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Deleting Database Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16


8/38



Overview

Beforeaservercanconnecttoadatabase,theservermustfirstreceiveinformationaboutthedatabase.Yousupplydatabaseconnectioninformationbyconfiguringadatabase

alias.Youmustconfiguredatabasealiasesifyouwanttocreatedatabaseflowservices.

Thischapterdescribeswhatadatabasealiasconsistsofandhowtoidentify,update,anddeleteadatabasealiasintheIntegrationServerAdministrator.

Suppor ted Databases

The

webMethods

Integration

Server

can

connect

to

the

following

databases

using

WmDB:

Oracle8iand9i

SQLServer2000

DB2UDB8.1

MSSQL7

MSAccess

WmDBconnectstothesedatabasesusingtheJDBCdriverprovidedbythevendor.

Database Connection Information

Adatabasealiasconsistsofthefollowinginformation:

The type of database and where it is located.JDBCusesaURLnamingschemetolocateandidentifydatabases.EachJDBCdriverrespondstoaslightlydifferentsyntaxfortheseURLs.Consultthedocumentationforthedriveryouareusingfordetails.IfyouareusingtheJDBCODBCbridgedriver,theURLisjdbc:odbc:yourdatasource.

The user name and password required to connect to the database.Ifthedatabaserequiresausernameandpasswordtoconnecttoit,youmustspecifytheserverwiththeuser

nameandpassworditshouldsupply.

The JDBC driver.YouidentifythefullyqualifiedJavaclassnameoftheJDBCdrivertouseforthisconnection(forexample,com.company.jdbc.Driver).Thisclassmustbeintheserversclasspath.

Note: TheWmDBpackageisnotincludedinthemainProgramcomponentofwebMethodsIntegrationServer.Ifyouneedthispackage,besuretoselectWmDBonthelistofinstallablecomponentsduringinstallation.


9/38



Theserverusesthedatabaseconnectioninformationtoconnecttoadatabasewhen:

YouusetheIntegrationServerAdministratortodisplayinformationaboutdatabasetableswhencreatingadatabaseservice(Generatefromtable).Theservermustconnecttothedatabasetogetinformationaboutthestructureofthedatabase.

TheserverexecutesadatabaseservicethatwascreatedusingtheIntegrationServerAdministrator.

About the Server Configuration File

Theserverconfigurationfile(server.cnf),locatedintheIntegrationServer_directory\configdirectory,containstheparametersyouwilladdtocontroltheserverconnectiontothe

database.

Thefollowingtabledescribestheparametersthatyoumustaddtoserver.cnftospecifydatabaseconnectionsettings:

Note: Forinformationaboutcreatingservicesthataccessadatabase,AccessingDatabaseswithServicesonpage 17.

Note: Typically,youwillusetheSettings>Extended screenfromtheIntegrationServerAdministratortoupdatethisfile,buttheremightbetimeswhenyouneedtoeditthefiledirectlyusingatexteditor.Ifyoueditthefiledirectly,youshouldfirstshutdowntheIntegrationServerbeforeupdatingthefile.Afteryoumakethechanges,restarttheserver.

This parameter... Specifies

watt.server.db.connectionCache Howtheservermanagesconnectionstoadatabase.

Specifyingservertellstheservertomaintainapoolofconnectionsforeachdatabasethatisdefinedtotheserverthroughanalias.Ifarequestcannotbesatisfiedbecausethepoolhasreacheditsmaximumnumberofconnections,theserverblockstherequestandtriesagainlater.

Specifyingsessiontellstheservertotreatrequestsfromeachserviceindividually.Thatis,whenitreceivesarequest,theserverimmediatelyrequestsaconnectionfromthedatabase.Ifthedatabasehasnoavailableconnections,therequestfails.Thisisthedefault.


10/38



Preloading JDBC Drivers at Server Initialization

YoucanhavetheserverpreloadtheJDBCdriverswhenitinitializes.LoadingtheJDBCdriversatinitializationincreasestheperformanceofthefirstrunofthefirstdatabaseservicethatrequiresaspecificJDBCdriver.IftheserverdoesnothaveaJDBCdriverloadedwhenadatabaseservicerequiresit,theservermustloadtheJDBCdriverwhenthedatabaseserverexecutes.Also,ifyoupreloadJDBCdrivers,theserverdisplaysthe

listof

drivers

in

adrop

down

list

on

the

screens

that

require

aJDBC

driver

name.

When

thedropdownlistisavailable,youcanselectadriverfromitratherthantypethenameofadriver.

TohavetheserverloadJDBCdriverswhenitinitializes,specifyacommadelimitedlistofJDBCdriversthatyouwantpreloadedinthewatt.server.jdbc.driverListfieldintheserver.cnffileintheIntegrationServer_directory\configdirectory.Ifthisfielddoesnotexistintheserver.cnffile,youcanaddit.TochangethissettingusetheSettings>ExtendedscreenfromtheIntegrationServerAdministratorasdescribedinthewebMethodsIntegrationServerAdministratorsGuide.

Making the Java Classes for JDBC Drivers Accessib le

TheserverrequiresaccesstotheJavaclassesforeachJDBCdriverthatitistouse.YouneedtoplacetheJavaclassesinalocationthattheservercanaccess.Typically,youplacetheJavaclassesintheserversclasspath.

Toplacetheclassesintheserversclasspath,placethe.zipor.jarfilecontainingtheclassesintheIntegrationServer_directory\lib\jarsdirectory.Ifthejarssubdirectorydoesnotexist,createit.Theserverwillautomaticallyaddthe.zipor.jarlibrariestoitsclasspath.

Althoughenablingdatabaseconnectionpoolingcreatesapoolforeachdatabasedefinedtoyourserver,youcan

controlthe

characteristics

of

each

pool

individually

by

usingtheEdit Alias InformationscreenoftheIntegrationServerAdministrator.SeeEnablingDatabaseConnectionPoolingonpage 14formoreinformation.

watt.server.jdbc.defaultDriver ThenameoftheJavaclassforthedriveryouwanttousetoconnecttodatabaseswhennodrivernameissuppliedforadatabasealias.ThedefaultisthedrivernamefortheSunJVM:sun.jdbc.odbc.JdbcOdbcDriver.SeeIdentifyingDatabaseAliasesonpage 11formoreinformation.

watt.server.jdbc.driverList AcommadelimitedlistofJDBCdriversyouwantthe

serverto

load

when

it

initializes.

There

is

no

default.

SeePreloadingJDBCDriversatServerInitializationonpage 10formoreinformation.

This parameter... Specifies


11/38



Ifapatchyouareunzippingorunjarringoverwritesexistingclasses,besuretobackuptheexistingclassesincasethepatchdoesnotwork.

IftheserverdoesnothaveaccesstotheJavaclassesfortheJDBCdriver,usersreceivethefollowingerrorwhentheserverattemptstoconnecttothedatabase:

Could not connect: No suitable driver

Ifthedriverloadssuccessfullybutcannotconnecttothedatabaseforsomereason,theresultingerrormessageusuallyincludessomedriverspecificcodesormessages.Themostcommonsourceofsucherrorsisaninvalidusernameorpasswordonthedatabase.

Consultyour

driver

documentation

for

details.

Identi fying Database Aliases

Identifyadatabasealiastospecifytheconnectioninformationthattheservermustsupplytoconnecttoadatabase.Setupaliasesif:

YouwantdeveloperstobeabletodefinedatabaseflowservicesusingthewebMethodsIntegrationServerAdministrator.

Youwanttomaintainalldatabaseconnectionparametersinoneplacetoallowforeasiermaintenance.Forexample,youcaneasilyupdatetheinformationifapassword

changesoradatabasemoves.

Tobettermanagerequestsfordatabaseconnections,youcanspecifythattheserverusedatabaseconnectionpools.Withdatabaseconnectionpoolsineffect,theIntegrationServercontrolsthenumberofdatabaseconnectionsitmakestoadatabase,preventingthedatabasefromexceedingitsconnectionlimitandrejectingrequests.Ifarequestexceedsadatabaseconnectionpoolslimit,theserverblocksitandtriestheconnectionrequestagainlater.

SeeEnablingDatabaseConnectionPoolingonpage 14formoreinformationabouthowdatabaseconnectionpoolsworkandhowtosetthemup.

Note: IfyouareusinganODBCdatasourceonaWindowsplatform,youdonotneedtochangetheserversclasspath.IfyouareusingSunsJRE(thedefaultinstalledwiththewebMethodsIntegrationServer),theJDBCODBCbridgedriverissun.jdbc.odbc.JdbcOdbcDriver.AnODBCdatasourcecorrespondingtoyourdatabasemustexist.

Note: Beforeyouconfigureadatabasealias,makesuretheWmDBpackageisenabled.Forinformationaboutenablingpackages,seethewebMethodsIntegrationServerAdministratorsGuide.


12/38



UsethefollowingproceduretoidentifydatabasealiasestoyourIntegrationServer:

1 Openthe

Integration

Server

Administrator

if

it

is

not

already

open.

2 IntheAdaptersmenuofthenavigationarea,clickDatabase.Theserverdisplaysadatabasemanagementscreen.

3 Inthenavigationarea,clickAlias Management .

4 ClickAdd.TheserverdisplaystheNew DB Aliasscreen.

5 Setthenewaliasparametersasfollows:

To ident ify a database alias

For this parameter... Spec ify

Alias Thealiasnamethatyouwanttouseforthedatabase.You

canspecifyanycombinationofletters,numbers,andtheunderscorecharacterforanaliasname;thereisnorestrictiononthenumberorofcharactersyoucanspecify.

DB URL TheURLforthedatabase.Forexample:jdbc:odbc:Support.

DB Username Theusernamethattheservermustsupplytologontothespecifieddatabase.Ifausernameandpasswordarenotrequired,leavethisfieldblank.

DB Password Thepasswordthattheservermustsupplytologontotheselecteddatabase.Ifausernameandpasswordarenotrequired,leavethisfieldblank.

DB Driver ThenameoftheJavaclassfortheJDBCdriver.

Iftheserverhasanydriverscurrentlyloaded,theserverdisplaysaLoaded Driversfieldthathasadropdownlistcontainingthedriversthatareloaded.Ifyouselectadriverfromthelist,theserverplacesthedrivernameintheDBDriverfield.

Ifyoudonotspecifyadriver,theserverusesthedefaultdriverspecifiedinthewatt.server.jdbc.defaultDriverparameterintheserver.cnffile.Iftheserver.cnffiledoesnotcontainavalueinthisparameter,theserverusestheSun

JDBC

ODBC

bridge.Toseethevalueofthedefaultdriver,usetheSettings>ExtendedscreenfromtheIntegrationServerAdministratorasdescribedinthewebMethodsIntegrationServerAdministratorsGuide.


13/38



Important! BesuretheserverhasaccesstotheJavaclassesforthedriver.FormoreinformationaboutmakingtheJava

classesavailable,seeMakingtheJavaClassesforJDBCDriversAccessibleonpage 10.

IfyouareusingSunsJREonaWindowsplatform,theserverhasaccesstotheJavaclassesfortheonaJDBCODBCbridgedrivernamedsun.jdbc.odbc.JdbcOdbcDriver.

MinimumConnections

Theminimumnumberofconnectionstomaintaininthedatabaseconnectionpool.Theservercreatestheseconnectionswhenitfirstreceivesarequesttoconnecttothedatabase.Ifmoreconnectionsareneeded,theservercreatesadditionalconnectionsuntilthevalueforMaximum

Connections, describedbelow,isreached.

Thedefaultis0.

Note: Thisfielddisplaysonlyiftheserverisconfiguredfordatabaseconnectionpooling(thatis,ifthewatt.server.db.connectionCachepropertyintheserver.cnffileissettoserver).

SeeEnablingDatabaseConnectionPoolingonpage 14formoreinformation.

MaximumConnections

Themaximumnumberofconnectionstomaintaininthedatabaseconnectionpool.Whenthenumberofconnectionrequestsreachesthisvalue,theserverblockstherequests.

Thedefaultis1.


SeeEnablingDatabaseConnectionPoolingonpage 14formoreinformation.



14/38



6 ClickSubmit.

Enabling Database Connection Pooling

Forgreaterscalabilityyoucanpooldatabaseconnections.Withthisfeature,theservercreatesapoolofconnectionsforeachdatabasedefinedtothewebMethodsIntegrationServer.Theservermaintainstheseconnections,creatinganddroppingthemasneeded.

Thepool

controls

the

number

of

connections

aserver

can

have

to

the

database

at

any

giventime.Forexample,ifyourdatabaseallows50connectionsandyouhavefiveserversthatconnecttothedatabase,youcanlimiteachserversdatabaseconnectionpoolto10.Thisway,thenumberofconnectionstothedatabaseneverexceeds50andnorequestswillberejectedduetolackofavailableslots.Ifthenumberofconnectionrequeststoaserverexceeds10,thatserverwillblocktherequestandtryitagainlater.Therequestwillnotberejected.

Withoutdatabaseconnectionpooling,eachserverwillobtainasmanyconnectionstothedatabaseasrequesteduntilthedatabasereachesitslimitof50.Subsequentrequestswillberejectedbythedatabaseuntilthenumberofdatabaseconnectionsdropsdownbelow50.

Whenyouenabledatabaseconnectionpooling,itappliestoalldatabasesdefinedtotheserver.Inotherwords,theserverwillmaintainaconnectionpoolforeachdatabaseforwhichanaliasisdefined.Youcan,however,controlthecharacteristicsofeachpoolindividually.Forexample,youmightspecifymoreconnectionsforalarge,busydatabasethanforasmall,relativelyquietone.

Usethefollowingproceduretoenabledatabaseconnectionpoolingforyourserver.

Expiration Time (ms) Theamountoftimetheserverwaitsbeforediscardinganinactiveconnectionfromthedatabaseconnectionpool.The

serveronly

discards

connections

if

the

pool

contains

more

thantheminimumnumberofconnections.Afterwards,ifmoreconnectionsareneededthanexistinthepool,theservercreatesnewones.

Thedefaultexpirationtimeis60000milliseconds.


SeeEnabling

Database

Connection

Pooling

on

page 14

for

moreinformation.



15/38



1 OpentheIntegrationServerAdministratorifitisnotalreadyopen.

2 Inthe

Settings

menu

of

the

navigation

area,

click

Extended.

The

server

displays

a

screenthatlistsconfigurationparametersspecifiedintheserver.cnffile.

3 Dooneofthefollowing:

IftheExtended Settingslistswatt.server.db.connectionCache=serverthenconnectionpoolingisalreadyenabledforyourserver.

Ifthewatt.server.db.connectionCachepropertyisnotsettoserverordoesnotappearintheExtended Settingslist,clickEdit Extended Settings andspecifythefollowing:

watt.server.db.connectionCache=server

ClickSave Changes.

4 Ifyouwanttochangethealiasparametersfortheminimumandmaximumnumberofconnectionsintheconnectionpoolandtheconnectionexpirationtime,seeUpdatingInformationforDatabaseAliasesonpage 15.

5 Restarttheserverforthechangestotakeeffect.

Updating Information for Database Aliases

Iftheconnectioninformationchangesforadatabase,updatethedatabasealiasinformationtoidentifythenewconnectioninformation.



3 Inthenavigationarea,clickAlias Management .

4 FromtheCurrent Data Sourcesfield,selectthedatabasealiasforthedatabaseyouwanttoupdate.

5 ClickEdit.Theserverdisplaysthe Edit Alias Informationscreen.

6 Setthealiasparameters.Forinformationaboutwhattospecifyforeachofthefields,refertotheprocedureinIdentifyingDatabaseAliasesonpage 11.

To enable database connection pooling

Note: Thisprocedureassumesthedatabasealiaseshavealreadybeendefined.Iftheyhavenot,seeIdentifyingDatabaseAliasesonpage 11forinstructions.

To update information for a database alias


16/38



7 ClickSubmit.

8 IfyouchangedtheMinimum ConnectionsorMaximum Connectionsaliasparameters,restarttheserverforthechangestotakeeffect.

Deleting Database Aliases

Whenyounolongerneedaccesstoadatabase,youcandeletethedatabasealiasforthedatabase.



3 Fromthe Current Data Sourceslist,selectthedatabasealiasyouwanttodelete.

4 ClickDelete.Theserverissuesaprompttoverifythatyouwanttodeletethedatabasealias.

5 ClickOKtodeletethedatabasealias.

To delete a database alias


17/38


2 Accessing Databases with Services

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Deciding Which Type of Service to Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Creating Database Flow Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Creating Database Services with Java, C/C++, or Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . 26

Creating Clients that Access Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28


18/38



Overview

Alltypesofservicescanaccessdatabases,includingflowservices,Javaservice,C/C++services,andVisualBasicservices.Youcancreate:

Flow services using the Integration Server Administrator.Whenyoucreateaflowservicethataccessesadatabase,youmakeselectionsfromIntegrationServerAdministratorscreenstodescribethefunctionthatyouwanttheservicetoperform.ThewebMethodsIntegrationServergeneratestheflowserviceforyoubasedonyourselections.

Java, C/C++, and Visual Basic services using webMethods Integration Server or your owndevelopment environment.webMethodsIntegrationServerprovidesbuiltinservicesthatperformbasicdatabaseoperations,suchasconnectingtoadatabase,selectingrows,insertingrows,anddeletingrows.Yourservicescanaccessthesebuiltinservicestoperformdatabaseoperations.YourservicescanalsouseotherdatabaseAPIs(forexample,JDBC)toaccessdatabases.

Thischapterdescribeshowtodecidewhichtypeofservicetocreate,howtocreatedatabaseflowservices,howtocreatedatabaseserviceswithJava,C/C++,orVisualBasic,andhowtocreateclientsthataccessdatabases.

Deciding Which Type of Service to Create

Usetheinformationinthefollowingtabletodecidewhichtypeofserviceyoushouldcreate.

Type of Service Advantages and Disadvantages

Flow servicescreated with theIntegration Server

Administrator

Advantages YoucancreatetheflowserviceusingtheIntegrationServerAdministratoruserinterface.

Youdonotneedtorecompilecodewhenyoumakechangestotheflowservice.

Disadvantages Theflowservicemightnotbeabletohandlenonstandarddatabasefeatures,suchasWindowsSQLtypes.

YoucanonlymakeJDBCcallsinaflow

service.Use

aJava,

C/C++,

or

Visual

Basic

servicetoconnecttoadatabaseusingotherlibraries.


19/38



Creating Database Flow Services

WhenyouusetheIntegrationServerAdministratortocreateflowservicesthataccessdatabases,youprogressthroughaseriesofscreens,selectingoptionsandspecifyinginformationthatindicatesthefunctionyouwanttheservicetoperform.Theserverbuildsaflowservicefromtheselectionsyouspecify.

TheresultingflowserviceinvokesthesamebuiltinservicesthatyoucaninvokefromJava,C/C++,andVisualBasic.Formoreinformationabouttheseservices,seeBuiltinDatabaseServicesonpage 27.

UsingtheIntegrationServerAdministrator,youcancreateaflowserviceinoneofthefollowingways:

Generate from tables. Youselectthetablethatyouwanttheservicetoaccess.Then,youselectthedatabaseoperationyouwantyourservicetoperform(Select,Insert,Delete,orUpdate).Theserverdisplaysthecolumnsinthetablethatyoucanusetoindicatetheinputthattheserviceexpects.Whenyouusethisoption,theserverautomaticallygeneratestherequiredSQLstatements.Formoreinformation,seeGeneratingaDatabaseFlowServicefromaTableonpage 23.

Generate from a SQL statement. YouspecifytheSQLstatementthatyouwanttheservicetoperform.TheSQLstatementyouspecifycanbemorecomplexthantheSQLstatementstheservergenerateswhenitgeneratesaservicefromtables.Inaddition,youcanspecifydatabasespecificSQL.UsethisoptionifyouwanttousedatabasespecificSQLthatrequiresthefullyqualifiedtablenames.Formoreinformation,seeGeneratingaDatabaseFlowServicefromaSQLStatementonpage 20.

Regardlessofhowyougeneratethem,databaseflowservicesareallstandardflowservices.Afteraserviceiscreated,youcanedititusingDeveloperinthesamewayyou

Java, C/C++, orVisual BasicServices

Advantages Theservicecanbecodedmoreflexiblyintermsofprocessingdata.Youcanmanipulatedatadirectly,ratherthaninvokingwebMethodsIntegrationServerservicelibraries.Forexample,youcanuseconfigurationfilestoguideprocessingsettings.

Theservicecanincludemorerobusterrorhandling.Forexample,youcanlogerrorstoyourownfilesorsendemailnotestoseveralpeople.

TheservicecanmakedirectcallstodatabaseAPIs(forexample,JDBC,ADO,andODBC)

tohandle

nonstandard

database

features.

Disadvantage Youmustcodeandcompiletheservice.

Type of Service Advantages and Disadvantages


20/38



editanyotherflowservice.Youcaninvoketheresultingdatabaseflowservicefromotherservices.

Generating a Database Flow Service from a SQL Statement

TogenerateaservicefromaSQLstatement,youmustselecttheSQLstatementthatyouwanttheservicetoperform.YoucanspecifyastaticSQLstatementoradynamicSQLstatement.

Specifying a Dynamic SQL Statement

YoucancreateadynamicSQLstatementbyincludingquestionmarksortemplatetagsintheSQLstatement.WhenyouspecifyadynamicSQLstatement,theserviceexpectsinputvaluestoreplacethequestionmarksortemplatetagsthatyouspecify.

Using Question Marks (?) in SQL Statements

Useaquestionmarkinplaceofasingleparameterthattheserviceexpectsasinput.WhenyoutesttheserviceinIntegrationServerAdministrator,itrecognizesthequestionmarkandpromptsyoufortherequiredinputvalue.

Example 1

Toselect

all

rows

from

the

Names

table

that

match

the

values

specified

for

the

Last_Name

column,specifythefollowingSQLstatement:

select * from Names where Last_Name=?

TheserviceexpectsaninputvaluetousetomatchrowsintheLast_Namecolumn.

Note: Allgenerateddatabaseflowservicescallthepub.db:execSQLservice.ThisserviceexecutesaSQLstatement.IfyouwanttochangetheSQLstatementtheflowserviceexecutes,openthatserviceinDeveloperandchangethe$dbsqlparameterintheINVOKEexecSQLstepintheflow.

Important! BeforeyoucanusetheIntegrationServerAdministratortobuildflowservices,theservermusthaveaconfigureddatabasealiasforthedatabasethatyouwanttoaccess.Thedatabasealiasmustbeconfiguredwhenyoucreateaserviceandwhentheserverexecutestheservice.Formoreinformationabouthowtoconfigureadatabasealias,seeIdentifyingDatabaseAliasesonpage 11.

Important! Thegeneratedflowserviceisunabletoproperlycallastoredprocedureorreturntheresultsetoroutputparameters.Ifyouwanttocallastoredprocedure,createtheserviceinJava,C/C++,orVisualBasicandcallthestoredprocedureusingthepub.db:call service.


21/38



Example 2

ToaddanewrowtotheAddressestableandpopulateitwithspecifiedvalues,specifythefollowingSQLstatement:

insert into Addresses (name,street,city,state,zip) values (?,?,?,?,?)

Theserviceexpectsinputvaluestousetopopulatethenewrow.

Using Template Tags in SQL Statements

ThetemplatetagsyoucanuseinanSQLstatementarethesametagsyouuseinanoutputtemplate.Besidesallowingyoutospecifythevaluesofindividualinputparameters,templatetagsalsoallowyoutodynamicallyconstructentireportionsoftheSQLstatementatruntime.(Foracompletelistoftemplatetags,seetheDynamicServerPagesandOutputTemplatesDevelopersGuide.)

WhenyouusetemplatetagsinanSQLstatement,youcannottestthestatementwiththeIntegrationServerAdministrator;(theIntegrationServerAdministratordoesnot

recognizetemplatetagsandwillnotpromptyouforinputwhenyouexecutetheservice).Totestaservicethatusestemplatetags,youmustopenthatserviceinDeveloperandaddtoitsinputparametersanyvariablesthatarereferencedinatag.YoucanthentesttheservicewithDeveloperanditwillpromptyouforeachinputvariableyoudefined.Forinformationaboutdeclaringinputparametersforaservice,seethewebMethodsDeveloperUsersGuide.

Example 1

ThefollowingshowsanSQLstatementthatselectsallrowssatisfyingthecriteriathatwillbespecifiedinavariablenamedconditionatruntime:

select * from Names where %value condition%

Atruntime,theserverwillsubstitutethevalueofconditionforthe%value%tag.Thefollowingshowsexamplesofwhatyoumightuseasthevalueofcondition:

name = 'Steve'

name like 'Jim%'

Example 2

TodeleteallrowsfromtheMusictablethatmeetaspecifiedcondition,specifythefollowingSQLstatement:

delete from Music where %value outdated%

Theserviceexpectsinputforaninputvariablenamedoutdatedthatitusestoreplacetheentiretoken.Followingisanexampleofwhatausercanspecifyfor%valueoutdated%:

ReleaseDate < '1950'

Format = '8-track'


22/38



Steps for Generating a Flow Service from a SQL Statement

UsethefollowingproceduretogenerateaflowservicefromaSQLstatement.


2 OntheDatabasemenu,selectService Generation.

3 IntheSource aliaslist,selectthedatabaseyouwanttheservicetoaccess.

4 InthePackagelist,selectthepackageinwhichyouwanttheservicetoreside.

5 IntheFolderfield,typethenameofthefolderinwhichyouwanttosavetheservice.

6 IntheServicefield,typethenameyouwanttoassigntotheservice.

7 IntheExecuteACL list,selecttheACLgrouptowhichyouwanttolimitaccesstothe

service.OnlytheuserswhoaremembersofthegroupsintheselectedACLwillbeabletoinvoketheservice.

8 Ifyouwanttooverwriteanyexistingserviceswiththesamenameasthenewservice,nexttoOverwrite Existing,selecttheGenerated objects overwrite existing objectscheckbox.

9 ClickGenerate from SQL.TheserverdisplaystheEdit SQL Statementscreen.

10 IntheEnter SQL statementsectionofthescreen,entertheSQLstatementyouwanttheservicetoexecute.Youcanspecifyastatementthatisdynamic(thatis,containsquestionmarksortemplatetags)orstatic.

11 IfyouincludedtemplatetagsintheSQLstatement,selecttheProcess webMethodstemplate tags in thi s SQL statement checkbox.

12 ClickEvaluate. Theserverdisplaysthe Input Binding Generation screen.

Ifyouspecifiedquestionmarks(?)intheSQLstatementforinputvalues,theserverdisplaysaBind parameterssectionofthescreen.UnderBind parameters,oneParameter#fieldexistsforeachquestionmarkyouspecifiedintheSQLstatement.ThefirstquestionmarkcorrespondstoParameter 0,thesecondtoParameter 1,andsoforth.Usethissectionofthescreentoindicateadditionalinformationabouttheinputparametersthatauserwillsupplyinplaceofthequestionmarks.

13 ForeachParameter#fieldunderBind parameters,specifythefollowinginformation:

14 ClickGenerate.

To generate a flow servi ce from a SQL statement

For this field Specify or select

name Thenamethatyouwanttheservicetousefortheinputparameter.

type Thedatatypeoftheinputparameter.


23/38



Generating a Database Flow Service from a Table

Whenyouspecifythatyouwanttogeneratetheservicefromdatabasetables,theserverdisplaysinformationaboutthetablesintheselecteddatabase.Ifyourdatabasecontains

many

tables,

you

can

restrict

the

list

of

tables

that

the

server

displays.

Restr icting the List of Database Tables

Youcanrestrictthelistofdatabasetablesthattheserverdisplaysbyspecifyingoneormoreofthefollowing:

Catalog. Youspecifythenameofthecatalogwhosetablesyouwanttouse.

Ifyouarenotworkingwithadistributeddatabase,donotrestrictbycatalog.

Ifyouareworkingwithadistributeddatabase,youcanspecifythenameofthedatabasewithwhichyouwanttowork.IfyouareusingDB2,usethisfieldtospecifythenameofaDB2location.

Schema pattern.Youspecifytheschemaswhosetablesyouwanttoworkwith(ifyouareusingDB2,usethisfieldtospecifyanAuthID).

Ifyouwanttablesforallschemasintheselecteddatabase,donotrestrictbyschemapattern.

Ifyouwanttorestrictyoursearchtotablesbyselectedschemas,specifytheschemaname.YoucanspecifyapatternmatchingstringifyourJDBCsupportsit.MostdriverssupportthepatternmatchingcharactersdescribedforTable namepatternbelow;however,checkyourdriversdocumentationforinformationaboutitspatternmatchingcapabilities.

Table name pattern.

You

specify

the

names

of

the

tables

with

which

you

want

to

work.

Specifyatablenameorapatternmatchingstringthatspecifiesthenamesofthetables.Mostdriverssupportthefollowingpatternmatchingcharacters;however,checkyourdriversdocumentationforinformationaboutitspatternmatchingcapabilities.

Table type.Thetypeofthetablesforwhichyouwantinformation.YoucanchoosefromthefollowingcommonJDBCtabletypes:Table,View,SystemTable,GlobalTemporary,LocalTemporary,Alias,andSynonym.

Use To match For example

% Anystringofcharacters HR%matches:HR30all,HR15mgmt,HR01payroll,andsoforth.

_ Asinglecharacter HR3_mgmtmatches:HR30mgmt,HR31mgmt,HR3Amgmt,andsoforth.


24/38



Steps for Generating the Flow Service from a Table

Usethefollowingproceduretogenerateaflowservicefromdatabasetables.


2 OntheDatabasemenu,selectService Generation.

3 IntheSource aliaslist,selectthedatabaseyouwanttheservicetoaccess.

4 InthePackagelist,selectthepackageinwhichyouwanttheservicetoreside.

5 IntheFolderfield,typethenameofthefolderinwhichyouwanttosavetheservice.

6 IntheServicefield,typethenameyouwanttoassigntotheservice.

7 IntheExecuteACL list,selecttheACLgrouptowhichyouwanttolimitaccesstothe

service.OnlytheuserswhoaremembersofthegroupsintheselectedACLwillbeabletoinvoketheservice.

8 Ifyouwanttooverwriteanyexistingserviceswiththesamenameasthenewservice,nexttoOverwrite Existing,selecttheGenerated objects overwrite existing objects checkbox.

9 ClickGenerate from table.TheserverdisplaystheSpecifyConnection Parametersscreen.

10 Determinewhichtablesyouwanttosearchbyperformingoneofthefollowing:

Tosearchalldatabasetables,clickConnect.

Torestrictyoursearch,fillinoneormorefieldsintheRestrictionsparametersasfollows,andthenclickConnect.Formoreinformationabouthowtorestrictthe

search,seeRestrictingtheListofDatabaseTablesonpage 23.

AfteryouclickConnect,theserverdisplaystheTables in DataSourceNamescreen.

To generate a flow service from a table

For this parameter... Specify...

Catalog Catalognameswhosetablesyouwanttouse.Ifyouarenotworkingwithadistributeddatabase,donotrestrictbycatalog.

Schema Pattern Schemaswhosetablesyouwanttoworkwith.Ifyouwanttablesforallschemasintheselecteddatabase,donotrestrictbyschemapattern.

Table Name Pattern Tablenameorapatternmatchingstringthatidentifies

thenamesofthetablewithwhichyouwanttowork.

Ifthedefaultwildcardcharacter%isspecified,theneverytablenamewillmatch.

Table Types Typesoftablesforwhichyouwantinformation.


25/38



11 IntheSelect a tablesectionofthescreen,clickthetablenamethatyouwanttousetogeneratetheservice.

12 IntheService typesectionofthescreen,selectthedatabaseoperationthatyouwanttheservicetoperform(Select,Insert,Delete,orUpdate).TheserverdisplaystheColumns

in TableNamescreen.

13 IntheColumnssectionofthescreen,selectthecolumnsthatyouwanttouseasinputparameters.Whentheserviceisexecuted,itexpectsinputvaluesforeachofthecolumnsyouselect.Theserviceusestheinputvaluesasfollows:

14 ClickGenerate SQL.TheserverdisplaystheInput Binding Generationscreen.

Ifyouselectedanycolumnsforinputparameters,theserverdisplaysaBind parameterssectionofthescreen.ThereisoneParameter#fieldforeachcolumnyouselected.

For this operat ion The service

Select Selectsrowsthathavecolumnsthatmatchtheinputvalues.

Insert Populatesthecolumnsoftheinsertedrowsusingtheinputvalues.Ifyouwanttopopulateallcolumnsintherow,selectallcolumnnames.

Delete Selectsrowsthathavethecolumnsthatmatchtheinputvaluesanddeletestheselectedrows.

Update Selectsrowsandupdatesthem.

Toidentifythecriteriatousetoselectrows,youcheckcolumnnamesintheCriteriacolumn.Theserviceexpectsinputvaluesforeachcolumnnameyoucheck.Theserviceselectsrowsthathavecolumnsthatmatchtheinputvalues.Ifyouwanttoselectallrows,donotcheckanyCriteriacolumns.

Toidentifythecolumnstoupdateintheselectedrows,usetheSetcolumn.Theserviceexpectsinputvaluesforeachcolumnyoucheck.Theservicesetsthevalueofthecheckedcolumns(forallselectedrows)tothespecifiedinputvalues.


26/38



15 UsetheBind parameterssectionofthescreentoidentifythenameanddatatypeforeachinputparameter.Specifythefollowinginformation:

16 ClickGenerate.

Output from the Flow Service

Whenyougenerateaflowservicefromadatabasetable,thedatabaseoperationdeterminestheserviceoutput.Thefollowingtabledescribestheserviceoutputproducedbyeachdatabaseoperation:

Creating Database Services with Java, C/C++, or Visual Basic

YoucancodeservicesthataccessdatabasesinJava,C/C++,orVisualBasic.Codeyourownservicesifyouneedaservicethatperformsmorecomplexdatabaseoperationsthanaflowservicecanprovide.

Toassistyouincodingdatabaseservices,youcanusethebuiltindatabaseservicestoperformbasicdatabaseoperationsandtestSQLstatementsbeforeyouaddthemtoyourservices.

Ifyouwantyourservicetoaccessadatabasethathasnonstandardfeatures(forexample,datatypesthatarenotsupportedbySQL),useotherdatabaseconnectionAPIs.Forexample,youcanmakedirectcallstoJDBCoruseotherconnectionlibraries,suchasADO.

For this parameter... Specify

name Thenamethatyouwanttheservicetousefortheinputparameter.Bydefault,theserverusesthedatabasecolumnname.Ifyouwanttouseadifferentname,typethenewnameinthisfield.

type Thedatatypeoftheinputvalue.Bydefault,theserverusesthedatatypethatisassociatedwiththedatabasecolumn.Ifyouwanttouseadifferentdatatype,selectitfromthelist.

Database Operat ion Output

Select Numberofrowsthattheserviceretrievedandthecolumnsfromthoserowsthattheservicerequested

Insert UpdatecountthatthedatabasereturnedinresponsetotheSQLcommand

Delete Updatecount

that

the

database

returned

in

response

to

the

SQL

command

Update UpdatecountthatthedatabasereturnedinresponsetotheSQLcommand


27/38



Bui lt-in Database Services

webMethodsIntegrationServerprovidesseveralbuiltindatabaseservicesthatperformbasicdatabaseoperations.TheseservicesuseJDBCtoconnecttothedatabasetoperform

the

specific

database

operation.

You

can

invoke

the

built

in

database

services

from: Java,C/C++,andVisualBasicservices

AnyflowservicethatyoucreateinDeveloperbyusingtheINVOKEflowstep

Clients

ThewebMethodsIntegrationServerBuiltInServicesReferencecontainsalistofbuiltindatabaseservicesandshowsinputandoutputinformationforeach.Yourserviceorclientmustinvokethebuiltindatabaseservicethatopensaconnectiontoadatabasebeforeitcaninvokeanyoftheotherbuiltindatabaseservices.

Testing SQL StatementsYoucanusetheIntegrationServerAdministratortotestanSQLstatementthatyouwanttoexecuteusingthebuiltindatabaseservicepub.db:execSQLorthatyouwanttoinvokedirectlyusingaJDBCcall.

BeforeyoucanusetheIntegrationServerAdministratortotestanSQLstatement,theservermusthaveaconfigureddatabasealiasforthedatabasethatyouwanttoaccess.Formoreinformationabouthowtoconfigureadatabasealias,seeIdentifyingDatabaseAliasesonpage 11.


2 OntheDatabasemenu,selectAlias Management .

3 UnderCurrent Data Sources,selectthedatabasealiasforthedatabaseyouwanttheservicetoaccess.

4 ClickConnect.TheserverdisplaystheConnection Parametersscreen.

5 Indicatewhichtablesyouwanttosearchbyperformingoneofthefollowing:

Tosearchalldatabasetables,clickConnect.TheserverdisplaystheTablesscreen.

Torestrictyoursearch,fillinoneormorefieldsintheRestrictionsparametersas

follows,andthenclickConnect.TheserverdisplaystheTablesscreen.Formoreinformationabouthowtorestrictthesearch,seeRestrictingtheListofDatabaseTablesonpage 23.

To test a SQL statement


28/38



6 IntheTest SQL Queries sectionoftheTablesscreen,typetheSQLstatementyouwanttotest.

7 ClickExecute query.

The

server

sends

the

SQL

statement

you

specified

to

the

database

for

execution

and

displaysascreenthatliststheresultsfromyourSQLquery.

Error Handling

Somedatabaseservicesreturna$dbMessageoutputvaluewhichcontainsatextmessagethatdescribestheresultsoftheservice.Iftheserviceresultsinanerror,theservicealsoreturnsstandarderroroutputvalues.

Creating Clients that Access Databases

YoucanaccessthedatabasesfrombrowserbasedclientsandclientscodedinJava,C/C++,orVisualBasic.

Invoking a Database Service from a Browser-based Client

Severalofthedatabaseservicescanacceptinputfromabrowserbasedclient.(ThedescriptionsofthedatabaseservicesinthewebMethodsIntegrationServerBuiltInServicesReferenceindicatewhetheryoucaninvokeabuiltindatabaseservicefromabrowserbasedclient.)Whenabrowserbasedclientsubmitsinputvariablescontainingrowinformation,theseservicesautomaticallyconverttherowinformationintoanestedIDataobject.Theservicedetermineswhichvariablestoconvertbasedonthenamesofthevariables.Allvariablesexceptthosewhosenamesbeginwith_or$dbareconvertedintonestedIDataobjects.

Forexample,supposeabrowserusersubmitsthefollowingnamevaluepairs:

Variable Name Contents

$dbTable Table Name

Name Joe B

Company Widgets, Inc.


29/38



Thepub.db:insertserviceconvertstheinputsasfollows:

Invoking a Built-in Service from a Java, C/C++, or VB Client

YoucancreateclientapplicationsinJava,C/C++,orVisualBasic.Theclientapplicationscanusethebuiltindatabaseservicestoperformdatabaseoperations.Forinformationaboutthesebuiltinservices,seethewebMethodsIntegrationServerBuiltInServices

Reference.

Ifyouwantyourclienttoaccessadatabasethathasnonstandardfeatures(forexample,datatypesthatarenotsupportedbySQL),youuseotherdatabaseAPIs.Forexample,youcanmakedirectcallstoJDBCoruseotherconnectionlibraries,suchasADO.

Sample Code - IData

ThefollowingshowsasampleJavaclientthataccessesadatabaseusinganIDataobjecttopassandreceivedatafromthedatabaseservice.

Variable Name Contents

$dbTable Table Name

$data Variable Name Contents

Name Joe B

Company Widgets, Inc.

import com.wm.data.*;

import com.wm.app.b2b.client.Context;

public class DBClient

{

public static void main (String [] args) throws Exception

{

IData in = null;

IData out = null;

IData criteria = null;

IData set = null;

//

// connect to your integration server using an appropriate user

// name and password (doesn't have to be Administrator)

//Context ctx = new Context();

ctx.connect ("localhost:5555", "Administrator", "manage");


30/38



//

// (1) request a DB connection by DB alias (if the DB

// changes location or something, we won't have to change

// this client code)

//

in = IDataFactory.create();IDataCursor inCursor = in.getCursor();

inCursor.insertAfter ("$dbAlias", "Employees");

inCursor.destroy();

out = ctx.invoke ("wm.util.db", "connect", in);

//

// (2) update the Identification table to set Fonz's ID

// to 6500. note that we couldn't do this from a Web

// browser because we couldn't build up the complex

// nested data structures

in = IDataFactory.create();

inCursor = in.getCursor();

inCursor.insertAfter ("$dbAlias", "Employees");

inCursor.insertAfter ("$dbTable", "Identification");criteria = IDataFactory.create();

IDataCursor criteriaCursor = criteria.getCursor();

criteriaCursor.insertAfter ("name", "fonzie");

criteriaCursor.destroy();

inCursor.insertAfter ("$criteria", criteria);

set = IDataFactory.create();

IDataCursor setCursor = set.getCursor();

setCursor.insertAfter ("ID", "6500");

setCursor.destroy();

inCursor.insertAfter ("$set", set);

inCursor.destroy();

try {

out = ctx.invoke ("wm.util.db", "update", in);

//

// (3) look at the return values (updateCount is the

// most important in this case)

//

IDataCursor outCursor = out.getCursor();

if (outCursor.first("updateCount"))

{

int uc = Integer.parseInt ((String)outCursor.getValue());

System.err.println ("Update count: "+uc);

}


31/38



else

System.err.println ("Error: no update count returned");

outCursor.destroy();

} catch (Exception e) {

// maybe something went wrong with the DB access; we

// can get more information hereif (outCursor.first("$error")) {

System.err.println ("Error: "+outCursor.getValue());

}

if (outCursor.first("$errorType")) {

System.err.println ("Error type: "+outCursor.getValue());

}

outCursor.destroy();

}

}

}


32/38




33/38


A Determining Whether to Use the WmDB Package orthe JDBC Adapter

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

When to Use the WmDB Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

When to Use the webMethods JDBC Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34


34/38

A Determining Whether to Use the WmDB Package or the JDBC Adapter


Overview

webMethodsproductsprovidetwomethodsforaccessingdatabases:

WmDB packageto

use

for

prototyping,

design,

or

temporary

database

access. webMethods JDBC Adaptertouseforallenterprise,missioncriticalapplications.

ThisappendixdescribesusecasestohelpyoudeterminewhentousetheWmDBpackageandwhentousethewebMethodsJDBCAdapter.

When to Use the WmDB Package

TherearecaseswhenitismoreappropriatetousetheWmDBpackageratherthanthewebMethodsJDBCAdapter.UsetheWmDBpackagewhen:

YouneedimmediateresultsfromtheexecutionofaSQLquery.TheWmDBpackageallowsyoutorunquickSQLqueriesdirectlyfromtheIntegrationServerAdministratororDSPpages.

Youhaveaneedforadhocintrospectionofdatabaseobjects,suchastables,views,aliases,synonyms,orstoredprocedures.

Youwanttocustomizemanagementofthedatabaseconnectionpool.

Youhavealimitednumberoftasksthatneedtoaccessadatabase.

Youarerequiredtointegratewithaproprietaryoranonmainstreamdatabase,andyouwanttoperformaquick,easycompatibilitytestbeforeexploringanimplementationthatusesthewebMethodsJDBCAdapter.ThewebMethodsJDBCAdaptersupportsallJDBCcompliantdatabaseimplementationsandiscertifiedonspecificmainstreamdatabases.

Youaredevelopingathrowawaytestscenario.

When to Use the webMethods JDBC AdapterYouwillwanttousethewebMethodsJDBCAdapterinmostcases,includingthefollowing:

Important! TheWmDBpackagehasbeendeprecated.Whendevelopingnewapplications,usethewebMethodsJDBCAdapterinsteadoftheWmDBpackage.TheJDBCAdapterprovidesmorefunctionality,improvedperformance,andsupportsadapternotifications.FormoreinformationabouttheJDBCAdapter,seethewebMethodsJDBCAdapterUsersGuide.


35/38



Yoursystemislikelytobeexpandedandmodernized.Thisistypicalforenterprise,missioncriticalapplications.

Yourequirebetterdatabaseperformance.TheperformanceoftheJDBCadapterissuperiortothatoftheWmDBpackage,particularlyforbatchoperations.For

example,toinsertdataintoadatabaseusingtheWmDBpackage,youusethepub.db:insertservice;yousupplytheitemstoinsertusingadocumentlistasinput,andthepub.db:insertserviceprocesseseachiteminthedocumentlistsequentiallywithoutusingJDBCstandardfacilities.

Yourequireorplantousenotificationfeatures.

Youneedautomaticandefficientdatabaseconnectionpoolmanagement.

YourequireXAtransactionality.

YouneedtouseJDBCstandarddatatypes,includingBLOBandCLOB.

Youneedtobeabletoconfigureservicesratherthanhardcodethem.

Youneedtouserolebasedsecurity.TheJDBCadapterallowstheseparationofthedatabaseadministratoranddevelopmentenvironmentsasneeded.TheWmDBpackagerequiresAdministratorprivileges.

Youwantaconfigurableandstructureduserinterface.JDBCadapterusestemplatebasedconfigurationthatismorestructuredandeasiertouse.TheJDBCadapterusesmetadatathathelpsprotecttheusersinvestmenteveniftechnologychanges.

YouwanttomanageyourdatabaseconnectionusingwebMethodsOptimizeforInfrastructure.


36/38




37/38


Index

Aadding database aliases 11aliases, database

adding 11deleting 16information to supply for 8updating 15

B

browser clients, invoking database services from 28

CC/C++ clients for database services 29C/C++ services, accessing databases through 26changing database aliases 15classpath, updating servers 10client applications for database services 28,29configuration settings, descriptions 9conventions used in this document 6

D

database aliases

adding 11deleting 16information to supply for 8updating 15

database connectionsenabling pooling 14information to supply 8making JDBC driver classes accessible 10maximum connections in pool 13minimum connections in pool 13parameter for pooling 9pooling expiration 14

preloading JDBC drivers at server initialization 10specifying database location 10, 12specifying JDBC driver 12

database servicesconverting database rows to IData 28creating 18

creating flow services 19creating from a table 23, 24creating from SQL 20,22creating in Java, C/C++ or VB 26error handling 28invoking from a browser 28invoking from a client application 29

defining database aliases 11deleting database aliases 16documentation

additional 6conventions used 6feedback 6

E

error handling in database services 28

I

invoking database services from a browser 28,29

J

Java clients for database services 29

Java services, accessing databases through 26JDBC driversmaking classes accessible 10preloading at server initialization 10specifying in database alias 12

P

pooling database connectionsenabling 9, 14setting expiration 14specifying maximum 13specifying minimum 13

preloading JDBC drivers 10program code conventions in this document 6

R

removing database aliases 16


38/38

Index

S

server.cnfdescription of settings 9location 9

SQLcreating services from 20specifying dynamic SQL 20testing 27

Structured Query Language. See SQL

T

troubleshooting information 6typographical conventions in this document 6

U

updating database aliases 15

V

Visual Basic clients for database services 29Visual Basic services, accessing databases through

26

W

watt.server.db.connectionCache 9watt.server.jdbc.defaultDriver 10watt.server.jdbc.driverList 10webMethods Integration Server configuration

settings 9

Documents

7-1-1 WmDB Users Guide