WebSphere Application Server Z/OS V8.5 Unit 6 - WOLA

2013 IBM CorporationIBM Advanced Technical SkillsWBSR85WebSphere Application Server z/OS V8.5Unit 6 - WOLA

This page intentionally left blank2IBM Americas Advanced Technical SkillsGaithersburg, MD 2012 IBM Corporation

Overview of WebSphere Optimized Local AdaptersWOLA is a means of communicating between WAS z/OS and external address spacesby transferring message blocks between virtual memory locations:ControlRegionWLMServantRegion(s)AppWOLA is this piece .CICS, IMSor Batch Prog Built on function WAS z/OS has had since thevery early daysAllows and coordinates this cross-memoryexchangeProvides the higher-level interface to thelower-level exchangeProvides the infrastructure code for use withCICS and IMSRegistration 3IBM Americas Advanced Technical SkillsGaithersburg, MD 2012 IBM Corporation

RegistrationAn important key concept is "registration" . the construction of the cross-memorylinkage into the WAS z/OS application server:ControlRegionServantRegion(s)WLMServes as the cross-memory"pipe" over which exchanges occurAppRegistration is really a set of control blocks that permits andcontrols the specific cross-memory exchangesCICS, IMSor BatchProgThe outside address space always registers into the WAS z/OSserver, never the other way aroundThe interaction between CR and SR is the same as for any form ofinputAny given WAS z/OS server may have multiple registrations into itRegistration is accomplished in several ways: A supplied CICS control transactionThe BBOA1REG APIOutbound vs. Inbound 4IBM Americas Advanced Technical SkillsGaithersburg, MD 2012 IBM Corporation

"Outbound" and "Inbound"WOLA is bi-directional. The key to "outbound" vs. "inbound" is thinking about whoinitiates the conversation . or, what program invokes the other program.OutboundWAS z/OS AppServerCICS, IMS or BatchProgAppJava program invokes "outbound"Uses supplied JCA resource adapterWOLA JCAResourceAdapterWOLASupportImplementation in external A/S dependson system - CICS, IMS or BatchInboundWAS z/OS AppServerCICS, IMS or BatchAppProgCOBOL, C/C , Assembler or PL/IUses WOLA APIsWOLASupportWOLAAPIsInvokes "inbound" to WAS EJBTo target EJB it looks like IIOPWOLA Information 5IBM Americas Advanced Technical SkillsGaithersburg, MD 2012 IBM Corporation

Source of Information on WOLAIn addition to the InfoCenter, which has many valuable reference articles, the WP101490Techdoc is ATS's central location for WOLA-related ter/wasinfo/v8r0/index.jspInfoCenter cdat f/WebIndex/WP101490TechDocsWP101490Quick Start GuideIntroduction to WOLAHistory of Updates to WOLANative API PrimerYouTube Video URL PDFWOLA is a functionally richfeature of WAS z/OSIn this Unit we'll cover theessential frameworkIn the hands-on lab you'll useWOLA with CICS and BatchOutbound to CICS 6IBM Americas Advanced Technical SkillsGaithersburg, MD 2012 IBM Corporation

Outbound to CICSUsing the Supplied CICS Link Server Task7IBM Americas Advanced Technical SkillsGaithersburg, MD 2012 IBM Corporation

The WOLA Infrastructure Components for CICSWAS z/OS supplies a few key components that install into a CICS region so it may useWOLA to communicate with WAS z/OS:BBOC3270CICS Region4Utility TranDirect Program Link (DPL)2Application ServerWAS z/OSControlRegionWOLA3BBO BBO#Link Server TaskInvocation TaskTRUETask Related User ExitTarget CICSProgram11. CICS Task Related User Exit (TRUE)This provides the essential low-level connectivity to WAS using the cross-memoryservices provided by WOLA.ServantRegion(s)2. BBO Link Server TaskApplication3. BBO# Invocation TaskServes as receiver of WOLA calls from WAS into the CICS regionPerforms the DPL to the named CICS program. Plays a role in security (more in a bit)4. BBOC Control TransactionA 3270 application useful for things such as starting the link server taskEnabling in CICS 8IBM Americas Advanced Technical SkillsGaithersburg, MD 2012 IBM Corporation

Enabling WOLA in CICS RegionThe following diagram summarizes the steps. The InfoCenter article has iles/default/bin/copyZOS.shcopyZOS.sh OLASAMPS 'USER1.WAS8.WOLA.SAMPLES'copyZOS.sh OLAMODS'USER1.WAS8.WOLA.LOADLIB'FB 80USER1.WAS8.WOLA.SAMPLESCSDUPDATUpdates the CICS CSD with the WOLA programs, transactions and screen mapsDFHPLTOLAdds program to PLT to initialize WOLA TRUE at CICS startupCICS start procedure//DFHRPL////InfoCenter9DD DSN &CICSDS.SDFHLOAD,DISP SHRDD DSN SYSS.CICS.LOADLIB,DISP SHR:DD DSN USER1.WAS8.WOLA.LOADLIBLIBRARYtdat enableconnectorcicsIBM Americas Advanced Technical SkillsGaithersburg, MDUSER1.WAS8.WOLA.LOADLIBEnable WOLA in WAS 2012 IBM Corporation

Enabling WOLA in WAS z/OSJust a few relatively easy steps to begin using WOLA from an application server:Two scope cell environment variablesWAS DAEMON ONLY enable adapter 1ola cicsuser identity propagate 1InfoCenterRARCFcdat olacustpropola.rarFound in the /installableApps directorySimple connection factory . no native librarypath, no custom properties to start withWill require a restart ofthe entire WAS cell topick up these changesThe installation of this RAR fileis like any JCA RAR fileWAS z/OS SAF ProfileCB.BIND.Z9*InfoCenter10 Grant CICS ID READ, or Make profile UACC READtdat enableconnectorIBM Americas Advanced Technical SkillsGaithersburg, MDStarting Link Server Task 2012 IBM Corporation

Starting the WOLA Link Server Task in CICSThis performs two roles -- it initates the registration into the WAS server, and it preparesthe Link Server to accept requests from the application in WAS:BBOC3270Utility TranOperationRegister NameCell SHORTNode SHORTServer SHORTBBOC START SRVR RGN CICSXREG DGN Z9CELL NDN Z9NODEA SVN Z9SR01SVC *Accept anyservice nameWAS ServerApplication4MNC 1MXC 10TXN NSEC NREU saction?PropagateSecurity?Reuse BBO#?CICS Region35TRUEBBO 1267CICSProgramBBO#8See notes for explanation of numbered blocksInfoCenter11rdat cicsJava application considerations IBM Americas Advanced Technical SkillsGaithersburg, MD 2012 IBM Corporation

Java Application ConsiderationsFor outbound use of WOLA to CICS using the Link Server Task the followingconsiderations come into play:ApplicationServlet or EJBola.rarCF JNDI eis/olaContext ctx new InitialContext();ConnectionFactory cf1 Impl csi new ConnectionSpecImpl();csi.setRegisterName ("CICSXREG");RegistrationCICSXREGTRUEBBO /BBO#Connection con cf.getConnection(csi);CICS ProgramInfoCenter123Interaction int con.createInteraction();InteractionSpecImpl isi new );MYPROG12int.execute(isi, data);4Either COMMAREA or CICS channeland container. If channel andcontainer, see InfoCenter rdat cicstdat connect2wasapp, tdat useoutboundconnectionIBM Americas Advanced Technical SkillsGaithersburg, MDRA failover 2012 IBM Corporation

Using Resource Failover with WOLA Outbound to CICSIn many ways this is just like what we saw with resource failover earlier. But there's afew important things to note about making this work properly:Connection Pool Custom PropertiesalternateResourceJNDIName eis/ola-altfailureThreshold n attemptsresourceAvailabilityTestRetryInterval n secsfailureNotificationActionCode 1, 2 or 3ApplicationServlet or gistrationCICSXREGCICSYREGSet the RegisterName as acustom property of the CF,not in the applicationprogram as we saw earlierFailover custom properties same as we saw for JDBCand JCA resource connectionsSame properties, settings and behaviorThe registration into the WAS server must existahead of timeCICSXCICSXCICSYCICSYRegistration is always performed from external space into WAS. For CICS andWOLA, start Link Server in each CICS region ahead of usageSet RegisterName custom property on each CF toname the registration to communicate overPermits different registration names to be used transparent to applicationRound-robin 13IBM Americas Advanced Technical SkillsGaithersburg, MD 2012 IBM Corporation

V8.0.0.1 and WOLA Round-RobinThe 8.0.0.1 fixpack brought new WOLA function, including ability to round-robinbetween multiple CICS regions registered into the server with the same name:Environment Variableola locate service search algorithm1The last external addressspace to register in gets work2Round-robin across likenamed registrationsWebSphere ApplicationServer z/OS V8.0.0.1ApplicationCommon Client InterfaceOLARARCICS RegionWOLA RegistrationName AAAWOLA RegistrationName AAATargetServiceCICS RegionTargetServiceFor calls outbound from WAS to external address spaceRegistration names must be identicalTargeted service must be present in address spacesparticipating in the work distribution14IBM Americas Advanced Technical SkillsGaithersburg, MDAny supported externaladdress space, not just CICSTX, Security summary 2012 IBM Corporation

Summary of Transaction and Security SupportThe following picture summarizes the support for TX and security:WAS z/OSCICSTransaction 2PCSecurity ID on WAS ion NoneSecurity No ID PropagationWOLAWOLAAPIsAPIsBypass LinkServer formaximumperformanceTransaction 2PCSecurity Region ID orApplication User IDWOLAWOLAAPIsAPIsInboundThe registration into WAS must have the appropriateTXN and SEC settings to support propagation of globaltransaction and propagation of security identityInbound? 15IBM Americas Advanced Technical SkillsGaithersburg, MD 2012 IBM Corporation

Inbound to WAS from CICS?It is possible to have a program in CICS invoke a Java service in WAS z/OS usingWOLA. It implies the use of the WOLA native APIs:CICS RegionOther CICSProgramsThe TRUE is still neededAlways needed in CICS because it provides the fundamental WOLA functionLink Server Task not usedLink Server task is for outbound WAS-to-CICS, not inbound to WASRegistration into WAS server must be presentCICSProgramWOLAAPIsTRUEAccomplish with BBOC REGISTER or BBOA1REG native APICICS program must use WOLA APIsNote the concept of a "bridge" program that shields other CICS programs fromhaving to understand the APIs. We'll explore those APIs nextThe ola.rar adapter not usedThat's for outbound calls . general WOLA support used for inbound callsRegistrationTarget must be stateless EJBAnd it must implement using the supplied WOLA class filesApplicationStateless EJBWAS ServerThis is just like what an external batchprogram would use. We'll exploreinbound from batch next . keep in mindsame lessons apply to inbound from CICSBatch 16IBM Americas Advanced Technical SkillsGaithersburg, MD 2012 IBM Corporation

Inbound from BatchUsing the native APIs of WOLA17IBM Americas Advanced Technical SkillsGaithersburg, MD 2012 IBM Corporation

Essentials of Batch Program Use of WOLARelatively simple setup, but there is a bit more exposure to the programming interfacesof WOLA:Eclipse Toolingi.e. IBM Rational Application DeveloperJob Control Language (JCL)2ola apis.jarSTEPLIB DD DSN hlq.OLAMODSINPUTDD DSN hlq.datasetOUTPUT DD DSN hlq.dataset./util/zos/OLASamples/libBatch Program1WAS EJBCOBOL, C/C ,High Level Assembler, PL/IBBOA1REGBBOA1INVHome InterfaceBBOA1URGRemote Interface4WOLA APIs within batchprogram structure3WOLA Native ModulescopyZOS.sh, specify OLAMODSInfoCenter18cdat olaapis, tdat useola in step2IBM Americas Advanced Technical SkillsGaithersburg, MDApplicationStateless EJBexecute()input: byte arrayoutput: byte array5OtherApplicationsThis WOLA-aware EJB becomesa "bridge" to other EJBs unawarethat WOLA is in the pictureAPI InfoCenter 2012 IBM Corporation

The WOLA Native APIs InfoCenter ArticleAn incredibly useful InfoCenter article that details all 13 of the native APIs, includingparameters and return code / reason code descriptions13 APIs plus an internallink to JCA adapter APIsParameter map (with full descriptions following)Return Code / Reason Code descriptions for each APIAPIs that start with BBO*are 31-bit callable; BBG*are 64-bit callableA wonderful reference article, but it doesn'thighlight how easy using the APIs can be .InfoCenter19cdat olaapisSimplest use IBM Americas Advanced Technical SkillsGaithersburg, MD 2012 IBM Corporation