WebSphere Application Server Liberty Profile z/OS … Application Server Liberty Profile z/OS...

© 2014 IBM CorporationIBM Advanced Technical Skills

ZCONN1WebSphere Application Server Liberty Profile z/OS

Liberty Profile and WOLA

© 2014 IBM CorporationIBM Americas Advanced Technical SkillsGaithersburg, MD2

This page intentionally left blank


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/OSz/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 Adaptersz/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.


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


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


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.


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


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.


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


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


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


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

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.


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 Classification Provides 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.

MODIFY Provides 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


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.WOLAGrant server ID READ to that. There's a bit more to it, but that's the basic idea.


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


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


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


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


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.


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.


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


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.


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.


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

BBOA1REG This 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


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

Differences …

BBOA1REGBBOA1URGBBOA1CNGBBOA1CNRBBOA1SRQBBOA1SRPBBOA1SRXBBOA1RCABBOA1RCSBBOA1RCLBBOA1GETBBOA1INVBBOA1SRV

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


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

WebSphere Application Server Liberty Profile z/OS … Application Server Liberty Profile z/OS...

Documents

Transcript of WebSphere Application Server Liberty Profile z/OS … Application Server Liberty Profile z/OS...