TXSeriesfor Multiplatforms
CICS IIOP and Java Programming Guide
Version6.0
SC34-6635-00
TXSeriesfor Multiplatforms
CICS IIOP and Java Programming Guide
Version6.0
SC34-6635-00
Note
Beforeusingthisinformationandtheproductitsupports,besuretoreadthegeneralinformationunder“Notices”onpage 77.
FirstEdition(November2005) ThiseditionreplacesSC09-4585-02.
OrderpublicationsthroughyourIBMrepresentativeorthroughtheIBMbranchofficeservingyourlocality.
©CopyrightInternationalBusinessMachinesCorporation2001,2005.Allrightsreserved.
USGovernmentUsersRestrictedRights–Use,duplicationordisclosurerestrictedbyGSAADPScheduleContract
Contents
Figures . . . . . . . . . . . . . . . v
Tables . . . . . . . . . . . . . . . vii
Aboutthis book . . . . . . . . . . . ix
Whoshouldreadthisbook . . . . . . . . . ix
Documentorganization . . . . . . . . . . ix
Conventionsusedinthisbook . . . . . . . . x
Howtosendyourcomments . . . . . . . . xi
Chapter1.IntroductiontotheCICS IIOP ORB . . . . . . . . . . . . . . . . 1
DescriptionoftheCICSIIOPORB . . . . . . . 1
CORBAservicesandtheCICSIIOPORB . . . . 2
Loadbalancing . . . . . . . . . . . . 2
TheJavaclasslibraryfortheCICSAPI . . . . 2
Javadatabasesupport . . . . . . . . . . 3
IBMWebSphereStudioApplicationDeveloper support . . . . . . . . . . . . . . . 3
Chapter2.Developinga CICSIIOP ORB application . . . . . . . . . . . . . 5
Theinterfacedefinition . . . . . . . . . . . 5
Clientprogrammingmodel . . . . . . . . . 6
Serverprogrammingmodel . . . . . . . . . 6
Constructors . . . . . . . . . . . . . . 6
Objectreferences . . . . . . . . . . . . . 7
ExchangingdatabetweenJavaclassesandother programs . . . . . . . . . . . . . . . 7
Usingmanuallycreatedclasses . . . . . . . 7
Usingautomaticallygeneratedrecordbeansor classes . . . . . . . . . . . . . . . 7
Runninggeneratedrecordclasses . . . . . . 7
Errorhandling. . . . . . . . . . . . . . 8
Multilevelprograms. . . . . . . . . . . 9
Chapter3.Definingan interface . . . . 11
ThestructureofanIDLfile . . . . . . . . . 11
UsingtheJavaIDLcompiler. . . . . . . . . 12
Chapter4.DevelopingCICS applicationsinthe Javaprogramming language. . . . . . . . . . . . . . 15
Programminginformation . . . . . . . . . 15
SupportforJavabeans . . . . . . . . . 15
Resourceidentification. . . . . . . . . . 16
Methodarguments . . . . . . . . . . . 16
Memorymanagement . . . . . . . . . . 16
Lengthrestrictions . . . . . . . . . . . 17
Exceptionhandling. . . . . . . . . . . 17
Threads . . . . . . . . . . . . . . 20
TheJavaSecurityManager . . . . . . . . 20
Configuration . . . . . . . . . . . . 21
DescriptionoftheCICSJavaAPI . . . . . . . 21
Errorhandlingandabnormaltermination support. . . . . . . . . . . . . . . 21
APPCmappedconversations . . . . . . . 22
Authentication . . . . . . . . . . . . 23
BasicMappingSupport . . . . . . . . . 23
BuildingaCICSJavaapplication . . . . . . . 29
CICSJavaAPIexamples . . . . . . . . . . 31
Chapter5.Developingclients . . . . . 33
InitializingtheORB . . . . . . . . . . . 33
Creatingafactory . . . . . . . . . . . . 33
Creatinganobject . . . . . . . . . . . . 34
Chapter6.Implementingan interface 35 DevelopingaclassinJava . . . . . . . . . 35
InstallingaJavaclass . . . . . . . . . . . 36
UpdatingaJavaclass . . . . . . . . . . . 37
UsingtheJavaclassupdateprogram . . . . . 37
Chapter7.Problemdetermination . . . 39
Tracing . . . . . . . . . . . . . . . . 39
ORBtrace . . . . . . . . . . . . . . 39
Servercommunicationstrace . . . . . . . 39
IIOPlistenertrace . . . . . . . . . . . 40
Chapter8.Workloadmanagement . . . 41
DynamicDNS . . . . . . . . . . . . . 41
IProuter . . . . . . . . . . . . . . . 41
Configurationforworkloadmanagement . . . . 42
CICSRegionDefinition(RD) . . . . . . . 42
CICSObjectDefinition(OD). . . . . . . . 42
CICSworkloadmanagementsampleconfiguration 42 CICSserverconfiguration(foreachserverinthe servergroup). . . . . . . . . . . . . 43
IBMInteractiveNetworkDispatcher(IND) configuration . . . . . . . . . . . . . 43
Clientconfiguration . . . . . . . . . . 44
Runningtheworkloadmanagementsample . . 44
Chapter9.UsingSSLprotocol security 47 IntroductiontotheSSLprotocol . . . . . . . 47
ConfiguringSSLforCICS . . . . . . . . . 49
ConfiguringSSLbyusingawell-known,trusted CA . . . . . . . . . . . . . . . . 49
ConfiguringSSLbyusinganunknownCA. . . 51
Creatingaself-signedcertificate . . . . . . 52
ConfiguringandtestingtheCICSregionwith SSL . . . . . . . . . . . . . . . . 52
Changingthedefaultkeyringpassword . . . 52
UsingcertificatesfromotherIBMkeydatabase files . . . . . . . . . . . . . . . . 53
©CopyrightIBMCorp. 2001,2005 iii
Chapter10.UsingtheIIOPsecurity exit
program . . . . . . . . . . . . . . 55
Introductiontothesecurityexitprogram . . . . 55
Detailsofthesecurityuserexitprogram. . . . . 55
Chapter11.UsingtheIIOP certificate userexit program . . . . . . . . . . 61
Introductiontothecertificateuserexitprogram . . 61
Detailsofthecertificateuserexitprogram . . . . 61
AppendixA. Example application . . . 65
TheBankingexampleapplication . . . . . . . 65
Description . . . . . . . . . . . . . 65
Filesprovided . . . . . . . . . . . . 65
UsingMakefiles . . . . . . . . . . . . 66
Buildingandrunningthebankserver-side application . . . . . . . . . . . . . 66
BuildingandrunningthebankJavaclient application . . . . . . . . . . . . . 66
Buildingandrunningtheuserinterfaceto DFHORBUP . . . . . . . . . . . . . 67
Buildingandrunningtheworkloadmanagement client . . . . . . . . . . . . . . . 67
AppendixB. Installation and configuration . . . . . . . . . . . . 69
Serverinstallation . . . . . . . . . . . . 69
Configuration . . . . . . . . . . . . . 69
ServerConfiguration . . . . . . . . . . 69
Regionpropertiesfile . . . . . . . . . . 69
ObjectDefinition(OD). . . . . . . . . . 69
RegionDefinition(RD) . . . . . . . . . 70
ListenerDefinition(LD) . . . . . . . . . 70
ProgramDefinition(PD) . . . . . . . . . 70
TransactionDefinition(TD) . . . . . . . . 70
Configuringforsecurity . . . . . . . . . 70
Workloadmanagementconfiguration. . . . . 71
Serverinitialization. . . . . . . . . . . . 71
AppendixC.System exceptionsand minorcodes . . . . . . . . . . . . 73
MinorCodes . . . . . . . . . . . . . . 73
Minorcodemessages . . . . . . . . . . . 73
Notices . . . . . . . . . . . . . . 77
Trademarksandservicemarks . . . . . . . . 78
Index . . . . . . . . . . . . . . . 81
Figures
1. CICSIIOPORBprogrammingmodel . . . . 5
2. TheCICSerrorandexceptionclasshierarchy 8 3. TheBankAccount.idlfile . . . . . . . . 12
4. Instantiatingthefactory . . . . . . . . 33
5. Usingthefactorytocreateanobject . . . . 34
6. DevelopingaJavaclass . . . . . . . . 36
7. TheCOMMAREAfortheDFHORBUP program . . . . . . . . . . . . . 37
8. TheIProuterimplementation . . . . . . 42
9. Addressentries . . . . . . . . . . . 43
10. AsampleISSconfigurationfile . . . . . . 44
11. IIOPsecurityexitdatastructure. . . . . . 57
12. ThedefinitionoftheIIOPcertificateuserexit structure . . . . . . . . . . . . . 62
©CopyrightIBMCorp. 2001,2005 v
Tables
1. Conventionsthatareusedinthisbook. . . . x 2. Datatypemappings. . . . . . . . . . 11 3. MappingbetweenCICSconditionsandJava
exceptions . . . . . . . . . . . . . 18
4. APPCmappedconversationsandJavaclasses 22 5. Classesandmethodsforkeyedfiles . . . . 26 6. Classesandmethodsfornonkeyedfiles 26
©CopyrightIBMCorp. 2001,2005 vii
About this book
Thismanualprovides guidanceand referenceinformationabouthowtowrite Java™applicationsontheCICS® IIOPObjectRequestBroker (ORB).TheCICS IIOP ORBconformstothestandardsthatare prescribedbytheObjectManagement Group’sCommonObjectRequestBrokerArchitecture (CORBA)specification.The Internet Inter-ORBProtocol(IIOP)isbasedonTCP/IP,whichenablescompliant ORBs tocommunicateovertheInternet.
TheCICS IIOPORBissupportedontheAIX®platform.TheuseofJavafor writingCICS serversissupportedonAIX, Windows®,and Solarisplatforms.
Who should read this book
Themanual isintended primarilyforapplicationprogrammers,butwillalsobe usefultosystem programmersandsystemsanalysts.BecauseCICSresource definitions arereferredtothroughoutthis book,youmustbe familiarwithhow theyare definedand usedinCICS.Resourcedefinitions aredescribedinthe TXSeriesforMultiplatformsAdministrationReference.
ThisguideassumesthatyouhaveaccesstoreferencedocumentationforCORBA and arefamiliarwith theJava programminglanguage.
Document organization
Thisguideisorganizedasfollows:
v Chapter1,“IntroductiontotheCICSIIOPORB,”onpage1isanintroductionto theCICSIIOPORBandtheservicesthatit provides.
v Chapter2,“Developinga CICSIIOPORBapplication,”onpage5describesthe stepsfordevelopinganapplication ontheCICS IIOPORB.
v Chapter3,“Defininganinterface,”onpage11 describeshowtouseInterface DefinitionLanguage(IDL)tocreateaninterface.
v Chapter4,“DevelopingCICSapplicationsintheJavaprogramminglanguage,”
onpage15describes howtodevelop CICSapplicationswith theCICSJava classes.
v Chapter5,“Developingclients,”onpage33outlinesthestepsthatarerequired foraclientprogramtoaccesstheCICSIIOPORB.
v Chapter6,“Implementinganinterface,”onpage35describes howtodevelop, update,andinstall aJava class.
v Chapter7,“Problem determination,”onpage39describesproblem determinationontheCICSIIOPORB.
v Chapter8,“Workloadmanagement,”onpage41describes loadbalancing betweenseveralCICSIIOPORBservers.
v Chapter9,“UsingSSLprotocolsecurity,”onpage47describeshow tousethe SecureSocketLayer(SSL)protocol.
v Chapter10,“UsingtheIIOPsecurityexitprogram,”onpage55describes howto usetheIIOPsecurityexitprogram.
v Chapter11,“UsingtheIIOPcertificate userexitprogram,”onpage61describes howtousetheIIOPcertificateexitprogram.
©CopyrightIBMCorp. 2001,2005 ix
v AppendixA, “Exampleapplication,”onpage65describes howtousethe exampleprograms.
v AppendixB,“Installationand configuration,”onpage69provides installation andconfigurationinstructions.
v AppendixC,“System exceptionsandminor codes,”onpage73provides informationaboutsystem exceptionsandminorcodes.
Conventions used in this book
TXSeries® forMultiplatformsdocumentationusesthefollowingtypographicaland keying conventions.
Table1.Conventionsthatareusedinthisbook
Convention Meaning
Bold Indicatesvaluesthatyoumustuseliterally,suchascommands, functions,andresourcedefinitionattributesandtheirvalues.When referringtographicaluserinterfaces(GUIs),boldalsoindicates menus,menuitems,labels,buttons,icons,andfolders.
Monospace Indicatestextthatyoumustenteratacommandprompt.
Monospacealsoindicatesscreentextandcodeexamples.
Italics Indicatesvariablevaluesthatyoumustprovide(forexample,you supplythenameofafileforfile_name).Italicsalsoindicates emphasisandthetitlesofbooks.
<> Enclosesthenamesofkeysonthekeyboard.
<Ctrl-x> Wherexisthenameofakey,indicatesacontrol-charactersequence.
Forexample,<Ctrl-c>meansholddowntheCtrlkeywhileyou presstheckey.
<Return> ReferstothekeylabeledwiththewordReturn,thewordEnter,or theleftarrow.
% RepresentstheUNIX®command-shellpromptforacommandthat doesnotrequirerootprivileges.
# RepresentstheUNIXcommand-shellpromptforacommandthat requiresrootprivileges.
C:\> RepresentstheWindowscommandprompt.
> Whenusedtodescribeamenu,showsaseriesofmenuselections.
Forexample,″SelectFile>New″means″FromtheFilemenu,select theNewcommand.″
Enteringcommands Wheninstructedto“enter”or“issue”acommand,typethe commandandthenpress<Return>.Forexample,theinstruction
“Enterthelscommand”meanstypelsatacommandpromptand thenpress<Return>.
[] Enclosesoptionalitemsinsyntaxdescriptions.
{} Encloseslistsfromwhichyoumustchooseaniteminsyntax descriptions.
| Separatesitemsinalistofchoicesenclosedin{}(braces)insyntax descriptions.
... Ellipsesinsyntaxdescriptionsindicatethatyoucanrepeatthe precedingitemoneormoretimes.Ellipsesinexamplesindicatethat informationwasomittedfromtheexampleforthesakeofbrevity.
Table1.Conventionsthatareusedinthisbook (continued)
Convention Meaning
IN Infunctiondescriptions,indicatesparameterswhosevaluesare usedtopassdatatothefunction.Theseparametersarenotusedto returnmodifieddatatothecallingroutine.(DonotincludetheIN declarationinyourcode.)
OUT Infunctiondescriptions,indicatesparameterswhosevaluesare usedtoreturnmodifieddatatothecallingroutine.These parametersarenotusedtopassdatatothefunction.(Donot includetheOUTdeclarationinyourcode.)
INOUT Infunctiondescriptions,indicatesparameterswhosevaluesare passedtothefunction,modifiedbythefunction,andreturnedto thecallingroutine.TheseparametersserveasbothINandOUT parameters.(DonotincludetheINOUTdeclarationinyourcode.)
$CICS IndicatesthefullpathnameofthelocationinwhichtheCICS productisinstalled;forexample,/usr/lpp/cicsonAIX.IftheCICS environmentvariableissettotheproductpathname,youcanuse theexamplesexactlyasshowninthisbook;otherwise,youmust replaceallinstancesof$CICSwiththeCICSproductpathname.
CICSonOpen Systems
ReferscollectivelytotheCICSproductforallsupportedUNIX platforms.
TXSeriesfor Multiplatforms
ReferscollectivelytotheCICSforAIX,CICSforHP-UX,CICSfor Solaris,andCICSforWindowsproducts.
CICS RefersgenericallytotheCICSforAIX,CICSforHP-UX,CICSfor Solaris,andCICSforWindowsproducts.OtherCICSproductsin theCICSFamilyaredistinguishedbytheiroperatingsystem(for example,IBM®mainframe-basedCICSfortheESA,MVS™,and VSEplatforms).
How to send your comments
Yourfeedbackisimportantinhelpingtoprovidethemostaccurate andhighest qualityinformation.Ifyouhaveanycommentsaboutthisbookoranyother TXSeriesforMultiplatforms documentation,sendyour commentsbye-mailto [email protected]. Besuretoinclude thenameofthebook,thedocument number ofthebook,theversionofTXSeriesforMultiplatforms,and,ifapplicable, thespecific locationof theinformationyouarecommentingon(forexample,a pagenumber ortablenumber).
Aboutthisbook xi
Chapter 1. Introduction to the CICS IIOP ORB
TheCICS InternetInter-ORBProtocol(IIOP)ObjectRequestBroker (ORB)enables CICS applicationstocommunicatewithapplicationsthatusetheIIOPprotocolthat was definedaspartof theCommonObject RequestBrokerArchitecture (CORBA).
CORBAclientscanusecommunicatewithCICS applications,andCICS applicationscansendrequeststoCORBAservers.
TheObject ManagementGroup(OMG)created theCORBAspecificationto
facilitatethedevelopmentofobject-orientedapplicationsacrossanetwork. CORBA objectsare standardsoftware objectsthatareimplementedinanyobject-oriented programming language.AnORBmediatesthetransfer ofmessagesbetweenclient programsand objects.Whena clientprograminvokesamethod onan object,the ORBinterceptstherequestand findsanobjectthatisimplementingthatmethod.
Theresult ofthemethodinvocationisreturnedtotheclientprogrambytheORB.
From theprogrammer’spointofview,alloftheworkseemstobe doneonone computersystem.
IIOPenablescommunicationsbetweendifferentORBimplementations.TheIIOPis based onTCP/IPand includesadditional message-exchangeprotocols thatare definedbyCORBA.
TheCICS IIOPORBissupportedonAIX,withthefollowingprerequisites:
v Youmust haveJava2 SDKVersion1.4.2,orhigher,installed.
v Youmust setJAVA_HOMEto/usr/java14ortothelocationofyourSDK installation.
Description of the CICS IIOP ORB
Thissectionsummarizesthefunctionsand restrictionsoftheCICSIIOPORB.
TheCICS IIOPORBenablesyoutousetheInternet tointegrateCICSapplications with CORBA-compliantclientORBs.TheCICSIIOPORBistheIBM
implementationoftheJavaORB,whichhasbeen enhancedtoruninsideCICS.
TheCICS IIOPORBsupportsthefollowingfunctions:
v InboundIIOPfromanyCORBA-compliantclient v OutboundIIOPtoanyCORBA-compliantserver
v Objectinterfacesthatare definedintheCORBAInterfaceDefinition Language (IDL)
v ObjectimplementationsthatarewritteninJava v Theuseofservergroupsforloadbalancing v TheSecureSocketLayer(SSL)protocol
All objectsthatareexportedfromtheserverarestatelessobjects,whichmeansthat nodataisheldintheobjectbetweensuccessivemethodcalls.Attheendofevery method,theobjectimplementationmust freeallresourcesthathavebeenacquired bytheobject.
©CopyrightIBMCorp. 2001,2005 1
