Java
programs
and
enterprise
beans
written
for
CICS
Javaprogramsandenterprisebeanswritten forCICScanuseseveralmethods to accessdataheldinaDB2database.Theycan:
v Usea JCICSLINKcommand,ortheCCIConnectorforCICSTS,to linkto a
CICSprogramthatusesStructuredQueryLanguage(SQL)commandsto access thedata.Formoreinformationabout usingtheCCIConnectorfor CICSTS,see JavaApplicationsinCICS.
v Usea beanto accessthedata.Thebeancouldbea DataAccess bean;a
JavaBeanthatusesJDBCorSQLJ toaccessthedata;oranentitybean running onanotherEJB server.Formoreinformationabout usingbeansto accessdata, seeJavaApplicationsinCICS.
v DirectlyaccessthedatabyusingtheJavaDataBaseConnectivity(JDBC)or
StructuredQueryLanguagefor Java(SQLJ) applicationprogramminginterfaces. Thischaptertellsyouhowto dothis.
This chaptercovers:
v “MakingJDBCandSQLJ workintheCICSDB2environment”
v “RequirementstosupportJavaprogramsintheCICSDB2environment” onpage
119
v “ProgrammingwithJDBCandSQLJ intheCICSDB2environment”onpage121
– “Acquiringaconnection toadatabase”onpage122
- “Acquiringa connectionusingtheJDBCDriverManagerinterface”onpage
123
- “Acquiringa connectionusingtheDataSourceinterface”onpage124
– “Committinga unitofwork”onpage 129
– “CICSabendsduringJDBCorSQLJ requests”onpage130
– “UsingJDBCandSQLJinenterprisebeans:specialconsiderations”onpage
130
Making
JDBC
and
SQLJ
work
in
the
CICS
DB2
environment
When aJavaapplicationforCICSmakesJDBCandSQLJ requests,therequests areprocessedbyaJDBCdriver suppliedbyDB2.In aCICSenvironment,the DB2-suppliedJDBCdriver islink-edited withtheCICSDB2languageinterface (stub) DSNCLI.Thedriver convertstheJDBCorSQLJ requestsintotheirEXEC SQLequivalents.TheconvertedrequestsfromtheDB2-suppliedJDBCdriverflow into theCICSDB2attachmentfacilityinexactlythesamewayasEXECSQL requests fromanyotherprogram(forexample,aCOBOLprogram).Sothereareno operationaldifferencesbetweenJavaprogramsforCICSDB2andotherprograms for CICSDB2,andallcustomizationandtuningoptionsavailableusingRDOapply to Javaprograms forCICSDB2.
DB2 Version6 providestheJDBC1.2driver,thatsupportstheJDBC1.2application programming interface.DB2Version7providesthreelevelsof theJDBCdriver,the 1.2level,the2.0level,andtheDB2Universal JDBCDriver.DB2Version8provides two levelsoftheJDBCdriver,the2.0levelandtheDB2Universal JDBCDriver. Javaprogramsandenterprisebeanswritten forCICScanuseanyoftheseJDBC drivers. # # # # # #
TheJDBC2.0driversupports aselectedsubsetoftheJDBC2.0application programming interface,andit isdownward compatible,soitsupports theJDBC 1.2 API aswell.Existing Javaapplicationsandenterprisebeansthatwere writtenusing theJDBC1.2APIandthatruninaJVM,canrunusingtheJDBC2.0driver,and can benefitfromperformanceimprovementsmade intheJDBC2.0driver.Ifyou createnewJavaapplicationsandenterprisebeansthatusetheJDBC2.0API,you need tousetheJDBC2.0driveror theDB2 UniversalJDBCDriver.
TheDB2Universal JDBCDriverprovidesenhancedsupportfortheJDBC2.0 programming interfaceandmostof theJDBC3.0applicationprogramming interface.LiketheJDBC2.0driver,itisdownwardcompatible,soitsupportsthe JDBC 1.2API aswell.Because itisanentirely newdriver,ratherthanafollow-on to theJDBC2.0driver,youcan expectsomedifferencesinbehaviorbetweenthis driver andtheJDBC1.2and2.0drivers.For moreinformationabouttheDB2 Universal JDBCDriver,seethetheDB2UniversalDatabasefor OS/390andz/OS Application ProgrammingGuideandReferencefor Javawhich isappropriateto your versionofDB2.Thedocumentnumberfor DB2Version7isSC26-9932,and thedocumentnumberforDB2Version8isSC18-7414.
Tousea JDBCdriverprovided byDB2, CICSmust beconnectedto aDB2 subsystemthatsupportstheappropriatelevelofJDBCdriver.Forexample,when CICSisconnectedto aDB2Version6subsystem,youcannotusetheJDBC2.0 driver providedbyDB2Version7or byDB2 Version8.
Thefollowingtable summarizeswhichleveloftheJDBCdriverissupportedby which versionsandreleasesofCICSandDB2.
Table8.SupportfortheJDBCdriverinCICSandDB2
Product JDBCdriversupported
DB2Version6(withAPARPQ84783) 1.2level
DB2Version7(withAPARPQ84783) 1.2leveland2.0level DB2Version7(withAPARPQ86525) DB2UniversalJDBCDriver DB2Version8(withAPARPQ84783) 2.0level
DB2Version8(withAPARPQ86525) DB2UniversalJDBCDriver CICSTSforOS/390Version1Release3(withAPAR
PQ34321)
1.2level
CICSTSforz/OSVersion2Release2(withAPARs PQ57455andPQ85283)
1.2level,2.0levelandDB2 UniversalJDBCDriver CICSTSforz/OSVersion2Release3(withAPAR
PQ85283)
1.2level,2.0levelandDB2 UniversalJDBCDriver CICSTSforz/OSVersion3Release1 1.2level,2.0levelandDB2
UniversalJDBCDriver
“Requirements tosupportJavaprogramsintheCICSDB2environment”onpage 119hasinformationonthesystemrequirements tosupporteachlevelof theJDBC driver.
Full detailsofhow tocode andbuildJavaapplicationsthatusetheJDBCandSQLJ applicationprogramminginterfacescanbefoundintheDB2UniversalDatabasefor OS/390andz/OSApplicationProgrammingGuideandReferenceforJavathat applies toyourversion ofDB2.Thedocumentnumberfor DB2Version6is # # # # # # # # # # # # # # # # # # # # # #
documentnumberforDB2Version8 isSC18-7414.Particularprogramming featuresapplyto JDBCandSQLJwhentheyareusedinaCICSenvironment,so read“ProgrammingwithJDBCandSQLJintheCICSDB2environment” onpage 121for morespecificguidancebeforedevelopingyourJavaapplication.
Requirements
to
support
Java
programs
in
the
CICS
DB2
environment
TouseJavaprogramsintheCICSDB2environment,youneedto applythe following systemandsetuprequirements:
RequirementsforJavaprogramsandenterprisebeans, whichrunin aJVM v ForJavaprogramsandenterprisebeans,which runintheIBMJavaVirtual
Machine(JVM),thefollowingAPARsarerequiredonDB2: – PQ84783onDB26.1
– PQ84783(JDBC1.2and2.0drivers)andPQ86525(DB2 UniversalJDBC
Driver)onDB27.1
– PQ84783(JDBC2.0driver)andPQ86525(DB2Universal JDBCDriver)on
DB28.1
v TousetheDB2-suppliedJDBCdriverswithJavaprogramsandenterprisebeans,
youneedto amendtheJVMprofilesthatareusedbytheJavaprogramsor enterprisebeans.Youneed toaddaDB2-suppliedzipfile(or fortheDB2 UniversalJDBCDriver, threeDB2-suppliedjarfiles)tothetrustedmiddleware classpath,andaDB2-supplieddirectory containingdynamicloadlibrariesto the librarypathfortheJVM.(NotethatiftheJVMisaworkerJVMthatusesthe sharedclasscache,itstrustedmiddlewareclasspathandlibrarypatharetaken fromtheJVMprofilefor themasterJVMthatinitializesthesharedclasscache, notfromtheJVMprofilefortheworkerJVMitself.)
– TheCICS-supplied sampleJVMprofilescontain commented-outexamplesof
howto amendthetrustedmiddlewareclasspath andlibrarypathto addthese filesfor theJDBC 1.2driver.
– IfyouwanttousetheJDBC2.0driverinstead, followthesuppliedexample
forthelibrarypathsetting,butforthetrustedmiddlewareclasspath, addthe zipfiledb2j2classes.zipinsteadofthefilenamedintheexample.
– FortheDB2UniversalJDBCDriver, theappropriatesettingsareinthe
CICS-suppliedsampleJVMprofilesascommented-outexamples.Youneed to specifythelibrarypathsettingas/usr/lpp/db2710/db2710/jcc/lib,where
db2710isthehigh-levelqualifier foryourDB2libraries (notetheadditional subdirectoryjcc).TheDB2-suppliedjarfilesdb2jcc.jar,db2jcc_javax.jar, anddb2jcc_license_cisuz.jarneedto beaddedto thetrustedmiddleware classpathfollowingthisexample:
TMSUFFIX=/usr/lpp/db2710/db2710/jcc/classes/db2jcc.jar:\
/usr/lpp/db2710/db2710/jcc/classes/db2jcc_javax.jar:\ /usr/lpp/db2710/db2710/jcc/classes/db2jcc_license_cisuz.jar
wheredb2710isthehigh-levelqualifierfor yourDB2libraries.
JavaApplicationsinCICStellsyouhowto locateandcustomize JVMprofiles.If youhaveany applicationsthatuse theJDBC2.0API, youmustuseeither the JDBC2.0driver(whichsupports asubsetof theJDBC2.0application
programminginterface),ortheDB2UniversalJDBCdriver.TheJDBC2.0driver andtheDB2UniversalJDBCDriveralsosupportapplicationswrittenusingthe JDBC1.2API.
v FortheJDBC1.2driver,theJDBC 2.0driver,andtheDB2UniversalJDBC
Driver,youalso needtoaddtheDB2directory containingtheserializedprofile
DSNJDBC_JDBCProfile.sereitherto theJVM’sstandard classpath(the # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
CLASSPATHoptionintheJVMprofile),ortoitsshareableapplicationclasspath (theibm.jvm.shareable.application.class.pathoptionintheJVMproperties file).IftheJVMisaworkerJVMthatusesthesharedclasscache,itsshareable applicationclass pathistakenfromtheJVMprofilefor themasterJVMthat initializesthesharedclasscache,butitsstandardclasspathistakenfromthe JVMprofilefortheworkerJVMitself.Theserializedprofileisinitiallycreatedin theDB2directorywherethecommanddb2genjdbcwasissued,butitmighthave beensubsequentlymovedto anotherlocation.Thedirectorythatneedstobe addedto theJVM’sclass pathisthedirectory thatcurrentlycontainsthe serializedprofile.Whenyouhave addedthedirectoryto theJVM’sclasspath, youalsoneed toensurethattheDB2systemproperty
db2sqljjdbcprogram=dsnjdbcissetintheJVMpropertiesfilefor theJVM.This systempropertyisthedefault,soitdoes notneed tobeaddedto theJVM propertiesfile ifitisnotpresent.For fulldetails,seetheDB2UniversalDatabase forOS/390andz/OSApplicationProgrammingGuideandReferenceforJava whichisappropriatetoyourversionof DB2.
Requirementsforthe DB2-suppliedJDBCdrivers
v TousetheJDBC1.2driver ortheJDBC2.0drivershipped withDB2Version7
orlater, ortheDB2UniversalJDBCDriver,you needtoaddtheSDSNLOD2 librarytotheCICSSTEPLIBconcatenation.TheJDBC1.2drivershipped with DB2Version6does notrequirethislibrary.
v ToenableyourapplicationstousetheDB2-suppliedJDBCdrivers,youneedto
namethedriversbyusingthejdbc.driverssystem propertyintheJVM
propertiesfilesthatarereferencedbytheJVMprofilesusedbyyourapplications. TheCICS-suppliedsampleJVMpropertiesfilescontain commented-out
examplesofhow todothis.JavaApplicationsinCICStellsyouhow tolocate andcustomizeJVMpropertiesfiles.NamingtheJDBCdriversremovestheneed forapplicationsto loadthedriversthemselvesusingtheClass.forName()
method.Instead,theDriverManagerclassloadstherequiredclass forthe application.Thename ofthedriveristhesamefor theJDBC1.2driver,the JDBC2.0driver,andtheDB2Universal JDBCDriver,soifyoufollow this method,youdonotneed tochangeyourexistingapplicationsoryour JVM propertiesfileswhenyoumigratefromonedriverto another.
v WhenrunningtheJDBCdriverinaCICSenvironment,youmightwanttoalter
thesystempropertiesinyourJVMpropertiesfilesto tailoryourenvironment. WithCICS,theDB2environmentvariableDB2SQLJPROPERTIES,whichnames asystem propertiesfileto beused bytheJDBCdriver,isnotused.Instead, you cansetsystempropertiesrelatedtotheJDBCdriverintheJVMpropertiesfiles. ThesearethefilesnamedbytheJVMPROPSparameterinyourJVMprofiles.If youwanttoalterthesystemproperties,notethatmost DB2JDBCdriversystem propertiesarenotusedinaCICSenvironment.TheappendixesoftheDB2 UniversalDatabasefor OS/390andz/OSApplicationProgrammingGuideand ReferenceforJavahavea listofthepropertiesthatarenotused orhavea differentmeaninginaCICSenvironment,andthedocumentalsocontainsthefull listof DB2JDBCdriverproperties.ForDB2Version6, thedocumentnumberis SC26-9018,thefulllistofdriver propertiesisinChapter7,andthechangesto propertiesinaCICSenvironmentareinAppendixB.For DB2Version7,the documentnumberisSC26-9932,thefulllistof driverpropertiesisinChapter6, andthechangesto propertiesinaCICSenvironmentareinAppendixB.For DB2Version8,thedocumentnumberisSC18-7414,thefulllistof driver
propertiesisinChapter7, andthechangestopropertiesina CICSenvironment areinAppendixA.
connectto adatabase,youneedasuitablyconfigurednamingserver.Ifyou needto configureanaming server,see JavaApplicationsinCICS,inparticular thetopicsDefiningnameservers,EnablingJNDI references,SettingupanLDAP server,andSettingupaCOS NamingDirectoryServer.
RequirementsforusingJava2 securitywithJDBCorSQLJ
v TouseJDBCorSQLJ froma JavaprogramorenterprisebeanwithaJava2
securitypolicy mechanismactive,you mustusetheJDBC2.0driverortheDB2 UniversalJDBCDriver.TheJDBC1.2driverdoes notsupportJava2security, andwillfailwitha securityexception.
v Toactivatea Java2securitypolicymechanism,youneedto amendyour JVM
propertiesfiles.ThesearethefilesnamedbytheJVMPROPSparameterinyour JVMprofiles.JavaApplicationsinCICShasmoreinformationabout settingupa Java2 securitypolicy mechanism.In summary,to usethedefaultJava2security managerfora JVMwithaparticularJVMprofile,includethefollowingstatement intheJVMpropertiesfilethatisreferencedbythatJVMprofile:
java.security.manager=default
Youalso needtoname yourJava2 securitypolicyfile intheJVMpropertiesfile, usingthefollowing statement:
java.security.policy= /directory/tree/file.name
CICSsuppliesanexampleJava2 securitypolicyfor usewithJavaprogramsor enterprisebeansintheCICSenvironment,andyoucanfindtheexamplefile at
/usr/lpp/cicsts/cicsts31/lib/security/dfjejbpl.policy,wherecicsts31is yourchosenvaluefortheUSSDIRinstallationparameter thatyoudefinedwhen youinstalledCICSTS.
v TouseJDBCandSQLJ,youneed toamendyourJava2securitypolicy togrant
permissionstotheJDBCdriver,byaddingthefollowinglines:
grant codeBase "file:/usr/lpp/db2710/-" {
permission java.security.AllPermission;
};
Inplaceof db2710, specifyadirectory belowwhichallyourDB2Version7 librariesarelocated.Thepermissionsareappliedto allthedirectoriesandfiles belowthislevel.TheexampleJava2securitypolicydfjejbpl.policydoes not containthisstatement,soyouneedto addit.
v InyourJava2securitypolicy,youalso needtogrant readpermissions,by
addingthefollowinglines:
grant {
// allows anyone to read properties
permission java.util.PropertyPermission "*", "read";
};
Ifyoudonotdothis, runningaJavaprogramproducesAccessControlExceptions andunpredictableresults.TheexampleJava2securitypolicy dfjejbpl.policy
alreadycontainsthisstatement.
Programming
with
JDBC
and
SQLJ
in
the
CICS
DB2
environment
TheJDBC1.2driversupports theJDBC1.2levelapplicationprogramming interface.TheJDBC 2.0driver supportstheJDBC1.2APIandasubsetof the JDBC2.0API.The DB2UniversalJDBCDriverprovidesenhancedsupportfor the JDBC2.0API andmostoftheJDBC3.0API,andalso supportstheJDBC1.2API. #
# # #
AllthreedriverssupporttheSQLJPart 0(ANSI98)levelAPI. Javaprogramsfor CICSmust adhereto theprogramming rulesoftheseapplicationprogramming interfaces,which aremorerestrictivethan thegeneralCICSprogrammingmodel. You canfindmoreinformationabouttheJDBCAPIsat theJDBCWebsite, http://java.sun.com/products/jdbc.For informationaboutthefeaturesof theJDBC APIsthataresupportedbytheDB2-suppliedJDBCdrivers,andhowto codeand buildJavaapplicationsthatusetheJDBCandSQLJAPIs,seetheDB2Universal Database forOS/390andz/OSApplication ProgrammingGuideandReferencefor Javawhichisappropriateforyourversion ofDB2.Thedocumentnumberfor DB2 Version6 isSC26-9018,thedocumentnumberforDB2Version7isSC26-9932, andthedocumentnumberforDB2Version8isSC18-7414.
TheparticularprogrammingfeaturesthatapplytoJDBCandSQLJ whenused ina CICSenvironment aredescribedinthefollowing sections:
v “Acquiringa connectiontoa database”
– “Acquiringaconnection usingtheJDBCDriverManagerinterface” onpage
123
– “Acquiringaconnection usingtheDataSourceinterface” onpage 124
v “Committingaunitofwork”onpage129
v
“CICSabendsduringJDBCor SQLJrequests”onpage130
v “UsingJDBCandSQLJ inenterprisebeans:specialconsiderations” onpage 130
Acquiring
a
connection
to
a
database
Before executingSQLstatements,a JDBCorSQLJapplicationhastoacquire a connection orconnectioncontext toadatabase.Thedatabaseisidentifiedbya databaseUniformResourceLocator(URL)thatisprovidedto theJDBCdriver.The JDBC driverrecognizestwo typesof URL:
DefaultURL
AdefaultURLdoesnotincludethelocationnameof aDB2subsystem.A defaultURLforDB2for OS/390andz/OS canbespecifiedinoneoftwo formats:
jdbc:db2os390sqlj:
or
jdbc:default:connection
Whena defaultURLisspecified,theapplicationisgivenaconnection to thelocalDB2towhich CICSisconnected.If yourinstallationusesDB2 datasharing, youcanaccessallthedatainyoursysplexfromthelocal DB2.
Explicit URL
An explicitURLincludesthelocationnameof aDB2subsystem.Thebasic