Unit 2 - Liberty and WOLA - IBM WWW Page this unit we will cover two topics – Liberty Profile and WOLA. Both are key parts of the z/OS Connect story. But rather than merging this

Unit 1a - Overview

Unit 1a - 1

© 2014 IBM CorporationIBM Advanced Technical Skills

ZCONN1WebSphere Application Server Liberty Profile z/OS

Liberty Profile and WOLA

WebSphere Application Server Liberty Profile z/OS

Unit 2 – Liberty Profile and WOLA


Unit 2 - 2

© 2014 IBM CorporationIBM Americas Advanced Technical Skills

Gaithersburg, MD2

This page intentionally left blank


Unit 2 - 3


Gaithersburg, MD3

Two Topics to CoverIn this unit we will cover two topics, both of which serve as a foundation to the discussion of z/OS Connect in the next unit:

Liberty …

Liberty Profile

z/OS Connect

CICS or Batch

WOLA

Liberty Profile z/OS

z/OS Connect is an application that runs inside Liberty Profile server. Any discussion of z/OS Connect necessarily relies upon knowledge of Liberty itself

WebSphere Optimized Local Adapters

z/OS Connect uses WOLA to communicate to the backend CICS or batch regions.

There are two elements to this discussion: WOLA in Liberty, and WOLA in the outside region.

In this unit we will cover two topics – Liberty Profile and WOLA. Both are key parts of the z/OS Connect story. But rather than merging this in with the z/OS Connect topic itself, we'll split it out and cover it here first. Then, with that foundation set, we'll move on to z/OS Connect.


Unit 2 - 4


Gaithersburg, MD4

Liberty Profile z/OSUnderstanding how it works on z/OS


Unit 2 - 5


Gaithersburg, MD5

Liberty Profile – More than Web, Less than Java EELiberty Profile z/OS contains functionality greater than the Java “web profile” but less than the full Java EE specification:

Functions and features …

Jave EE Specification

Java Web Profile

Liberty Profile

WAS z/OS is the full Java EE specification; Liberty is a subset of that

The function of Liberty has expanded since initial release with 8.5.5.0

Functional enhancements are provided through the maintenance stream

Latest is 8.5.5.3

The picture in the chart above illustrates how Liberty Profile represents function that is more than the Java “web profile” specification (servlets and JSPs), but something less than the full Java EE specification. WebSphere Application Server for z/OS (the “full profile” product) is full Java EE. In this sense Liberty Profile is a subset of the full-profile WAS z/OS product

Applications written to run in Liberty Profile z/OS will run in WAS z/OS, but the other way around is not necessarily true – applications written to full-profile WAS z/OS may call functions of Java EE that aren't present in Liberty. So the path is Liberty up to WAS z/OS, but not necessarily the other way.

The features of Liberty Profile have been expanded since the initial release with 8.5.0.0 of Liberty Profile. Functional enhancements are coming with maintenance releases, which means the introduction of new function is on a much more rapid basis than if released on major version boundaries. The latest Liberty Profile version is 8.5.5.3.


Unit 2 - 6


Gaithersburg, MD6

Liberty Profile z/OS at a High LevelThe following sets the stage for our discussion of Liberty Profile:

Connectivity …

Liberty Profile

Single JVM server modelUnlike the full-function WAS z/OS model (with CR/SR), this is a single JVM model. Nearly identical to Liberty Profile on distributed platforms.

Start as UNIX process or z/OS Started TaskOn z/OS you can start a Liberty Profile server instance as a UNIX process or as a z/OS started task. We expect most will run as started tasks.

Single XML file is primary configurationThe server.xml file acts as the primary configuration file. Configuring Liberty Profile involves editing the server.xml to provide the features and functions desired. z/OS Connect is configured through the server.xml file as well.

Dynamic updatesLiberty Profile will detect changes to the configuration or applications and dynamically update the runtime. This is true for most updates (there are some updates that require a restart … changing JVM heap, for example).

No admin console yetThere is a beta preview admin console available, but its functionality is limited. Configuration and administration is largely through manual edit of server.xml

You may configure / run multiple instancesAnd if under the same user directory then there are mechanisms to share configuration and application elements across server instances.

This chart provides a high-level overview of what Liberty Profile for z/OS is. The words on the chart convey the message, so we will not repeat the same message in the notes.

The key thing to understand is that Liberty Profile started out somewhat limited in in functionality and has been getting more function with each release, and often with maintenance as well. It is often called a “subset” of the traditional, full-function WAS z/OS product. That is true, but the gap is closing. For now, traditional WAS z/OS remains the production workhorse, with Liberty finding a place in development, test, and now in some portions of the production environment. z/OS Connect, which relies on Liberty Profile, is intended to be used for production level work. Therefore, Liberty Profile itself is part of that story.


Unit 2 - 7


Gaithersburg, MD7

Connectivity OptionsA summary chart of connectivity options with Liberty z/OS:

Liberty in the file system …

Liberty Profile z/OS

DB2

Browser

JDBC T4 RemoteJDBC T2 Local

CICSJMS MQWeb Services

IMSJMS MQ

Web Services

MQJMS MQ

WAS z/OSJMS MQJMS SIB

Web Services

HTTP

Program Client

JMS MQJMS SIB

Web Services

Not universal, but growing

Think about how Liberty might map into the lower end of the architecture

Batch

WOLA

JCAWOLA

8.5.0.0 – Initial Release

8.5.5.0 – JMS, Web Services

8.5.5.2 – JCA, WOLA

JCA

This chart provides a summary of the connectivity options to commonly used IBM data resources. It is intended to give a sense for how you might use Liberty Profile on z/OS. The chart also shows how clients may access a Liberty Profile server. The inclusion of JMS support in 8.5.5 expanded the connectivity options from what was available in 8.5.0. And the inclusion of WOLA support in 8.5.5.2 provides additional connectivity options to backend CICS or to/from batch programs.


Unit 2 - 8


Gaithersburg, MD8

Liberty Profile z/OS in the File SystemStarting with 8.5.5.0, Liberty is installed separately using IBM Installation Manager. When installed, it's simply a collection of files in the file system:

Key components …

/bin

featureManager

server

/clients

/dev

/lafiles

/lib

/templates

/servers

/zos

/procs

bbgzangl.jcl

bbgzsrv.jcl

/usr

/Copyright.txt

/README.TXT

/usr/lpp/zWebSphere/Liberty/V8R55FP03

/u/libserv

/servers

/server1

server.xml

The server configuration can be placed in this file structure, but on z/OS this install directory will typically be mounted as READ only.

An alternative – and what we'll do in lab – is to create the “WLP_USER_DIR” at a different READ/WRITE location:

Same principles, just a different location.

Starting with Liberty Profile z/OS Version 8.5.5.0, the target for the install can be at any location you wish. In other words, they broke out Liberty as a separately installed package from WebSphere Application Server z/OS. That gives you more flexibility; before it was included in the same file system as WAS z/OS, now it's separate.

When installed, it is simply a file system with a set of directories and files. The chart illustrates what that file system looks like. We've expanded it a bit to show where some key shell scripts are located, and where the sample JCL is located to start Liberty Profile z/OS as a started task.

The server configuration files can be created in the same file system, but on z/OS that is not likely to be the case. On z/OS the Liberty Profile installation file system will very likely be mounted as READ only. That would prevent the creation of the configuration file structure in that directory. What will be more common is the creation of the server configuration tree outside the installation directory. That's what we're showing here. How exactly that is done you will see when you get to the labs.

The reason we point this out is because if you have familiarity with Liberty Profile on some other platform – Windows or Linux, for example – then you may have created your server directly in the installation file system structure. But with a READ only file system that becomes impossible, so we point out that the configuration tree can go somewhere else. Liberty Profile itself does not really care … it can work with either.


Unit 2 - 9


Gaithersburg, MD9

Key Components of Liberty Profile Server InstanceThis picture provides a guide to the key components that make up a server instance:

Creating a server …

Liberty Profile

server.xml

USERDIRDirectory where your Liberty Profile configuration is located

JAVA_HOMEDirectory where a 64-bit Java SDK is located

INSTDIRDirectory where Liberty Profile z/OS is installed

BBGZSRVJCL start procedure

1

2

3

4

5

1. Liberty Profile z/OS is installed at a location of your choosing. It is installed using IBM Installation Manager (IM), and at time of install you indicate where you want it installed.

2. Your instance of Liberty Profile will exist in a location you specify when you create the server. On z/OS this will typically be somewhere other than INSTALLDIR.

3. The server.xml file is the primary configuration file for Liberty Profile. This is where all your z/OS Connect definitions will go.

4. Liberty Profile z/OS needs to know where a valid 64-bit Java SDK is located on your system.

5. A supplied JCL start procedure sample is provided, which you customize and use to start the server

This chart is intended to convey the pieces of the Liberty Profile runtime environment. It is actually fairly straight-forward:

1. Liberty Profile z/OS is installed using IBM Installation Manager. Starting with version 8.5.5, Liberty Profile is a separate install from the traditional, full-function WAS z/OS. You may install Liberty Profile z/OS at any mount point location you wish. It's relatively small … less than 100MB.

2. The user directory is where your runtime configuration files will reside. This can be in the install directory, but on z/OS, where install directories tend to be read only, the more likely practice is to locate this directory somewhere else. You can have this be at any location you wish. You are not limited to one user directory … you can have different locations for different purposes. For now, let's focus on one user directory location.

3. The server.xml file is the key configuration file for a given instance of Liberty Profile. Configuring Liberty Profile involves updating this XML file with the appropriate entries to provide the function you wish.

4. Liberty Profile z/OS operates with a 64-bit Java SDK, either Java 6 or Java 7. Java does not come with Liberty Profile; you need to tell Liberty Profile where a valid 64-bit SDK is located on your system. This is done with an environment variable.

5. You can run Liberty Profile as a UNIX process on z/OS, but the more likely way of running it is as a z/OS started task. For this purpose IBM supplies a sample JCL start procedure. A few simple updates to indicate where the install directory is located and where the user directory is located is all that's needed.

That is the overview of the components – the files IBM supplies as part of the installation; the configuration files in the user directory (how these are created initially we'll show you next); and a 64-bit Java SDK.


Unit 2 - 10


Gaithersburg, MD10

Creating a Server Instance ConfigurationCreating a server instance configuration is a simple matter of setting up some UNIX environment variables, then running a supplied shell script:

Key files and directories related to a server instance …

/shared/zWebSphere/Liberty/V8R55FP02

/bin

server

/u/libserv/liberty

/servers

/server1

server.xml

export WLP_USER_DIR=/u/libserv/liberty

export JAVA_HOME=/<path>/java_1.7_64

server create server1

server start server1

server stop server1Telnet or

OMVS

Simple but necessary step to create the server configuration structure in the “user directory” you indicate

Once Liberty Profile z/OS is installed (at the INSTDIR we mentioned on the previous chart), you can create a server instance. This is done with a supplied shell script.

Before you can use the shell script, you must export to your UNIX shell environment two variables – (1) the location of your user directory, which is done with the WLP_USER_DIR variable; and (2) the location of a valid 64-bit Java SDK, which is done with the JAVA_HOME variable. Then the server shell script can be used as shown in the chart. This will create a server instance with the name given under the user directory you specified.

This process will create a directory tree with various files, including the key server.xml configuration file. You could at this point start Liberty Profile with the start command. However, the default server.xml has very little in it, so while the server will start, it won't do much. The lab exercises in this workshop will show you how to update the XML for z/OS Connect.

By the way, you are not limited to one server instance under a given user directory. You could use the “start” verb to create many servers … server1, server2, etc., or whatever names you wished. There are directories that are shared between server instances under a given user directory, and supplied substitution variables that allow you to share configuration elements and applications between multiple Liberty Profile servers. How that works is a bit beyond this workshop. However, the WP102110 Techdoc at ibm.com/support/techdocs has more on that subject.


Unit 2 - 11


Gaithersburg, MD11

Directories and Files Related to a Server InstanceHere's a summary of directories and files you'll see:

Started task …

/u/libserv/liberty

/servers

/server1

/apps

/dropins

/logs

/resources

server.env

server.xml

jvm.options

/server2

/server3

/shared

/apps

/config

The WLP_USER_DIR location

Location of the 'server1' directory tree

Directory for application WAR/EAR files

Directory for dynamic pickup of app files

Directory for log files

Directory for Liberty-generated resources

UNIX environment variables file (JAVA_HOME)

Main configuration XML file

JVM options file (heap, verboseGC, etc.)

Location of other servers if created

Shared directory structure accessible by all servers under WLP_USER_DIR using built in variables that resolve to this location

On this chart we're providing a quick tour of the directories and files that you'll see under the location where you create a Liberty Profile server. Some quick notes about this:

● The WLP_USER_DIR location is whatever you set that UNIX environment variable to when you used the server shell script to create the server. You may have several different locations where Liberty Profile servers are located. For any given server, the location under which it was created is that server's WLP_USER_DIR.

● The /apps directory is where you may locate application files if you wish. Then you can use an XML element to reference the WAR or EAR file and Liberty knows you mean this directory.

● The /dropins directory is monitored by Liberty Profile and if you drop an application EAR or WAR file in this directory, Liberty Profile will dynamically pick it up and deploy it.

● The /logs directory is where you will find the messages.log file and the FFDC (error) files.

● The server.env file is used to define UNIX environment variables that apply to this server. When Liberty Profile is started as a started task, this is where you tell Liberty Profile about its JAVA_HOME location.

● The server.xml file is the key configuration file for Liberty Profile. This is where all the z/OS Connect configuration elements go. This is required. The server.env and jvm.options are optional.

● The jvm.options file is for coding options to be used by the JVM of Liberty Profile. This is where you would set things like the heap sizes, verboseGC, compressed references, and any other JVM option. One option per line.

● You may have other servers configured under the WLP_USER_DIR location.

● Finally, the /shared directory is accessible by all the servers under the WLP_USER_DIR location. These servers can use built-in variables to reference the shared location, and with that pull in configuration elements and application files from the shared location. Changes to shared files are dynamically detected and brought into all servers that reference the shared resource.

The WP102110 Techdoc at ibm.com/support/techdocs has a “Quick Start Guide” that illustrates how the shared directory location can be used.


Unit 2 - 12


Gaithersburg, MD12

Starting as a z/OS Started TaskYou can start Liberty as a UNIX process, but on z/OS we anticipate most will wish to start as a z/OS started task. A supplied JCL start procedure accomplishes that:

server.xml …

//BBGZSRV PROC PARMS='defaultServer'

//*-----------------------------------------------------------------

:

//*-----------------------------------------------------------------

// SET INSTDIR='/shared/zWebSphere/Liberty/V8R55FP02'

// SET USERDIR='/u/user1/liberty'

//*-----------------------------------------------------------------

:

//*-----------------------------------------------------------------

//STEP1 EXEC PGM=BPXBATSL,REGION=0M,

// PARM='PGM &INSTDIR./lib/native/zos/s390x/bbgzsrv &PARMS'

//WLPUDIR DD PATH='&USERDIR.'

//STDOUT DD SYSOUT=*

//STDERR DD SYSOUT=*

Set INSTDIR= and USERDIR= to the appropriate values for your

instance of LIberty Profile server

Then, from MVS Command Extension (to preserve case):

START BBGZSRV,PARMS='server1'

Create a server.env file in same directory as server.xml and populate with JAVA_HOME= and pointer to 64-bit Java SDK

Create SAF STARTED profile so Liberty ID is assigned to this started

task when BBGZSRV started

Starting a Liberty Profile z/OS server instance as a started task is really fairly simple. A JCL start procedure is provided that you copy to your JCL proclib. The JCL start proc name is BBGZSRV, but you may change that to anything you like. You will need a SAF STARTED profile to assign the ID to the started task.

Then you modify two variables in the JCL – one for the installation directory, and one for the user directory.

Finally, the Liberty Profile z/OS server needs to know where to get the 64-bit JVM. You accomplish that by creating a file called server.env and populating that with the JAVA_HOME= value that points to the location.

From there it's just a matter of starting the procedure. The syntax is as shown on the chart, with PARMS= used to indicate which server instance under USERDIR to start. The JCL has a default value of defaultServer, but you can override with the PARMS= you pass in. Here's where you have to be a little careful … that ends up being a pointer to a UNIX directory, and UNIX is case sensitive. You need to make sure the z/OS START command, when enters, preserves the case you enter. The MVS Command Extension accomplishes that.

Note: you are not required to start Liberty as a started task. The only function you lose by starting as a UNIX process is the MODIFY command suppoert (since MODIFY acts against a started task). But all the other functionality, including z/OS Connect, works when Liberty is started as a UNIX process or a started task. We anticipate most z/OS installations will use started tasks simply because that maps to operational patterns better than UNIX processes do.


Unit 2 - 13


Gaithersburg, MD13

The server.xml Configuration FileThis is the key configuration file in which all the Liberty Profile and z/OS Connect configuration elements will appear:

Platform exploitation …

<server description="new server">



<featureManager>

<feature>jsp-2.2</feature>

</featureManager>



<httpEndpoint id="defaultHttpEndpoint"

httpPort="9080"

httpsPort="9443" />

</server>

This is the server.xml that you'll see when you first create your server.

For features such as WOLA and z/OS Connect, you update this section of XML and add appropriate keywords.

You update XML here for various Liberty and z/OS Connect function …

such as using SAF, or configuring z/OS Connect services.

This is where you configure your host and ports

This comes down to knowing what XML to add to the file. The IBM Knowledge Center has this information, as do the Techdocs we have published on this topic.

This chart shows what the default server.xml looks like when you first create a server instance. This is your starting point for additional XML that brings in the features and functions you want.

The <featureManager> section is where you specify what features you want Liberty Profile to load. When we speak of Liberty as “composable,” this is what we mean – you can compose the functionality that gets loaded. For z/OS Connect and the WOLA function you add a line each to indicate those functions. You'll see that in lab.

Other updates to server.xml go below that (and in truth, the order does not really matter). Updates for things like SSL in SAF, or z/OS Connect configured services, or the WOLA specifics there.

Finally, the last section is for HTTP ports. You see the default values here.

The message here is this – configuring Liberty Profile is all about configuring this server.xml file. The syntax of the updates to accomplish various things will typically be found by finding samples in documentation; for example, the WP102110 Liberty Profile Quick Start Guide, or the WP102439 z/OS Connect Quick Start Guide.


Unit 2 - 14


Gaithersburg, MD14

Taking Advantage of the z/OS PlatformLiberty Profile z/OS has much in common with Liberty Profile on other platforms, but on z/OS it goes one step further and provides key things to take advantage of z/OS:

Angel process …

JDBC Type 2 and RRSProvides JDBC Type 2 provides cross-memory access to DB2 z/OS. z/OS Resource Recovery Services (RRS) is used for synchpoint coordination between transaction participants.

WLM ClassificationProvides both Service Class and Report Class classification of requests that come into the Liberty Profile server.

SAF SecurityProvides use of the z/OS Security Access Facility (SAF) for security actions such as user registry, user role authority checking, and SSL key and trust store.

MODIFYProvides use of the z/OS MODIFY command against started task to process DUMP operations.

WOLAProvides cross-memory communications using the Optimized Local Adapters function.

These two will be used in this workshop

Liberty Profile is designed to be operated across many different server platforms. z/OS is one of the platforms, and in many ways Liberty Profile z/OS is just like Liberty Profile on any other platform. But the developers of Liberty Profile z/OS wanted to provide the ability to take advantage of (or “exploit”) the z/OS platform in key ways. Those additional functions are shown on the chart.

The two that we'll focus on in this workshop are indicated by the green dots – SAF Security and WOLA. The others could be used with z/OS Connect as well, but the objective of this workshop is to deliver the key things about z/OS Connect in something less than two days. So we won't go into detail on the other functions. If you're interested, see the WP102110 Quick Start Guide at ibm.com/support/techdocs.


Unit 2 - 15


Gaithersburg, MD15

The 'Angel' ProcessThere's one more piece of the puzzle … the 'Angel' process. This is used to provide access to z/OS authorized services through SAF SERVER profiles:

Liberty Quick Start …

Liberty Profile

server.xml

Angel Process

Okay to access authorized?

Yes, you are authorized

Not a 'server'We deliberately call it a 'process' and not a server because it has no configuration, no ports, and uses no CPU once started. It's just an 'anchor point' for authorized service access.

Not requiredOnly required when server needs access to authorized services. WOLA is an authorized service that requires the Angel.

One per LPARWhen required, only one Angel is needed, regardless of the number of Liberty Profile servers on the LPAR.

Designed to start and leave up foreverThe design of the Angel is such that it should not need to be stopped and restarted. There are exceptions – move to WOLA and 8.5.5.2 required stop and restart with new level of the code.

Access through SAF SERVER profilesThis is the key … each authorized service has a SAF SERVER profile associated with it. You grant a server access to the authorized service by granting the server ID. For example:

BBG.AUTHMOD.BBGZSCFM.WOLA

Grant server ID READ to that. There's a bit more to it, but that's the basic idea.

There is another component we must introduce – the “Angel” process. This is used to provide access to z/OS authorized services, such as RRS or WOLA. The Angel is a started task. A simple JCL start procedure is supplied.

The chart provides the commentary we wish to get across about the Angel. Most importantly, it is not really a 'server' because it has no configuration, no TCP ports, and it uses no CPU once started. It's really just an anchor point for protected access to the authorized services. It's not required … if you don't wish to use authorized services, then the Angel is not required. However, z/OS Connect uses WOLA, and WOLA requires the Angel.

Access to the authorized services is provided with SAF SERVER profiles. For example, the chart shows the WOLA SERVER profile. Throughout this workshop's labs, and in the unit on security, you will see us return again and again to SERVER profiles to grant your Liberty Profile server instance access to the authorized services.


Unit 2 - 16


Gaithersburg, MD16

Collectives and AdministrationThe administrative model that is emerging for Liberty Profile (all platforms) involves organizing servers into a 'collective' and administering through a GUI:

Liberty Quick Start …

Collective Controller Collective

Member

Collective Member

Collective Member

Cluster

Jython Script

Java Client

Web Admin Center Liberty Profile does not have a

defined topology like full profile WAS … no DMGR, no Node Agents, etc.

A “collective” is a federation of Liberty Profile servers with a designated server acting as the “controller”Multiple controllers possible for an HA configuration

User can interact with controller using one of several different methods

This management model is getting more functionally rich over time

Liberty Profile does not have a defined management topology like full-profile WAS has with its Deployment Manager and Node Agents. The design of Liberty Profile is to be more flexible. But a management model for multiple servers is still worthwhile; otherwise, you would be left managing each individually.

To address this, Liberty Profile has a management model based on grouping Liberty Profile servers into a “collective,” which is then managed by a server designated as the “controller”.

Note: it is possible to configure multiple controllers such that one is active and the others are ready to take over with the loss of the active server.

The controller can be accessed in several ways – using Jython scripts, using a Java client you write, or by using the Admin Center function. The controller then monitors and manages the servers in the collective.

Clustering of Liberty Profile servers is possible. Through the collective controller you can create a plugin-cfg.xml file that can be used with the WAS plugin for load balancing across a cluster and affinity routing.


Unit 2 - 17


Gaithersburg, MD17

The Liberty Profile “Quick Start Guide”If you're interested in diving deeper into Liberty Profile z/OS and what it can do, see the “Quick Start Guide” at the WP102110 Techdoc:

WOLA …

http://www.ibm.com/support/techdocs/atsmastr.nsf/WebIndex/WP102110

Step-by-step instructions for setting up and exercising key

functions of Liberty Profile z/OS

Finally, as mentioned earlier, if you're interested in going deeper into setting up and using Liberty Profile z/OS, the WP102110 Techdoc at the URL shown above provides quite a few documents, including a Quick Start guide that gives you a step-by-step guide to setting up and exercising key functions.


Unit 2 - 18


Gaithersburg, MD18

Optimized Local AdaptersUnderstanding WOLA and how it works with Liberty Profile z/OS


Unit 2 - 19


Gaithersburg, MD19

The History of WOLAThe roots of WOLA go back more than 10 years … to the original full-function WAS z/OS product and its use of z/OS cross-memory services:

Registration …

Application Server

Servlet

Application Server

EJB

Example: Servlet to EJB, Same LPARFrom the very beginning WAS z/OS has had the ability to bypass the TCP stack entirely when IIOP calls would flow between servers (address spaces) on the same LPAR.

Because z/OS had cross-memory services, bypassing TCP stack reduced latency and saved codepath and cycles processing unnecessary network processing.

This cross-memory function in WAS was called “LOCALCOMM”

WOLA is Bi-DirectionalWhich means Java programs in WAS can call out to programs in external address space, and programs outside WAS can call in and invoke Java assets

Liberty and WOLA Started with 8.5.5.2WOLA and traditional WAS z/OS was introduced starting with 7.0.0.4, and has undergone many enhancements since then.

With Liberty the WOLA support came into being with V8.5.5 Fixpack 2.

WOLA is LOCALCOMM ExternalizedThe cross-memory exchange mechanism was in place from the beginning. To allow address spaces other than WAS z/OS to participate it meant creating an external interface to the LOCALCOMM function.

API

Address Space

Program

The roots of WOLA go way back to the very early days of WAS on z/OS. Back then, the designers of WAS z/OS took advantage of the cross-memory services the z/OS operating system provided. They used it for internal exchanges between servers. For example, when a servlet called an EJB in another server, WAS z/OS was smart enough to know when it was on the same LPAR, and if so then it would invoke the cross-memory services to call between servers. No TCP stack was involved. The exchange was between the virtual storage of the two server address spaces. This cross-memory functionality was called “LOCALCOMM.”

WOLA is based on this. WOLA is really a means of externalizing LOCALCOMM so address spaces other than WAS address spaces can participate. It involves a programming interface to the cross-memory functions so programs can access and use it.

WOLA is bi-directional, which means the direction of invocation can be either direction – Java in WAS can call out to a program in another address space, or an outside program can call in.

WOLA in traditional WAS z/OS first came available in the 7.0.0.4 time frame. It became available with Liberty in the 8.5.5.2 time frame. For the purposes of discussing z/OS Connect, we will focus on WOLA in Liberty. Most aspects of WOLA are common across the two environments, but there are some differences. Rather than create potential confusion citing differences and exceptions, we'll focus here on just what WOLA in Liberty looks like because z/OS Connect is strictly a Liberty Profile function.


Unit 2 - 20


Gaithersburg, MD20

Key Concept #1 - RegistrationBefore any WOLA communications can occur, the outside address space must create a registration into the Liberty Profile server:

Multiple registrations …

Liberty Profile

server.xml

CICS, BatchOutside Address

Space

Registration is Logical ConnectionThe purpose of the registration is to create a logical cross-memory connection between the two address spaces. This is what creates the “pipe” over which the exchanges will take place.

Outside Address Space Always InitiatesThe outside address space initiates the registration; the Liberty Profile server never registers out to the CICS or Batch address space. Always “outside registers in.”

How this is done depends on the outside address space. The CICS Link Server Task does this one way; batch programs another. More on this coming up. Both end up with same thing: a registration.

Liberty Server and 3-part WOLA Server NameFor the outside address space to uniquely identify which Liberty Profile server (out of perhaps many on the LPAR), a three-part name is provided in the Liberty Profile server.xml:

<zosLocalAdapters

wolaGroup="GROUP"

wolaName2="NAME2"

wolaName3="NAME3" />

That creates a unique WOLA name for the Liberty Profile server. The outside address space then uses this name to identify the server for the creation of the WOLA registration.

Max 8 characters each. Values are really arbitrary. Must be unique on LPAR.

One of the first key concepts to explore is registration. Before any communications over WOLA can take place, a logical connection between the address spaces must be in place. That logical connection is used by the WOLA control mechanisms to understand which address spaces are participating. That logical connection is the registration.

The outside address space – the CICS region or the batch program – always initiates registration. Liberty Profile will never register out to a CICS program or a batch program; the outside address space always registers into the Liberty Profile server. For batch programs one of the WOLA APIs is used – BBOA1REG. For CICS, a supplied long running task called the “Link Server” will perform the registration. In either case, both end up accomplishing the same thing – building a logical connection between the two address spaces and providing the “pipe” through which the WOLA calls will take place.

Registration requires the outside address space to uniquely identify the Liberty Profile server into which the registration will occur. This is done with a three part name specifed in the server.xml of the Liberty Profile server.

Note: why a three-part name? It mimics the registration mechanism used by traditional WAS z/OS, which is based on the cell, node and server name. Liberty Profile does not have the notion of cells or nodes, so rather than invent a new registration mechanism (and change the APIs), Liberty Profile uses a made-up three-part name for registration.

The three-part name consists of three strings, up to 8 characters each, that together comprise the unique name. The value of the each string is really arbitrary … you can use whatever values you want. But it must be unique on the z/OS LPAR. The outside address space then uses the three-part name as part of its registration process into the Liberty Profile z/OS server.


Unit 2 - 21


Gaithersburg, MD21

Multiple Registrations PossibleAn instance of Liberty Profile can support many registrations:

Outbound and Inbound …

Liberty Profile


Space


Space


Space

This is how you would have a single instance of z/OS Connect connect to multiple CICS regions and/or long running tasks

Each registration carries a name (up to 12 characters) … that's how you identify which WOLA registration you want to communicate over

In Unit 3 you will see how the server.xml for z/OS Connect identifies the registration a configured service maps to.

A given instance of Liberty Profile is capable of supporting multiple registrations into it. The architecture of WOLA does not limit a server to just one registration. If you had multiple CICS regions you wanted to communicate with over WOLA, each CICS region could establish a WOLA registration into the Liberty Profile server.

WOLA registrations carry a name, and that name is used to identify which WOLA registration to communicate over. The registration name is up to 12 characters long. For z/OS Connect, the registration over which a service maps is defined in the server.xml file. We'll see how that's done in Unit 3 of this workshop.


Unit 2 - 22


Gaithersburg, MD22

Key Concept #2 – Outbound vs. Inbound The key here is who starts the conversation after the registration has been created. WOLA is bi-directional … but for z/OS Connect the flow is “outbound”:

Link Server Task …

Liberty Profile


Space

Program

Java

“Outbound”

Java program in Liberty uses a supplied JCA resource adapter to communicate

over WOLA. The target in outside address space requires WOLA

awareness and be in “listen state” ready to take the call. More on this coming up

Liberty Profile


Space

Program

Java

“Inbound”

Program (COBOL, C/C++, PL/I or High Level Assembler) uses WOLA APIs to invoke the target Java EJB in Liberty.

This is not related to z/OS Connect so we will not focus on this in this workshop.

Our Focus

The next concept is the flow of the conversation; or who starts the conversation after the registration is in place. There are two options –

● Outbound – the Java program in Liberty initiates and calls the outside program

● Inbound – the outside program initiates and calls into Liberty and targets a Java program

For this workshop we are going to focus on the outbound model. That's because z/OS Connect is an outbound model application. z/OS Connect is a Java program – a servlet – that runs in Liberty Profile and calls backend programs.

When WOLA is used in the outbound model, the program in the outside address space must be ready to accept the call from Java in Liberty, whenever that call takes place. For a CICS region that is handled by the WOLA Link Server Task, which is a long-running CICS task that will receive a call coming over WOLA and then call the named CICS program. For a long-running COBOL program, one of the WOLA APIs is used to “host a service” – that is, go into a listen state and wait for the call to come over.

We'll explore both next.


Unit 2 - 23


Gaithersburg, MD23

Outbound and CICS Link Server TaskWhen the outside address space is a CICS region, then the supplied WOLA Link Server Task is used to shield the target CICS programs from any awareness of WOLA:

BBOC START_SRVR …

Liberty Profile CICS Region

Program

Java

WOLA Task Related User Exit

BBO$ BBO#

WOLA JCA Resource

Adapter

1

2

3 4 5

1. Java program uses methods on JCA resource adapter to access WOLA. Java program is largely unaware WOLA is in use.

2. TRUE in CICS handles low-level WOLA calls coming over from Liberty Profile

3. The BBO$ long running Link Server task gets the request and prepares to invoke the target program, which is the named “service” of the WOLA call.

4. The BBO# invocation task is short-lived*. It is started by BBO$ to perform the EXEC CICS LINK to the target program. BBO# is part of design to allow security assertion: if SEC=Y, then BBO# is started under asserted ID and EXEC CICS LINK is performed under that ID.

5. The target program is invoked by BBO# with EXEC CICS LINK. It is business-as-usual CICS as this point. Target is unaware WOLA in use.

Installation of these components in CICS region performed with sample JCL jobs. Very easy to do and takes a few minutes

* Short lived when registration has SEC=Y. If SEC=N and REU=Y then BBO# stays active.

For CICS, the calls flowing outbound from Liberty Profile into CICS is handled by something called the Link Server Task. This is a long-running CICS task provided by IBM that makes using WOLA as simple as possible, and that shields the CICS programs from having to know anything about WOLA. The picture above illustrates how this works, and the numbered blocks correspond to the notes on the chart and the notes below:

1. Java programs in Liberty – z/OS Connect is a Java program in Liberty – uses the supplied WOLA JCA resource adapter to communicate outbound using WOLA. The Java program needs to know very little about WOLA; most of WOLA is shielded behind a methods of the JCA resource adapter.

2. A WOLA Task Related User Exit (TRUE) is enabled in the CICS region. This handles the low-level WOLA interaction.

3. The long running Link Server task is by default called BBO$. This is started by you either manually or when the region starts up. Think of this as the program that “catches” the calls coming over WOLA into the CICS region.

4. Another task is used to invoke the target CICS program. This by default is called BBO#, and it is this that does the EXEC CICS LINK to the named target. The reason this is part of the design is it allows assertion of individual security identities across WOLA. When that is chosen, then different copies of BBO# are started, each under the asserted identity. Then normal CICS security takes over – is the ID under which BBO# running allowed to call the program it is trying to call? If yes, then the link takes place; if no, then the link is rejected. The alternative is to have BBO# started each time under the same ID as BBO$. That's a less granular security model, but it may be perfectly acceptable for what you're trying to accomplish.

5. The last step of this, as noted, is for BBO# to perform an EXEC CICS LINK to the program named by the Java program as the target of the call. To the CICS program this is normal CICS processing. The target CICS programs doesn't realize WOLA is in use.

For any CICS system programmers in the audience, the installation process for these components is very simple. Install JCL samples are provided. That updates the CSD. Then the WOLA program modules are concatenated to the DFHRPL DD statement of the CICS region proc. WOLA is then available to the region.


Unit 2 - 24


Gaithersburg, MD24

CICS Link Server Task and RegistrationWhen using CICS, you can register into the Liberty Profile server as part of the starting the Link Server Task in the CICS region:

Long-running COBOL …

CICS TerminalSession

BBOC START_SRVR RGN=CICSREG DGN=GROUP NDN=NAME2 SVN=NAME3

SVC=* MNC=1 MXC=10 TXN=N SEC=N REU=Y

Supplied Utility Tran Action

Registration Name

The three-part name specified in server.xml

Service restrictions

Connection Pool Values

Transaction Propagation

(always N with Liberty WOLA)

Security Propagation

Either Y or N

Reuse BBO# if SEC=N

This can be automated so it starts at region startup – either INITPARM or using sequential terminal.

Here we're showing the command used to start the Link Server Task in a CICS region. This also creates a registration into the Liberty Profile server.

Note: this command can be performed manually at a CICS terminal session, or it can be automated using INITPARM or sequential terminal so the link server starts when the region starts.

● BBOC is a supplied utility transaction

● START_SRVR is one of the verbs on the BBOC utility transaction. There are several others to stop the link server, and start and stop the TRUE.

● RGN= specifies the registration name to be associated with the registration into the Liberty Profile server. The name is up to 12 character long.

● DGN=, NDN= and SVN= specifies the three-part name used by Liberty Profile to identify itself uniquely for WOLA. We saw this earlier. The three-part name is specified in the server.xml of the Liberty Profile server.

● SVC= indicates which CICS programs can be called across this WOLA registration. An asterisk indicates any program can be called (no restrictions). You can limit it. For example, SVC=XYZ* means only programs that start with XYZ can be called.

● MNC= and MXC= specifies the starting number of active connections and the maximum connections allowed for this registration.

● TXN= indicates whether transaction can be propagated across the registration. Liberty Profile WOLA does not support TX propagation, so this is always N.

● SEC= indicates whether or not security is propagated across the registration. We spoke of this earlier when we described the function of the BBO# invocation task. If SEC=Y, then security is asserted and BBO# runs under the asserted ID; if SEC=N then BBO# runs under the ID of the long-running BBO$ task.

● REU= is used to indicate whether BBO# is re-used when SEC=N is specified. Default is REU=Y.


Unit 2 - 25


Gaithersburg, MD25

WOLA and Long-Running COBOL*This involves using some of the Native APIs** supplied with WOLA:

The 13 APIs …* Or C/C++, PL/I or High Level Assembler** See WP101490 “WOLA API Primer” for more on each of the 13 APIs

BBOA1REGThis will register into the Liberty Profile server. The parameters are just like what you saw on the START_SRVR command from the previous chart

BBOA1SRVThis will “host a service” … that is, will wait for Java in Liberty to call. At that point it will “wake up” and your business processing takes place. You then loop back and call BBOA1SRV to host the service again.

Liberty Profile Long Running Job

Java

WOLA JCA Resource

Adapter

1

BBOA1REG

BBOA1SRV

BBOA1URG

Perform business logic here, or link

off to other COBOL* assets

Other COBOL Assets

2

34

6

5

When the outside address space is a long-running COBOL program (or C/C++, PL/I or High Level Assembler), then there's no Link Server Task available like there is with CICS. So what serves as the “listener” to accept the call over from Java? The answer is the WOLA native APIs; specifically, the BBOA1SRV API. Let's go through the numbered blocks on the chart:

1. The Java program in Liberty Profile uses the supplied WOLA JCA resource adapter, just like it would if CICS was the outside address space. That aspect of WOLA and Liberty Profile is the same.

2. The program uses the BBOA1REG API to register into the Liberty Profile z/OS server using the three-part name we discussed earlier. BBOA1REG has the same parameters the BBOC START_SRVR command did. The same principles apply – the name of the registration; the server into which the registration will be formed; the restricted services names; the minimum and maximum connections in the pool.

3. The program then calls BBOA1SRV. This API “hosts a service” … that is, program control is held until a call comes over WOLA from Java. When that call is received, program control is released. BBOA1SRV “wakes up” and returns control to the program.

4. At that point the program can do whatever it is designed to do. The business logic may be in the program itself, or the program may link off to other assets.

5. When the processing is complete, the program loops back and calls BBOA1SRV again. This puts the program back into a “listen state” waiting for the Java side to call again.

6. When all the processing is complete, the program can drop out of the loop and call BBOA1URG to unregister from the Liberty Profile server.

Note: what we're showing you here is the synchronous case … this is a single-threaded model where only one call from Java can be handled at any given time. That may work perfectly well for what's needed. An asynchronous model exists as well, which would allow for multiple calls from Java to be “in flight” at any given time. That's a bit more complicated. For now, understand that both synchronous and asynchronous models exists.


Unit 2 - 26


Gaithersburg, MD26

The 13 WOLA APIsThe 13 APIs organize into the following way:

Differences …

BBOA1REG

BBOA1URG

BBOA1CNG

BBOA1CNR

BBOA1SRQ

BBOA1SRP

BBOA1SRX

BBOA1RCA

BBOA1RCS

BBOA1RCL

BBOA1GET

BBOA1INV

BBOA1SRV

BBOA1CNGGet connection

BBOA1SRQSend request

BBOA1GETGet response

BBOA1CNRRelease connection

BBOA1RCLResponse length

Inbound Advanced

BBOA1INVInvoke EJB

Inbound Basic

BBOA1RCAReceive any

BBOA1RCSReceive specific

BBOA1GETGet response

BBOA1CNGGet connection


BBOA1SRXSend exception

Outbound Advanced

BBOA1REGRegisters

BBOA1URGUnregisters

Common

BBOA1SRVHost service

BBOA1SRPSend response


Outbound Basic

cdat_olaapisInfoCenter

Simplest model for listener to receive calls from

z/OS Connect

The previous chart mentioned three WOLA APIs that can be used in a long-running listener program written in either COBOL, C/C++, PL/I or High Level Assembler – BBOA1REG (register), BBOA1SRV (host a service), and BBOA1URG (unregister). But that's 3 of 13 APIs … what about the other 10? The chart above illustrates how the 13 APIs organize into four categories – inbound basic, inbound advanced, outbound basic and outbound advanced.

The difference between “basic” and “advanced” is based on what assumptions are made by the API. The “basic” APIs make assumptions to keep the API simple to use. Those assumptions may or may not be acceptable, however, depending on what you're trying to do. So the “advanced” APIs give you more control over the behavior of the APIs. But with that comes a bit more programming effort to use them. That's the trade off – simplicity (basic) vs. more control (advanced).

The Knowledge Center has a very nice reference page with all the APIs – the parameter maps and return codes for each API. The search string for that page is shown on the chart.

For this workshop that's enough detail on the APIs. The WP101490 Techdoc at ibm.com/support/techdocs has a “Primer” document that provides exercises to walk you through usage of all 13 APIs.


Unit 2 - 27


Gaithersburg, MD27

Full-Profile WAS WOLA vs. Liberty Profile WOLAThe two are similar at the programming interface, but different in some other respects:

WOLA Techdocs …

Similarities

● Outbound JCA programming interfaces are the same

● Inbound native API programming model is the same

● CICS Link Server Task function very similar in design and operation

● Security assertion with CICS both directions supported

● Supplied samples nearly identical

Differences

● Global transaction not supported with Liberty WOLAApplications that start global transactions will need to be modified before using with Liberty WOLA

● General programming APIs of Liberty not as complete as full-function WASDepending on what application is doing, it may or may not operate with Liberty (this is more a Liberty statement than a WOLA statement)

● Target EJB for inbound must be EJB 3.x and has Liberty-specific design requirements

● Round-Robin and Alternate JNDI not supportedRelied on function of traditional WAS not present in Liberty

● Liberty WOLA and IMS not supported

● No WOLA MODIFY commands or SMF 120.10 for WOLA

WOLA on full-profile WAS z/OS and WOLA on Liberty Profile is designed to be as similar as possible, but there were some things are different. The programming interface is the same for both full-profile and Liberty, but the functionality available is not quite the same. The chart summarizes the similarities and the differences.

The key differences arise because of the difference between full Java EE of full-profile WAS z/OS and the Java function supported by Liberty Profile. Liberty Profile, as noted earlier, is not a Java EE runtime. The other differences come from function in full-profile WAS z/OS WOLA that could not be duplicated in Liberty Profile z/OS WOLA because of the differences in the underlying server runtime – again, the Java EE vs. not Java EE issue.

Bottom line – WOLA is very similar but not exactly the same. For z/OS Connect the differences are not really an issue because what z/OS Connect is doing with WOLA – rapid request/response to backend system using the WOLA outbound model – is not hindered by the limitations cited above.


Unit 2 - 28


Gaithersburg, MD28

WOLA-Related TechdocsIf you're interested in diving deeper into WOLA, see the WP101490 Techdoc:

http://www.ibm.com/support/techdocs/atsmastr.nsf/WebIndex/WP101490

Step-by-step instructions for setting up and exercising WOLA with Liberty Profile z/OS

Step-by-step instructions for using the native APIs

We've taken a fairly brief and high-level tour of WOLA. If you're interested in digging deeper, the WP101490 Techdoc has more information, including the two documents shown in the chart.

End of UnitEnd of Unit

Documents

Unit 2 - Liberty and WOLA - IBM WWW Page this unit we will cover two topics – Liberty Profile and WOLA. Both are key parts of the z/OS Connect story. But rather than merging this