Session 1172 WebSphere z/OS Optimized Local Adapters (WOLA)
Transcript of Session 1172 WebSphere z/OS Optimized Local Adapters (WOLA)
© 2010 IBM Corporation
Session 1172
WebSphere z/OS
Optimized Local
Adapters (WOLA)
SHARE Spring 2010
Seattle, WA
March 14 – 18
(Or “OLA” … same thing)
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
2
Other WebSphere Application Server Sessions
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
3
Four Big Questions
We aim to address four big questions in this presentation:
• WOLA -- What is it?We explain the basic structure of the new function
• Why Should I Care?We explain the functional and performance benefits of the new function
• How Do I Enable It?We explain what’s involved with enabling WAS and external address spaces to
use the new function
• How Do I Use It?We explain the how the new function is used and what’s involved.
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
4
Overview“What is it?”
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
5
Starting Point -- Reusing WAS EJB Assets
More and more people are seeking to use WAS z/OS EJB assets from outside
the WAS environment:
Local Comm …
WebSphere z/OS
EJB Assets
Batch
ProgramsCICS
As time goes by, more and
more business value is
represented by EJB assets
Hence desire to leverage
Most solutions are designed to go outbound from WAS, not inbound
There are other solutions to come inbound to WAS, but none have the ability
to reach throughput rates seen with WOLA
WOLA was born to provide highly scalable transactional inbound solution
But developers did not stop with inbound … they made it bi-directional to complete the picture
Before we get to what WOLA is … let’s see what it’s based on
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
6
Let’s Set the Stage -- WAS z/OS “Local Comm”
“Local Comm” is a cross-memory communication structure used within WAS
when servers want to talk to others in the same cell on the same LPAR:
What is WOLA? …
WAS uses this for internal communications … IIOP between servlet and
EJB in different servers* for example. No TCP, no SSL … very efficient.
CR SR
DMGRDaemon
Shared
Space
CR SR
AppServer
CR SR
AppServer
Cross memory
“Local Comm”
LPAR
CR SR
AppServer
CR SR
AppServer
Daemon
CR
Shared Space
Data
Buffers
Data
BuffersServer
Storage
Server
Storage
Data
Buffers
Above the bar
owned by Daemon
We’ll use this rough
schematic to illustrate this
Not actually in
the Daemon
address space
… but it’s owned
by the Daemon
so we represent
it like this
* Servlet to EJB inside the same server is done entirely locally. No communications at all, not even Local Comm.
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
7
So … What Is WOLA?
WOLA is a new cross-memory communication structure for WAS V7. It’s an
extension of a WAS “Local Comm” used inside of WAS:
High Level Picture …
This extension is implemented with a new set of modules that provide an API for
external address to access servers using this Daemon shared space mechanism
CR SR
AppServer
CR SR
DMGRDaemon
Shared
Space
WOLACICSAssembler/Cobol/PLI/C or C++
z/OS BatchAssembler/Cobol/PLI/C or C++
UNIX Systems ServicesAssembler/Cobol/PLI/C or C++
Airline Control SystemAssembler/Cobol/PLI/C or C++
WOLA
WOLA
WOLA
LPAR
This is bi-directional
Cross memory
“Local Comm”
CR SR
AppServer
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
8
Very High Level Picture of WOLA
This is just a schematic, but it helps position some key concepts:
Simple example scenario …
Local CommExternal Address SpaceAssembler/Cobol/PLI/C or C++
WebSphere z/OS Cell on an LPAR
External address spaces use the
supplied WOLA modules to
register to the Daemon and
access Local Comm
A supplied JCA adapter provides the Java outbound
interface to completes the connection
For inbound communications, EJB does not require
WOLA JCA
STEPLIB DD DSN=hlq.WOLA.LOADLIB
Essentially this is a set of APIs that externalizes the Local Comm function
that is already in use within a WebSphere cell on an LPAR
Shared Space
Daemon
AppServer
EJBsJCA
External
WOLA
APIs
The Daemon owns the shared above-the-
bar storage where WOLA registrations live
and that data buffers flow through
The Daemon owns the System LX which
anchors the non-space-switching PC
routines used to access WOLA services Again … not actually in the Daemon address
space … but it’s owned by the Daemon so we
represent it like this to emphasize the key role
the Daemon plays in this.
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
9
A Simple Use-Case Scenario
Here’s a picture … just to help us get our minds around this thing:
Five perspectives …
1. Flat record file serves as
input to batch program
2. WAS 7.0.0.4 WOLA
modules STEPLIBed to
from batch JCL
3. Batch program uses
WOLA APIs to access WAS
and invoke EJB
4. EJB initiates transaction
and updates CICS, IMS
with two-phase commit
using standard WAS data
connector archictures
Daemon
Shared
Space
CR SR
AppServerCICS
IMS
RRS
Flat record file
Batch Program
LPAR
Cell
14
WOLA
Modules
2
3
This illustrates a relatively simple -- but likely common -- usage: batch file
using an existing transactional EJB to update data.
Local Comm
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
10
WOLA Interface -- Perspective from Five Angles
This conceptual picture offers insight into the interface requirements:
Reducing impact …
Enterprise
Java Bean(Or Servlet)
Enterprise
Java Bean
WOLA Execute()
ExecuteHome()
WOLA
JCA Adapter
WOLA
CICS
Program
CICS
Program
WOLA BBO$/BBO#
WOLA
Modules/APIs
Batch
ProgramWOLA
Modules/APIs
WebSphere Environment
CICS EnvironmentBatch Environment
EJBs that initiate a call to WOLA do
so through a supplied JCA adapter.
Several WOLA-specific methods
used to invoke services over WOLA
EJBs that will be the target of inbound calls
need to implement the WOLA-supplied
Execute() and ExecuteHome() classes.
Calls into CICS come across WOLA-supplied
BBO$/BBO# task and transaction. Target CICS
program unchanged if able to be invoked over
COMMAREA or Channel/Container
A CICS program
that wishes to
initiate an outbound
connection must
write to the WOLA
APIs
A Batch program that wishes to
initiate an outbound connection
must write to the WOLA APIs
WAS z/OS 7.0.0.4 supplies the WOLA artifacts. We’ll see how to enable the environment later.
You make modules/classes available: STEPLIB, DFHRPL, ola.rar and ola_apis.jarBatch CICS WAS Development Tool
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
11
Reducing Coding Impact to Environment
It’s possible to architect WOLA to be a “service” to EJBs and CICS programs
so the amount of “WOLA-specific” programming is reduced:
WOLA Execute()
ExecuteHome()
WOLA
JCA Adapter
WOLA Aware
CICS Program
WOLA BBO$/BBO#
Enterprise
Java Beans
Servlets
Enterprise
Java Beans
CICS
Programs
CICS
Programs
WOLA Aware
EJB
Daemon
Shared
Space
CO
MM
AR
EA
Ch
an
nels
/Co
nta
iners
WebSphere Environment
CICS Environment
1
2
3
4
1. WOLA Service EJB written to use WOLA JCA interface
2. WAS CICS flows invoke WOLA BBO$/BBO# task and transaction and then invoke named CICS program
3. CICS WAS flows require custom code in CICS written to the WOLA APIs to initiate the call. Other CICS
programs can EXEC the WOLA Service Program
4. WOLA Service EJB written to implement WOLA Execute() and ExecuteHome() methods
Not “transparent,” but effort reduced. Benefits gained.
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
12
Performance“Why should I care?”
The performance charts contained here are based on a specific IBM measured test.
Performance is based on a number of factors and your results may vary. The results
shown here do not suggest a guarantee of performance, implied or expressed.
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
13
To Start Things Off
It’s important we cover two important concepts about performance numbers
Relative comparisons …
1. “Relative” comparisons
2. “Normalized” findings
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
14
“Relative” Benchmark Study Comparisons
Used when the focus is not on the raw values, but on how one thing
compares to another. For example, consider these two hypothetical findings:
“Normalizing” data …
100
A
200
B
300
A
600
B
“T
hro
ug
hp
ut”
Large Message Small Message
The absolute numbers
are quite different
But relatively they’re
saying the same thing:
B is twice A.
Using relative comparisons is helpful when
the objective is to compare things without
so much focus on details like machine
models, resources, etc.
2X
2X
Hypothetical … just
to make a point
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
15
“Normalized” Benchmark Study Findings
Normalizing is the process of taking multiple sets of relative findings and
making them easier to compare to one another:
123
367
199
430
219
135.3
440.4
258.7
602
328.5
0
100
200
300
400
500
600
700
1 2 3 4 5
Look at this picture. What
conclusion can you draw from it?
Nothing immediately jumps out.
1 1 1 1 1
1.11.2
1.31.4
1.5
0.5
0.6
0.7
0.8
0.9
1
1.1
1.2
1.3
1.4
1.5
1.6
1.7
1.8
1.9
2
1 2 3 4 5
Make the blue values “1”
and adjust the green
values proportionally
A meaningful trend emerges
The data has been
“normalized” with the blue
values serving as the baseline
Normalizing data is useful to further clarify important relationships
without getting too distracted by details
Hypothetical … just
to make a point
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
16
A Comparison of CICS Invoking WAS Web Services
A recent benchmark compared the case of web services into WAS against
invoking the EJB using WOLA:
CICS
Transaction
Server
Program
WebSphere
Application
Server
EJB
LPAR
SOAP/HTTP
SOAP/HTTP
Some notes:
• We are not suggesting WOLA can or should replace web services in all cases.
But in some cases it might well make sense
• In this test CICS and WAS on same LPAR, so TCP is optimized between the two
• The test was a relatively simple echo application
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
17
Relative Throughput for 100 Byte Message
The following chart serves as our starting point … a comparison of relative
throughput based on a 100 byte message exchange:
What about larger messages? …
Small Messages(100 bytes)
Relative ThroughputBased on the specific CPU and
memory of this benchmark system
Web ServicesNormalized so it
represents the
baseline “100”
WOLARelative throughput …
relative to the
normalized web
services baseline
Given the machine resources used for the test …
WOLA saw 6X throughput
Why? No network, no XML
creation, no XML parsing, etc.
Performance measurements are dependent on many factors.
Results vary. No guarantee of performance is implied by this chart
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
18
Larger Messages
We see WOLA outperforming web services across a range of message sizes:
EXCI …
Small Messages
(100 bytes)
Medium Messages
(4K bytes)
Big Messages
(32K bytes)
WOLARelative throughput … relative to the
normalized web services baseline
Web ServicesNormalized so it
represents the
baseline “100”
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
19
WAS CICS Transaction Gateway - Local EXCI
CTG EXCI is itself a cross-memory technology … yet we still see a delta in
favor of OLA. Not as much as with web services, but it’s still there:
IPIC …
Again … relative throughput, normalizedIn this case, CTG EXCI is the constant reference; OLA is adjusted proportionally
100 bytes 4K bytes 32K bytes
CTG EXCINormalized so it
represents the
baseline “100”
WOLARelative throughput …
relative to the
normalized CTG EXCI
baseline
We see WOLA improving its advantage as the message size gets bigger and
reaches the limit of EXCI, with is 32KWe have some careful positioning information coming!
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
20
WAS CICS Using IPIC of CICS TS3.2
IPIC supports channels and containers and allows us to get back the 32K limit
of EXCI. How does WOLA compare to that?
Positioning …
IPICNormalized so it
represents the
baseline “100”
WOLARelative throughput …
relative to the
normalized IPIC
baseline
Relative throughput, normalizedCTG IPIC is the constant reference; OLA is adjusted proportionally
100 bytes 4K bytes 32K bytes 128K bytes
EXCI 32K
Boundary
WOLA is a very good large message local transfer mechanismWe have some careful positioning information coming!
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
21
Let’s Be Very, Very Careful
Before we go any further it’s essential we make sure the proper conclusion
are drawn from those charts:
Relative advantages …
WOLA is magic and fits every conceivable requirement?
WOLA replaces CICS Transaction Gateway?
WOLA is like other technology solutions … it has its
place but it is not a universal one-size-fits-all?
Yes! No!
We’re going to look at a functional comparison of WOLA and CTG next …
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
22
Relative Advantages
Of WOLA and CICS Transaction Gateway
WOLA is a complementary technology with CTG. Both will have their place within an enterprise architecture.
Relative Advantage Favors …
WOLA CTG
Bi-directional … WASCICS and CICSWASWOLA is bi-directional, CTG is only WASCICS
Part of the WebSphere Application Server z/OS ProductWOLA shipped with 7.0.0.4, CTG is a separate FMID
Able to be used for local or remote access to CICSWOLA is a local technology only, CTG supports both local EXCI as well as TCP-based remote access
Two-Phase Commit WASCICSWOLA is limited at present ot synconreturn only. In future WOLA maintenance that support will be
upgraded to 1-phase. 2-phase limited by design of CICS TRUE, which is what WOLA’s support in CICS uses
Two-Phase Commit CICSWASCTG can not be used for CICSWAS. WOLA able to propagate TX CICSWAS with full 2-phase commit
support using RRS for syncpoint coordination.
Flexible use of CICS channels and containersWOLA restricts container usage to one named channel only: IBM-WAS-ADAPTER. CTG supports multiple
channels. WOLA uses indexedrecord while CTG uses mappedrecords. That means CTG supports the
passing of multiple named containers on a channel while WOLA can not.
Positioning framework …
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
23
Discussion Starter -- Positioning Chart
Here’s a suggested framework -- not formula -- for positioning …
Strong
Less Strong
Review
Architectural
Criteria
Outbound from WAS z/OS where …
• Target is on another LPAR or off platform
• Existing solutions are seen as working well
WAS z/OS Inbound or outbound where …
• Existing solutions seen as limiting
• Subset of overall archicture has specific throughput needs
Inbound to WAS z/OS from local source with …
• High throughput requirements
• Large message size requirements
WOLA may be
very good fit
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
24
Installing and Enabling“How do I enable it?”
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
25
Comes with 7.0.0.4 Maintenance
WOLA is a function introduced with 7.0.0.4. Applying that maintenance provides
the function to the SMP/E product file system …
File system …
CR SR
AppServer
CR
Node Agent
CR SR
AppServerNode
CR SR
DMGR
CR
Daemon
SMP/E Product
File System
7.0.0.4
1
2
4
???
3
Several questions …
1. What does WOLA look like in the product file system?Knowing this is helpful because some instructions drive you into the
product file system to retrieve files
2. What’s needed to enable a node to use WOLA?Hint: it’s not automatic. You need to intentionally enable nodes.
3. What about “intermediate symlinks?”Hint: this is automatic … it piggybacks on a node’s intermediate symlinks
4. Does the DMGR node need to be enabled?Answer: only if you intend to invoke the “deploy” (build) option during
installation of a WOLA-using application
Standard SMP/E work
here … nothing special
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
26
WOLA in the SMP/E File System
Busy chart … but a few key points that need to be made:
Essentials …
• Everything is under /mso/OLA
• The modules are found here
• The JCA resource adapter is
found here
• The samples are found here
• Using WOLA involves
pointing to or extracting files
from this location
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
27
The Essentials of Enabling WOLA for Use
Four things:
olaInstall.sh …
CR SR
AppServer
CR
Node Agent
CR SR
AppServer
Node
CR SR
DMGR
CR
Daemon
JCA
CF
WAS_DAEMON_ONLY_enable_adapter = 1
1
_________ BBOACALL
_________ BBOACHAB
_________ BBOACLNK
_________ BBOACNTL
_________ BBOACPLT
_________ BBOA1URG
PDS
2
3
4
olaInstall.sh
1. Symlinks to SMP/EThis is what makes the WOLA modules available to the
node.
2. Modules copied out to PDSSo external address spaces (batch, CICS) can access
modules and APIs
olaRar.py or do manually
3. JCA adapter installed with CFThis is what makes the WOLA modules available to the
node.
4. WAS environment variableSimple switch to enable function in Daemon
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
28
“Enabling” a Node -- olaInstall.sh Shell Script
Located in the node’s /bin directory*, this shell script has a few different
functions, depending on the parameters you pass it:
olaRar.jy …
olaInstall.sh function target_olaload_dataset_name
INIT Initializes the HFS and copies OLA modules to target data set
(Initialize = creates symblinks and copies some files)
UNINIT Uninitializes the HFS
(Uninitialize = removes symblinks and copies of files)
OLAMODS Copies OLA modules to target data set only
(From the SMP/E product HFS out to your pre-allocated load module PDS)
Pre-allocated load module PDS-E
Notes:
• Located in the node’s /bin directory
• Make sure the ID under which you run this has write access to node’s configurationWebSphere Admin ID is a safe bet to work
• Run this from every node in which you wish to use the OLA functionalityDMGR enablement only if you intend to use “Deploy EJB” option during application installation
• Don’t need to worry about “intermediate symlinks” … it’ll programmatically determine if
they’re in use and simply piggyback on the node’s intermediate symlinks if present
* applyPTF.sh will put that file in the /bin directory of each node after 7.0.0.4 is applied
Approximately
40 tracks
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
29
The olaRar.py WSADMIN Jython Script
This WSADMIN script does a few simple things in an automated way:
• Creates variable WAS_DAEMON_ONLY_enable_adapter = true at the cell scope
• Installs the ola.rar J2C resource adapter archive into the specified nodeThat RAR file is located in the SMP/E install root for WAS … /mso/OLA/installableApps/
• Creates a J2C connection factory under adapter with JNDI of esi/ola
Notes:
• Invoke WSADMIN client from the /bin directory of your node configuration file systemSo the shell script can operate against that node’s file system easily. “su” to ID that has write permission in the file system.
• The WSADMIN script itself is located in the SMP/E install root, under /mso/OLA/binIt is not copied into the configuration root by olaInstall.sh. You can copy it there manually if you’d like.
• Takes two parameters: Cell long name and node long name
• Standard WSADMIN process … if you’re familiar with that, then this should be quite easy
But if you’re not familiar with WSADMIN, or you’d like to experience by hand
what the script does automatically, then simply do those things manually
through the Admin Console … very easy
Restart servers in the node after completion
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
30
Function Usage“How do I use it?”
Batch and CICS
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
31
Using WOLA With External Batch Programs
In one sense this is the easiest. In another sense it’s a bit more involved
because it implies writing to the WOLA APIs:
Registration …
1. WOLA modules copied out of the WAS SMP/E file systemVery simple process .. we’ll see this in the last unit of this presentation
2. Batch JCL STEPLIBs to WOLA module librarySo access to WOLA modules can be loaded
3. Program uses WOLA APIsA handful of APIs is what provides the interaction function
4. External batch “registers” into DaemonRegistration into the Daemon is a key element of this that we’ll explore more
5. Program invokes EJBThe BBOA1INV API takes as a parameter the JNDI name for the home interface
of the target EJB.
CR
Node Agent
CR SR
AppServerNode
CR SR
DMGR BBOA1REG
:
BBOA1INV
:
BBOA1URG
WOLA
Modules
STEPLIB DDJCL Batch Program Loadlib
1
3
2
CR SR
AppServer
5
CR
Daemon 4
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
32
Two Key Concepts -- Registration and RegisterName
Registration provides the access to Local Comm; RegisterName provides a
named pool of connections for each registered external address space
Key Points:
• Registration is specific to a server in the cell on that LPAR
• As picture shows, multiple registrations into a Daemon are possible -- to the same server or to different servers
• Once registration is done, then communications conducted across the pool of connections associated with the RegisterName
Before a program can use WOLA, it must register into Daemon
CR SR
MYSR01A
Daemon
BATCHREG001
BATCHREG999
Cell: MYCELL
Node: MYNODEA
Server: MYSR01A
BBOA1REG(MYCELL,MYNODEA,MYSR01A,BATCHREG001)Batch 001
Batch 999 BBOA1REG(MYCELL,MYNODEA,MYSR01A,BATCHREG999)
WOLA
WOLA
Both batch programs are seeking to use EJBs in the same
server -- server MYSR01A
Both register with Daemon and name server MYSR01A
But they use different RegisterName values to keep their
pool of Local Comm connections separate
Multiple servers …
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
33
Reinforce Point on Previous Chart
Imagine the two batch programs were to use different servers. What then?
Registration API …
Both register with the same Daemon
They specify different servers
They provide different RegisterNamesCR SR
MYSR01A
Daemon
BATCHREG001
Cell: MYCELL
Node: MYNODEA
Server: MYSR01A
BBOA1REG(MYCELL,MYNODEA,MYSR01A,BATCHREG001)Batch 001
Batch 999 BBOA1REG(MYCELL,MYNODEA,MYSR02A,BATCHREG999)
WOLA
WOLA
BATCHREG999
Cell: MYCELL
Node: MYNODEA
Server: MYSR02A
CR SR
MYSR02A
Registration is a key first step in the usage of WOLA
How exactly does a program register? With the BBOA1REG API …
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
34
Example of API -- BBOA1REG (from OLACC01 Batch Sample)
BBOA1REG is one of thirteen APIs that come with WOLA. It’s used by external
address spaces to register into the WAS Daemon:
OLACC01 Sample …
Like any new API it takes a bit of time to learn the operations and syntax. But
it’s relatively easy, and the samples provide some nice examples
BBOA1REG ( &daemonGroupName
, &nodeName
, &serverName
, ®isterName
, &minConn
, &maxConn
, ®Flags
, &rc
, &rsn
);
if (rc != 0)
{
printf("Register error! rc: %d rsn: %d\n",rc,rsn);
return(-1);
}
&variables set higher in the OLACC01 sample program
InfoCenter search on: cdat_olaapis.html
InfoCenter has very nice writeups of the
APIs and the parameters
Some error? Returns beautiful return and reason
codes. Same InfoCenter page spells it all out.
Wonderful granularity of error reporting.
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
35
The OLACC01 Sample
The recommended first sample to use … it’s a very simple single invocation
model batch program
What does BBOA1INV look like? …
BBOA1REG
BBOA1INV
BBOA1URG
Establishes
connection to
the server
Invokes the
EJB in the
server
Tears down the
connection …
unregisters
//OLACC01 JOB (),'ME',REGION=0M,
// MSGCLASS=H,NOTIFY=&SYSUID
:
//COMPILE.SYSIN DD DATA,DLM=@@
char registerName[12] = "OLACC01 ";
:
GETARG(daemonGroupName, 1, 8, 0x00, "SY1");
GETARG(nodeName, 2, 8, ' ', "SY1");
GETARG(serverName, 3, 8, ' ', "BBOS001");
:
• Deploy OLASample01.ear into WAS server and start
• Modify the source code -- supply cell, node and server short
• Compile source code
• Modify sample JCL and submit
• You’ll see:
Invoking service "ejb/com/ibm/ola/olasample1_echoHome"
Invoke response length matches expected: 61
Invoke response data matches expected
CR SR
MYSR01A
Daemon
OLACC01
Cell: MYCELL
Node: MYNODEA
Server: MYSR01A
OLACC01
WOLA
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
36
Example of API -- BBOA1INV (from OLACC01 Batch Sample)
Once registered to Daemon, how does batch invoke EJB? With the BBOA1INV API
and naming the EJB’s home interface JNDI:
Looping …
BBOA1INV ( ®isterName
, &requestType
, &requestServiceName
, &requestServiceNameLen
, &requestDataPtr
, &requestDataLen
, &responseDataPtr
, &responseLen
, &waittime
, &rc
, &rsn
, &rv
);
The name of the registration connection
to use to access the EJB. This is the pool
of connections over to the WAS server
address space
The JNDI name of the home interface for the
target EJB in WAS
Earlier in OLACC01 sample this was set to:
ejb/com/ibm/ola/olasample1_echoHome
Which is the default JNDI name on the OLASample01.ear file
Point here is not to drill deep into programming specifics
Point is to illustrate key concept -- register into Daemon and make connection to target WAS appserver,
then invoke the target EJB using the registration pool and the EJB’s JNDI home interface name
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
37
Have Some Fun … Modify the OLACC01 Sample
It’s very easy to change the OLACC01 sample to make it loop through multiple
iterations:
InfoCenter …
int x;
for (x = 1; x <= 10; x++)
{
}
BBOA1REG
BBOA1INV
BBOA1URG
Establish
connection to
the server
Invokes the EJB in
the server … each
time through loop
Unregister
Useful because it illustrates how
a registration may be re-used
many times before unregistration
Useful because it will let you see
just how fast this connection is.
Set the iteration to some high
number and time the execution.Well … be a little careful with that number! J
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
38
Reminder: InfoCenter Has Very Good Doc on APIs
Search on key phrase cdat_olaapis.html
Each section has a very detailed
parameter description and return
code and reason code details
InfoCenter documentation on WOLA is very good … please rely on it
Installing into CICS …
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
39
Installing WOLA into CICS is Straightforward
WOLA is supplied as a set of programs and transactions that install into CICS.
From a CICS perspective it’s business as usual stuff.
TRUE …
WOLA ModulesWhich includes several WOLA-related
CICS programs and transactions
CICS Transaction Server
//DFHRPL DD
CICS region start JCL
CICS
CSDBBOACSD groupCSDUPDAT sample JCL
DISPLAY GROUP(BBOACSD)
ENTER COMMANDS
NAME TYPE GROUP
OLAMAP MAPSET BBOACSD
BBOACALL PROGRAM BBOACSD
BBOACHAB PROGRAM BBOACSD
BBOACICS PROGRAM BBOACSD
BBOACLNK PROGRAM BBOACSD
:
BBOACSRV PROGRAM BBOACSD
BBOATRUE PROGRAM BBOACSD
BBO$ TRANSACTION BBOACSD
BBO# TRANSACTION BBOACSD
BBOC TRANSACTION BBOACSD
BBOQ TDQUEUE BBOACSD
The CICS system programmer aspect of this is quite straight-forward
Then install the BBOACSD group:
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
40
WOLA is Implemented as a TRUE
Task Related User Exit, along with some supplied transactions and link server
tasks:
OLAUTIL …
CR
Daemon
BBOCTerminal-based transaction
(Control and operations transaction for
WOLA in CICS)
Existing CICS
Program
COMMAREA
or
Container
BBO$LINK server task
CICS Transaction Server
BBOATRUETask Related User Exit
BBO#Invocation Task
WOLACR SR
AppServer
Reg
Name of this can
be passed in as a
parameter.
Defaults to BBO# if
not specified
1
2
3
1. BBOC is a 3270 terminal application that you can use to start the TRUE and SRVRTo start the TRUE (#2): BBOC START_TRUE … can be started automatically at CICS region start with PLT module
To start the link server task (#3): BBOC START_SRVR parm parm
2. The TRUE is what provides the user exit into and out of the CICS regionThis must be started for any of this to work. BBOC START_TRUE will start it, or PLT module.
3. The link server task is what registers into the Daemon and establishes the connectionStarted with the BBOC START_SRVR parm parm command
4. Instance of BBO# invocation task started by the link server task for work WASCICSName of transaction can be passed in as a parameter; or allow it to default to BBO#
4
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
41
Invoking CICS Program WASCICS
Earlier we had pointed out that an EJB in WAS wishing to invoke a CICS
program has to use the WOLA JCA adapter. The CICS program named there:
OLAUTIL sample …
WOLA Aware
EJBDevelopment Tool
(Rational or equivalent)
ola_apis.jar
JCA Adapter: ola.rar
CR SR
AppServer
connectionSpecImpl.setLinkTaskTranID(‘ABCD');
interactionSpecImpl.setServiceName("PROGRAM1");
Class Method
PROGRAM1COMMAREA
or
Container
BBO$LINK server task
CICS Transaction Server
BBOATRUETask Related User Exit
ABCDInvocation Task
WOLA
Transaction Name
set with setLinkTaskID()
Program named with setServiceName()
WOLA
This illustrates use of WOLA-supplied BBO$ and BBO# to invoke
CICS program without any modification to the CICS program code.
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
42
The OLAUTIL Sample
A useful sample that illustrates the use of the CICS program using WOLA APIs
directly to receive from WAS or send to WAS:
The CICS 3270 screen …
CICS
Transaction
Server
ProgramBBOA1INV(EJB JNDI)
WebSphere
Application
Server
EJB JNDI
BBOA1SRV and BBOA1INV below
the JCA layer. EJB unaware.
BBOA1SRV(Service Name)
1
2
PF05
PF04
1. WASCICS: On the CICS side the PF05 function is used to “host a service”OLAUTIL program uses BBOA1SRV API to ready itself to receive from the WAS side. The API has a parameter for “service name” which
the WAS side uses to specify the service to invoke over the registration connection. On the WAS side clicking the button results in
BBOA1INV being used below the JCA layer. The EJB doesn’t know anything about WOLA APIs, but JCA adapter does.
2. CICSWAS: PF04 function to “invoke a service” From the CICS side you can invoke an EJB with the BBOA1INV API. The “service name” is the JNDI home interface name. WAS
manages the WOLA BBOA1SRV below the JCA layer.
OLAU
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
43
The OLAUTIL CICS Sample and CICS
This sample is provided as a supplied program, transaction and 3270 mapset:
WAS webpage sample …
OLAMAP BMS
3270 Map
OLAUTIL Sample
Application
Green
Screen
OLAU
------------------------------------------------------------------------------
* Optimized Local Adapters WAS z/OS Testing *
---------------------------------------------
Provide Run Parms Below:
Send message data :
==> : Hello from CICS
Received message data :
==> :
Register first? (Y/N) : Y
Register name : CICSTEST
Service name : ejb/com/ibm/ola/olasample1_echoHome
WAS server short name : MYSR01A
WAS node short name : MYNODEA
WAS cell short name (DG name) : MYCELL
Number of Tests to run : 00001
Number of Tests Completed :
------------------------------------------------------------------------------
-- PF03=Exit -- PF04=Invoke Srv -- PF05=Host Srv -- PF06=Send Reply --
CR SR
MYSR01A
WOLA
WOLA
1
2
3
4
5
1. This is the message you’ll send to WAS, and the message OLASample01.ear echoes back
2. On first try you register; once registered you can send message after message
3. The JNDI name of the deployed OLASample01.ear EJB (or service name of CICS if “Host a Service”)
4. The short names used to register to the Daemon and server
5. PF04 tells the program to use the BBOA1INV API and drive the EJB over in WAS. The program then
waits for the echo response from WAS and displays it on the screen (block #1)
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
44
Sample WAS EJB has Web Interface to Go Other Direction
You can tell OLAUTIL to “Host a Service” (PF05) and it’ll wait for something to
come to it. This web page provides the WAS-side interface to send message.
DISPLAY …
Message to send to the CICS application
Register Name(Must match what CICS program used)
Service NameNamed on the CICS program’s use of BBOA1SRV API
(host a service) This is what’s invoked when F5 is
pressed.
Button sends message to CICS over OLA
http://<host>:<port>/OLA_Sample1_Web/
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
45
The DISPLAY,ADAPTER Command Updates for WOLA
To help you see what’s going on within your environment, an addition to the DISPLAY command has been made:
Wrap up …InfoCenter search: tdat_mvsmodifyola.html
BBOA0007I: SHOWING REGISTRATIONS FOR DAEMON GROUP:
BBOA0003I: Name Jobname SWT TL Min Max Act State
BBOA0004I: CTSRGN01 CICS1 101 00 0001 0010 0002 00
BBOA0004I: $WASDEFAULT$ CICS1 000 00 0000 0001 0000 00
BBOO0188I END OF OUTPUT FOR COMMAND DISPLAY,ADAPTER,DAEMONRGES
/F <server>,DISPLAY,ADAPTER,parms
STATUS
Displays the status of the optimized local adapters component.
REGISTRATIONS
Displays a list of optimized local adapters clients connected to this server.
DAEMONRGES
Displays a list of optimized local adapters clients connected to any server in this daemon group.
SEARCHRGES
Displays a list of optimized local adapters clients connected to any server in this daemon group, matching search criteria.
Example shows CICS region registered in with name CTSRGN01. Security propagation
turned on, TX propagation turned on. Min connections 1, Max 10, two are in active.
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
46
Section Conclusion
Building knowledge of WOLA and how to use it is like anything else:
Start developing your
own solutionsYou’re on your way
Explore the sample and
see how they work and
what they’re doingGood introduction to APIs
Get OLAUTIL working
in a test CICS regionSimple steps for anyone
familiar with CICS
Get the OLACC01 batch
program workingEasiest validation there is
Enable the function in
your test WAS cell(Next section)
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
47
Conclusion
© 2010 IBM CorporationIBM Americas Advanced Technical Skills
Gaithersburg, MD
SHARE Sprint 2010, Seattle, March 14 - 18 Session 1172
48
• High speed, bi-directional local connection mechanism
• Extension of existing Local Comm architecture inside of WAS
• External Address Spaces: CICS, Batch, USS and Airline Control
• Languages: Assembler, Cobol, PLI , C or C++
• Positioning:
Not magic … use where it makes sense and provides good business value
Not a replacement for other technologies … complement
• Enabling into WAS is very easy
• Enabling into CICS is very easy
• Use samples to become familiar when starting out
• Don’t overlook the InfoCenter … terrific stuff there