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

Don [email protected]

(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


Gaithersburg, MD


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.


Gaithersburg, MD


4

Overview“What is it?”


Gaithersburg, MD


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


Gaithersburg, MD


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.


Gaithersburg, MD


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


Gaithersburg, MD


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.


Gaithersburg, MD


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


Gaithersburg, MD


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


Gaithersburg, MD


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.


Gaithersburg, MD


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.


Gaithersburg, MD


13

To Start Things Off

It’s important we cover two important concepts about performance numbers

Relative comparisons …

1. “Relative” comparisons

2. “Normalized” findings


Gaithersburg, MD


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


Gaithersburg, MD


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


Gaithersburg, MD


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


Gaithersburg, MD


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


Gaithersburg, MD


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”


Gaithersburg, MD


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”


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!


Gaithersburg, MD


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”


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!


Gaithersburg, MD


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 …


Gaithersburg, MD


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 …


Gaithersburg, MD


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


Gaithersburg, MD


24

Installing and Enabling“How do I enable it?”


Gaithersburg, MD


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


Gaithersburg, MD


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


Gaithersburg, MD


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


Gaithersburg, MD


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


Gaithersburg, MD


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


Gaithersburg, MD


30

Function Usage“How do I use it?”

Batch and CICS


Gaithersburg, MD


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


Gaithersburg, MD


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 …


Gaithersburg, MD


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 …


Gaithersburg, MD


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

, &registerName

, &minConn

, &maxConn

, &regFlags

, &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.


Gaithersburg, MD


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


Gaithersburg, MD


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 ( &registerName

, &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


Gaithersburg, MD


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


Gaithersburg, MD


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 …


Gaithersburg, MD


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:


Gaithersburg, MD


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


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


Gaithersburg, MD


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


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.


Gaithersburg, MD


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


Gaithersburg, MD


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)


Gaithersburg, MD


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/


Gaithersburg, MD


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.


Gaithersburg, MD


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)


Gaithersburg, MD


47

Conclusion


Gaithersburg, MD


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

session 1172 websphere z/os optimized local adapters (wola)

Documents