Java applications in CICS

(1)

CICS

®

Transaction

Server

for

z/OS

™

Java

™

applications

in

CICS

Version

2 Release

2

SC34-6000-06

(2)

(3)

CICS

®

Transaction

Server

for

z/OS

™

Java

™

applications

in

CICS

Version

2 Release

2

SC34-6000-06

(4)

Note!

Beforeusingthisinformationandtheproductitsupports,besuretoreadthegeneralinformationunder“Notices”onpage 303.

Secondedition(January2002)

ThiseditionappliestoVersion 2 Release 2ofCICSTransactionServerforz/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.

(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 . . . 17

Error handlingandabnormal termination . . . 19

APPCmappedconversations . . . 19

BasicMappingSupport (BMS) . . . 20

Diagnosticservices . . . 20 Environmentservices . . . 20 Fileservices. . . 23 Program services . . . 25 Schedulingservices . . . 26 Serializationservices. . . 26 Storage services . . . 26

Temporarystoragequeueservices . . . 26

Terminalservices . . . 27

Transientdataqueueservices . . . 27

©Copyright IBM Corp.1999, 2004

iii

# # ||

(6)

UnitofWork(UOW)services. . . 28

UnsupportedCICSservices . . . 28

JCICS exceptionmapping. . . 28

Using JCICS. . . 29

Writing themain method . . . 29

Creatingobjects . . . 29

Using objects . . . 30

Chapter5.AccessingdatafromCICSapplicationswritteninJava . . . . 31

Using DataAccess beans. . . 32

Chapter6. Usingthe JCICSsampleprograms . . . 33

Building thesample programs . . . 33

Building theJavasamples. . . 34

DefiningCICSresources . . . 34

CICSstoragerequirements . . . 35

RunningtheJavasamples . . . 35

RunningtheHelloWorldsample . . . 35

RunningtheProgramControl sample . . . 35

RunningtheTDQsample . . . 36

RunningtheTSQsample . . . 36

Part

3. Using

the

JVM

.

. 39

Chapter7.Aboutthe JVM . . . 41

Enabling serialreuse oftheJVM . . . 41

Therun-timestructureof theJVM. . . 42

HowCICSmanagesJVMsinapool . . . 43

HowCICSselectstheright typeofJVM . . . 43

Useofresource definitionsfor JVMselection. . . 44

SelectinganopenTCBfortheJVM . . . 45

CICSrestrictions onuseof persistentreusableJVM . . . 46

Resourcedefinitions fortheJVM . . . 47

AuthorizingCICSregionuseridstoUNIXsystemservices . . . 47

Groupnamingconsiderations . . . 49

Chapter8. Configuringthe JVM. . . 51

DefiningresourcesfortheJVM. . . 51

Debugging intheCICSJVM. . . 52

Attaching adebuggerto aCICSJVM . . . 53

TheCICSJVMpluginmechanism. . . 55

Part

4. CICS

and

IIOP

.

. 59

Chapter9. IIOPsupportinCICS. . . 61

TheObjectRequestBroker(ORB). . . 61

CICSIIOPapplicationmodels . . . 62

Some commonCORBAterminology . . . 62

Chapter10.TheIIOPrequestflow . . . 65

IIOPinasysplex . . . 66

Workloadbalancingof IIOPrequests. . . 67

DomainNameSystem(DNS)connection optimization . . . 68

Connectionoptimizationregistration . . . 68

Nameresolutionexample . . . 69 #

#

|| ||

(7)

Resourcedefinitionfor DNSconnection optimization . . . 70

Avoiding DomainNameSystem(DNS)problems . . . 71

Authenticationof IIOPrequests. . . 71

TheIIOPsecurityURM. . . 72

CONNECTIONauthentication . . . 72

Chapter11.ConfiguringCICSforIIOP . . . 73

Settingupthehost systemfor IIOP . . . 73

Defininghfsfiles . . . 74

Definingname servers . . . 74

Enabling JNDIreferences. . . 74

SettingupanLDAPserver . . . 75

If youhaveanexistingLDAPserverconfiguredforWebSphere. . . 75

Configuringanew LDAPserver. . . 76

Determiningthevaluesfor theCICSproperties . . . 79

TheLDAPnamespacestructure . . . 80

Thecontainerroot. . . 81

Thelegacyroot. . . 81

Domains . . . 81

Nodes . . . 82

Securityconsiderations. . . 82

SettingupaCOSNamingDirectoryServer . . . 84

SettingupTCP/IPfor IIOP . . . 84

Using DNSconnection optimization . . . 85

SettingupCICSfor IIOP . . . 85

DefiningCICSstart-upjobstream . . . 85

InitializingtheJVM . . . 87

DefiningCICSresources . . . 87

Chapter12.ProcessingIIOPrequests . . . 93

Obtaininga CICSuserID. . . 93

Using theIIOPuser-replaceable securityprogram . . . 93

Using DFHXOPUS . . . 95

Obtaininga CICSTRANSID . . . 96

Pattern matching . . . 97

Name-manglingoftheOPERATIONfield . . . 97

REQUESTMODELexamples. . . 98

Dynamic routing . . . 98

HandlingIIOPdiagnostics. . . 98

Part

5. Using

enterprise

beans

.

. 101

Chapter13.Whatare enterprisebeans? . . . 103

Enterprise beans—thebigpicture . . . 103

JavaBeansandEnterprise JavaBeans. . . 104

Components . . . 104

JavaBeans . . . 105

Enterprise JavaBeans. . . 105

TheEJB server—overview . . . 106

TheEJB container—overview . . . 106

Theexecutionenvironment . . . 107

Enterprise beans—thehome andcomponentinterfaces . . . 107

Enterprise beans—thedeploymentdescriptor . . . 108

Typesof enterprisebean. . . 109

Session beans . . . 109 Entity beans . . . 110 Contents

v

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

(8)

Session beansandentitybeanscompared . . . 111

Enterprise beans—managingtransactions . . . 112

Enterprise beans—securityoverview . . . 113

Authentication. . . 113

Access control. . . 113

TheJava2securitymanager . . . 114

Enterprise beans—usertasks . . . 114

Thebeanprovider . . . 114

Theapplicationassembler . . . 114

Thedeployer . . . 115

Thesystem administrator. . . 115

Deployingenterprisebeans—overview. . . 115

ConfiguringCICSasanEJB server—overview. . . 118

Logical servers—enterprisebeansinasysplex. . . 119

SettingupalogicalEJB server . . . 121

Enterprise beans—whatcanaclientdowithabean? . . . 125

Get areferenceto thebean’shome. . . 125

Usethehomeinterface . . . 125

Usethecomponentinterface . . . 126

Enterprise beans—whatcanabean do?. . . 126

Benefits ofEJBtechnology . . . 127

Requirements forEJBsupport. . . 128

Hardware . . . 128

Software. . . 128

Chapter14.SettingupanEJBserver . . . 129

Settingupasingle-regionEJBserver . . . 129

Before runningtheEJB IVP. . . 129

AfterrunningtheEJBIVP—optionalsteps . . . 134

Testing yourEJBserver . . . 136

RunningtheEJBIVP . . . 136

Using theEJB “HelloWorld”sample . . . 136

Using theEJB BankAccountsample . . . 137

Using yourownenterprisebeans. . . 137

Settingupamulti-regionEJB server . . . 137

Chapter15.RunningtheEJBIVP. . . 141

Prerequisites fortheEJBIVP . . . 141

Installing theEJB IVP. . . 141

HFSsetup . . . 142

CICSsetup. . . 142

Configuringtheclient . . . 143

RunningtheEJBIVP . . . 144

Chapter16.RunningthesampleEJBapplications . . . 145

TheEJB “HelloWorld”sampleapplication . . . 145

WhattheEJB “HelloWorld”sample does. . . 145

Prerequisites fortheEJB“HelloWorld”sample . . . 146

Supplied componentsof theEJB “HelloWorld”sample. . . 146

InstallingtheEJB “HelloWorld”sample . . . 147

Testing theEJB“HelloWorld”sample . . . 149

TheEJB BankAccountsampleapplication . . . 153

WhattheEJB BankAccountsampledoes . . . 153

Prerequisites fortheEJBBankAccountsample . . . 154

Supplied componentsof theEJB BankAccountsample . . . 155

Securityof theEJBBankAccountsample . . . 156 ||

||

(9)

InstallingtheEJB BankAccountsample . . . 159

Testing theEJBBankAccountsample. . . 163

Anoteaboutdistributedtransactions . . . 167

Anoteaboutdataconversion . . . 168

Chapter17.Writingenterprise beans . . . 171

Preparingbeansforexecution. . . 171

Coding asessionbean . . . 172

Coding thehomeinterface . . . 172

Coding theremoteinterface. . . 173

Coding thebeanimplementation. . . 173

Compilingthecode. . . 175

Packagingthecode. . . 175

Writing theclientprogram . . . 175

Creatingobjectreferencesinthenamespace . . . 175

Using JNDItoobtainbeanreferences. . . 176

Writing aClientprogramtouseLDAP. . . 176

Writing aclientprogramtouseCOS Naming . . . 179

Transactioninteroperabilitywithwebapplicationservers . . . 181

WorkingwithEJBHandles,HomeHandlesandEJBMetaData . . . 182

Using EDFwithenterprisebeans. . . 182

Bean-to-beancommunication . . . 183

Chapter18.Deployingenterprise beans . . . 185

Thedeployment toolsfor enterprisebeansinaCICSsystem . . . 185

AAT . . . 185

Theresourcemanagerfor enterprisebeans. . . 185

CREA. . . 185

Using CICSdeployment toolsfor enterprisebeans . . . 186

Chapter19.Updatingenterprisebeansin aproductionregion . . . 189

Theproblem . . . 189

Possiblesolutions . . . 192

Solutionsfora singlelistener/AOR . . . 192

Solutionfor amulti-regionEJB server . . . 195

Other possiblesolutions . . . 197

Chapter20.TheCICSConnectorforCICSTS . . . 199

Overview oftheCICSConnectorforCICSTS. . . 199

WhatareCICSconnectors? . . . 199

TheCICSConnectorforCICSTS . . . 200

Thebackground—accessingCICSprogramsfromJava . . . 200

Benefitsof theCICSConnectorfor CICSTS . . . 203

Asampleapplication . . . 204

Using theCICSConnectorfor CICSTS’sCCFinterface . . . 204

SettingtheCCFinterface attributes. . . 206

IntroducingVisualAge forJavaEnterpriseAccessBuilder. . . 208

DataconversionandtheCICSConnectorforCICSTS. . . 210

TheCICSConnectorforCICSTS—usingtheCICSTransactionGatewayAPI 211 ECIRequest . . . 212

JavaGateway . . . 213

Restrictions andrecommendationsfor theCICSConnectorfor CICSTS . . . 214

InstallingtheCICSConnectorforCICSTS . . . 215

Requirements fortheCICSConnectorforCICSTS . . . 215

Installingtheconnector . . . 215

CICSConnectorfor CICSTSmessages . . . 216

Contents

vii

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

(10)

Tracing theCICSConnectorfor CICSTS. . . 216

CICStrace . . . 216

CICSTransactionGatewayforOS/390trace . . . 216

Chapter21.DealingwithCICSenterprisebeanproblems . . . 219

CICSenterprisebeanset-upproblems. . . 219

Methods thatrequiremultiplerequestprocessors. . . 219

Using EJBserverruntimediagnostics . . . 220

CICSenterprisebeanerrorsandmessages. . . 220

JVMtrace . . . 221

Debugging JavaapplicationsinCICS . . . 221

Using EJBclientruntimediagnostics . . . 221

CORBAexceptions. . . 222

Chapter22.Managingsecurityforenterprisebeans . . . 225

Protecting JavaapplicationsinCICS . . . 225

SpecifyingJVMsystem properties . . . 226

ConfiguringtheJVMtousetheJava2securitypolicy . . . 227

Enabling thedefaultJava2securitymanager . . . 227

Defininga securitypolicy. . . 227

Policyfileentries. . . 228

CICS-supplied enterprisebeanssecuritypolicy . . . 228

Using enterprisebean security. . . 231

Definingfileaccesspermissionsforenterprisebeans . . . 231

Derivingdistinguished names . . . 233

Security roles . . . 233

Deployed securityroles . . . 234

Enabling anddisablingsupportforsecurityroles . . . 236

Securityrolereferences . . . 236

Charactersubstitutionindeployedsecurityroles . . . 236

Securityroles inthedeployment descriptor . . . 238

Implementingsecurityroles. . . 239

Using theRACFEJBROLEgeneratorutility. . . 240

Definingsecurityrolesto RACF . . . 241

Chapter23.CICSPlex SMwithEnterpriseJavaBeans. . . 243

CICSPlex SMsupportforenterprisebeans. . . 243

CICSPlexSM definitionsupportforenterprisebeans . . . 243

BASlogical scopeconsiderations . . . 244

Enterprise JavaBeancomponentmigration . . . 245

CICSPlexSM inquirysupportforenterprisebeans . . . 245

Typesof inquiryavailableforenterprisebeanobjects . . . 246

Using CICSPlexSMtomanage EnterpriseJavaBeanworkloads . . . 246

Workloadbalancing. . . 247

Workloadseparation . . . 247

CICSPlexSM resourcemonitoringconsiderationsfor EnterpriseJavaBeans 248 CICSPlexSM real-timeanalysisconsiderationsfor EnterpriseJavaBeans 248

Part

6. Using

stateless

CORBA

objects

.

. 251

Chapter24.StatelessCORBAobjects . . . 253

DevelopingstatelessCORBAobjects . . . 253

Obtaininganinteroperableobjectreference (IOR) . . . 255

CreatingtheInterfaceDefinitionLanguage(IDL) . . . 256

DevelopinganIIOPserverprogram. . . 257

IDLexample . . . 259 || || || || || || || || || ||

(11)

Serverimplementation. . . 259

Resourcedefinitionfor example . . . 259

DevelopingtheIIOPclientprogram. . . 260

Client example . . . 260

DevelopinganRMI-IIOPstatelessCORBAapplication. . . 262

Stand-aloneCICSCORBAclientapplications . . . 264

CORBAinteroperability . . . 264

Using non-JavaCORBAclients . . . 265

Writing aCORBAclientto anenterprisebean . . . 265

Enterprise beansasCORBAclients. . . 265

Codesets . . . 266

Chapter25.MigratingIIOPapplicationsfromCICSTS1.3 . . . 267

Chapter26.Usingthe IIOPsamples. . . 269

SettinguptheIIOPsampleenvironment . . . 269

RunningtheIIOPHelloWorldsample . . . 273

Building theserversideHelloWorldapplication. . . 273

Building theclientside HelloWorldapplication . . . 273

RunningtheHelloWorldsampleapplication. . . 274

RunningtheIIOPBankAccountsample . . . 274

CreatingtheVSAMfile . . . 274

Building theserversideBankAccount application. . . 274

Building theclientside BankAccountapplication . . . 274

RunningtheBankAccountsampleapplication . . . 275

Part

7. Using

VisualAge

for

Java

ET/390.

.

. 277

Chapter27.VisualAgeforJava,ET/390 . . . 279

RunningaJavaprogramobjectinCICS . . . 280

Run-timerequirements . . . 280

Chapter28.Javahot-poolingconcepts . . . 283

OpentransactionenvironmentTCBs . . . 283

H8mode TCBallocationforhot-pooling . . . 284

Using hot-poolingwithET/390. . . 285

DefiningLanguageEnvironmentrun-timeoptions. . . 285

Allocatingstorage . . . 285

Defininghot-pooledJavaprogramobjects . . . 286

Programmingfor Javahot-pooling . . . 287

Static storageandstaticinitializers . . . 287

Programminginterfaces . . . 288

Protection keys . . . 288

Exitprogramminginterface (XPI). . . 288

Hot-poolingexitprogram. . . 288

Security . . . 289

Problemdetermination . . . 289

Bibliography . . . 291

CICSTransactionServerforz/OS . . . 291

CICSbooksforCICSTransactionServerforz/OS . . . 291

CICSPlex SMbooksforCICSTransactionServer forz/OS . . . 292

Other CICSbooks . . . 292

Determiningif apublicationiscurrent . . . 293

Accessibility . . . 295 Contents

ix

# # # # # # # # # # # # # #

(12)

Index. . . 297

Notices . . . 303

Trademarks. . . 304

(13)

Preface

What

this

information

is

about

This informationtellsyouhow todevelop anduseJava™ applicationsand

Enterprise JavaBeans™inCICS®.Itisdesignedto beaccessedonlinethroughthe CICSInformationCenter,butisalsoavailableasapdf,inabook format,for printing.

This documentationisdesignedto beaccessed randomly,ratherthanread sequentially,usinghypertextlinkstomovelogicallythroughthetopics.

Who

should

read

this

information

This informationisintended forexperiencedJavaapplicationprogrammers,who have littleexperience ofCICS,andnogreatneedtoknowmoreaboutCICSthanis necessary todevelopandrunJavaprograms.Itshouldalso beusefulto

experiencedCICSusersandsystem programmers,whoneedto knowaboutCICS requirements fortheJavasupport.

(14)

(15)

Summary

of

Changes

This informationisbasedontheJava™_applications_in_CICS_for_CICS_Transaction

Serverfor z/OSVersion2Release1. Changesfromthateditionaremarkedby vertical barsintheleftmargin.

Changes

for

CICS

Transaction

Server

for

z/OS,

Version

2 Release

2

Themoresignificantchangesfor thiseditionare:

v _Parts_of_Chapter_11,_{“Configuring}_CICS_for_IIOP,”_on_page_73,_Chapter_13,_“What areenterprisebeans?,”onpage103,andChapter14,“SettingupanEJB

server,”onpage129have beenrewrittento describeCICSenhancedsupportfor enterprisebeans,includinganeasierwayto installdeployedJARfiles.

v _Chapter_15,_“Running_the_EJB_IVP,”_on_page₁₄₁_has_been_rewritten _to_reflect changesto theEJBInstallationVerificationProgram(IVP).

v _Chapter_16,_“Running_the_sample_EJB_{applications,”}_on_page₁₄₅_has_been rewrittento reflectchangestotheEJB sampleapplications.

v _Chapter_18,_“Deploying_enterprise_beans,”_on_page₁₈₅_and_“The_deployment toolsfor enterprisebeansinaCICSsystem”onpage185have beenupdatedto reflectthereplacement oftheEJBdeployment tools.

v _Support_has_been _added_for _Java_security_roles._See_“Security_roles”_on_page 233.

v _Support_is_added_for_a_Lightweight_Directory_Access_Protocol_(LDAP)_name server.See“SettingupanLDAPserver”onpage75.

(16)

(17)

Part

1. Java

Development

Roadmaps

This Parttellsyouallthestepsneededto implementJavaapplicationsinCICS.It coversthefollowingtasks:

v _“Java_application_roadmap_for_CICS”_on_page₃ v _“CICS_IIOP_application_roadmap”_on_page ₃ v _“CICS_enterprise_beans_roadmap”_on_page₃

(18)

(19)

Chapter

1. Java

development

roadmaps

Thefollowingroadmapsshowyouthestepstofollowto developthedifferent “Typesof JavaapplicationinCICS”onpage7thatyou canuse:

v _“Java_application_roadmap_for_CICS” v _“CICS_IIOP_application_roadmap” v _“CICS_enterprise_beans_roadmap”

Java

application

roadmap

for

CICS

1. WriteaJavaapplication,usingtheJCICSclassesto accessCICSservicesand resources.SeeChapter4, “JavaprogramminginCICS,”onpage13.

2. UsetheJavaVirtualMachineinCICSto executeyourapplication.See

Chapter7,“AbouttheJVM,”onpage41andChapter8, “ConfiguringtheJVM,” onpage51.

CICS

IIOP

application

roadmap

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

2. WriteyourIIOPserverapplication,alsoknown asa ’statelessCORBAobject’. See“DevelopingstatelessCORBAobjects” onpage 253,“CreatingtheInterface Definition Language(IDL)” onpage256, and“DevelopinganIIOPserver program”onpage257.

3. Writeyourclientprogram.See“DevelopingtheIIOPclientprogram”onpage 260.

CICS

enterprise

beans

roadmap

1. Readtheoverviewofthestepsinvolvedinsetting upaCICSEJB server—see “ConfiguringCICSasanEJBserver—overview”onpage118.

2. Set upa basic,single-regionEJBserverandname server—see“Settingupa single-regionEJBserver”onpage129.

3. Test yoursingle-regionEJBserverbyrunningtheEJBinstallationverification program(IVP)—seeChapter15,“RunningtheEJBIVP,” onpage 141. 4. Further testyourEJBserverbyrunningtheEJB sampleapplications—see

Chapter16,“RunningthesampleEJB applications,”onpage 145.

5. Optionally,expandyoursingle-regionEJBserverintoamulti-regionserver capable ofload balancing—see“Settingupamulti-regionEJB server”onpage 137.

6. Implementanysecuritycontrolsrequiredbyyoursystem,seeChapter22, “Managingsecurityforenterprisebeans,”onpage225.

7. Codeyoursessionbean.If youarenotusinganIntegratedDevelopment Environment(IDE),see “Codingasessionbean”onpage172.

8. Follow thedeployment processdescribedinChapter18,“Deployingenterprise beans,”onpage185,usingthetoolsasdescribedin“UsingCICSdeployment toolsforenterprisebeans”onpage 186

9. Writetheclientprogram.See“Writingtheclientprogram”onpage 175.

©Copyright IBM Corp.1999, 2004

3

| | | | | | | | | | |

(20)

(21)

Part

2. Developing

Java

applications

for

CICS

This Parttellsyouwhatyou needtoknowto developanduseCICSapplications writteninJava.Itcoversthefollowingtopics:

v _Chapter_2, _“Java_applications_in_CICS,”_on_page ₇

v _Chapter_3, _“What_you_need_to_know_about _CICS,”_on_page ₉ v _Chapter_4, _“Java_programming_in_CICS,”_on_page₁₃

v _Chapter_5, _“Accessing_data_from_CICS_applications_written_in_Java,”_on_page₃₁ v _Chapter_6, _“Using_the_JCICS_sample_programs,” _on_page₃₃

(22)

(23)

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 VisualAgeforJava,EnterpriseEditionforOS/390(ET/390)to bindthe

JavabytecodeintoOS/390®executablefiles,knownasJavaprogramobjects,

thatarestoredinMVS™PDSElibrariesandexecutedbyCICSinaLanguage Environment® (LE)run-unit,similarlytoC++.

Types

of

Java

application

in

CICS

You canusethefollowingtypesofJavaprograminCICS:

CICSapplicationsforJava

You canwriteJavaprogramsthatusetheJCICSclasslibrary.JCICSallows youto accessCICSresourcessuchasVSAM files,CICStransient dataqueues andtemporary storage.Italsoallowsyouto linkto CICSapplicationswrittenin otherlanguages Mostofthefunctionsof theEXECCICSprogramminginterface aresupported.JCICSissuppliedindfjcics.jarandcanbedownloadedto your workstation.It isalso availablewithsomereleasesof VisualAge®for Java. JCICS applicationscanbeboundbytheET/390bytecodebinderto formJava ProgramobjectsthatcanbeloadedandexecutedbyCICS,or theycanbe runintheCICSJVM.

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) distributedtransactions.If aclientcallsanIIOPapplicationinthescopeofan OTStransaction,informationabout thetransactionflowsasanextra parameter ontheIIOPcall.Ifa targetstatelessCORBAobjectimplements

CosTransactions::TransactionalObject,thentheobjectwillbetreatedas transactional.

Note: AnOTStransactionisadistributedunitof work,nota CICStransaction instanceorresourcedefinition.

StatelessCORBAobjects canusetheJCICSAPIto interactwithCICS. CICSstatelessCORBAobjectscanexecuteonly intheCICSJVM.

(24)

You canreadmoreaboutCICSstatelessCORBAobjects inChapter24, “StatelessCORBAobjects,”onpage 253.

Enterprisebeans

Enterprise beansareportableJavacomponentsthatcomplywithSun Microsystem’sEnterpriseJavaBeansSpecification,Version1.1(EJB) specification.CICShasimplementedtheseinterfacesbymappingthemto underlyingCICSservices.Enterprisebeanscanlink tootherCICSapplications usingconnectors.Youcanalsodevelop enterprisebeansthatusetheJCICS classlibraryto accessCICSservicesorprogramsdirectly, butthese

applicationswillnotbeportabletoanon-CICSEJB compliantserverplatform. TheEnterpriseJavaBeansspecification definestransactionaldistributedobjects thatcommunicateusingtheJavaRemote MethodInvocation(RMI)interface. CICSsupports RMIoverIIOP,mediatedusingaCORBAObjectRequestBroker (ORB)

Enterprise beanscanexecute onlyintheCICSJVM.

You canreadmoreaboutEnterprisebeansinChapter13,“Whatareenterprise beans?,” onpage 103

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

(25)

Chapter

3. What

you

need

to

know

about

CICS

CICSisatransactionprocessing subsystem.Thismeansthatit providesservices for youtorunapplicationsonline,byrequest,atthesametimeasmanyother users aresubmittingrequests torunthesameapplications,usingthesamefilesand programs. CICSmanagesthesharingofresources;integrity ofdataand prioritizationof execution,withfastresponse.

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,transactionsandtasks.Thesetermsareused throughout CICSdocumentationandappearinmanyprogrammingcommands

CICS

transactions

Atransactionisapieceofprocessinginitiatedbyasinglerequest.Thisisusually fromanend-userata terminal,butmayalso bemade fromaWebpage, froma remoteworkstationprogram,fromanapplicationinanotherCICSsystemor

triggeredautomatically ata predefinedtime.TheCICSInternetGuideandtheCICS ExternalInterfacesGuidedescribedifferentwaysof runningCICStransactions. Asingletransactionconsistsofoneor moreapplicationprogramsthat,whenrun, carry outtheprocessing needed.

However, thetermtransactionisusedinCICStomean bothasingleeventandall other transactionsof thesametype.Youdescribeeachtransaction typetoCICS withaTRANSACTIONresource definition.This definitiongivesthetransactiontype a name(thetransactionidentifier,orTRANSID)andtellsCICSseveralthings about theworkto bedone; suchaswhatprogramto invokefirst,andwhatkindof authentication isrequiredthroughouttheexecutionofthetransaction.

You runa transactionbysubmittingitsTRANSIDto CICS.CICSusesthe informationrecordedintheTRANSACTIONdefinitiontoestablishthecorrect executionenvironment,andstartsthefirstprogram.

ThetermtransactionisnowusedextensivelyintheITindustryto describea unit of recoveryorwhatCICScallsa unitofwork.Thisistypicallya complete

operation thatisrecoverable;itcanbecommittedorbacked outasanentiretyasa resultofprogrammedcommandorsystem failure.Inmanycasesthescopeof a CICStransactionisalso asingleunitof work,butyoushouldbeawareofthe difference inmeaning whenreadingCICSdocumentation.

(26)

CICS

tasks

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

transaction, itstartsanew taskthatisassociatedwiththisoneinstanceofthe execution ofthetransactiontype.Thatis,oneexecutionofa transaction,withits own privatesetofdata,usuallyonbehalfof aspecificuser.Youcan alsoconsider a taskasathread.Tasksaredispatched byCICSaccordingto theirpriorityand readiness.When thetransaction completes,thetaskisterminated.

CICS

application

programs

You writea CICSprograminmuchthesamewayasyouwriteanyotherprogram. You canuseCOBOL,OO COBOL,C,C++ ,Java,PL/I,orassemblerlanguageto writeCICSapplicationprograms. Mostof theprocessing logicisexpressedin standard languagestatements, butyouuse CICScommands, ortheJavaandC++ class librariestorequestCICSservices.

Theuseof theCICScommandlevelprogramminginterface,’EXEC CICS’,whichis used inCOBOL,OOCOBOL,C,C++,PL/Iorassemblerprogramsisdescribedin theCICSApplication ProgrammingReferenceandtheCICSSystemProgramming Reference.

In Javaprograms,youcanusetheJCICSclassesto accessCICSservicesandlink to CICSapplicationprogramswritteninotherlanguages.ThetypesofJava

programthatyoucanwritearelistedin“TypesofJavaapplicationinCICS”on page 7andJCICSisdescribedin“TheJCICSclass library”onpage13. You canwriteenterprisebeansthatusetheinterfacesdefinedintheSun

Microsystem’sEnterpriseJavaBeansSpecification,Version1.1,which isavailable at http://www.javasoft.com/products/ejb.CICSimplementsthisspecificationby mapping programrequeststransparentlyto underlyingCICSservices.You canalso use theJCICS classesto callCICSservicesdirectly,butthenyourEnterprise beanswillnotbeportableto non-CICSservers.

CICS

services

CICSprovidesthefollowingservices,whichyoucanaccessthroughtheJCICS and EXECCICSprogramminginterfaces.CICSservicesmanagersaretraditionally called ’control’,suchasterminalcontrolorprogramcontrol.Youwillfindthese terms usedextensivelyinCICSpublications:

Data managementservices

CICSprovides:

v _Record-level_sharing_with_integrity _in_accessing_Virtual_Storage_Access Method(VSAM)datasets.CICSlogsactivitytosupportdatabackout inthe caseof transactionorsystem failure,andtosupportforwardrecoveryinthe caseof mediafailure.ManagementofVSAM dataisprovidedbyCICSFile Control.CICSalsoimplementstwoproprietaryfilestructures,andprovides commandstomanipulate them:

TemporaryStorage

Temporarystorageisameansof makingdatareadilyavailableto multipletransactions.Dataiskept inqueues createdasrequiredby aprogramandcanbeaccessed sequentially,orbyitemnumber.

(27)

Temporarystoragequeuescanresideinmainmemory,or bewritten toastoragedevice.Atemporarystoragequeuecanbethoughtofas anamedscratch-pad.

TransientData

Transientdataisalso availabletomultipletransactions,andiskept inqueues, butthey mustbepredefinedandcanonly beread sequentially.Eachitemisremovedfromthequeuewhenit isread. Transientdataqueuesarealwayswrittento adataset.Youcan definea transientdataqueuesothatwritingitemstoitcan actasa triggerto startaspecifictransaction(forexample,to processthe queue).

v _Access_to_data _in_other_databases_(including_DB2®_),_through_interfaces_with databaseproducts.

Communications services

CICSprovidescommandsgivingaccessto awiderangeof terminals:displays, printersandworkstations, usingSNAandTCP/IPprotocols.You canwrite programs thatuseAPPC(AdvancedProgramto ProgramCommunication) commands tostartandcommunicatewithotherprogramsinremotesystems, usingSNAprotocols.CICSAPPCimplementsthepeer-to-peerdistributed applicationmodel.Managementof CICSManagement ofSNAandTCP/IP networksisprovidedbyCICSterminalcontrol.

CICSalso providesanObjectRequestBroker(ORB)to implementtheinbound andoutbound IIOPprotocolsdefinedbytheCommonObject RequestBroker Architecture(CORBA), supportingrequests toexecute Javastatelessobjects andenterprisebeans.ThefollowingCICSproprietarycommunicationsservices areprovided:

Function Shipping

Program requeststoaccessresources(files,queues andprograms) thataredefinedasexistingonremoteCICSsystemsareautomatically routed byCICSto theowning system.

DistributedProgramLink(DPL)

Program LINKrequestsfor aprogramdefinedasexistingonaremote CICSsystemareautomaticallyrouted totheowningsystem.CICS providescommandstomaintaintheintegrityof thedistributed application.

AsynchronousProcessing

CICSprovidescommandstoallowa programto startanother transactioninthesame,orremote,CICSsystem andoptionallypass datato it.Thenewtransaction isscheduled independently,ina new task.Thisfunctionissimilarto thefork operationprovided byother softwareproducts.

TransactionRouting

Requeststo runtransactionsthataredefinedasexistingonremote CICSsystemsareautomatically routedto theowning system.

Responsesto theend-userareroutedbacktothesystem thatreceived therequest.

Unit-of Workservices

WhenCICScreatesa newtaskto runa transaction,anew unit-of-workis startedautomatically.CICSdoes notprovide aBEGINcommand.CICS transactionsarealwaysexecutedin-transaction.CICSprovidesa SYNCPOINT commandto commitorrollbackrecoverableworkdone. Whenthesyncpoint

(28)

completes, CICSautomatically startsanotherunit-of-work.If youterminateyour programwithout issuingaSYNCPOINTcommand,CICStakesanimplicit syncpoint andattemptstocommit.

Thescopeof thecommit includesallCICSresourcesthathavebeendefined as recoverable, andanyotherresourcemanagersthathaveregisteredaninterest throughCICSprovidedinterfaces.

If youwriteenterprisebeansusingtransaction servicesprovided bycommands definedbytheJavaTransactionService(JTS),thesecommands(including BEGIN)areimplementedinCICSbymapping themtounderlying unit-of-work services.

Programservices

CICSprovidescommandsenablingyou tolinkor transfercontrolto another program,andreturn.

Diagnosticservices

CICSprovidescommandsenablingyou totraceanddump programactivity.

Otherservices

CICSprovidesotherservices,suchasjournaling,timer,storagemanagement, thatarenotavailablethroughtheJCICS interface,butaredescribedinthe CICSApplication ProgrammingGuide

(29)

Chapter

4. Java

programming

in

CICS

You canwriteJavaapplicationprograms thatuseCICSservicesandexecute under CICScontrol.

You writeJavaprogramsonaworkstation,orintheOS/390UNIXSystemServices shell,usinganeditorof yourchoice,orinavisual compositionenvironment suchas VisualAge.

CICSprovidesaJavaclasslibrary,known asJCICS, suppliedindfjcics.jar.JCICS istheJavaequivalentoftheEXECCICSapplicationprogramminginterface (API) thatyouwould usewithotherCICSsupportedlanguages,suchasCOBOL.It allowsyouto accessCICSresourcesandintegrateyourJavaprograms with programs writteninotherlanguages. Mostofthefunctionsof theCICSEXECAPI aresupported.See“TheJCICSclasslibrary”for adescriptionof theJCICSAPI. TheJavalanguageisdesignedtobeportableandarchitecture-neutral.The bytecodegenerated bycompilationisportable,butrequiresamachine-specific interpreter forexecutionondifferentplatforms.CICSprovidesthisexecution environment intwo differentways:

1. Using aJavaVirtualMachine(JVM)thatisexecutingunderCICScontrol.This istherecommendedmethod.

2. Using VisualAgeforJava,EnterpriseEditionforOS/390to bindtheJava bytecodeintoOS/390executablefiles,knownasJavaprogramobjects,that arestoredinOS/390PDSElibrariesandexecutedbyCICSinaLanguage Environmentrun-unit,similarlyto C++.

Note: CICSTS forz/OSVersion 2 supportshpj-boundJavaprogramobjects thatweredevelopedusingCICS TSOS/390Version1Release 3 and itsassociatedtooling. Suchprogramobjects willruninCICSTSfor z/OS Version 2unchanged, butCICSTSforz/OS Version 2CICSTSV2 providesnosupportfordeveloping newJavaprogramobjectsnorfor modifyingexistingJavaprogramobjects.Theversionof JCICSsupplied inCICSTSfor z/OSVersion 2shouldnotbeusedto compileJava programobjects.

You canreadaboutVisualAgefor Java,Enterprise Editionfor OS/390in Chapter27,“VisualAgeforJava,ET/390,”onpage279andtheCICSJVMin Chapter7,“AbouttheJVM,”onpage41.

The

JCICS

class

library

TheJavaclasslibraryforCICS,JCICS,supports mostof thefunctionsof theEXEC CICSAPIcommands, withthelimitationsdescribedin“JCICScommandreference” onpage17.

TheJCICSclassesarefullydocumentedinJAVADOC htmlthatisgeneratedfrom theclassdefinitions.ThisisavailablethroughtheCICSInformationCenter,andcan befoundat JCICSJavadocclassReference.

Translation

There isnoneedfor aCICStranslatorfor Javaprograms.

(30)

JavaBeans

Some oftheclassesinJCICS maybeused asJavaBeans,whichmeansthatthey can becustomizedinanapplicationdevelopmenttoolsuchasVisualAgeforJava, serialized, andmanipulatedusingtheJavaBeansAPI.ThebeansinJCICSare currently: 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 callingnew fortheclassitself.(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 besetbyinvokingtheappropriatesetter methods at run-time.

Library

structure

JCICS librarycomponentsfallintooneof 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 classthatprovidesfor commoninitializationfor everyclassthat corresponds toa partof theCICSAPI, exceptforABENDsandexceptions.For example,theTaskclassprovidesasetof methodsandvariablesthat

correspondto aCICStask.

ErrorsandExceptions

TheJavalanguagedefines bothexceptionsanderrorsassubclassesofthe classThrowable.JCICSdefinesCicsError asasubclassof Errorandit providesthesuperclassfor allotherCICSerrorclasses.Theseareusedfor severeerrors.

JCICS definesCicsExceptionasasubclassof Exception.CicsException providesthesuperclassfor allCICSexceptionclasses.Thisincludesthe

(31)

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,byusingCEDAorCICSPlex®SM BAS.See theCICSApplication ProgrammingReferenceor CICSPlexSystemManager Concepts andPlanningforinformationabout definingCICSresources.Itispossible to useimplicitremoteaccessbydefiningaresource locallyto pointtoa remote resource.

Note: BeforeusingCEDA,youmayneedto useCEOTto enableyour terminalto handlemixedcaseinput— fordetails, seeCICSSupplied Transactions.

CICS

storage

requirements

Memoryrequirements torunJavaprograms arehigherthanforconventional programs. Therefore:

1. You shouldaskyourCICSsystemprogrammer tosetthevalueoftheEDSALIM system initializationparameterto aminimumof200MB,otherwisea

Short-on-Storageconditionmayoccur.Notethatthisvaluemustbesetinthe startupjob-controlcommands;it cannotbechanged duringCICSexecutionby meansof CEMTSETcommands.

2. Your CICSjobshouldseta minimumREGIONvalueof 400MB.

Command

arguments

ManyCICSprogrammingcommands,suchas“DistributedProgramLink” onpage 11passdataina structureknownasaCOMMAREA.This,andsimilarparameters arepassedasargumentstotheappropriatemethods.Manyofthemethodsare overloaded, thatis,theyhavedifferentversionsthattakeeithera differentnumber of argumentsorargumentsofadifferenttype.Theremay beonemethodthathas noarguments,ortheminimummandatoryarguments,andanotherthathasallof thearguments.Forexample,therearethefollowingdifferentlink()methodsinthe Program class:

link()

This versiondoesa simpleLINKwithoutusinga COMMAREAtopassdataor anyother options.

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

This versiondoesa simpleLINKusingaCOMMAREAto passdata butwithout anyother options.

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

This versiondoesa distributedLINKusingaCOMMAREAto passdataand also aDATALENGTH valueto specifythelengthofthedatawithinthe COMMAREA.

Chapter4.JavaprogramminginCICS

15

# # # # # # # # #

(32)

link(com.ibm.record.IByteBuffer)

This versiondoesa LINKusinganobjectthatimplementstheIByteBuffer interface oftheJavaRecordFrameworksuppliedwithVisualAgefor Java.

Serializable

classes

ThefollowingJCICS classesareserializableandsocansurvivea Passivate/Activater 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-basedmessagepassingschemes.Youcanalso usetheframework for newapplications, andfor applicationsaccessingexistingfiles.

TheJavaRecordFrameworkispartof VisualAgeforJava.Youcanfindoutmore about itintheVisualAgedocumentation,whichissuppliedinHTMLformatwiththe product.

System.out

and

System.err

If aCICStaskisbeingdrivenfroma terminal(theterminaliscalledaprincipal facility inthis case)thenCICSautomatically createstwoJavaPrintWritersthatcan beused asstandard outandstandarderrorstreamsandaremappedtothetask’s terminal. Ifthetaskdoes nothaveaterminal asitsprincipalfacility,thestreams are sent toSystem.outandSystem.err.Thetwostreams arepublicfieldsintheTask called outanderrSystem.outandSystem.erraremappedto theCICStransient data queuesCESOandCESErespectively.YourCICSsystemsprogrammer creates thesequeues,andothersusedfor CICSmessages,duringCICS

installation.Youcanaccessandprintordisplaythesemessagequeuesusingutility | | | | | | | | | | | | | | | | | | | | | |

(33)

programs, orusetheDFH$TDWTsampleprogramdescribedintheCICS

CustomizationGuide.DFH$TDWTissuppliedwiththeCICSpregeneratedsystem inCICSTS22.CICS.SDFHLOAD.

Threads

Onlyonethread (theinitialthread) canaccesstheCICSAPI.Youcan createother threadsbutyoumust routeallrequeststo theCICSAPIthroughtheinitialthread. Additionally,youmust ensurethatallthreadsotherthantheoriginalthread have terminatedbefore doinganyof thefollowing:

v _link() v _xctl()

v _{setNextTransaction(),}_{setNextCOMMAREA()} v _commit(),_rollback()

v _returning_an_{AbendException}

Note: MultiplethreadsarenotsupportedbyET/390.

JCICS

command

reference

Some oftheoptionsandservicesavailablethroughtheEXECCICSAPIarealso availablefromJCICS. Thissectionshows therelationshipbetweenEXECCICS commands andtheequivalent JCICSfunction.For afulldescription oftheEXEC CICScommands, seetheCICSApplicationProgrammingReference.

JCICS supportisdescribedunderthefollowingheadings: v _“Error_handling_and_abnormal_{termination”}_on_page₁₉ v _“CICS_exception_handling_in_Java_programs”

v _“APPC_mapped_{conversations”}_on_page₁₉ v _“Basic_Mapping _Support_(BMS)” _on_page₂₀ v _{“Diagnostic}_services”_on_page₂₀

v _{“Environment}_services”_on_page ₂₀ v _“File_services”_on_page ₂₃

v _“Program_services”_on_page₂₅ v _{“Scheduling}_services”_on_page ₂₆ v _{“Serialization}_services”_on_page₂₆ v _“Storage_services”_on_page₂₆

v _“Temporary_storage_queue_services”_on_page₂₆ v _“Terminal_services”_on_page₂₇

v _“Transient_data_queue_services”_on_page₂₇ v _“Unit_of _Work_(UOW)_services”_on_page₂₈ v _{“Unsupported}_CICS_services”_on_page₂₈

CICS

exception

handling

in

Java

programs

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

This leadsto anABEND-handlingmodelinJavathatissimilartotheother

programming languages;asinglehandlerisgivencontrolforeveryABEND,andthe handlerhasto querytheparticularABENDandthendecidewhatto do.

If theexceptionrepresentingaconditioniscaughtbyCICSitself,it isturned intoan ABEND.

(34)

Javaexception-handlingisfullyintegratedwiththeABENDandcondition-handling inotherlanguages,sothatABENDscanpropagate betweenJavaandnon-Java programs, inthestandardlanguage-independentway.Aconditionismappedto an ABENDbeforeit leavestheprogramthatcausedordetected thecondition. In addition,there areseveraldifferencesto theabend-handlingmodelfor other programming languages,resultingfromthenatureof theJavaexception-handling architecture andtheimplementation ofsomeofthetechnology underlyingtheJava API:

v _ABENDs_that_are_considered _unhandleable_in_other_programming_languages_can becaughtinJavaprograms.TheseABENDstypicallyoccurduringSYNCPOINT processing.ToavoidtheseABENDs interruptingJavaapplicationstheyare mappedtoanextensionof anunchecked exceptionandthereforethey donot haveto bedeclared orcaught.

v _Several_internal_CICS_events, _such_as_program_termination_are_also _mapped_to JavaexceptionsandcanthereforeagainbecaughtbyaJavaapplication.Again, toavoidinterruptingthenormalcasethesearemappedto extensionsof an uncheckedexceptionandsodonothave tobecaughtordeclared.

Note: CICSrequiresthattheLanguageEnvironmentproductisinstalledandactive onyourOS/390system inorderto runJavaapplications.Youshouldnot definetheLanguageEnvironmentrun-timeoptionTRAP=OFF, asthis will disableAbendHandlinginJCICS.

There arethreeCICS-related classhierarchiesofexceptions:

1. CicsError whichextendsjava.lang.Error andisthebase forAbendErrorand UnknownCicsError.

2. CicsRuntimeExceptionwhichextends java.lang.RuntimeExceptionandisin turnextendedby:

AbendException

representsanormalCICSABEND.

EndOfProgramException

indicatesthata linked-toprogramhasterminatednormally.

TransferOfControlException

indicatesthata programhasused anxctl()method,theequivalentof the CICSXCTLcommand.

3. CicsException whichextendsjava.lang.Exception andhas thesubclass:

CicsConditionException.

thebase classforallCICSconditions.

CICS

error

handling

commands

CICSconditionhandlingisintegratedintotheJavaexception architectureas describedabove.Thewaythateach commandissupportedisdescribedbelow:

HANDLEABEND

TohandleanABENDgenerated byaprograminanyCICSsupportedlanguage, you canuseaJavatry-catchstatement,withAbendExceptionappearingina catchclause.

HANDLE CONDITION

Tohandleaspecificcondition,suchasPGMIDERR,youcanuseacatch clause thatnamestheappropriateexception,inthiscase

InvalidProgramException.Alternatively,you canuseacatchclausenaming CicsConditionExceptionifallCICSconditions areto becaught.

(35)

IGNORECONDITION

This commandisnotrelevantinJavaapplications.

POPandPUSHHANDLE

ThesecommandsarenotrelevantinJavaapplications.TheJavaexceptions used torepresentCICSABENDsandconditions arecaughtbyanycatchblock inscope.

CICS

conditions

Thecondition-handling modelinJavaisdifferentfromotherCICSprogramming languages.

In COBOL,you candefineanexception-handlinglabelfor eachcondition,andif thatconditionoccursduringtheprocessingof aCICScommand,controltransfers to thelabel.

In CandC++,youcannotdefineanexception-handlinglabelforacondition;the RESPfieldintheEIBmustbecheckedaftereachCICScommandto detecta condition.

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 28for adescriptionof therelationship betweenCICSconditionsandJavaexceptions.

Error

handling

and

abnormal

termination

Methods JCICS class EXEC CICS commands

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), thenCICSwill terminate androll-backthetransaction.

ABEND CANCEL

ToinitiateanABENDthatcannotbehandled, youinvokethe

Task.forceAbend(String)method, supplyinganABENDcode.Asdescribed above,this willcauseanAbendCancelExceptiontobethrownwhichcanbe caughtinJavaprograms.Ifyoudoso,youmustre-throwtheexceptionto completeABEND_CANCELprocessing,sothatwhencontrolreturnsto CICS,it willterminateandrollbackthetransaction.Youshouldonly catch

AbendCancelExceptionfornotificationpurposesandthen youshouldre-throwit.

APPC

mapped

conversations

APPCunmappedconversationsupportisnotavailablefromtheJCICSAPI. APPCmappedconversations:

(36)

Methods JCICS class EXEC CICS Commands

initiate() AttachInitiator ALLOCATE,CONNECT PROCESS

converse() Conversation CONVERSE

get*() methods Conversation EXTRACT ATTRIBUTES

get*() methods Conversation EXTRACT PROCESS

free() Conversation FREE

issueAbend() Conversation ISSUE ABEND

issueConfirmation() Conversation ISSUE CONFIRMATION

issueError() Conversation ISSUE ERROR

issuePrepare() Conversation ISSUE PREPARE

issueSignal() Conversation ISSUE SIGNAL

receive() Conversation RECEIVE

send() Conversation SEND

flush() Conversation WAIT CONVID

Basic

Mapping

Support

(BMS)

sendControl() TerminalPrincipalFacility SEND CONTROL

sendText() TerminalPrincipalFacility SEND Text

Not supported SEND MAP, RECEIVE MAP

Diagnostic

services

Not supported DUMP

enterTrace() EnterRequest ENTER

enableTrace(), disableTrace() Region, Task TRACE

Environment

services

CICSenvironment servicesprovideaccesstoCICSdataareas,parametersand resource attributesthatarerelevanttoanapplicationprogram.TheonlyEXEC CICScommandsandoptions thathaveequivalentJCICSsupportare:

v _ADDRESS v _ASSIGN v _INQUIRE_SYSTEM v _INQUIRE_TASK v _INQUIRE_{TERMINAL/NETNAME}

ADDRESS

Thefollowingsupportisprovided fortheADDRESSoptions. SeetheCICS Application ProgrammingReferencemanual forinformationabouttheEXECCICS

ADDRESS command.

COMMAREA

(37)

link().TheCOMMAREApointerispassedautomaticallyto thelinked programbytheCommAreaHolderargument .See“Commandarguments”on page 15formoreinformation.

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

eibtrnid

isreturnedbythegetTransactionName()methodoftheTaskclass.

eibaid isreturnedby thegetAIDbyte()method of the TerminalPrincipalFacilityclass.

eibcposn

isreturnedbythegetRow()andgetColumn()methods oftheCursor class.

TCTUA

TheTerminalControlTableUserArea(TCTUA)containsuserdatathatis associatedtheterminalthatisdrivingtheCICStransaction(theprincipal facility).Thisareaisusedto passinformationbetweenapplication programs, butonly ifthesameterminalisassociatedwiththeapplication programsinvolved.ThecontentsoftheTCTUAcanbeobtained usingthe getTCTUA()methodoftheTerminalPrincipalFacilityclass.

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

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

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

ASSIGN

Thefollowingsupportisprovidedfor theASSIGNoptions. SeetheCICSApplication ProgrammingReferencemanualfor informationabouttheEXECCICSASSIGN command.

Thefollowingsupportisprovidedfor theASSIGNoptions:

getABCODE() AbendException ASSIGN ABCODE

getAPPLID() Region ASSIGN APPLID

getCWA() Region ASSIGN CWALENG

getName() TerminalPrincipalFacility or

ConversationPrincipalFacility

ASSIGN FACILITY

getFCI() Task ASSIGN FCI

getNetName() TerminalPrincipalFacility or ConversationPrincipalFacility ASSIGN NETNAME getPrinSysid() TerminalPrincipalFacility or ConversationPrincipalFacility ASSIGN PRINSYSID

getProgramName() Task ASSIGN PROGRAM

(38)

getQNAME() Task ASSIGN QNAME

getSTARTCODE() Task ASSIGN STARTCODE

getSysid() Region ASSIGN SYSID

getTCTUA() TerminalPrincipalFacility ASSIGN TCTUALENG

getTERMCODE() TerminalPrincipalFacility ASSIGN TERMCODE

getTWA() Task ASSIGN TWALENG

getUserid(), Task.getUSERID() Task,

TerminalPrincipalFacility or

ConversationPrincipalFacility

ASSIGN USERID

No otherASSIGNoptions aresupported.

INQUIRE

SYSTEM

Thefollowingsupportisprovided fortheINQUIRESYSTEMoptions:

getAPPLID(), getSYSID() Region INQUIRE SYSTEM

No otherINQUIRESYSTEMoptionsaresupported.

INQUIRE

TASK

Thefollowingsupportisprovided fortheINQUIRETASKoptions:

getAPPLID(), getSYSID() Task INQUIRE TASK FACILITY

getSTARTCODE() Task INQUIRE TASK STARTCODE

get TransactionName() Task INQUIRE TASK TRANSACTION

getUserid() Task INQUIRE TASK USERID

Note:

FACILITY

Youcanfindthename ofthetask’sprincipalfacilitybycalling the getName()methodonthetask’sprincipalfacility,whichinturncanbe foundbycalling thegetPrincipalFacility()methodonthecurrent Taskobject.

FACILITYTYPE

YoucandeterminethetypeoffacilitybyusingtheJavainstanceof operatortochecktheclassofthereturnedobjectreference. No otherINQUIRETASKoptionsaresupported.

INQUIRE

TERMINAL

or

NETNAME

Thefollowingsupportisprovided forINQUIRETERMINALorNETNAME options:

Terminal.getUser(), getUserid() Terminal,

ConversationalPrincipalFacility

INQUIRE TERMINAL USERID

(39)

Note: Youcanalso findtheUSERIDvaluebycallingthegetUSERID()methodon thecurrentTaskobject,or ontheobjectrepresentingthetask’sprincipal facility

No otherINQUIRETERMINALorNETNAMEoptions aresupported.

File

services

CICSsupports thefollowing typesof files: v _Key_Sequenced_Data_Sets_(KSDS) v _Entry_Sequenced_Data_Sets_(ESDS) v _Relative_Record_Data_Sets_(RRDS)

KSDSandESDSfilescan havealternate(orsecondary) indexesthataretreatedby CICSasthoughtheywereseparate KSDSfilesintheirownright,which means they haveseparateFDentries.However, therearea fewdifferencesbetween KSDS,ESDS(primaryindex)andESDS(secondaryindex)accessing,whichmeans thatthey cannotalwaysusea commoninterface.CICSdoes notsupportaccessto anRRDSthroughasecondary index.Recordscanberead,updated,deletedand browsedinalltypesof file,withtheexceptionthatrecordscannotbedeletedfrom anESDSfile.

SeetheCICSApplicationProgrammingGuideformoreinformationabout datasets. Javacommandsthatreaddatasupportonly theequivalent oftheSEToptionon EXECCICScommands.Thedatareturnedisautomatically copiedfromCICS storageto aJavaobject.

TheJavainterfacesrelatingtoFileControl thereforeseparate intofivecategories:

File Thesuperclassfortheotherfileclasses;containsmethodscommon toall fileclasses.

KeyedFile

Containingtheinterfacescommon toa KSDSfileaccessed viatheprimary index,a KSDSfileaccessed viaasecondaryindexandanESDSfile accessed viaasecondaryindex.

KSDS ContainingtheinterfacespecifictoKSDSfiles.

ESDS ContainingtheinterfacespecifictoESDSfilesaccessedviaRelativeByte Address(RBA-itsprimaryindex).

RRDS ContainingtheinterfacespecifictoRRDS filesaccessed viaRelative Record Number(RRN-itsprimaryindex).

For eachfile, therearetwo objectsthatcanbeoperatedon;thefileobjectandthe file browseobject.Thefileobjectrepresentsthefileitselfandcanbeused with methods toperformthefollowingoperations:

v _DELETE v _READ v _REWRITE v _UNLOCK v _WRITE v _STARTBR

Afileobjectiscreatedbytheuserapplicationexplicitlyinstantiatingthedesiredfile class.Thefilebrowse objectrepresentsabrowse operationonafile(therecanbe

(40)

more thanoneactivebrowseagainstagivenfileat anytime,distinguished bya REQID).Methodscanbeinvokedagainsttheseobjectstoperformthefollowing operations:

v _ENDBR

v _READNEXT

v _READPREV

v _RESETBR

Afilebrowseobjectisnotinstantiatedexplicitlybytheuserapplication;itiscreated andreturnedto theuserclass bythemethods thatperformtheSTARTBR

operation.

Thefollowingtablesshowhow theJCICS classesandmethodsmapto theEXEC CICScommandsfor eachtype ofCICSfile(andindex).Inthesetables,theJCICS classesandmethods areshown intheformclass.method(),forexample

KeyedFile.read()refersto theread()methodintheKeyedFileclass. This tableshows theclassesandmethods forkeyedfiles:

KSDS primary or secondary index ESDS secondary index CICS File command

KeyedFile.read() KeyedFile.read() READ

KeyedFile.readForUpdate() KeyedFile.readForUpdate() READ UPDATE

KeyedFile.readGeneric() KeyedFile.readGeneric() READ GENERIC

KeyedFile.rewrite() KeyedFile.rewrite() REWRITE

KSDS.write() KSDS.write() WRITE

KSDS.delete() DELETE

KSDS.deleteGeneric() DELETE GENERIC

File.unlock() File.unlock() UNLOCK

KeyedFile.startBrowse() KeyedFile.startBrowse() START BROWSE

KeyedFile.startGenericBrowse() KeyedFile.startGenericBrowse() START BROWSE GENERIC

KeyedFileBrowse.next() KeyedFileBrowse.next() READNEXT

KeyedFileBrowse.previous() KeyedFileBrowse.previous() READPREV

KeyedFileBrowse.reset() KeyedFileBrowse.reset() RESET BROWSE

FileBrowse.end() FileBrowse.end() END BROWSE

This tableshows theclassesandmethods fornon-keyedfiles.ESDSandRRDS areaccessedbytheirprimaryindexes:

ESDS primary index RRDS primary index CICS File command

ESDS.read() RRDS.read() READ

ESDS.readForUpdate() RRDS.readForUpdate() READ UPDATE

ESDS.rewrite() RRDS.rewrite() REWRITE

ESDS.write() RRDS.write() WRITE

RRDS.delete() DELETE

File.unlock() File.unlock() UNLOCK

ESDS.startBrowse() RRDS.startBrowse() START BROWSE

(41)

ESDS primary index RRDS primary index CICS File command

ESDS_Browse.previous() RRDS_Browse.previous() READPREV

ESDS_Browse.reset() RRDS_Browse.reset() RESET BROWSE

FileBrowse.end() FileBrowse.end() END BROWSE

Datatobewrittento afilemustbeinaJavabytearray.

DataisreadfromafileintoaRecordHolderobject; thestorageisprovidedby CICSandwillbeautomatically releasedat theendof theprogram.

TheKEYLENGTHdoes notneedtobeexplicitlyspecifiedonanyfilemethod; the lengthused willbetheactuallengthof thekeypassed.Whena filebrowseobject iscreated,it containsthekeylengthof thekeyspecifiedonthestartBrowse

method,andthis lengthispassedto CICSonsubsequent browserequestsagainst thatobject.

It isnotnecessaryfor theusertoprovidea REQIDfor abrowseoperation;each browse objectwillcontain auniqueREQIDwhichisautomatically usedforall subsequent browserequestsagainst thatbrowseobject.

Program

services

JCICS supportfortheCICSprogramcontrolcommandsisdescribedbelow:

link() Program LINK

SetNextTransaction() setNextCOMMAREA()

TerminalPrincipalFacility RETURN

xctl() Program XCTL

Not supported SUSPEND

LINKandXCTL

You cantransfercontrolto anotherprogramthatisdefinedto CICSusingthe

link()andxctl()methods.Theseprogramscanbeinanylanguagesupported byCICS,exceptanotherJVMprogramasa CICStask canonlyhave oneJVM programinitsstack.

If youusethexctl()method,aTransferOfControlExceptionisthrownto the issuingprogram,evenif itcompletessuccessfully.

RETURN

Onlythepseudoconversationalaspectsof thiscommandaresupported.Itisnot necessary tomakeaCICScallsimplyto return;theapplicationcan just

terminate asnormal.Thepseudoconversationalfunctionsaresupportedby methods intheTerminalPrincipalFacilityclass;setNextTransaction()is equivalent tousingtheTRANSIDoptionofRETURN,and

setNextCOMMAREA()replacestheCOMMAREAoption.Thesemethodscan beinvokedatanytimeduringtherunningoftheprogram,andwilltake effect whentheprogramterminates.

Note: ThelengthoftheCOMMAREAprovidedisused astheLENGTHvaluefor CICS.Thisvaluemaynotexceed32500bytesif theCOMMAREAistobe passedbetweenanytwoCICSservers(foranycombinationof

product/version/release).