WebSphere z/os Optimized Local Adapters (WOLA) (Or OLA same thing)

Transcription

1 SHARE Summer 2009 Denver, CO August 23-28, 2009 Session 1144 WebSphere z/os Optimized Local Adapters () (Or OLA same thing) Don Bagwell IBM Washington Systems Center 1

2 Four Big Questions We aim to address four big questions in this presentation: -- What is it? We explain the basic structure of the new function Why Should I Care? We explain the functional and performance benefits of the new function How Do I Enable It? We explain what s involved with enabling WAS and external address spaces to use the new function How Do I Use It? We explain the how the new function is used and what s involved. 2 IBM Americas Advanced Technical Support This presentation is structured around four questions we believe are on your mind. We aim to answer those questions by the end of the presentation. 2

3 Overview What is it? 3 IBM Americas Advanced Technical Support 3

4 Starting Point -- Reusing WAS EJB Assets More and more people are seeking to use WAS z/os EJB assets from outside the WAS environment: Batch Programs WebSphere z/os EJB Assets CICS As time goes by, more and more business value is represented by EJB assets Hence desire to leverage Most solutions are designed to go outbound from WAS, not inbound There are other solutions to come inbound to WAS, but none have the ability to reach throughput rates seen with was born to provide highly scalable transactional inbound solution But developers did not stop with inbound they made it bi-directional to complete the picture Before we get to what is let s see what it s based on Local Comm 4 IBM Americas Advanced Technical Support Generally speaking, when people think of WAS they think of the applications inside of WAS being users of data and services outside of WAS. But that s changing. More and more we find that people have a desire to leverage EJB assets inside of WAS as part of a broader service architecture. It makes sense -- WAS is a powerful Java EE runtime environment; WAS provides a wide range of key services such as security, transaction and container services. EJBs written to leverage the power of the WAS platform can in turn be leveraged by things outside of WAS. The issue is access the EJBs inside of WAS. There are solutions. Please don t misunderstand. And they are often very good technologies. was created to address the specific need to access WAS z/os EJBs in a highly efficient and high throughput manner. So inbound to WAS z/os the original intent. But the developers did not wish to create a partial solution, so they made bi-directional both inbound to WAS z/os and outbound from WAS z/os. is not a brand new technology. It s actually an extension of an existing WAS z/os communication mechanism called Local Comm. 4

5 Let s Set the Stage -- WAS z/os Local Comm Local Comm is a cross-memory communication structure used within WAS when servers want to talk to others in the same cell on the same LPAR: LPAR Shared Space Data Buffers Above the bar owned by Daemon Daemon CR Daemon Shared Space DMGR CR SR AppServer Not actually in the Daemon address space but it s owned by the Daemon so we represent it like this Data Buffers Server Storage AppServer CR SR Cross memory Local Comm CR SR AppServer Data Buffers Server Storage AppServer CR SR WAS uses this for internal communications IIOP between servlet and EJB in different servers* for example. No TCP, no SSL very efficient. CR SR We ll use this rough schematic to illustrate this * Servlet to EJB inside the same server is done entirely locally. No communications at all, not even Local Comm. 5 IBM Americas Advanced Technical Support What is? Local Comm is a feature of WAS z/os whereby communications between servers in the same cell on the same LPAR (that s key, as you ll soon see) are optimized by avoiding the TCP stack and the network altogether. After all, why bother incurring the overhead of that when the source and target are in the same operating system instance? Local Comm is based on a memory-to-memory transfer. Data buffers are transferred to a portion of memory above the bar (above the 2GB boundary), then transferred to the target server. That s a direct memory-to-memory transfer with no serialization, no invocation of the TCP code path, no need to encrypt. It s very, very efficient. The key to this is a pool of above-the-bar memory that s owned by the Daemon server instance for the cell on that LPAR. The above-the-bar memory is not strictly speaking in the Daemon address space, it s simply owned by the Daemon. In the picture above, the right-half of the chart shows a representation of this. We re showing a block of memory in the Daemon, and what that s meant to represent is the pool of above-the-bar memory owned by the Daemon for that cell on that LPAR. When one server wishes to communicate with another in the cell, the data buffers are transferred cross-memory. That is Local Comm. Going node-to-node can use Local Comm provided the two nodes are in the same cell and on the same z/os operating system instance. Cross-LPAR is another thing altogether. There TCP does get involved. But depending on how the Sysplex is configured, that TCP communication can be optimized. So it s still very efficient, but it s not Local Comm when going LPAR-to-LPAR within a cell on a Parallel Sysplex. Now we re ready to introduce. 5

6 So What Is? is a new cross-memory communication structure for WAS V7. It s an extension of a WAS Local Comm used inside of WAS: LPAR CICS Assembler/Cobol/PLI/C or C++ Daemon Shared Space DMGR CR SR z/os Batch Assembler/Cobol/PLI/C or C++ AppServer UNIX Systems Services Assembler/Cobol/PLI/C or C++ Cross memory Local Comm CR SR Airline Control System Assembler/Cobol/PLI/C or C++ AppServer CR SR This is bi-directional This extension is implemented with a new set of modules that provide an API for external address to access servers using this Daemon shared space mechanism High Level Picture 6 IBM Americas Advanced Technical Support The designers of looked at the Local Comm structure already in existence and thought, Why don t we just extend Local Comm so external address spaces can participate in this? The basic structure of becomes evident -- it is a way in which address spaces outside of the WAS cell can hook in ( register is the term we ll use later) to the Daemon s Local Comm pool of memory above the bar. That allows them to transfer data buffers into and out of the WAS cell via the Local Comm facility. The picture above illustrates the four types of external address spaces that at the present time can partcipate in. The picture also illustrates the programming languages that are supported by the APIs. Note: What about Java batch? Java batch can participate in, but it would involve writing a piece of stub code in C/C++. The stub code is what would register and link to the functionality; the Java code would use JNI to invoke the stub. Remember this is bi-directional. Into WAS; out from WAS. 6

7 Very High Level Picture of This is just a schematic, but it helps position some key concepts: The Daemon owns the shared above-thebar storage where registrations live and that data buffers flow through The Daemon owns the System LX which anchors the non-space-switching PC routines used to access services Daemon Shared Space WebSphere z/os Cell on an LPAR Again not actually in the Daemon address space but it s owned by the Daemon so we represent it like this to emphasize the key role the Daemon plays in this. STEPLIB DD DSN=hlq..LOADLIB External Address Space Assembler/Cobol/PLI/C or C++ External APIs Local Comm JCA AppServer EJBs External address spaces use the supplied modules to register to the Daemon and access Local Comm A supplied JCA adapter provides the Java outbound interface to completes the connection For inbound communications, EJB does not require JCA Essentially this is a set of APIs that externalizes the Local Comm function that is already in use within a WebSphere cell on an LPAR Simple example scenario 7 IBM Americas Advanced Technical Support Here s a very high-level schematic picture of this. We ve already introduced the notion of Local Comm and the above-the-bar shared space owned by the Daemon. We ve pointed out that while the shared space is not physically in the Daemon s address space, it is owned by the Daemon. So we represent it as in the Daemon just for purposes of simplicity. supplies a set of modules that provide the APIs and facilities to connect to the extension of the Local Comm architecture. An external address space (batch program, CICS region, USS process) needs to have access to those modules (example, STEPLIB for batch) and it s able to make the connection. On the WAS side there s a new Java Connector Architecture (JCA) resource adapter supplied that provides the way EJBs access. That JCA adapter installs like any other JCA adapter. We ll discuss the programming implications of this (at a high level) later in this presentation. The yellow box summarizes the key point -- is a set of APIs that externalizes the Local Comm cross-memory mechanism so programs outside of WAS can participate. 7

8 A Simple Use-Case Scenario Here s a picture just to help us get our minds around this thing: LPAR 1 Flat record file Batch Program 2 3 Modules Daemon Shared Space Local Comm Cell 4 AppServer CR SR RRS CICS IMS 1. Flat record file serves as input to batch program 2. WAS modules STEPLIBed to from batch JCL 3. Batch program uses APIs to access WAS and invoke EJB 4. EJB initiates transaction and updates CICS, IMS with two-phase commit using standard WAS data connector archictures This illustrates a relatively simple -- but likely common -- usage: batch file using an existing transactional EJB to update data. Five perspectives 8 IBM Americas Advanced Technical Support Let s take a look at a very simple use case. Doing this helps us picture how this is used. The essential point here is that an existing EJB represents a business resource that s already taking advantage of the WAS z/os platform. Accessing that EJB from outside of WAS can be done with other technologies. But using provides a very efficient, very high-speed transfer mechanism. 8

9 Interface -- Perspective from Five Angles This conceptual picture offers insight into the interface requirements: EJBs that initiate a call to do so through a supplied JCA adapter. Several -specific methods used to invoke services over A Batch program that wishes to initiate an outbound connection must write to the APIs Batch Environment WebSphere Environment Enterprise Java Bean (Or Servlet) JCA Adapter Enterprise Java Bean Execute() ExecuteHome() EJBs that will be the target of inbound calls need to implement the -supplied Execute() and ExecuteHome() classes. Calls into CICS come across -supplied BBO$/BBO# task and transaction. Target CICS program unchanged if able to be invoked over COMMAREA or Channel/Container CICS Environment Batch Program Modules/APIs BBO$/BBO# Modules/APIs CICS Program CICS Program A CICS program that wishes to initiate an outbound connection must write to the APIs WAS z/os supplies the artifacts. We ll see how to enable the environment later. You make modules/classes available: STEPLIB, DFHRPL, ola.rar and ola_apis.jar Batch CICS WAS Development Tool Reducing impact 9 IBM Americas Advanced Technical Support This is a busy chart, so let s slow down and make sure we catch the important messages. One of the initial misunderstandings we have to combat is that is transparent to all the applications. is no more transparent than JCA or JDBC; both of those require at least some application awareness to complete the access. But because it s not transparent does not mean it s really complicated. The five angles (or perspectives) on the chart above represent the five ways of looking at, depending on who s look at it. For example, from an external batch program, (and the whole WAS environment behind it) simply looks like a set of programming APIs. There are 13 such APIs, and we ll touch upon them a bit later. The point here is that to a C/C++ or COBOL program using, the APIs supplied by are business-as-usual API. Different syntax from other APIs, but conceptually no different from other APIs. From the perspective of CICS, can in fact be transparent. Coming from WAS going into CICS the functionality -- once installed into CICS (easy process; we ll cover that as well) is capable of taking the call from WAS, formatting into a COMMAREA or Container and invoking the named CICS program. Coming the other way -- CICS program initiating the call to WAS -- involves some customer code to invoke the APIs. But even here, that doesn t mean every CICS program has to code to the APIs. You can code a -access program and other CICS programs can simply use that as an invocable service within CICS. Finally, up in the WAS space, we have EJBs either looking to invoke external resources or to serve as the target for inbound calls. supplies a JCA adapter for the outbound case. It implements the standard JCA interfaces, with key methods customized to support. For inbound the EJB is required to implement the Execute() and ExecuteHome() methods provided with. 9

10 Reducing Coding Impact to Environment It s possible to architect to be a service to EJBs and CICS programs so the amount of -specific programming is reduced: WebSphere Environment Daemon Servlets Enterprise Java Beans Enterprise Java Beans Aware EJB 1 4 JCA Adapter Execute() ExecuteHome() Shared Space 2 BBO$/BBO# Aware CICS Program 3 COMMAREA Channels/Containers CICS Programs CICS Programs CICS Environment 1. Service EJB written to use JCA interface 2. WAS CICS flows invoke BBO$/BBO# task and transaction and then invoke named CICS program 3. CICS WAS flows require custom code in CICS written to the APIs to initiate the call. Other CICS programs can EXEC the Service Program 4. Service EJB written to implement Execute() and ExecuteHome() methods Not transparent, but effort reduced. Benefits gained. 10 IBM Americas Advanced Technical Support We alluded to this in the previous chart just because there are some interface requirements for, it does not follow that every single program that wishes to use must implement those -specific requirements. It is possible to code up service EJBs and service programs for CICS. Then other EJBs can simply use standard RMI; CICS programs can use standard EXEC routines inside of CICS. 10

11 Performance Why should I care? The performance charts contained here are based on a specific IBM measured test. Performance is based on a number of factors and your results may vary. The results shown here do not suggest a guarantee of performance, implied or expressed. 11 IBM Americas Advanced Technical Support 11

12 To Start Things Off It s important we cover two important concepts about performance numbers 1. Relative comparisons 2. Normalized findings Relative comparisons 12 IBM Americas Advanced Technical Support We re going to show you some performance charts in just a bit. Before we do, we have to make sure two key concepts are understood since the performance charts are based on these concepts. 12

13 Relative Benchmark Study Comparisons Used when the focus is not on the raw values, but on how one thing compares to another. For example, consider these two hypothetical findings: Throughput Hypothetical just to make a point 100 A 2X 200 B 300 A 2X 600 B The absolute numbers are quite different But relatively they re saying the same thing: B is twice A. Using relative comparisons is helpful when the objective is to compare things without so much focus on details like machine models, resources, etc. Small Message Large Message Normalizing data 13 IBM Americas Advanced Technical Support The first concept is relative comparisons. Here the focus is not on the absolute numbers, but one the relative proportion of one variable to another. For example, the picture above is trying to show two hypothetical tests one with small message sizes and one with large message sizes. Two variables are in play -- A representing one communication method; B a different one. The absolute numbers are based on a lot of different factors. For instance, the absolute throughput possible with a small server is less than that of a very large and powerful one. So, rather than focus on the absolutes -- which implies paying close attention to the specifics of the server itself -- our focus turns to the relative comparison. In this picture we see that communication method B is able to achieve twice A for both small messages and large messages. The relative message here is that the relative advantage of B over A is consistent. 13

14 Normalized Benchmark Study Findings Normalizing is the process of taking multiple sets of relative findings and making them easier to compare to one another: Hypothetical just to make a point Look at this picture. What conclusion can you draw from it? Nothing immediately jumps out. Make the blue values 1 and adjust the green values proportionally A meaningful trend emerges The data has been normalized with the blue values serving as the baseline Normalizing data is useful to further clarify important relationships without getting too distracted by details 14 IBM Americas Advanced Technical Support The next key concept is normalizing the data. Normalizing simply means taking each one of the variable results and adjusting it to a constant value, then adjusting the other variable proportionally. The key is proportionally. The degree of adjustment imposed on the control variable for each data point is imposed on the comparison variable as well. The chart above shows a hypothetical example. Focus on the blue bars on the left. Look at the numbers for each blue bar. Now imagine dividing each blue bar number by itself to form 1. That becomes the blue bars on the chart on the right. Then divide each green bar by the blue bar number. That s where proportionally comes in the degree of adjustment for each green bar is the same as done to the blue bar. The blue resulted in 1 each time, the green bar becomes whatever number is the proportionally appropriate result. The data is normalized with the blue bar being the control constant and the green bar being the comparison value. Why do this? Because it often helps to make sense of things. The picture on the left has no clear message immediately evident. But if you normalize to the blue data you see a clear message reveal itself. For the five tests -- 1 through 5 -- the green bar result had a steady rate of increase. The following performance charts make use of relative comparisons and normalized results. Keep that in mind as we review them. 14

15 A Comparison of CICS Invoking WAS Web Services A recent benchmark compared the case of web services into WAS against invoking the EJB using : LPAR CICS Transaction Server SOAP/HTTP WebSphere Application Server Program SOAP/HTTP EJB Some notes: We are not suggesting can or should replace web services in all cases. But in some cases it might well make sense In this test CICS and WAS on same LPAR, so TCP is optimized between the two The test was a relatively simple echo application 15 IBM Americas Advanced Technical Support The first comparison test is an inbound to WAS from CICS using web services. Please read the notes this test was done to establish a framework for performance comparisons. It was not intended to represent real life or make any suggestions about the merits of web services. 15

16 Relative Throughput for 100 Byte Message The following chart serves as our starting point a comparison of relative throughput based on a 100 byte message exchange: Relative Throughput Based on the specific CPU and memory of this benchmark system Relative throughput relative to the normalized web services baseline Given the machine resources used for the test saw 6X throughput Web Services Normalized so it represents the baseline 100 Why? No network, no XML creation, no XML parsing, etc. Small Messages (100 bytes) Performance measurements are dependent on many factors. Results vary. No guarantee of performance is implied by this chart 16 IBM Americas Advanced Technical Support What about larger messages? Here s the first test inbound to WAS from CICS using web services with a message size of 100 bytes. The application in WAS is a simple echo application. The web services run was able to achieve some level of throughput based on the specifics of the server. Whatever the absolute number is doesn t really matter because our test is focused on relative comparisons. So the web services data was normalized to a value of 100 and the throughput number adjusted proportionally. We see the result. Using the exact same server platform, was able to achieve six times the throughput. How is that possible? Go back to our earlier pictures about Local Comm and crossmemory transfer. With there s no network, no TCP stack invocation, no XML parsing, etc. Does this mean replaces web services? Absolutely not web services plays an important role in a service oriented architecture. But does this mean that there may be cases where makes sense given the application requirements? Yes. That is the message we are trying to send. 16

17 Larger Messages We see outperforming web services across a range of message sizes: Relative throughput relative to the normalized web services baseline Web Services Normalized so it represents the baseline 100 Small Messages (100 bytes) Medium Messages (4K bytes) Big Messages (32K bytes) EXCI 17 IBM Americas Advanced Technical Support The natural next question is, Okay, that was for 100 bytes. What about bigger message sizes? The chart above shows the results. Again remember our discussion about normalizing. The web services results for each message size has been normalized to a value of 100. The results adjusted proportionally. We see outperforming web services across the range of message sizes. The degree of difference varies a little, but is generally in the 6X range across all message sizes. 17

18 WAS CICS Transaction Gateway - Local EXCI CTG EXCI is itself a cross-memory technology yet we still see a delta in favor of OLA. Not as much as with web services, but it s still there: Again relative throughput, normalized In this case, CTG EXCI is the constant reference; OLA is adjusted proportionally CTG EXCI Normalized so it represents the baseline 100 Relative throughput relative to the normalized CTG EXCI baseline 100 bytes 4K bytes 32K bytes We see improving its advantage as the message size gets bigger and reaches the limit of EXCI, with is 32K We have some careful positioning information coming! IPIC 18 IBM Americas Advanced Technical Support Let s turn the direction around and make it WAS invoking a CICS program. Next, let s compare what many see as a more apples to apples test: compared with CICS Transaction Gateway using the local EXCI capabilities of CTG. EXCI is itself a kind of crossmemory local connector. Three message sizes; CTG EXCI being the control variable with normalized to the CTG constant. We see that for smaller message sizes the difference between CTG and is not dramatic. Some advantage to, but not as striking as we saw with web services. As we go to larger message sizes we see the relative differences expanding. At 32K, which is the limit of EXCI, we see a fair amount of difference. Note: it is really important that you not form a conclusion yet. There are some important functional differences between and CTG EXCI that we will explore in a few charts. The 32K barrier is broken with channels and containers, which is implemented with the IPIC support of CICS TS 3.2 and CTG 7.0. Let s look at that next. 18

19 WAS CICS Using IPIC of CICS TS3.2 IPIC supports channels and containers and allows us to get back the 32K limit of EXCI. How does compare to that? Relative throughput, normalized CTG IPIC is the constant reference; OLA is adjusted proportionally IPIC Normalized so it represents the baseline 100 EXCI 32K Boundary Relative throughput relative to the normalized IPIC baseline 100 bytes 4K bytes 32K bytes 128K bytes is a very good large message local transfer mechanism We have some careful positioning information coming! Positioning 19 IBM Americas Advanced Technical Support IPIC is a TCP-based exchange mechanism that allows for message sizes creater than 32K. Four message sizes; CTG IPIC being the control variable with normalized to the CTG constant. We see the results. 19

20 Let s Be Very, Very Careful Before we go any further it s essential we make sure the proper conclusion are drawn from those charts: is magic and fits every conceivable requirement? Yes! No! replaces CICS Transaction Gateway? is like other technology solutions it has its place but it is not a universal one-size-fits-all? We re going to look at a functional comparison of and CTG next Relative advantages 20 IBM Americas Advanced Technical Support Let s get our feet planted firmly on the ground here... take a look at what s clearly implied by the chart above. It s very important be viewed as another tool in our arsenal, but not the universal one-size-fits all solution many seek. With this in place, let s compare and CTG on a functional level 20

21 Relative Advantages Of and CICS Transaction Gateway Bi-directional WAS CICS and CICS WAS is bi-directional, CTG is only WAS CICS Relative Advantage Favors CTG Part of the WebSphere Application Server z/os Product shipped with , CTG is a separate FMID Able to be used for local or remote access to CICS is a local technology only, CTG supports both local EXCI as well as TCP-based remote access Two-Phase Commit WAS CICS is limited at present ot synconreturn only. In future maintenance that support will be upgraded to 1-phase. 2-phase limited by design of CICS TRUE, which is what s support in CICS uses Two-Phase Commit CICS WAS CTG can not be used for CICS WAS. able to propagate TX CICS WAS with full 2-phase commit support using RRS for syncpoint coordination. Flexible use of CICS channels and containers restricts container usage to one named channel only: IBM-WAS-ADAPTER. CTG supports multiple channels. uses indexedrecord while CTG uses mappedrecords. That means CTG supports the passing of multiple named containers on a channel while can not. is a complementary technology with CTG. Both will have their place within an enterprise architecture. Positioning framework 21 IBM Americas Advanced Technical Support The intent of this chart is to position and CTG and to show that each has its relative advantages. Neither technology obsoletes the other. 21

22 Discussion Starter -- Positioning Chart Here s a suggested framework -- not formula -- for positioning Strong Review Architectural Criteria may be very good fit Inbound to WAS z/os from local source with High throughput requirements Large message size requirements WAS z/os Inbound or outbound where Existing solutions seen as limiting Subset of overall archicture has specific throughput needs Less Strong Outbound from WAS z/os where Target is on another LPAR or off platform Existing solutions are seen as working well 22 IBM Americas Advanced Technical Support This chart is a very broad positioning framework. As always, It depends is the answer to where fits. 22

23 Installing and Enabling How do I enable it? 23 IBM Americas Advanced Technical Support 23

24 Comes with Maintenance is a function introduced with Applying that maintenance provides the function to the SMP/E product file system Daemon CR CR DMGR SR 4 SMP/E Product File System Node Agent CR AppServer CR SR??? 3 1 Standard SMP/E work here nothing special Node AppServer CR SR 2 Several questions 1. What does look like in the product file system? Knowing this is helpful because some instructions drive you into the product file system to retrieve files 2. What s needed to enable a node to use? Hint: it s not automatic. You need to intentionally enable nodes. 3. What about intermediate symlinks? Hint: this is automatic it piggybacks on a node s intermediate symlinks 4. Does the DMGR node need to be enabled? Answer: only if you intend to invoke the deploy (build) option during installation of a -using application File system 24 IBM Americas Advanced Technical Support comes with the WAS z/os maintenance. When that maintenance is applied the code is copied into the SMP/E target libraries. Here s the key --applyptf will not enable the function in a node. We re going to see how that s done over the next few charts. It s not difficult, but it needs to be done. 24

25 in the SMP/E File System Busy chart but a few key points that need to be made: Everything is under /mso/ola The modules are found here The JCA resource adapter is found here The samples are found here Using involves pointing to or extracting files from this location Essentials 25 IBM Americas Advanced Technical Support This is a summary picture of what looks like in the SMP/E product file system. Knowing that this is where the code is located is important because the samples are located there as well as key files used to support the Eclipse development tooling. 25

26 The Essentials of Enabling for Use Four things: 4 WAS_DAEMON_ONLY_enable_adapter = 1 olainstall.sh Daemon CR DMGR CR SR 1. Symlinks to SMP/E This is what makes the modules available to the node. Node Agent CR Node 3 JCA CF AppServer CR SR AppServer CR SR 1 2. Modules copied out to PDS So external address spaces (batch, CICS) can access modules and APIs olarar.py or do manually 3. JCA adapter installed with CF This is what makes the modules available to the node. 2 PDS BBOACALL BBOACHAB BBOACLNK BBOACNTL BBOACPLT BBOA1URG 4. WAS environment variable Simple switch to enable function in Daemon olainstall.sh 26 IBM Americas Advanced Technical Support For to be used in a node four essential things need to be in place. Two are supplied by running the olaintall.sh shell script, two are done either manually or with the olarar.py WSADMIN script. The olainstall.sh script is necessary it s what creates the symlinks from the node s configuration to the modules in the SMP/E product file system. (And it build those symlinks based on the node s existing symlink information, which means that if the node has intermediate symlinks then will use the same intermediate symlink.) The other think the olainstall.sh shell script does is copy the module libraries out to a pre-allocated PDS so other programs can access the modules using STEPLIB or DFSRPL. The olarar.py WSADMIN script is somewhat optional in that the tasks it does are easily done manually. The chart shows the two things the script does. 26

27 Enabling a Node --olainstall.sh Shell Script Located in the node s /bin directory*, this shell script has a few different functions, depending on the parameters you pass it: olainstall.sh function target_olaload_dataset_name Pre-allocated load module PDS-E Approximately 40 tracks Notes: INIT Initializes the HFS and copies OLA modules to target data set (Initialize = creates symblinks and copies some files) UNINIT Uninitializes the HFS (Uninitialize = removes symblinks and copies of files) OLAMODS Copies OLA modules to target data set only (From the SMP/E product HFS out to your pre-allocated load module PDS) Located in the node s /bin directory Make sure the ID under which you run this has write access to node s configuration WebSphere Admin ID is a safe bet to work Run this from every node in which you wish to use the OLA functionality DMGR enablement only if you intend to use Deploy EJB option during application installation Don t need to worry about intermediate symlinks it ll programmatically determine if they re in use and simply piggyback on the node s intermediate symlinks if present * applyptf.sh will put that file in the /bin directory of each node after is applied 27 IBM Americas Advanced Technical Support olarar.jy This chart shows the syntax of the olainstall.sh shell script. 27

28 The olarar.py WSADMIN Jython Script This WSADMIN script does a few simple things in an automated way: Creates variable WAS_DAEMON_ONLY_enable_adapter = true at the cell scope Installs the ola.rar J2C resource adapter archive into the specified node That RAR file is located in the SMP/E install root for WAS /mso/ola/installableapps/ Creates a J2C connection factory under adapter with JNDI of esi/ola Notes: Invoke WSADMIN client from the /bin directory of your node configuration file system So the shell script can operate against that node s file system easily. su to ID that has write permission in the file system. The WSADMIN script itself is located in the SMP/E install root, under /mso/ola/bin It is not copied into the configuration root by olainstall.sh. You can copy it there manually if you d like. Takes two parameters: Cell long name and node long name Standard WSADMIN process if you re familiar with that, then this should be quite easy But if you re not familiar with WSADMIN, or you d like to experience by hand what the script does automatically, then simply do those things manually through the Admin Console very easy Restart servers in the node after completion 28 IBM Americas Advanced Technical Support And this chart offers the process of running the olarar.py WSADMIN script if you choose to do that. (If you choose to avoid running the olarar.py script, you still must do these things manually. Having those thing in place is necessary what s optional is doing it with the WSADMIN script.) 28

29 Function Usage How do I use it? Batch and CICS 29 IBM Americas Advanced Technical Support 29

30 Using With External Batch Programs In one sense this is the easiest. In another sense it s a bit more involved because it implies writing to the APIs: JCL 2 STEPLIB DD Batch Program Loadlib DMGR CR SR Daemon 4 CR BBOA1REG : BBOA1INV : BBOA1URG 3 1 Modules Node Agent AppServer CR Node CR SR 5 AppServer CR SR 1. modules copied out of the WAS SMP/E file system Very simple process.. we ll see this in the last unit of this presentation 2. Batch JCL STEPLIBs to module library So access to modules can be loaded 3. Program uses APIs A handful of APIs is what provides the interaction function 4. External batch registers into Daemon Registration into the Daemon is a key element of this that we ll explore more 5. Program invokes EJB The BBOA1INV API takes as a parameter the JNDI name for the home interface of the target EJB. Registration 30 IBM Americas Advanced Technical Support We re going to start with the batch example because it is the most approachable from a conceptual viewpoint. It also helps us position some key concepts about without too much complexity. This picture is representing a very high level view of things: For the batch program to make the connection it needs the modules. Those are part of the maintenance stream and are packaged into the SMP/E product file structure. To get them out involves copying them out. There is a -supplied shell script to do that, which we ll see later. The point here is that we need them in a standard module library so batch programs can STEPLIB to them. The batch program, written in one of the languages (C/C++, COBOL, PLI or Assembler) makes use of the APIs. There are 13 APIs that provide the function. We ll take a look at some of those as well. The key here is that supplies a set of APIs that provide the interfaces to the functions. The functions are packaged in the library modules, which the batch program STEPLIBs to. The batch program s first task is to register to the Daemon. This is what establishes the connection between the external address space (the batch program) and the server. Registration is specific to the Cell:Node:Server. Once registered, the batch program is then able to use the other APIs to invoke the EJB and make use of it. 30

31 Two Key Concepts -- Registration and RegisterName Registration provides the access to Local Comm; RegisterName provides a named pool of connections for each registered external address space Daemon Cell: Node: Server: MYCELL MYNODEA MYSR01A Batch 001 BBOA1REG(MYCELL,MYNODEA,MYSR01A,BATCHREG001) BATCHREG001 BATCHREG999 Batch 999 BBOA1REG(MYCELL,MYNODEA,MYSR01A,BATCHREG999) Key Points: MYSR01A Registration is specific to a server in the cell on that LPAR CR SR Both batch programs are seeking to use EJBs in the same server -- server MYSR01A Both register with Daemon and name server MYSR01A But they use different RegisterName values to keep their pool of Local Comm connections separate As picture shows, multiple registrations into a Daemon are possible -- to the same server or to different servers Once registration is done, then communications conducted across the pool of connections associated with the RegisterName Before a program can use, it must register into Daemon Multiple servers 31 IBM Americas Advanced Technical Support We need to establish two very key concepts -- registration and the registration name used during that registration. Registration, as we noted on the previous page, is the act of establishing the connection between the external address space and the specified server. Registration is done using the BBOA1REG API of. Registration is specific to a server you have to know which server you re connecting to. One of the parameters on the BBOA1REG API is RegisterName. That provides a way to name the connection and its associated properties. This allows you to maintain separate connection pools. The picture shows the example of two batch programs looking to access the same server. Imagine that they have different registration requirements one has a need to propagate security, the other does not, for example. Or one only needs a small number of maximum connections and the other requires many more. In this example, both batch programs register in but use different names. The names are arbitrary, up to 12 characters. Before a batch program can use, it must register to the server it wants to communicate with. 31

32 Reinforce Point on Previous Chart Imagine the two batch programs were to use different servers. What then? Daemon Cell: MYCELL Node: MYNODEA Server: MYSR01A BATCHREG001 Batch 001 Batch 999 BBOA1REG(MYCELL,MYNODEA,MYSR01A,BATCHREG001) BBOA1REG(MYCELL,MYNODEA,MYSR02A,BATCHREG999) Cell: MYCELL Node: MYNODEA Server: MYSR02A BATCHREG999 MYSR01A CR SR MYSR02A CR SR Both register with the same Daemon They specify different servers They provide different RegisterNames Registration is a key first step in the usage of How exactly does a program register? With the BBOA1REG API Registration API 32 IBM Americas Advanced Technical Support This chart is meant to reinforce how registration is specific to the target server. Imagine the two batch programs again, but they re targeting different servers. Each registers as before, but they specify different servers. The registration connection pools are formed under each server with the registration names. 32

33 Example of API --BBOA1REG (from OLACC01 Batch Sample) BBOA1REG is one of thirteen APIs that come with. It s used by external address spaces to register into the WAS Daemon: &variables set higher in the OLACC01 sample program BBOA1REG ( &daemongroupname, &nodename, &servername, &registername, &minconn, &maxconn, &regflags, &rc, &rsn ); InfoCenter has very nice writeups of the APIs and the parameters InfoCenter search on: cdat_olaapis.html if (rc!= 0) { printf("register error! rc: %d rsn: %d\n",rc,rsn); return(-1); } Some error? Returns beautiful return and reason codes. Same InfoCenter page spells it all out. Wonderful granularity of error reporting. Like any new API it takes a bit of time to learn the operations and syntax. But it s relatively easy, and the samples provide some nice examples OLACC01 Sample 33 IBM Americas Advanced Technical Support The BBOA1REG API is what s used to register. The InfoCenter has some very good information on the syntax of that API. The chart above shows how BBOA1REG might be used the example was clipped out of the supplied OLACC01 sample. One of the very nice things about is that error codes are very nicely broken down by return and reason code, and the InfoCenter has a complete write-up of all the combinations. 33

34 The OLACC01 Sample The recommended first sample to use it s a very simple single invocation model batch program Cell: Node: Server: BBOA1REG BBOA1INV BBOA1URG Daemon MYCELL MYNODEA MYSR01A OLACC01 Establishes connection to the server Invokes the EJB in the server Tears down the connection unregisters OLACC01 MYSR01A CR SR //OLACC01 JOB (),'ME',REGION=0M, // MSGCLASS=H,NOTIFY=&SYSUID : //COMPILE.SYSIN DD DATA,DLM=@@ char registername[12] = "OLACC01 "; : GETARG(daemonGroupName, 1, 8, 0x00, "SY1"); GETARG(nodeName, 2, 8, ' ', "SY1"); GETARG(serverName, 3, 8, ' ', "BBOS001"); : Deploy OLASample01.ear into WAS server and start Modify the source code -- supply cell, node and server short Compile source code Modify sample JCL and submit You ll see: Invoking service "ejb/com/ibm/ola/olasample1_echohome" Invoke response length matches expected: 61 Invoke response data matches expected What does BBOA1INV look like? 34 IBM Americas Advanced Technical Support The OLACC01 sample is what we recommend you first use to validate your environment. It is very simple to use and requires little more than a few modifications and compiling the code. The sample s flow is represented above -- a registration, a single invocation of the target sample EJB in WAS, then unregister and quit. 34

35 Example of API --BBOA1INV (from OLACC01 Batch Sample) Once registered to Daemon, how does batch invoke EJB? With the BBOA1INV API and naming the EJB s home interface JNDI: BBOA1INV ( &registername, &requesttype, &requestservicename, &requestservicenamelen, &requestdataptr, &requestdatalen, &responsedataptr, &responselen, &waittime, &rc, &rsn, &rv ); The name of the registration connection to use to access the EJB. This is the pool of connections over to the WAS server address space The JNDI name of the home interface for the target EJB in WAS Earlier in OLACC01 sample this was set to: ejb/com/ibm/ola/olasample1_echohome Which is the default JNDI name on the OLASample01.ear file Point here is not to drill deep into programming specifics Point is to illustrate key concept -- register into Daemon and make connection to target WAS appserver, then invoke the target EJB using the registration pool and the EJB s JNDI home interface name Looping 35 IBM Americas Advanced Technical Support Let s look at the BBOA1INV API, which is the middle step in the OLACC01 flow. This invokes the target EJB. To use this API you have to specify which registration pool name you want to use (this is the name used with the BBOA1REG API), then you name the target service. When invoking an EJB in the server, you specify the JNDI name of the EJB s home interface. ships with a sample EAR file that requires nothing more than installing into the server. Once there, OLACC01 can invoke it. 35

36 Have Some Fun Modify the OLACC01 Sample It s very easy to change the OLACC01 sample to make it loop through multiple iterations: BBOA1REG Establish connection to the server int x; for (x = 1; x <= 10; x++) { } BBOA1INV Invokes the EJB in the server each time through loop Useful because it illustrates how a registration may be re-used many times before unregistration Useful because it will let you see just how fast this connection is. Set the iteration to some high number and time the execution. Well be a little careful with that number! BBOA1URG Unregister InfoCenter 36 IBM Americas Advanced Technical Support The samples are there for you to experiment with. One experiment is to build a loop into the OLACC01 sample so it registers, loops some specified number of times, then unregisters and quits. This helps illustrate that once the registration is done the connection pool is there for repeated reuse. Have it loop some significant number of times you ll be amazed at how fast it truly is. 36

37 Reminder: InfoCenter Has Very Good Doc on APIs Search on key phrase cdat_olaapis.html Each section has a very detailed parameter description and return code and reason code details InfoCenter documentation on is very good please rely on it Installing into CICS 37 IBM Americas Advanced Technical Support Again please do not overlook the InfoCenter. The stuff is excellent. 37

38 Installing into CICS is Straightforward is supplied as a set of programs and transactions that install into CICS. From a CICS perspective it s business as usual stuff. CICS Transaction Server CICS CSD CICS region start JCL //DFHRPL DD BBOACSD group CSDUPDAT sample JCL Modules Which includes several -related CICS programs and transactions Then install the BBOACSD group: DISPLAY GROUP(BBOACSD) ENTER COMMANDS NAME TYPE GROUP OLAMAP MAPSET BBOACSD BBOACALL PROGRAM BBOACSD BBOACHAB PROGRAM BBOACSD BBOACICS PROGRAM BBOACSD BBOACLNK PROGRAM BBOACSD : BBOACSRV PROGRAM BBOACSD BBOATRUE PROGRAM BBOACSD BBO$ TRANSACTION BBOACSD BBO# TRANSACTION BBOACSD BBOC TRANSACTION BBOACSD BBOQ TDQUEUE BBOACSD The CICS system programmer aspect of this is quite straight-forward TRUE 38 IBM Americas Advanced Technical Support Let s turn our attention to CICS. To enable CICS to support involves a few fairly straight forward CICS system programmer tasks, such as making the module library available to CICS via the DFHRPL DD statement, and installing the BBOACSD group into the CICS CSD. When you install the group, you make the programs, tasks and transactions available to CICS. The next chart explains the structure of the support that gets installed. That s how to install the support into CICS. But what exactly gets installed? That s next. 38

39 is Implemented as a TRUE Task Related User Exit, along with some supplied transactions and link server tasks: CR AppServer CR SR Daemon Reg 1 BBOC Terminal-based transaction (Control and operations transaction for in CICS) 3 BBO$ LINK server task 2 BBOATRUE Task Related User Exit 4 BBO# Invocation Task Name of this can be passed in as a parameter. Defaults to BBO# if not specified CICS Transaction Server COMMAREA or Container Existing CICS Program 1. BBOC is a 3270 terminal application that you can use to start the TRUE and SRVR To start the TRUE (#2): BBOC START_TRUE can be started automatically at CICS region start with PLT module To start the link server task (#3): BBOC START_SRVR parm parm 2. The TRUE is what provides the user exit into and out of the CICS region This must be started for any of this to work. BBOC START_TRUE will start it, or PLT module. 3. The link server task is what registers into the Daemon and establishes the connection Started with the BBOC START_SRVR parm parm command 4. Instance of BBO# invocation task started by the link server task for work WAS CICS Name of transaction can be passed in as a parameter; or allow it to default to BBO# OLAUTIL 39 IBM Americas Advanced Technical Support CICS has an structure called a Task Related User Exit, and that s what uses to implement its support in CICS. This is what provides the lower-level switching in and out of the CICS region. A 3270 control transaction called BBOC is supplied this allows you to manually start the TRUE. A LINK Server task -- BBO$ -- is what receives inbound requests and maps over to the requested program. The BBO$ link server task is what registers with the Daemon/Server and provides the pool of connections. That needs to be started for any inbound calls to CICS. BBO$ starts an instance of BBO#, which then invokes the named CICS program. 39

40 Invoking CICS Program WAS CICS Earlier we had pointed out that an EJB in WAS wishing to invoke a CICS program has to use the JCA adapter. The CICS program named there: ola_apis.jar AppServer CR SR Class Method Development Tool (Rational or equivalent) Aware EJB connectionspecimpl.setlinktasktranid( ABCD'); interactionspecimpl.setservicename("program1"); JCA Adapter: ola.rar BBO$ LINK server task ABCD Invocation Task COMMAREA or Container PROGRAM1 BBOATRUE Task Related User Exit Transaction Name set with setlinktaskid() Program named with setservicename() CICS Transaction Server This illustrates use of -supplied BBO$ and BBO# to invoke CICS program without any modification to the CICS program code. 40 IBM Americas Advanced Technical Support OLAUTIL sample This is a bit more detail what goes on when invoking a CICS program from WAS using the supplied BBO#/BBO$ tasks. We wish to show how from the EJB side the CICS program is named, and how it is possible to override the default transaction name of BBO# with a transaction name of your setting. The EJB uses the ola.rar JCA adapter to access functions in WAS. Two methods on two classes in that JCA adapter provide the key to understanding this. On the connectionspecimpl class the setlinktasktranid gets passed into CICS and will override the default BBO# tran ID that is used if no override value is supplied. In this example we see ABCD overrides BBO#. The CICS program name invoked is set using the interactionspecimpl class and the setservicename method. Here we re showing PROGRAM1 being the CICS program to invoke. 40

41 The OLAUTIL Sample A useful sample that illustrates the use of the CICS program using APIs directly to receive from WAS or send to WAS: OLAU WebSphere Application Server EJB JNDI BBOA1SRV and BBOA1INV below the JCA layer. EJB unaware. 1 2 PF05 BBOA1SRV (Service Name) PF04 BBOA1INV (EJB JNDI) CICS Transaction Server Program 1. WAS CICS: On the CICS side the PF05 function is used to host a service OLAUTIL program uses BBOA1SRV API to ready itself to receive from the WAS side. The API has a parameter for service name which the WAS side uses to specify the service to invoke over the registration connection. On the WAS side clicking the button results in BBOA1INV being used below the JCA layer. The EJB doesn t know anything about APIs, but JCA adapter does. 2. CICS WAS: PF04 function to invoke a service From the CICS side you can invoke an EJB with the BBOA1INV API. The service name is the JNDI home interface name. WAS manages the BBOA1SRV below the JCA layer. The CICS 3270 screen 41 IBM Americas Advanced Technical Support There s a sample supplied with called OLAUTIL which is a CICS program as well as a 3270 BMS map. This is an interesting sample because it illustrates the use of the APIs by a CICS program to directly interact with. On the previous chart we showed how a CICS program can be invoked from WAS without requiring a change to the CICS code. Here some coding to the APIs is seen. The OLAUTIL application, which is invoked on the CICS screen with OLAU, has two modes -- it can invoke a service over in WAS (PF04 function) or it can host a service and wait for the WAS side to invoke it (PF05 function). On the WAS side all that s needed is the OLASample01.ear file that comes with and we mentioned before. The easiest to start with is the PF04 Invoke A Service function. With the sample EAR installed in the WAS server and started, the OLAUTIL screen has fields to do the registration and to invoke the EJB. We ll see what that looks like on the next page of the presentation. You can also host a service with this sample. That s done by specifying information on the CICS panel and pressing PF05. You ll see an X-Clock on the 3270 screen as the program essentially waits to receive something from WAS. Then you can use a web page that comes with the WAS sample to invoke the service from WAS into CICS. We ll see that web page as well. 41