Liberty Profile and WOLA

Transcription

1 Unit 1a - Overview IBM Advanced Technical Skills ZCONN1 WebSphere Application Server Liberty Profile z/os Unit WebSphere 2 Liberty Application Server Profile Liberty and Profile z/os WOLA Liberty Profile and WOLA Unit 1a - 1

2 This page intentionally left blank 2 Unit 2-2

3 Two Topics to Cover In 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 Profile z/os Connect 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 WOLA CICS or Batch 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. 3 Liberty 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-3

4 Liberty Profile z/os Understanding how it works on z/os 4 Unit 2-4

5 Liberty Profile More than Web, Less than Java EE Liberty Profile z/os contains functionality greater than the Java web profile but less than the full Java EE specification: Liberty Profile Java Web Profile Jave EE Specification 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 Functional enhancements are provided through the maintenance stream Latest is Functions and features 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 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 Unit 2-5

6 Liberty Profile z/os at a High Level The following sets the stage for our discussion of Liberty Profile: Liberty Profile Single JVM server model Unlike 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 Task On 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 configuration The 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 updates Liberty 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 yet There 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 instances And if under the same user directory then there are mechanisms to share configuration and application elements across server instances. Connectivity 6 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-6

7 Connectivity Options A summary chart of connectivity options with Liberty z/os: Initial Release JMS, Web Services JDBC T4 Remote JDBC T2 Local DB JCA, WOLA Browser HTTP JMS MQ Web Services JCA WOLA CICS Program Client JMS MQ JMS SIB Web Services Liberty Profile z/os WOLA Batch JMS MQ Web Services JCA JMS MQ IMS MQ Not universal, but growing Think about how Liberty might map into the lower end of the architecture JMS MQ JMS SIB Web Services WAS z/os Liberty in the file system 7 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 expanded the connectivity options from what was available in And the inclusion of WOLA support in provides additional connectivity options to backend CICS or to/from batch programs. Unit 2-7

8 Liberty Profile z/os in the File System Starting with , Liberty is installed separately using IBM Installation Manager. When installed, it's simply a collection of files in the file system: /usr/lpp/zwebsphere/liberty/v8r55fp03 /bin featuremanager server /clients /dev /lafiles /lib /templates /servers /zos /procs bbgzangl.jcl bbgzsrv.jcl /usr /Copyright.txt /README.TXT 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: /u/libserv /servers /server1 server.xml Same principles, just a different location. 8 Key components Starting with Liberty Profile z/os Version , 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-8

9 Key Components of Liberty Profile Server Instance This picture provides a guide to the key components that make up a server instance: 1 4 INSTDIR Directory where Liberty Profile z/os is installed JAVA_HOME Directory where a 64-bit Java SDK is located Liberty Profile 5 BBGZSRV JCL start procedure 3 2 server.xml USERDIR Directory where your Liberty Profile configuration is located 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 9 This chart is intended to convey the pieces of the Liberty Profile runtime environment. It is actually fairly straightforward: 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-9

10 Creating a Server Instance Configuration Creating a server instance configuration is a simple matter of setting up some UNIX environment variables, then running a supplied shell script: /shared/zwebsphere/liberty/v8r55fp02 /bin server 10 Telnet or OMVS export WLP_USER_DIR=/u/libserv/liberty export JAVA_HOME=/<path>/java_1.7_64 server create server1 server start server1 server stop server1 Simple but necessary step to create the server configuration structure in the user directory you indicate /u/libserv/liberty /servers /server1 server.xml Key files and directories related to a server instance 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 WP Techdoc at ibm.com/support/techdocs has more on that subject. Unit 2-10

11 Directories and Files Related to a Server Instance Here's a summary of directories and files you'll see: 11 /u/libserv/liberty /servers /server1 /apps /dropins /logs /resources /server2 /server3 /shared /apps /config server.env server.xml jvm.options 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 Started task 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 WP Techdoc at ibm.com/support/techdocs has a Quick Start Guide that illustrates how the shared directory location can be used. Unit 2-11

12 Starting as a z/os Started Task You 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: //BBGZSRV PROC PARMS='defaultServer' //* task when BBGZSRV started : //* // SET INSTDIR='/shared/zWebSphere/Liberty/V8R55FP02' // SET USERDIR='/u/user1/liberty' //* : the appropriate values for your instance of LIberty Profile server //* //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=* Create SAF STARTED profile so Liberty ID is assigned to this started Set INSTDIR= and USERDIR= to Create a server.env file in same directory as server.xml and populate with JAVA_HOME= and pointer to 64-bit Java SDK 12 Then, from MVS Command Extension (to preserve case): START BBGZSRV,PARMS='server1' server.xml 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-12

13 The server.xml Configuration File This is the key configuration file in which all the Liberty Profile and z/os Connect configuration elements will appear: <server description="new server"> <!-- Enable features --> <featuremanager> <feature>jsp-2.2</feature> </featuremanager> 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. <!-- To access this server from a remote --> <httpendpoint id="defaulthttpendpoint" httpport="9080" httpsport="9443" /> </server> This is where you configure your host and ports You update XML here for various Liberty and z/os Connect function such as using SAF, or configuring z/os Connect services. 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. 13 Platform exploitation 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 WP Liberty Profile Quick Start Guide, or the WP z/os Connect Quick Start Guide. Unit 2-13

14 Taking Advantage of the z/os Platform Liberty 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: JDBC Type 2 and RRS WLM Classification SAF Security MODIFY WOLA Provides 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. Provides both Service Class and Report Class classification of requests that come into the Liberty Profile server. Provides 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. Provides use of the z/os MODIFY command against started task to process DUMP operations. Provides cross-memory communications using the Optimized Local Adapters function. These two will be used in this workshop 14 Angel process 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 WP Quick Start Guide at ibm.com/support/techdocs. Unit 2-14

15 The 'Angel' Process There'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: Okay to access authorized? Angel Process Liberty Profile Yes, you are authorized server.xml 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 required Only required when server needs access to authorized services. WOLA is an authorized service that requires the Angel. One per LPAR When required, only one Angel is needed, regardless of the number of Liberty Profile servers on the LPAR. Designed to start and leave up forever The design of the Angel is such that it should not need to be stopped and restarted. There are exceptions move to WOLA and required stop and restart with new level of the code. Access through SAF SERVER profiles This 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. 15 Liberty Quick Start 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-15

16 Collectives and Administration The administrative model that is emerging for Liberty Profile (all platforms) involves organizing servers into a 'collective' and administering through a GUI: Web Admin Center Jython Script Collective Controller Java Client Collective Member 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 Collective Member Cluster Collective Member User can interact with controller using one of several different methods This management model is getting more functionally rich over time Liberty Quick Start 16 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 plugincfg.xml file that can be used with the WAS plugin for load balancing across a cluster and affinity routing. Unit 2-16

17 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 WP Techdoc: Step-by-step instructions for setting up and exercising key functions of Liberty Profile z/os 17 WOLA Finally, as mentioned earlier, if you're interested in going deeper into setting up and using Liberty Profile z/os, the WP 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-17

18 Optimized Local Adapters Understanding WOLA and how it works with Liberty Profile z/os 18 Unit 2-18

19 The History of WOLA The 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: Application Server Servlet Application Server EJB API Example: Servlet to EJB, Same LPAR From 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 Address Space Program WOLA is LOCALCOMM Externalized The 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. WOLA is Bi-Directional Which 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 WOLA and traditional WAS z/os was introduced starting with , and has undergone many enhancements since then. With Liberty the WOLA support came into being with V8.5.5 Fixpack 2. Registration 19 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 time frame. It became available with Liberty in the 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-19

20 Key Concept #1 - Registration Before any WOLA communications can occur, the outside address space must create a registration into the Liberty Profile server: server.xml Liberty Profile CICS, Batch Outside Address Space Registration is Logical Connection The 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 Initiates The 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 Name For 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" /> Max 8 characters each. Values are really arbitrary. Must be unique on LPAR. 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. 20 Multiple registrations 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-20

21 Multiple Registrations Possible An instance of Liberty Profile can support many registrations: Liberty Profile CICS, Batch Outside Address Space CICS, Batch Outside Address Space CICS, Batch Outside Address 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. Outbound and Inbound 21 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-21

22 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 : Outbound Liberty Profile Java Inbound Liberty Profile Java Our Focus Program CICS, Batch Outside Address Space Program CICS, Batch Outside Address Space 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 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. Link Server Task 22 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-22

23 Outbound and CICS Link Server Task When 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: Liberty Profile CICS Region Java BBO$ BBO# Program WOLA JCA Resource Adapter 1 2 WOLA Task Related User Exit 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. BBOC START_SRVR 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-23

24 CICS Link Server Task and Registration When using CICS, you can register into the Liberty Profile server as part of the starting the Link Server Task in the CICS region: CICS Terminal Session Supplied Utility Tran Action Registration Name BBOC START_SRVR RGN=CICSREG DGN=GROUP NDN=NAME2 SVN=NAME3 SVC=* MNC=1 MXC=10 TXN=N Service restrictions Connection Pool Values The three-part name specified in server.xml Transaction Propagation (always N with Liberty WOLA) SEC=N REU=Y 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. 24 Long-running COBOL 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-24

25 WOLA and Long-Running COBOL* This involves using some of the Native APIs** supplied with WOLA: 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 BBOA1SRV This 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 BBOA1REG BBOA1SRV BBOA1URG Perform business logic here, or link off to other COBOL* assets Other COBOL Assets * Or C/C++, PL/I or High Level Assembler ** See WP WOLA API Primer for more on each of the 13 APIs The 13 APIs 25 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-25

26 The 13 WOLA APIs The 13 APIs organize into the following way: BBOA1REG BBOA1URG BBOA1CNG BBOA1CNR BBOA1SRQ BBOA1SRP BBOA1SRX BBOA1RCA BBOA1RCS BBOA1RCL BBOA1GET BBOA1INV BBOA1SRV Inbound Basic BBOA1INV Invoke EJB Inbound Advanced BBOA1CNG Get connection BBOA1SRQ Send request BBOA1REG Registers Common BBOA1URG Unregisters Outbound Basic BBOA1SRV Host service BBOA1SRP Send response BBOA1CNR Release connection Outbound Advanced Simplest model for listener to receive calls from z/os Connect BBOA1GET Get response BBOA1CNR Release connection BBOA1RCL Response length BBOA1RCA Receive any BBOA1GET Get response BBOA1CNR Release connection BBOA1RCS Receive specific BBOA1CNG Get connection BBOA1SRX Send exception InfoCenter cdat_olaapis Differences 26 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 WP Techdoc at ibm.com/support/techdocs has a Primer document that provides exercises to walk you through usage of all 13 APIs. Unit 2-26

27 Full-Profile WAS WOLA vs. Liberty Profile WOLA The two are similar at the programming interface, but different in some other respects: 27 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 WOLA Applications 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 WAS Depending 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 supported Relied on function of traditional WAS not present in Liberty Liberty WOLA and IMS not supported No WOLA MODIFY commands or SMF for WOLA WOLA Techdocs 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-27

28 WOLA-Related Techdocs If you're interested in diving deeper into WOLA, see the WP Techdoc: Step-by-step instructions for setting up and exercising WOLA with Liberty Profile z/os Step-by-step instructions for using the native APIs 28 We've taken a fairly brief and high-level tour of WOLA. If you're interested in digging deeper, the WP Techdoc has more information, including the two documents shown in the chart. End End of of Unit Unit Unit 2-28