Java Applications in CICS

(1)

CICS

Transaction

Server

for

z/OS

Java

Applications

in

CICS

Version

2 Release

3

SC34-6238-05

(2)

(3)

CICS

Transaction

Server

for

z/OS

Java

Applications

in

CICS

Version

2 Release

3

SC34-6238-05

(4)

Note!

Beforeusingthisinformationandtheproductitsupports,besuretoreadthegeneralinformationunder“Notices”onpage 419.

Fifthedition(April2007)

ThiseditionappliestoVersion 2 Release 3ofCICSTransactionServerforz/OS,programnumber5697-E93,and toallsubsequentversions,releases,andmodificationsuntilotherwiseindicatedinneweditions.Makesureyouare usingthecorrecteditionfortheleveloftheproduct.

OrderpublicationsthroughyourIBMrepresentativeortheIBMbranchofficeservingyourlocality.Publicationsare notstockedattheaddressgivenbelow.

Atthebackofthispublicationisapageentitled“SendingyourcommentstoIBM”.Ifyouwishtosendcommentsby mail,pleaseaddressthemto:

User Technologies Department Mail Point 095

IBM United Kingdom Laboratories Hursley Park

WINCHESTER Hampshire SO21 2JN United Kingdom

WhenyousendinformationtoIBM,yougrantIBManonexclusiverighttouseordistributetheinformationinany wayitbelievesappropriatewithoutincurringanyobligationtoyou.

©CopyrightInternationalBusinessMachinesCorporation1999,2007.Allrightsreserved.

(5)

Part

1. Java

development

roadmaps

.

. 1

Chapter1. Javadevelopmentroadmaps . . . 3

JavaapplicationroadmapforCICS . . . 3

CICSIIOPapplicationroadmap . . . 3

CICSenterprisebeansroadmap . . . 3

Part

2. Developing

Java

applications

for

CICS

.

. 5

Chapter2. JavaapplicationsinCICS . . . 7

Typesof JavaapplicationinCICS . . . 7

Chapter3. WhatyouneedtoknowaboutCICS . . . 9

CICStransactions . . . 9

CICStasks . . . 10

CICSapplicationprograms . . . 10

CICSservices . . . 10

Chapter4. Javaprogrammingin CICS . . . 13

TheJCICSclass library. . . 13

Translation . . . 13

JavaBeans . . . 14

Librarystructure . . . 14

CICSresources . . . 15

CICSstoragerequirements . . . 15

Commandarguments . . . 15

Serializable classes . . . 16

Using theJavaRecordFramework . . . 16

System.outandSystem.err . . . 16

Threads . . . 17

JCICS commandreference . . . 17

CICSexceptionhandlinginJavaprograms . . . 18

Error handlingandabnormal termination . . . 19

APPCmappedconversations . . . 20

BasicMappingSupport (BMS) . . . 20

Diagnosticservices . . . 20 Document services . . . 20 Environmentservices . . . 21 Fileservices. . . 23 Program services . . . 26 Schedulingservices . . . 26 Serializationservices. . . 27 Storage services . . . 27

Temporarystoragequeueservices . . . 27

©CopyrightIBMCorp.1999,2007

iii

||

(6)

Terminalservices . . . 27

Transientdataqueueservices . . . 28

Unitofwork(UOW)services. . . 28

WebandTCP/IPservices . . . 29

UnsupportedCICSservices . . . 30

JCICS exceptionmapping. . . 30

Using JCICS. . . 31

Writing themain method . . . 31

Creatingobjects . . . 31

Using objects . . . 32

Chapter5.AccessingdatafromCICSapplicationswritteninJava . . . . 33

Using DataAccess beans . . . 34

Chapter6. Usingthe JCICSsampleprograms . . . 35

Building thesample programs . . . 36

Building theJavasamples. . . 36

DefiningCICSresources . . . 37

CICSWebsupport . . . 37

RunningtheJavasamples . . . 37

RunningtheHelloWorldsamples . . . 37

RunningtheProgramControl sample . . . 38

RunningtheTDQsample . . . 39

RunningtheTSQsample . . . 39

Runningthewebsample . . . 39

Part

3. Using

JVMs

.

. 43

Chapter7.AboutJVMs . . . 45

Thestructureof aJVM . . . 46

Classes ina JVM . . . 46

Wherea JVMisconstructed . . . 50

JVMs andthez/OSsharedlibraryregion . . . 50

Storage heapsina JVM . . . 51

ThreadsandsocketsinaJVM . . . 53

HowCICScreatesJVMs . . . 54

Executionkey(EXECKEYattribute) . . . 55

JVMprofiles (JVMPROFILEattribute) . . . 56

HowCICSlocatesthePROGRAM resourcedefinitiontocreateaJVM . . . 57

HowCICSmanagesJVMsintheJVMpool . . . 58

HowCICSallocatesJVMs toapplications . . . 62

HowCICSdealswithincomingrequests foraJVM . . . 64

HowCICSdealswitha queueof requestswaitingfora JVM . . . 65

Theselectionmechanism . . . 67

HowJVMs arereusedandreset . . . 68

ResettableJVMs(REUSE=RESET) . . . 68

ContinuousJVMs (REUSE=YES) . . . 73

Single-useJVMs (REUSE=NO). . . 76

Thesharedclasscache . . . 77

Removalof supportforCICSTransactionServerfor OS/390,Version1Release 3 JVMs . . . 80

Chapter8. Settingup andusingJVMs . . . 83

Giving CICSregionsaccessto z/OSUNIXSystemServicesandHFS directoriesandfiles . . . 84

|| || || # # || || || || || || || || || || || | ||

(7)

Giving CICSregionsaz/OSUNIXuseridentifier(UID)andgroupidentifier

(GID)andsettingupahomedirectory . . . 85

Giving CICSregionspermissiontoaccessHFSdirectoriesandfiles . . . . 87

SettingupJVMprofilesandJVMpropertiesfiles . . . 91

Enabling CICSto locatetheJVMprofiles andJVMpropertiesfiles. . . 92

Choosing aJVMprofileandJVMpropertiesfile. . . 94

Customizing orcreatingJVMprofilesandJVMpropertiesfiles . . . 98

Settingupthesharedclasscache . . . 102

Definingthesharedclasscache . . . 103

Enabling JVMstouse thesharedclasscache . . . 105

Managingthesharedclasscache . . . 106

Startingthesharedclass cache . . . 106

Adjustingthesizeof thesharedclasscache . . . 108

UpdatingclassesorJAR filesinthesharedclass cache . . . 109

Terminating thesharedclasscache . . . 112

Monitoringthesharedclasscache . . . 113

Enabling applicationstousea JVM . . . 115

SettingupaPROGRAMresourcedefinitionfor aJavaprogramto runina JVM . . . 116

Addingapplicationclassesto theclasspathsfor aJVM . . . 118

ManagingyourJVMs . . . 122

MonitoringJVMactivity . . . 122

Terminating ordisablingtheJVMpool . . . 124

RedirectingJVMoutput . . . 125

ProblemdeterminationforJVMs . . . 128

ControllingtracingforJVMs. . . 130

Debugging anapplicationthatisrunningina CICSJVM . . . 132

Attaching adebuggerto aCICSJVM . . . 133

TheCICSJVMpluginmechanism . . . 135

Part

4. CICS

and

IIOP

.

. 139

Chapter9. IIOPsupportinCICS . . . 141

TheObjectRequestBroker(ORB) . . . 141

CICSIIOPapplicationmodels . . . 142

Some commonCORBAterminology . . . 142

Chapter10.TheIIOPrequestflow . . . 145

IIOPinasysplex. . . 147

Workloadbalancingof IIOPrequests . . . 147

DomainNameSystem(DNS)connection optimization . . . 148

Connectionoptimizationregistration. . . 148

Nameresolutionexample . . . 149

Resourcedefinitionfor DNSconnection optimization . . . 150

Avoiding DomainNameSystem(DNS)problems . . . 151

Authenticationof IIOPrequests . . . 152

TheIIOPuser-replaceablesecurityprogram. . . 153

CONNECTIONauthentication . . . 153

Chapter11.ConfiguringCICSforIIOP . . . 155

Settingupthehost systemfor IIOP . . . 155

Defininga shelfdirectory. . . 156

Definingname servers . . . 157

Enabling JNDIreferences . . . 157

SettingupanLDAPserver . . . 158

If youhaveanexistingLDAPserverconfiguredforWebSphere . . . 158

Contents

v

| || || || || || || || || || || || || || || || || ||

(8)

Configuringanew LDAPserver . . . 159

Determiningthevaluesfor thesystem propertiesandaddingthemto your JVMpropertiesfiles. . . 162

TheLDAPnamespacestructure . . . 164

Thecontainerroot . . . 164

Thelegacyroot . . . 164

Domains. . . 164

Nodes. . . 165

Securityconsiderations . . . 165

SettingupaCOSNamingDirectoryServer . . . 168

SettingupTCP/IPfor IIOP . . . 168

Using DNSconnection optimization . . . 169

SettingupCICSfor IIOP. . . 169

DefiningCICSstart-upjobstream. . . 169

DefiningCICSresources. . . 171

Chapter12.ProcessingIIOPrequests . . . 175

Obtaining aCICSuserID . . . 175

Using theIIOPuser-replaceable securityprogram . . . 175

Using DFHXOPUS . . . 177

Obtaining aCICSTRANSID . . . 178

Pattern matching. . . 179

Name-manglingoftheOPERATIONfield. . . 179

REQUESTMODELexamples . . . 180

Dynamic routing . . . 180

Namemanglingfor Java . . . 180

WhymanglingisnecessaryforJavanames. . . 180

HowJavanamesaremangled . . . 181

HowmanglingaffectsCICS. . . 181

Handling IIOPdiagnostics . . . 182

Part

5. Using

enterprise

beans

.

. 183

Chapter13.Whatareenterprisebeans? . . . 185

Enterprise beans—thebigpicture . . . 185

JavaBeansandEnterprise JavaBeans. . . 186

Components . . . 186

JavaBeans . . . 187

Enterprise JavaBeans . . . 187

TheEJB server—overview . . . 188

TheEJB container—overview . . . 188

Theexecutionenvironment . . . 189

Enterprise beans—thehome andcomponentinterfaces . . . 189

Enterprise beans—thedeployment descriptor . . . 190

Typesof enterprisebean. . . 191

Session beans . . . 191

Entity beans . . . 192

Session beansandentitybeanscompared . . . 193

Enterprise beans—managingtransactions . . . 194

Enterprise beans—securityoverview . . . 195

Authentication. . . 195

Access control . . . 195

TheJava2securitymanager . . . 196

Enterprise beans—usertasks . . . 196

Thebeanprovider . . . 196

Theapplicationassembler . . . 197

|| || || || || ||

(9)

Thedeployer . . . 197

Thesystem administrator . . . 197

Deployingenterprisebeans—overview. . . 198

ConfiguringCICSasanEJB server—overview. . . 200

Logical servers—enterprisebeansinasysplex . . . 201

SettingupalogicalEJB server . . . 203

Enterprise beans—whatcanaclientdowithabean? . . . 207

Geta referencetothebean’shome. . . 207

Usethehomeinterface . . . 208

Usethecomponentinterface . . . 208

Enterprise beans—whatcanabean do? . . . 208

Benefitsof EJBtechnology . . . 209

Requirements forEJBsupport. . . 210

Hardware . . . 210

Software. . . 210

Chapter14.SettingupanEJBserver . . . 213

Settingupasingle-regionEJBserver . . . 213

BeforerunningtheEJB IVP. . . 214

AfterrunningtheEJBIVP—optionalsteps . . . 219

Testing yourEJBserver . . . 220

RunningtheEJBIVP . . . 220

Using theEJB “HelloWorld”sample . . . 220

Using theEJB BankAccountsample . . . 221

Using yourownenterprisebeans. . . 221

Settingupamulti-regionEJB server . . . 221

MigratinganEJBservertoCICSTSforz/OS,Version 2.3 . . . 224

Upgradinga single-regionCICSEJB/CORBAserver . . . 224

Upgradinga multi-regionCICSEJB/CORBAserver . . . 225

Migrationtips . . . 229

Chapter15.RunningtheEJBIVP. . . 231

Prerequisites fortheEJBIVP . . . 231

InstallingtheEJB IVP . . . 231

HFSsetup . . . 232

CICSsetup. . . 232

Configuringtheclient . . . 233

RunningtheEJBIVP . . . 234

Chapter16.RunningthesampleEJBapplications . . . 237

TheEJB “HelloWorld”sample application . . . 237

WhattheEJB “HelloWorld”sample does. . . 237

Prerequisites fortheEJB“HelloWorld”sample . . . 238

Supplied componentsof theEJB “HelloWorld”sample. . . 238

InstallingtheEJB “HelloWorld”sample . . . 239

Testing theEJB“HelloWorld”sample . . . 241

TheEJB BankAccountsampleapplication . . . 245

WhattheEJB BankAccountsampledoes . . . 245

Prerequisites fortheEJBBankAccountsample . . . 246

Supplied componentsof theEJB BankAccountsample . . . 247

Securityof theEJBBankAccountsample . . . 248

InstallingtheEJB BankAccountsample . . . 253

Testing theEJBBankAccountsample. . . 256

Anoteaboutdistributedtransactions . . . 260

Anoteaboutdataconversion . . . 261

Contents

vii

|| || || || || ||

(10)

Chapter17.Writingenterprise beans . . . 263

Preparingbeansfor execution. . . 263

Coding asessionbean . . . 264

Coding thehomeinterface . . . 264

Coding theremoteinterface. . . 264

Coding thebeanimplementation . . . 265

Compilingthecode. . . 267

Packagingthecode. . . 267

Writing theclientprogram . . . 267

Creatingobjectreferencesinthenamespace . . . 267

Using JNDItoobtainbeanreferences . . . 268

Writing aClientprogramtouse LDAP . . . 268

Writing aclientprogramtouseCOS Naming . . . 271

Transactioninteroperabilitywithwebapplicationservers . . . 273

WorkingwithEJBHandles,HomeHandlesandEJBMetaData . . . 274

Using EDFwithenterprisebeans. . . 274

Bean-to-beancommunication . . . 275

Chapter18.Deployingenterprise beans . . . 277

Thedeployment toolsfor enterprisebeansinaCICSsystem . . . 277

TheAssemblyToolkit(ATK)andtheApplicationAssemblyTool (AAT) . . . 277

Theresourcemanagerfor enterprisebeans. . . 277

CREA. . . 277

Using CICSdeployment toolsfor enterprisebeans . . . 278

Chapter19.Updatingenterprisebeansin aproductionregion . . . 281

Theproblem . . . 281

Possiblesolutions . . . 284

Solutionsfora singlelistener/AOR . . . 284

Solutionsfora multi-regionEJBserver . . . 288

Other possiblesolutions . . . 291

Chapter20.TheCCIConnectorforCICSTS . . . 293

Overview oftheCCIConnectorforCICSTS . . . 293

Thebackground—connectors . . . 293

TheCommonClientInterface . . . 294

TheCCIConnectorforCICSTS . . . 296

Benefitsof theCCIConnector forCICSTS . . . 297

Sampleapplications . . . 298

Using theCCIConnectorfor CICSTS. . . 298

Whichclassestouse? . . . 299

DataconversionandtheCCIConnectorforCICSTS . . . 302

Installing theCCIConnectorfor CICSTS. . . 302

Requirements fortheCCIConnectorforCICSTS . . . 302

CompilingCCIapplications . . . 302

RunningCCIapplicationsonCICSTS. . . 302

Using thesample utilityprogramstomanage andacquire aconnectionfactory 302 Installingthepublish andretractsampleprograms . . . 303

Publishinga connectionfactoryusingCICSConnectionFactoryPublish . . . 303

Looking upa connectionfactory . . . 305

Retracting aconnectionfactoryusingCICSConnectionFactoryRetract . . . 305

TheCCIConnectorsampleapplication . . . 306

Requirements fortheCCIConnectorsample . . . 307

InstallingtheCCIConnectorsample . . . 307

Testing thesample . . . 308

Problemdetermination . . . 309 # # || || || || || || || || || || || || || || || || || || || || || || || ||

(11)

CCIConnectorfor CICSTSmessages . . . 309

Tracing theCCIConnectorfor CICSTS . . . 309

MigratingfromtheCICSConnectorfor CICSTSto theCCIConnector for CICSTS . . . 309

Chapter21.TheCICSConnectorforCICSTS . . . 311

Overview oftheCICSConnectorforCICSTS . . . 311

WhatareCICSconnectors? . . . 312

TheCICSConnectorforCICSTS . . . 313

Thebackground—accessingCICSprogramsfromJava . . . 313

Benefitsof theCICSConnectorfor CICSTS . . . 316

Using theCICSConnectorfor CICSTS’sCCFinterface . . . 317

SettingtheCCFinterface attributes . . . 318

IntroducingVisualAge forJavaEnterpriseAccessBuilder. . . 321

DataconversionandtheCICSConnectorforCICSTS. . . 322

TheCICSConnectorforCICSTS—usingtheCICSTransactionGatewayAPI 323 ECIRequest . . . 323

JavaGateway . . . 325

Restrictions andrecommendationsfor theCICSConnectorfor CICSTS . . . 325

InstallingtheCICSConnectorforCICSTS . . . 327

Requirements fortheCICSConnectorforCICSTS . . . 327

Installingtheconnector . . . 327

CICSConnectorfor CICSTSmessages . . . 328

Tracing theCICSConnectorfor CICSTS. . . 328

CICStrace . . . 328

CICSTransactionGateway trace. . . 328

Chapter22.DealingwithCICSenterprisebeanproblems . . . 331

CICSenterprisebeanset-upproblems. . . 331

Methods thatrequiremultiplerequestprocessors. . . 331

Using EJBserverruntimediagnostics . . . 332

CICSenterprisebeanerrorsandmessages. . . 332

JVMtrace . . . 333

Debugging JavaapplicationsinCICS . . . 333

Using EJBclientruntimediagnostics . . . 334

CORBAexceptions . . . 335

Class versionissueswithRMI-IIOP . . . 336

Using EJBtraceandserviceabilitycommands . . . 337

Chapter23.Managingsecurityforenterprisebeans . . . 339

Protecting JavaapplicationsinCICSbyusingtheJava2securitypolicy mechanism . . . 339

Enabling aJavasecuritymanagerandspecifyingpolicyfilesfor aJVM 340 Specifyingpolicy filesto applyto allJVMs . . . 342

TheCICS-supplied enterprisebeanspolicyfile,dfjejbpl.policy . . . 343

Using enterprisebeansecurity. . . 344

Definingfileaccesspermissionsforenterprisebeans . . . 345

Derivingdistinguished names . . . 346

Securityroles . . . 347

Deployed securityroles . . . 348

Enabling anddisablingsupportforsecurityroles . . . 349

Securityrolereferences . . . 349

Charactersubstitutionindeployedsecurityroles . . . 349

Securityroles inthedeployment descriptor . . . 351

Implementingsecurityroles. . . 352

Using theRACFEJBROLEgeneratorutility . . . 353

Contents

ix

|| || | || || || ||

(12)

Definingsecurityrolesto RACF . . . 354

Chapter24.CICSPlex SMwithEnterpriseJavaBeans . . . 357

CICSPlex SMsupportforenterprisebeans . . . 357

CICSPlexSM definitionsupportforenterprisebeans . . . 357

BASlogical scopeconsiderations . . . 358

Enterprise JavaBeancomponentmigration . . . 359

CICSPlexSM inquirysupportforenterprisebeans . . . 359

Typesof inquiryavailableforenterprisebeanobjects . . . 360

Using CICSPlexSMtomanage EnterpriseJavaBeanworkloads . . . 360

Workloadbalancing. . . 361

Workloadseparation . . . 361

CICSPlexSM resourcemonitoringconsiderationsfor EnterpriseJavaBeans 362 CICSPlexSM real-timeanalysisconsiderationsfor EnterpriseJavaBeans 362

Part

6. Using

stateless

CORBA

objects

.

. 365

Chapter25.StatelessCORBAobjects . . . 367

DevelopingstatelessCORBAobjects . . . 367

Obtaininganinteroperableobjectreference (IOR) . . . 369

CreatingtheInterfaceDefinitionLanguage(IDL) . . . 370

DevelopinganIIOPserverprogram. . . 371

IDLexample . . . 373

Serverimplementation. . . 373

Resourcedefinitionfor example . . . 373

DevelopingtheIIOPclientprogram . . . 374

Client example . . . 374

DevelopinganRMI-IIOPstatelessCORBAapplication . . . 376

Stand-aloneCICSCORBAclientapplications . . . 378

CORBAinteroperability . . . 378

Using non-JavaCORBAclients . . . 379

Writing aCORBAclientto anenterprisebean . . . 379

Enterprise beansasCORBAclients. . . 379

Codesets . . . 380

Chapter26.MigratingIIOPapplicationsfrom CICSTS1.3 . . . 381

Chapter27.UsingtheIIOPsamples . . . 383

SettinguptheIIOPsampleenvironment . . . 383

RunningtheIIOPHelloWorldsample . . . 387

Building theserversideHelloWorldapplication. . . 387

Building theclientside HelloWorldapplication . . . 387

RunningtheHelloWorldsampleapplication . . . 388

RunningtheIIOPBankAccountsample . . . 388

CreatingtheVSAMfile . . . 388

Building theserversideBankAccount application. . . 388

Building theclientside BankAccountapplication . . . 388

RunningtheBankAccountsampleapplication . . . 389

Part

7. Using

VisualAge

for

Java

ET/390.

.

. 391

Chapter28.VisualAgeforJava,ET/390 . . . 393

RunningaJavaprogramobjectinCICS . . . 394

Run-timerequirements . . . 394 || || || || || || ||

(13)

Chapter29.Javahot-poolingconcepts . . . 397

OpentransactionenvironmentTCBs . . . 397

H8mode TCBallocationforhot-pooling . . . 398

Using hot-poolingwithET/390. . . 399

DefiningLanguageEnvironmentrun-timeoptions. . . 399

Allocatingstorage . . . 399

Defininghot-pooledJavaprogramobjects . . . 400

Programmingfor Javahot-pooling . . . 401

Static storageandstaticinitializers . . . 401

Programminginterfaces . . . 402

Protection keys . . . 402

Exitprogramminginterface (XPI). . . 402

Hot-poolingexitprogram. . . 402

Security . . . 403

Problemdetermination . . . 403

Bibliography . . . 405

TheCICSTransactionServerfor z/OSlibrary . . . 405

Theentitlementset . . . 405

PDF-only books . . . 405

Other CICSbooks . . . 407

Booksfromrelatedlibraries. . . 407

Determiningif apublicationiscurrent . . . 407

Accessibility . . . 409

Index . . . 411

Notices . . . 419

Trademarks. . . 420

Sendingyour commentstoIBM . . . 421

(14)

(15)

Preface

What

this

information

is

about

This informationtellsyouhow todevelop anduseJava™applicationsand

enterprisebeansinCICS®.It isdesignedto beaccessed onlinethroughtheCICS InformationCenter. Whentheinformationisaccessedinthisway,hypertextlinks areusedto movelogicallybetweensets ofrelatedtopics;theinformationis accessed logically,ratherthanreadsequentially.

TheinformationisalsoavailableasanAdobeAcrobatportabledocumentformat (PDF)file.This canbereadsequentially,or printedintraditional“book”format.

Who

should

read

this

information

This informationisintended for: v

ExperiencedJavaapplicationprogrammerswho mayhavelittleexperienceof

CICS,andnogreatneed toknowmoreabout CICSthanisnecessaryto develop andrunJavaprograms.

v ExperiencedCICSusersandsystem programmers,whoneed toknowabout

CICSrequirementsforJavasupport.

(16)

(17)

Summary

of

changes

This informationisbasedontheJavaApplicationsinCICSforCICSTransaction Serverfor z/OS™_,_Version₂_Release_2, _{SC34-6000-00.}_Changes_from_that_edition

aremarkedbyverticalbarsintheleftmargin.

This partlistsbrieflythechangesthathave beenmade forthefollowingrecent releases:

Changes

for

CICS

Transaction

Server

for

z/OS,

Version

2 Release

3

Themoresignificantchangesfor thiseditionare:

v Chapter5, “AccessingdatafromCICSapplicationswritteninJava,”onpage33

isanewchapter. ItdescribesthedifferentmethodsthatCICSJavaprograms, andenterprisebeans,canuseto accessdata.

v TheinformationabouttheCICSJVMhasbeenrefreshed.In particular,TheCICS

JVMnowsupports thesharingof acacheof commonly-usedclassfilesthatare alreadyloaded,enablingfasterJVMstartupandreducingthecostof class loading.SeeChapter7, “AboutJVMs,”onpage45andChapter8, “Settingup andusingJVMs,”onpage83.

v CICSnowsupportsVersion1.4.2 oftheIBM

®

SoftwareDeveloperKitfor z/OS, Java2TechnologyEdition.SeeChapter7, “AboutJVMs,”onpage45.

v TheCICSObject RequestBroker(ORB) nowsupports Version2.3of the

CommonObjectRequestBrokerArchitecture(CORBA).SeeChapter9,“IIOP supportinCICS,”onpage141and“MigratinganEJB serverto CICSTSfor z/OS,Version 2.3”onpage224.

v Chapter20,“TheCCIConnectorforCICSTS,”onpage 293isa newchapter.It

describesanew CICSconnectorthatiscompliantwiththeindustry-standard CommonClientInterface(CCI)definedbytheJ2EEConnectorArchitecture Specification.TheconnectorhelpsyoutobuildpowerfulEnterpriseJavaBean (EJB)servercomponentsthatlink toexisting(non-Java)CICSprograms. v Itisnowpossibleto enableanddisableCorbaServerexecutionenvironments.

Thishasledto betterwaysofupdating beansinproductionregions—see Chapter19,“Updatingenterprisebeansinaproductionregion,”onpage 281. v TheinformationaboutCICSsupportforCORBAandCORBAstatelessobjects

hasbeenrefreshed. Inparticular:

– “Stand-aloneCICSCORBAclientapplications”onpage378isanew section.

– “Name-manglingof theOPERATIONfield”onpage179isanewsection.

– Chapter25,“StatelessCORBAobjects,”onpage367hasbeen rewritten.

Muchnew informationhasbeenadded.“DevelopinganRMI-IIOPstateless CORBAapplication”onpage376and“CORBAinteroperability”onpage378 arenew sections.

v “Classversionissues withRMI-IIOP” onpage 336isa newsection.

Changes

for

CICS

Transaction

Server

for

z/OS,

Version

2 Release

2

Themoresignificantchangesfor thiseditionwere:

v PartsofChapter11,“ConfiguringCICSforIIOP,”onpage155,Chapter13,

“Whatareenterprisebeans?,”onpage185,andChapter14,“SettingupanEJB server,”onpage213were rewrittento describeCICSenhancedsupportfor enterprisebeans,includinganeasierwayto installdeployedJARfiles.

xv

# #

(18)

v Chapter15,“RunningtheEJBIVP,”onpage231wasrewrittento reflect

changesto theEJBInstallationVerificationProgram(IVP).

v Chapter16,“RunningthesampleEJBapplications,”onpage237wasrewritten

toreflectchangestotheEJBsample applications.

v Chapter18,“Deployingenterprisebeans,”onpage277and“Thedeployment

toolsforenterprisebeansinaCICSsystem”onpage277were updatedto reflectthereplacement oftheEJBdeployment tools.

v Supportwasaddedfor Javasecurityroles.See“Securityroles” onpage 347.

v

Supportwasaddedfor aLightweightDirectoryAccessProtocol(LDAP)name

(19)

Part

1. Java

development

roadmaps

This Partoutlinesthestepsneededto implementdifferenttypesof Javaapplication inCICS.Itcontains:

v “JavaapplicationroadmapforCICS”onpage3

v “CICSIIOPapplicationroadmap”onpage 3

v “CICSenterprisebeansroadmap”onpage3

(20)

(21)

Chapter

1. Java

development

roadmaps

Each ofthefollowingroadmapsoutlinesthestepsrequiredto developa particular type ofJavaapplicationinCICS:

v “JavaapplicationroadmapforCICS”

v “CICSIIOPapplicationroadmap”

v “CICSenterprisebeansroadmap”

Java

application

roadmap

for

CICS

1. WriteaJavaapplication,usingtheJCICSclassesto accessCICSservicesand

resources.SeeChapter4, “JavaprogramminginCICS,”onpage13. 2. UsetheJavaVirtualMachineinCICSto executeyourapplication.See

Chapter7,“AboutJVMs,”onpage 45andChapter8,“Settingupandusing JVMs,”onpage83.

CICS

IIOP

application

roadmap

1. Set upCICSasanIIOPserver.SeeChapter11,“ConfiguringCICSfor IIOP,”on

page 155.

2. WriteyourIIOPserverapplication,alsoknown asa “statelessCORBAobject”.

See“DevelopingstatelessCORBAobjects” onpage 367,“CreatingtheInterface Definition Language(IDL)” onpage370, and“DevelopinganIIOPserver program”onpage371.

3. Writeyourclientprogram.See“DevelopingtheIIOPclientprogram”onpage

374.

CICS

enterprise

beans

roadmap

1. FamiliarizeyourselfwithCICSsupportforenterprisebeansbyreading

Chapter13,“Whatareenterprisebeans?,”onpage185.

2. Readtheoverviewof thestepsinvolvedinsettingupaCICSEJBserverin

“ConfiguringCICSasanEJB server—overview”onpage200.

3. Setupabasic,single-regionEJBserverandnameserver—see“Settingupa

single-regionEJB server”onpage213.

4. Testyoursingle-regionEJBserverbyrunningtheEJB installationverification

program(IVP)—see Chapter15,“RunningtheEJB IVP,”onpage231. 5. FurthertestyourEJB serverbyrunningtheEJBsampleapplications—see

Chapter16,“Runningthesample EJBapplications,”onpage237.

6. Optionally,expandyoursingle-regionEJB serverintoa multi-regionserver

capableof loadbalancing—see“Settingupamulti-region EJBserver”onpage 221.

7. Implementanysecuritycontrols requiredbyyoursystem—see Chapter23,

“Managingsecurityforenterprisebeans,”onpage 339.

8. Codeyour sessionbean. IfyouarenotusinganIntegratedDevelopment

Environment(IDE),see“Codinga sessionbean” onpage264.

9. FollowthedeploymentprocessdescribedinChapter18,“Deployingenterprise

beans,”onpage277, usingthetoolsasdescribedin“UsingCICSdeployment toolsfor enterprisebeans”onpage278.

10. Writetheclientprogram.See“Writingtheclientprogram”onpage267.

3

| |

(22)

(23)

Part

2. Developing

Java

applications

for

CICS

This Parttellsyouwhatyou needtoknowto developanduseCICSapplications writteninJava.Itcoversthefollowingtopics:

v Chapter2, “JavaapplicationsinCICS,”onpage 7

v Chapter3, “Whatyouneedtoknowabout CICS,”onpage 9

v Chapter4, “JavaprogramminginCICS,”onpage13

v Chapter5, “AccessingdatafromCICSapplicationswritteninJava,”onpage33

v Chapter6, “UsingtheJCICSsampleprograms,” onpage35

(24)

(25)

Chapter

2. Java

applications

in

CICS

You canwriteJavaapplicationprograms thatuseCICSservicesandexecute under CICScontrol,buttheseprogramsarehandled differentlyfromproceduralprograms writteninthetraditionalCICSlanguages,suchasCOBOLandC.

TheJavalanguageisdesignedtobeportableandarchitecture-neutral.The bytecodegenerated bycompilationisportable,butrequiresamachine-specific interpreter forexecutionondifferentplatforms.CICSprovidesthisexecution environment intwo differentways:

1. Using aJavaVirtualMachine(JVM)thatisexecutingunderCICScontrol.

2. Using VisualAge

®

forJava,EnterpriseEditionforOS/390®(ET/390) tobindthe JavabytecodeintoOS/390executablefiles,knownasJavaprogramobjects,

thatarestoredinMVS™PDSElibrariesandexecutedbyCICSina Language Environment® run-unit,similarlyto C++.

Types

of

Java

application

in

CICS

You canusethefollowingtypesofJavaprograminCICS:

CICSapplicationsforJava

You canwriteJavaprogramsthatusetheJCICSclasslibrary.JCICSallows youto accessCICSresourcessuchasVSAM files,CICStransient dataqueues andtemporary storage.Italsoallowsyouto linkto CICSapplicationswrittenin otherlanguages. Mostof thefunctionsof theEXECCICSprogramming interface aresupported.JCICSissuppliedinthedfjcics.jarJARfileandcan bedownloadedtoyourworkstation.Itisalso availablewithsomereleasesof VisualAgefor Java.

JCICS applicationscanbeboundbytheET/390bytecodebinderto formJava programobjectsthatcan beloadedandexecutedbyCICS,or theycanberun intheCICSJVM.

You canreadmoreaboutJCICSin“TheJCICSclasslibrary”onpage 13.

StatelessCORBAobjects

StatelessCORBAobjects areJavaserverapplicationsthatcommunicatewitha clientapplicationusingtheIIOPprotocol.No stateismaintainedinobject attributesbetweensuccessive invocationsof methods;stateisinitializedat the startof eachmethodcall andreferencedbyexplicitparameters.

StatelessCORBAobjects canreceiveinboundrequests fromaclientandcan also makeoutbound IIOPrequests.

MethodinvocationsmayparticipateinObjectTransactionService(OTS) distributed transactions.IfaclientcallsanIIOPapplicationwithinthescope of anOTStransaction, informationaboutthetransactionflowsasanextra parameter ontheIIOPcall.If atargetstatelessCORBAobjectimplementsthe CosTransactions::TransactionalObject interface,theobjectistreatedas transactional.

Note: AnOTStransactionisadistributedunitof work,nota CICStransaction

instanceorresourcedefinition.

StatelessCORBAobjects canusetheJCICSAPIto interactwithCICS. CICSstatelessCORBAobjectscanexecuteonly intheCICSJVM.

(26)

You canreadmoreaboutCICSstatelessCORBAobjects inChapter25, “StatelessCORBAobjects,”onpage 367.

Enterprisebeans

Enterprise beansareportableJavacomponentsthatcomplywithSun Microsystem’sEnterpriseJavaBeans™Specification,Version1.1.CICShas implementedtheseinterfacesbymapping themtounderlyingCICSservices. Enterprise beanscanlink tootherCICSapplicationsusingconnectors.You can alsodevelopenterprisebeansthatusetheJCICS classlibrarytoaccess CICSservicesorprogramsdirectly, buttheseapplicationswillnotbeportableto a non-CICSEJB-compliant server.

TheEnterpriseJavaBeans(EJB) specificationdefinestransactionaldistributed objects thatcommunicateusingtheJavaRemoteMethodInvocation(RMI) interface.CICSsupportsRMIover IIOP,mediatedusingaCORBAObject RequestBroker(ORB).

Enterprise beanscanexecute onlyintheCICSJVM.

You canreadmoreaboutEnterprisebeansinChapter13,“Whatareenterprise beans?,” onpage 185.

Table1 showsthefeaturesthatcanbeusedinthedifferenttypesof Java applicationinCICS:

Table1.Javaapplicationfeatures

Feature Non-IIOPCICS

appl.

CICSstateless CORBAobject

CICSsession bean

OutboundIIOP YES YES YES

InboundIIOP NO YES YES

APPC/MROoutboundUOW YES YES YES

APPC/MROinboundUOW YES NO NO

EXECCICSSYNCPOINT

UOW YES NO NO

OutboundOTStransaction NO YES YES

InboundOTStransaction NO YES YES

ContainermanagedOTS

transaction NO NO YES

BeanmanagedOTS

transaction NO NO YES

FactorypublicationtoJNDI NO YES YES

ApplicationMetadata NO NO YES

hpjbytecodebinder YES NO NO

Statemanaged NO NO YES

OutboundSecureSockets

Layer(SSL) YES YES YES

InboundSecureSocketsLayer

(SSL) NO YES YES

Assertions YES YES YES

(27)

Chapter

3. What

you

need

to

know

about

CICS

CICSisatransactionprocessing subsystem.Thismeansthatit providesservices for auserto runapplicationsonline,byrequest,at thesametimeasmanyother usersaresubmittingrequeststo runthesameapplications,usingthesamefiles andprograms. CICSmanagesthesharingofresources,integrity ofdata,and prioritizationof execution,whilemaintainingfastresponsetimes.

ACICSapplicationisacollectionof relatedprogramsthattogetherperforma businessoperation,suchasprocessing aproductorderorpreparinga company payroll. CICSapplicationsexecute underCICScontrol,usingCICSservicesand interfacesto accessprograms andfiles.

CICSapplicationsarerunbysubmittinga transactionrequest.Theterm transaction hasaspecialmeaninginCICS;“CICStransactions”explainsthe difference fromthemorecommonindustryusage.Executionofthetransaction consistsof runningoneormoreapplicationprogramsthatimplementtherequired function.InCICSdocumentationyoumay findCICSapplicationprograms

sometimes simplycalledprograms,andsometimes thetermtransaction isused to implytheprocessingdone bytheapplicationprograms.

Todevelop andrunCICSapplications,youneedto understandtherelationship betweenCICSprograms,transactions,andtasks.Theseterms areused throughout CICSdocumentationandappearinmanyprogrammingcommands

CICS

transactions

Atransactionisapieceofprocessinginitiatedbyasinglerequest.Therequestis typically madebyanend-user ataterminal. However,itcouldbemadefroma Web page, fromaremoteworkstationprogram,orfromanapplicationinanotherCICS region;orit mightbetriggeredautomaticallyat apredefinedtime.TheCICS InternetGuideandtheCICSExternalInterfacesGuidedescribedifferentwaysof runningCICStransactions.

Asingletransactionconsistsofoneor moreapplicationprogramsthat,whenrun, carry outtheprocessing needed.

However, thetermtransactionisusedinCICStomean bothasingleeventandall other transactionsof thesametype.Youdescribeeachtransaction-type toCICS withaTRANSACTIONresource definition.This definitiongivesthetransactiontype a name(thetransactionidentifier,orTRANSID)andtellsCICSseveralthingsabout theworktobedone,suchaswhichprogramtoinvokefirst, andwhatkind of authentication isrequiredthroughouttheexecutionofthetransaction. You runa transactionbysubmittingitsTRANSIDto CICS.CICSusesthe informationrecordedintheTRANSACTIONdefinitiontoestablishthecorrect executionenvironment,andstartsthefirstprogram.

ThetermtransactionisnowusedextensivelyintheITindustryto describea unit of recoveryorwhatCICScallsa unitofwork.Thisistypicallya completelogical operation thatisrecoverable;itcanbecommittedorbacked outasanentiretyasa resultofa programmedcommandor ofsystemfailure.In manycases, thescopeof a CICStransaction isalso asingleunitof work,butyoushould beawareofthe difference inmeaning whenreadingCICSdocumentation.

(28)

CICS

tasks

You willalso seethewordtaskused extensivelyinCICSdocumentation.Thisword has aspecificmeaninginCICS.WhenCICSreceivesa requestto runa

transaction, itstartsanew taskthatisassociatedwiththisoneinstanceofthe execution ofthetransactiontype.Thatis,aCICStaskisoneexecutionof a

transaction, withitsown privatesetofdata,usuallyonbehalfof aspecificuser.You can alsoconsiderataskasathread.TasksaredispatchedbyCICSaccordingto their priorityandreadiness.When thetransactioncompletes, thetaskisterminated.

CICS

application

programs

You writea CICSprograminmuchthesamewayasyouwriteanyotherprogram. You canuseCOBOL,C++ ,Java,PL/I,or assemblerlanguageto writeCICS applicationprograms.Most oftheprocessinglogicisexpressedinstandard languagestatements,butto requestCICSservicesyoumust useoneofthe following:

v “EXECCICS”commands providedbytheCICSapplicationprogramming

interface(API)

v TheJavaclasslibraryfor CICS(JCICS)

v TheC++classlibraryforCICS

Theuseof the“EXECCICS”APIisdescribedintheCICSApplicationProgramming ReferenceandtheCICSSystemProgrammingReference.Itcanbeusedin

COBOL,C,C++,PL/I,orassemblerprograms. ItcannotbeusedinJavaprograms.

In Javaprograms,youcanusetheJCICSclassesto accessCICSservicesandlink to CICSapplicationprogramswritteninotherlanguages.JCICS isdescribedin “TheJCICSclass library”onpage13.(Thetypesof Javaprogramthatyoucan writearelistedin“Typesof JavaapplicationinCICS”onpage7.)

You canwriteenterprisebeansthatusetheinterfacesdefinedinSunMicrosystem’s

Enterprise JavaBeansSpecification,Version1.1.CICSimplementsthisspecification bymapping programrequests transparentlyto underlyingCICSservices.(You can also writeenterprisebeansthatusetheJCICSclassestocall CICSservices directly, butifyoudosoyourbeanswillnotbeportabletonon-CICSservers.)

CICS

services

CICSprovidesthefollowingservices,whichJavaprogramscanaccessthroughthe JCICS programminginterface.CICSservicesmanagerstraditionallyhave theword “control”intheirtitles—forexample,“terminalcontrol”and“programcontrol”.You willfindthesetermsused extensivelyinCICSpublications:

Data managementservices

CICSprovides:

v Record-levelsharing,withintegrity,inaccessingVirtualStorageAccess

Method(VSAM)datasets.CICSlogsactivitytosupport: – Databackout (inthecaseoftransactionor systemfailure)

– Forwardrecovery(inthecaseofmediafailure)

Managementof VSAMdataisprovidedbyCICSFileControl.

CICSalsoimplementstwoproprietaryfilestructures,andprovides commandstomanipulate them:

TemporaryStorage

(29)

tomultipletransactions.Dataiskeptinqueues,which arecreated asrequiredbyprograms. Queuescanbeaccessedsequentiallyor byitem number.

Temporarystoragequeuescanresideinmainmemory,or bewritten toastoragedevice.

Atemporarystoragequeuecanbethoughtof asanamed scratch-pad.

TransientData

Transientdata(TD)isalso availabletomultipletransactions,andis keptinqueues.However,unlikeTSqueues,TDqueuesmust be predefinedandcanonly bereadsequentially. Eachitemisremoved fromthequeuewhenitisread.

Transientdataqueuesarealwayswrittento adataset.Youcan definea transientdataqueuesothatwritingaspecificnumberof itemsto itacts asatriggerto startaspecifictransaction.(The triggeredtransactionmight,forexample,processthequeue.) v Accesstodata inotherdatabases(includingDB2

®

),throughinterfaceswith databaseproducts.

Communications services

CICSprovidescommandsthatgiveaccesstoa widerange of

terminals—displays,printers,andworkstations—usingSNAandTCP/IP protocols.Management ofSNAandTCP/IPnetworksisprovided byCICS

terminal control.

You canwriteprogramsthatuseAdvancedProgram-to-Program

Communication(APPC)commandsto startandcommunicatewithother programs inremotesystems,usingSNAprotocols.CICSAPPCimplementsthe peer-to-peer distributedapplicationmodel.

CICSalso providesanObjectRequestBroker(ORB)to implementtheinbound andoutbound IIOPprotocolsdefinedbytheCommonObject RequestBroker Architecture(CORBA).TheORBsupports requeststo executeJavastateless objects andenterprisebeans.

ThefollowingCICSproprietarycommunicationsservicesareprovided:

Function shipping

Program requeststoaccessresources(files,queues, andprograms) thataredefinedasexistingonremoteCICSregionsareautomatically routed byCICSto theowning region.

Distributedprogramlink(DPL)

Program-linkrequestsfor aprogramdefinedasexistingonaremote CICSregionareautomaticallyrouted totheowning region.CICS providescommandstomaintaintheintegrityof thedistributed application.

Asynchronousprocessing

CICSprovidescommandstoallowa programto startanother transactioninthesame,orinaremote,CICSregionandoptionally passdatatoit.Thenewtransactionisscheduledindependently,ina new task.Thisfunction issimilar totheforkoperation providedbyother softwareproducts.

Transactionrouting

Requeststo runtransactionsthataredefinedasexistingonremote

(30)

CICSregionsareautomaticallyroutedto theowningregion.Responses to theend-userarerouted backto theregionthatreceivedtherequest.

Unit ofworkservices

WhenCICScreatesa newtaskto runatransaction,anew unitof work(UOW) isstartedautomatically.(Thus CICSdoes notprovideaBEGINcommand, becauseoneisnotrequired.) CICStransactionsarealwaysexecuted

in-transaction.

CICSprovidesaSYNCPOINTcommandtocommitor rollbackrecoverable workdone.Whenthesyncpointcompletes, CICSautomaticallystartsanother unit ofwork.Ifyouterminate yourprogramwithout issuinga SYNCPOINT command,CICStakesanimplicitsyncpointandattempts tocommitthe transaction.

Thescopeof thecommit includesallCICSresourcesthathavebeendefined as recoverable, andanyotherresourcemanagersthathaveregisteredaninterest throughinterfacesprovidedbyCICS.

If youwriteenterprisebeansusingtransaction servicesprovided bycommands definedbytheJavaTransactionService(JTS),thesecommands(including BEGIN)aremappedbyCICSto itsunitofworkservices.

Programservices

CICSprovidescommandsthatenableaprogramtolink ortransfercontrolto anotherprogram,andreturn.

Diagnosticservices

CICSprovidescommandsthatenableyoutotrace programsandproduce dumps.

Otherservices

CICSprovidesotherservices,suchasjournaling,timer,andstorage management,thatarenotavailablethroughtheJCICSinterface.Theseare describedintheCICSApplicationProgrammingGuide.

(31)

Chapter

4. Java

programming

in

CICS

You canwriteJavaapplicationprograms thatuseCICSservicesandexecute under CICScontrol.

You canwriteJavaprogramsonaworkstation,orinthez/OSUNIX®_System

Services shell.You canuseanyeditorof yourchoice,or avisualcomposition environment suchasWebSphereStudioApplication Developer.

CICSprovidesaJavaclasslibrary,known asJCICS, suppliedinthedfjcics.jar

JAR file.JCICSistheJavaequivalent oftheEXECCICSapplicationprogramming interface (API)thatyouwouldusewithotherCICSsupportedlanguages,suchas COBOL.ItallowsyoutoaccessCICSresourcesandintegrate yourJavaprograms withprogramswritteninotherlanguages.Most ofthefunctionsoftheEXECCICS API aresupported.Fora descriptionoftheJCICSAPI,see“TheJCICSclass library.”

TheJavalanguageisdesignedtobeportableandarchitecture-neutral.The bytecodegenerated bycompilationisportable,butrequiresamachine-specific interpreter forexecutionondifferentplatforms.CICSprovidesthisexecution environment intwo differentways:

1. By meansofa JavaVirtualMachine(JVM)thatexecutesunder CICScontrol.

This istherecommendedmethod.

2. By usingVisualAgeforJava,EnterpriseEditionforOS/390tobind theJava

bytecodeintoOS/390executablefiles,knownasJavaprogramobjects,that arestoredinOS/390PDSElibrariesandexecutedbyCICSinaLanguage Environmentrun-unit,similarlyto C++programs.

Note: CICSTS forz/OS,Version 2supportshpj-boundJavaprogramobjects

thatweredevelopedusingCICS TSOS/390,Version1Release 3and itsassociatedtooling. Suchprogramobjects willruninCICSTSfor z/OS,Version 2unchanged,butCICSTSfor z/OS,Version 2provides nosupportfor developingnew Javaprogramobjectsnorformodifying existingJavaprogramobjects.Theversionof JCICSsuppliedinCICS TSforz/OS, Version 2should notbeusedto compileJavaprogram objects.

You canreadaboutVisualAgefor Java,Enterprise Editionfor OS/390in Chapter28,“VisualAgeforJava,ET/390,”onpage393andtheCICSJVMin Chapter7,“AboutJVMs,”onpage45.

The

JCICS

class

library

TheJavaclasslibraryforCICS,JCICS,supports mostof thefunctionsof theEXEC CICSAPIcommands. Thesearedescribedin“JCICScommandreference”onpage 17.

TheJCICSclassesarefullydocumentedinJAVADOC thatisgeneratedfromthe class definitions.ThisisavailablethroughtheCICSInformationCenter,andcanbe found intheJCICSClass Reference.

Translation

There isnoneedfor aCICStranslatorfor Javaprograms.

(32)

JavaBeans

Some oftheclassesinJCICS maybeused asJavaBeans,whichmeansthatthey can becustomizedinanapplicationdevelopmenttoolsuchasWebSphereStudio Application Developer,serialized, andmanipulatedusingtheJavaBeansAPI.The JavaBeansinJCICSarecurrently:

v Program v ESDS v KSDS v RRDS v TDQ v TSQ v AttachInitiator v EnterRequest

Thesebeansdonotdefineanyevents;they consistof propertiesandmethods. They canbeinstantiatedatrun-timeinoneofthreeways:

1. By callingthenewmethodfor theclassitself.(Thisistherecommendedway.)

2. By callingBeans.instantiate()for thenameof theclass, withpropertyvalues

setmanually.

3. By callingBeans.instantiate()of a.serfile,withpropertyvaluessetat design

time.

If eitherof thefirst twooptionsarechosen,thenthepropertyvalues,includingthe name oftheCICSresource,must besetbyinvokingtheappropriate“set”methods at run-time.

Library

structure

Each JCICSlibrarycomponentfallsintooneof fourcategories: v Interfaces v Classes v Exceptions v Errors Interfaces

Someinterfacesareprovidedto definesetsofconstants. Forexample,the TerminalSendBitsinterface providesasetof constantsthatcanbeusedto constructajava.util.BitSet.

Classes

Thesuppliedclassesprovidemostof theJCICSfunction.TheAPIclassisan abstract classthatprovidescommon initializationforeveryclassthat

corresponds toa partof theCICSAPI, exceptforABENDsandexceptions.For example,theTaskclassprovidesa setofmethods andvariablesthat

correspondto aCICStask.

ErrorsandExceptions

TheJavalanguagedefines bothexceptionsanderrorsassubclassesofthe classThrowable.JCICSdefinesCicsError asasubclassof Error.CicsErroris thesuperclassforalltheotherCICSerrorclasses,which areused forsevere errors.

JCICS definesCicsExceptionasasubclassof Exception.CicsException isthe superclassforalltheCICSexceptionclasses(includingthe

(33)

CicsConditionExceptionclassessuchasInvalidQueueIdException, which representstheCICSQIDERRcondition).

See“Errorhandlingandabnormaltermination”onpage19forfurther information.

CICS

resources

CICSresources,suchasprograms ortemporarystoragequeues,arerepresented byinstancesof theappropriateJavaclass,identifiedbythevaluesofvarious propertiessuchasname and,forsomeclasses,aSYSID(theidentifierof theCICS system thatownstheresource).

Resourcesmustbedefinedto CICS,usingtheCEDAtransactionorCICSPlex®SM BAS. SeetheCICSResourceDefinitionGuideortheCICSPlexSystemManager Concepts andPlanningmanualforinformationabout definingCICSresources.Itis possibleto useimplicitremoteaccessbydefiningaresourcelocallytopoint toa remoteresource.

CICS

storage

requirements

Memoryrequirements torunJavaprograms arehigherthanforconventional programs. Therefore:

1. You shouldaskyourCICSsystemprogrammer tosetthevalueoftheEDSALIM

system initializationparameterto aminimumof200MB,otherwisea short-on-storageconditionmayoccur.

NotethatyoucannotchangethevalueofEDSALIMduringCICSexecutionby meansof CEMTSETcommands.Furthermore, dynamicchangestoEDSALIM arecatalogedinthelocalcatalog,andthevalueinthelocalcatalogoverrides theEDSALIMparameterspecifiedinthesysteminitializationtable duringall forms ofrestart:initial,cold,andwarm.Therefore,to changeEDSALIM,you must specifyit asasysteminitialization tableoverrideorre-initializetheCICS catalog datasets.

2. Your CICSjobshouldseta minimumREGIONvalueof 400MB.

Command

arguments

ManyCICSprogrammingcommandspassdataina structureknownasa

“communications area”(COMMAREA).This,andany otherparameters,arepassed asargumentstotheappropriatemethods.

Manyofthemethods areoverloaded—thatis,theyhave differentversionsthattake either adifferentnumberofargumentsorargumentsofa differenttype. Theremay beonemethodthathasnoarguments,or theminimummandatoryarguments,and anotherthathasallof thearguments.For example,there arethefollowingdifferent link()methods intheProgramclass:

link()

This versiondoesa simpleLINKwithoutusinga COMMAREAtopassdata,nor anyother options.

link(com.ibm.cics.server.CommAreaHolder)

This versiondoesa simpleLINK,usingaCOMMAREAtopassdatabutwithout anyother options.

link(com.ibm.cics.server.CommAreaHolder,int)

This versiondoesa distributedLINK,usingaCOMMAREAto passdata anda DATALENGTH valuetospecifythelengthof thedatawithin theCOMMAREA.

Chapter4.JavaprogramminginCICS

15

| | | | | | | | | | | | | |

(34)

link(com.ibm.record.IByteBuffer)

This versiondoesa LINKusinganobjectthatimplementstheIByteBuffer interface oftheJavaRecordFrameworksuppliedwithVisualAgefor Java.

Serializable

classes

ThefollowingJCICS classesareserializableandsocansurvivea Passivate/Activate cycle. v AddressResource v AttachInitiator v CommAreaHolder v EnterRequest v ESDS v File v KeyedFile v KSDS v NameResource v Program v RemotableResource v Resource v RRDS v StartRequest v SynchronizationResource v SyncLevel v TDQ v TSQ v TSQType

Using

the

Java

Record

Framework

Themain purposeoftheJavaRecordFrameworkisto providerun-timesupportfor accessingapplicationrecorddata(suchasVSAM files,orCOMMAREAs).Seethe

CICSApplicationProgrammingGuideforadescription ofVSAM files.

You canusetheframeworkasthebase forrecord-orientedfile input/output,aswell asfor record-basedmessage-passingschemes.Youcanusetheframeworkfor new applications,andforapplicationsthataccessexistingfiles.

TheJavaRecordFrameworkispartof VisualAgeforJava.Youcanfindoutmore about itintheVisualAgedocumentation,whichissuppliedinHTMLformatwiththe product.

System.out

and

System.err

For eachJava-related CICStask,CICSautomaticallycreatestwoJava

PrintWritersthatcanbeusedasstandardoutandstandarderrorstreams.The standard outandstandard errorstreamsarepublicfieldsintheTaskcalledout and err.

If aCICStaskisbeingdrivenfroma terminal(theterminaliscalledaprincipal facility inthis case),CICSmapsthestandardoutandstandarderrorstreams to thetask’sterminal.

(35)

If thetaskdoesnothave aterminalasitsprincipalfacility,thestandardoutand standard errorstreamsaresentto System.outandSystem.err.System.outand System.err aremappedto theCICStransient dataqueuesCESOandCESE, respectively.YourCICSsystem programmercreatesthesequeues,andothersused for CICSmessages,duringCICSinstallation.Youcanaccessandprintordisplay thesemessagequeuesusingutilityprogramssuchastheDFH$TDWTsample programdescribedintheCICSCustomizationGuide.DFH$TDWTissuppliedwith theCICSpregeneratedsysteminCICSTS23.CICS.SDFHLOAD.

Threads

Onlyonethread (theinitialthread) canaccesstheJCICSAPI.Youcancreateother threadsbutyoumust routeallrequeststo theJCICSAPIthroughtheinitialthread. Additionally,youmust ensurethatallthreadsotherthantheoriginalthread have terminatedbefore doinganyof thefollowing:

v link() v xctl() v setNextTransaction(),setNextCOMMAREA() v commit(),rollback() v returninganAbendException

Note: MultiplethreadsarenotsupportedbyET/390.

JCICS

command

reference

Manyoftheoptionsandservicesavailableto non-Javaprograms throughthe EXECCICSAPIareavailabletoJavaprogramsthroughJCICS.Thissection shows therelationshipbetweenEXECCICScommandsandtheequivalentJCICS

function.Fora fulldescriptionof theEXECCICScommands,seetheCICS Application ProgrammingReference.

JCICS supportisdescribedunderthefollowingheadings: v

“Errorhandlingandabnormaltermination”onpage19

v

“CICSexceptionhandlinginJavaprograms” onpage18

v “APPCmappedconversations”onpage20

v “BasicMapping Support(BMS)” onpage20

v “Diagnosticservices”onpage20

v “Documentservices”onpage20

v “Environmentservices”onpage 21

v “Fileservices”onpage 23

v “Programservices”onpage26

v “Schedulingservices”onpage 26

v “Serializationservices”onpage27

v “Storageservices”onpage27

v “Temporarystoragequeueservices”onpage27

v “Terminalservices”onpage27

v “Transientdataqueueservices”onpage28

v “Unitof work(UOW)services”onpage28

v “WebandTCP/IPservices”onpage 29

v “UnsupportedCICSservices”onpage30

17

|

(36)

CICS

exception

handling

in

Java

programs

CICSABENDsandexceptionsareintegratedintotheJavaexception-handling architecture.AllregularCICSABENDsaremappedtoa singleJavaexception, AbendException,whereaseachCICSconditionismappedtoa separateJava exception.

This leadsto anABEND-handlingmodelinJavathatissimilartotheother

programming languages;asinglehandlerisgivencontrolforeveryABEND,andthe handlerhasto querytheparticularABENDandthendecide whatto do.

If theexceptionrepresentingaconditioniscaughtbyCICSitself,it isturned intoan ABEND.

Javaexception-handlingisfullyintegratedwiththeABENDandcondition-handling inotherlanguages,sothatABENDscanpropagate betweenJavaandnon-Java programs, inthestandardlanguage-independentway.Aconditionismappedto an ABENDbeforeit leavestheprogramthatcausedordetected thecondition. However, thereareseveraldifferencestotheabend-handlingmodelforother programming languages,resultingfromthenatureof theJavaexception-handling architecture andtheimplementation ofsomeofthetechnology underlyingtheJava API:

v ABENDsthatareconsidered unhandleableinotherprogramminglanguagescan

becaughtinJavaprograms.TheseABENDstypicallyoccurduringSYNCPOINT processing.ToavoidtheseABENDs interruptingJavaapplications,theyare mappedtoanextensionof anunchecked exception;thereforetheydonothave tobedeclaredor caught.

v SeveralinternalCICSevents, suchasprogramtermination,arealsomappedto

Javaexceptionsandcanthereforebecaughtbya Javaapplication.Again,to avoidinterruptingthenormalcase,thesearemappedto extensionsof an uncheckedexceptionandsodonothave tobecaughtordeclared.

Note: CICSrequirestheLanguageEnvironmentproductto beinstalledandactive

onyourOS/390system inorderto runJavaapplications.Youshouldnot specifytheLanguageEnvironmentrun-timeoptionTRAP=OFF,becausethis willdisableabendhandlinginJCICS.

There arethreeCICS-related classhierarchiesofexceptions:

1. CicsError,whichextends java.lang.Errorandisthebase forAbendErrorand

UnknownCicsError.

2. CicsRuntimeException,whichextends java.lang.RuntimeExceptionandisin

turnextendedby:

AbendException

RepresentsanormalCICSABEND.

EndOfProgramException

Indicatesthatalinked-toprogramhasterminatednormally.

TransferOfControlException

Indicatesthataprogramhasused anxctl()method,theequivalentof the CICSXCTLcommand.

3. CicsException,whichextendsjava.lang.Exception andhasthesubclass:

CicsConditionException.

(37)

CICS

error-handling

commands

CICSconditionhandlingisintegratedintotheJavaexceptionarchitecture as describedabove.Thewaythattheequivalent“EXECCICS”commandissupported inJavaisdescribedbelow:

HANDLEABEND

TohandleanABENDgenerated byaprograminanyCICS-supported language, usea Javatry-catch statement,withAbendExceptionappearinginacatch clause.

HANDLE CONDITION

Tohandleaspecificcondition,suchasPGMIDERR,use acatchclausethat namestheappropriateexception—inthis caseInvalidProgramException. Alternatively,useacatchclausenamingCicsConditionException,if allCICS conditions areto becaught.

IGNORECONDITION

This commandisnotrelevantinJavaapplications.

POPandPUSHHANDLE

ThesecommandsarenotrelevantinJavaapplications.TheJavaexceptions used torepresentCICSABENDsandconditions arecaughtbyanycatchblock inscope.

CICS

conditions

Thecondition-handling modelinJavaisdifferentfromotherCICSprogramming languages.

In COBOL,you candefineanexception-handlinglabelfor eachcondition.Ifthat conditionoccursduringtheprocessingof aCICScommand,controltransfers tothe label.

In CandC++,youcannotdefineanexception-handlinglabelforacondition;to detectacondition, theRESPfieldintheEIBmustbecheckedaftereach CICS command.

In Java,anyconditionreturnedbyaCICScommandismappedintoaJava exception.You canincludeallCICScommandsinatry-catchblockanddospecific processing foreach condition,orhavea singlenullcatchclauseif theparticular exceptionisnotrelevant.Alternatively,youcanlettheconditionpropagate,to be handled bya catchclauseata largerscope.

See“JCICSexceptionmapping” onpage 30for adescriptionof therelationship betweenCICSconditionsandJavaexceptions.

Error

handling

and

abnormal

termination

Methods JCICSclass EXECCICScommands

abend(),forceAbend() Task ABEND

ABEND

ToinitiateanABENDfromaJavaprogram,you invoketheTask.abend(String) method,supplying anABENDcode.This willcauseanabendconditionto be setinCICSandanAbendExceptiontobethrown.IftheAbendExceptionisnot caughtwithin ahigherlevelof theapplicationobject,orhandled byan

ABEND-handler registeredinthecallingprogram(ifany), CICSwillterminate androll-backthetransaction.

(38)

ABEND CANCEL

ToinitiateanABENDthatcannotbehandled, youinvokethe

Task.forceAbend(String) method,supplyinganABENDcode.Asdescribed above,this willcauseanAbendCancelExceptiontobethrownwhichcanbe caughtinJavaprograms.Ifyoudoso,youmustre-throwtheexceptionto completeABEND_CANCELprocessing,sothatwhencontrolreturnsto CICS,it willterminate androllbackthetransaction.Youshouldcatch

AbendCancelExceptiononlyfor notificationpurposesandthenre-throwit.

APPC

mapped

conversations

APPCunmappedconversationsupportisnotavailablefromtheJCICSAPI. APPCmappedconversations:

Methods JCICSclass EXECCICSCommands

initiate() AttachInitiator ALLOCATE,CONNECTPROCESS converse() Conversation CONVERSE

get*()methods Conversation EXTRACTATTRIBUTES get*()methods Conversation EXTRACTPROCESS

free() Conversation FREE

issueAbend() Conversation ISSUEABEND

issueConfirmation() Conversation ISSUECONFIRMATION issueError() Conversation ISSUEERROR

issuePrepare() Conversation ISSUEPREPARE issueSignal() Conversation ISSUESIGNAL receive() Conversation RECEIVE

send() Conversation SEND

flush() Conversation WAITCONVID

Basic

Mapping

Support

(BMS)

sendControl() TerminalPrincipalFacility SENDCONTROL sendText() TerminalPrincipalFacility SENDText

Notsupported SENDMAP,RECEIVEMAP

Diagnostic

services

Notsupported DUMP enterTrace() EnterRequest ENTER enableTrace(),disableTrace() Region,Task TRACE

Document

services

This sectiondescribesJCICSsupportfor thecommandsintheDOCUMENT applicationprogramminginterface.

| | |

(39)

You cannotusedocumentsupportwiththeVisualAgeforJava,EnterpriseEdition for OS/390,bytecodebinder.

Class Documentmapsto theEXECCICSDOCUMENTAPI. Constructorsfor class DocumentLocationmapto theATandTOkeywordsoftheEXECCICSDOCUMENT API. SettersandgettersforclassSymbolListmapto theSYMBOLLIST, LENGTH, DELIMITER,andUNESCAPE keywordsoftheEXECCICSDOCUMENTAPI.

create*() Document DOCUMENTCREATE append*() Document DOCUMENTINSERT insert*() Document DOCUMENTINSERT addSymbol() Document DOCUMENTSET setSymbolList() Document DOCUMENTSET retrieve*() Document DOCUMENTRETRIEVE

get*() Document DOCUMENT

Environment

services

CICSenvironmentservicesprovideaccesstoCICSdataareas,parameters,and resource attributesthatarerelevanttoanapplicationprogram.TheEXECCICS commands andoptionsthathaveequivalentJCICS supportare:

v ADDRESS v ASSIGN v INQUIRESYSTEM v INQUIRETASK v INQUIRETERMINAL/NETNAME

ADDRESS

SeetheCICSApplicationProgrammingReferencemanualfor informationaboutthe EXECCICSADDRESScommand.Thefollowingsupportisprovidedfor the

ADDRESS options.

ACEE TheAccessControl EnvironmentElement(ACEE)iscreatedbyanexternal securitymanagerwhenaCICSusersignson.Thisoptionnotsupportedin JCICS.

COMMAREA

ACOMMAREAcontainsuser datathatispassed witha command.The COMMAREApointerispassedautomatically tothelinkedprogrambythe CommAreaHolderargument.See“Commandarguments”onpage 15for moreinformation.

CWA TheCommonWorkArea(CWA)containsglobaluserdata, sharable betweentasks.ThisoptionisnotsupportedinJCICS.

EIB TheEXECInterfaceBlockcontainsinformationabout theCICScommand last executed.AccesstoEIBvalues isprovided bymethodsonthe appropriateobjects.Forexample,

eibtrnid

isreturnedbythegetTransactionName()methodoftheTaskclass.

eibaid isreturnedby thegetAIDbyte()method of the TerminalPrincipalFacilityclass.

21

| | | | | | |||| ||| ||| ||| ||| ||| ||| ||| | |

(40)

eibcposn

isreturnedbythegetRow()andgetColumn()methods oftheCursor class.

TCTUA

TheTerminalControlTableUserArea(TCTUA)containsuserdata associatedwiththeterminalthatisdrivingtheCICStransaction(the principalfacility).This areaisused topassinformationbetweenapplication programs, butonly ifthesameterminalisassociatedwiththeapplication programs involved.ThecontentsoftheTCTUAcanbeobtained usingthe getTCTUA()methodof theTerminalPrincipalFacilityclass.

TWA TheTransactionWorkArea(TWA)containsuserdatathatisassociated withtheCICStask.Thisareaisusedto passinformationbetween applicationprograms,butonlyif theyareinthesametask.Acopyof the TWAcanbeobtainedusingthegetTWA()methodoftheTaskclass.

ASSIGN

SeetheCICSApplicationProgrammingReferencemanualfor informationaboutthe EXECCICSASSIGNcommand.Thefollowingsupportisprovidedfor theASSIGN options.

getABCODE() AbendException ASSIGNABCODE

getAPPLID() Region ASSIGNAPPLID

getCWA() Region ASSIGNCWALENG

getName() TerminalPrincipalFacilityor ConversationPrincipalFacility

ASSIGNFACILITY

getFCI() Task ASSIGNFCI

getNetName() TerminalPrincipalFacilityor ConversationPrincipalFacility ASSIGNNETNAME getPrinSysid() TerminalPrincipalFacilityor ConversationPrincipalFacility ASSIGNPRINSYSID getProgramName() Task ASSIGNPROGRAM

getQNAME() Task ASSIGNQNAME

getSTARTCODE() Task ASSIGNSTARTCODE

getSysid() Region ASSIGNSYSID

getTCTUA() TerminalPrincipalFacility ASSIGNTCTUALENG getTERMCODE() TerminalPrincipalFacility ASSIGNTERMCODE

getTWA() Task ASSIGNTWALENG

getUserid(),Task.getUSERID() Task,TerminalPrincipalFacility or

ConversationPrincipalFacility

ASSIGNUSERID

No otherASSIGNoptions aresupported.

INQUIRE

SYSTEM

Thefollowingsupportisprovided fortheINQUIRESYSTEMoptions:

(41)

No otherINQUIRESYSTEMoptionsaresupported.

INQUIRE

TASK

Thefollowingsupportisprovidedfor theINQUIRETASKoptions:

getAPPLID(),getSYSID() Task INQUIRETASKFACILITY

getSTARTCODE() Task INQUIRETASK

STARTCODE getTransactionName() Task INQUIRETASK

TRANSACTION

getUserid() Task INQUIRETASKUSERID

Notes::

FACILITY

Youcan findthename ofthetask’sprincipalfacilitybycalling the getName()methodonthetask’sprincipalfacility,whichcaninturn befoundbycallingthegetPrincipalFacility()methodonthe currentTaskobject.

FACILITYTYPE

Youcan determinethetypeof facilitybyusingtheJava instanceofoperatortochecktheclassof thereturnedobject reference.

No otherINQUIRETASKoptionsaresupported.

INQUIRE

TERMINAL

and

INQUIRE

NETNAME

Thefollowingsupportisprovidedfor INQUIRETERMINALandINQUIRE NETNAME options:

Terminal.getUser(), getUserid()

Terminal,

ConversationalPrincipalFacility

INQUIRE TERMINAL USERID INQUIRE NETNAME USERID

Note: Youcanalso findtheUSERIDvaluebycallingthegetUSERID()methodon

thecurrentTaskobject,or ontheobjectrepresentingthetask’sprincipal facility

No otherINQUIRETERMINALorNETNAMEoptions aresupported.

File

services

CICSsupports thefollowing typesof files: v KeySequencedDataSets(KSDS)

v

EntrySequencedDataSets(ESDS)

v RelativeRecordDataSets(RRDS)

KSDSandESDSfilescan havealternate(orsecondary) indexes.(CICSdoesnot supportaccesstoanRRDSfilethrougha secondaryindex.)Secondaryindexesare treatedbyCICSasthoughtheywere separateKSDSfilesintheirownright, which meansthey haveseparateFDentries.