Rational Application Developer enhancements for WebSphere Optimized Local Adapters present new opportunities for end to end EIS integration

Complete integration from WebSphere Application Server for z/OS to CICS to SAP — and back

Enhancements to IBM® Rational® Application Developer for WebSphere® Software V9.0.1 added new capabilities for application integration between disparate enterprise environments, such as those made up of IBM WebSphere Application Server, CICS®, IMS™, and batch processing on z/OS®, and environments that contain SAP, Oracle, Seibel, and other IBM WebSphere Adapter-supported enterprise information systems. Support for optimized local adapters is now included in Rational Application Developer, offering optimized bi-directional calling between WebSphere Application Server for z/OS and external address space applications on the same z/OS system. Combining optimized local adapters with the WebSphere Adapters support presents many new opportunities for real time interactions between applications and environments that were too complex to realistically handle in the past. This article presents one such scenario, in which a CICS application uses optimized local adapters and WebSphere Application Server for z/OS to communicate with applications running on SAP servers. This content is part of the IBM WebSphere Developer Technical Journal.

Share:

James T Mulvey (jmulvey@us.ibm.com), Senior. Software Engineer, IBM

Jim Mulvey has worked in WebSphere Application Server development in the Poughkeepsie, NY IBM labs since 2007. He's the lead architect for WebSphere Application Server for z/OS and also leads the optimized local adapters design/development team. Prior to that, he spent ten years as a developer on the IBM z/OS Language Environment and IBM Problem Determination Tools teams. Before coming to IBM, Jim worked as an independent consultant for a number of years, specializing in MVS systems and CICS applications/systems programming.



Harold Gartner (hgartner@ca.ibm.com), Advisory Software Engineer , IBM

Harold Gartner is an Advisory Software Engineer at the IBM Toronto Lab in Markham, Ontario, with many years of experience in adapter technology. He currently works on IBM Business Process Manager (BPM) tooling, and has worked a majority of his career at IBM on other adapter tooling related products that were the precursors to BPM and Rational Application Developer (RAD).



18 December 2013

Also available in Chinese

Introduction

IBM Rational Application Developer for WebSphere Software Version 9.0.1 adds new support for WebSphere Optimized Local Adapters (WOLA). This new feature, when combined with existing WebSphere Adapters capabilities and tooling in Rational Application Developer, provides a simple way to integrate components on z/OS systems running in batch address spaces, CICS environments, and IMS environments with those that are supported today with WebSphere Adapters (such as SAP, Oracle, PeopleSoft, Seibel, and so on).

For more information on optimized local adapters, see the WebSphere Application Server Information Center and this developerWorks article.

This article steps through an end to end scenario in which a COBOL application running on CICS on z/OS is updated to call into an SAP R/3 business object to retrieve customer data. The COBOL CICS program could just as easily be a PL/I IMS transaction, or even a batch assembler application, and the target application could be an application running in a Seibel, Oracle, or other environment. Rational Application Developer tooling is used to generate virtually everything that's needed to do this. From a programming perspective, all you need is a few lines of implementation code to move the data from one side over to the other for the request and then back for the response. Presented below are the complete steps to make this a reality for the CICS to WebSphere Application Server to SAP R/3 customer scenario. The goal of this article is to provide a good use case and pattern to demonstrate this capability.

This information shared here, combined with another recent article on accessing SAP systems from applications in WebSphere Application Server for z/OS provides a solid foundation for improving productivity and reducing the complexity involved in writing composite applications that require parts of business logic located in several disparate places.


The end to end scenario

Suppose you have two applications that you want to integrate: one is a customer data application running as a set of CICS COBOL programs, and the other is a customer processing application that runs on an SAP R/3 server. You determine that the customer number is available on both sides and is the key to tying the applications together. On the CICS side, you have the customer number, but you require the rest of the customer data (name, address, and so on), which is maintained by the application on the SAP server. You can use existing artifacts on each side to make this work using WebSphere Application Server for z/OS and WOLA together with the WebSphere Adapters support and the SAP resource adapter. Rational Application Developer V9.0.1 is the component that brings everything together.


The process

The steps below explain how to make this work. This process assumes Rational Application Developer V9.0.1 or higher is in use, the CICS environment is at the CICS TS 3.1 or higher level (the minimal level where WOLA support starts), and that WebSphere Application Server for z/OS is at the V7.0.0.4 level or higher level. WOLA support must be enabled in WebSphere Application Server and CICS and ready for use. Figure 1 shows the main components involved in this scenario.

Figure 1. End to end scenario
End to end scenario

The steps for completing this end to end process can begin once the CICS environment is available and WebSphere Application Server for z/OS and WOLA are installed on the same z/OS system. The major steps involved are summarized below, and detailed in the sections that follow:

  1. Generate the WOLA enabled stateless session EJB that will serve as the target for the call from the CICS COBOL program.
  2. Create the calling CICS COBOL program, which uses the WOLA Register, Invoke, and Unregister APIs to call the target EJB to drive into the SAP server.
  3. Create the business object calling code using Rational Application Developer and the WebSphere Adapters support to locate the business objects on the target SAP server and generate the code to make the BAPI call.
  4. Add the implementation code in the WOLA target EJB to copy the customer number over from the CICS COBOL program and then drive the BAPI_CUSTOMER_GETDETAIL call to retrieve the customer information. There are very few lines of code needed to do this thanks to the tooling.
  5. Generate WOLA code to call to the CICS COBOL program over the WOLA resource adapter. Rational Application Developer is used to generate this code and to generate code for a JavaServer™ Pages web page to drive the outbound call, passing the customer number to the CICS program.
  6. Run the full end to end scenario, showing how to accept a customer number as input on the JSP web page and drive the call to the CICS COBOL program, which retrieves the customer number and calls the SAPCustomerGet EJB with it. The EJB then calls the SAP server with the provided number. The customer details returned are passed back to CICS, and then back to WebSphere Application Server and displayed on the web page.

Together, these steps provide instructions for generating a complete end to end flow, starting in WebSphere Application Server, then on to CICS, back to WebSphere Application Server and to SAP, and then all the way back to the initial web page, using Rational Application Developer to generate all but a few lines of code.


1. Generate the WOLA enabled stateless session EJB

In this step, you will use Rational Application Developer to initiate a request to create a WOLA J2C bean. The resulting Rational Application Developer generated Java™ source consists of a WOLA-enabled V3.1 EJB that declares an @RemoteHome of com.ibm.websphere.ola.ExecuteHome.class (this resolves from the ola_apis.jar file which the Rational Application Developer tooling will ensure is on the build path):

@RemoteHome(com.ibm.websphere.ola.ExecuteHome.class)

The EJB will contain a target method called execute():

public byte[] execute(byte[] theBytes) {
execute();
return (null);
}

This execute() method accepts a byte array and returns a byte array. As you'll see below, the Rational Application Developer generated method execute() populates a Record object that maps the COBOL program's copy book and then delegates to another method (also called execute) which accepts and returns a Record object representing the request and response data.

It's in this second execute() method that you place your implementation code which drives into the SAP BAPI business object to retrieve the customer information. This implementation uses Rational Application Developer generated helper classes to read the customer number key passed from the COBOL program, and pass it to the SAP retrieve customer data BAPI_CUSTOMER_GETDETAIL. The code that actually calls the SAP server and retrieves the data is also generated from Rational Application Developer.

Let's assume you have a CICS COBOL program called ZCUSTGET that retrieves a customer number from some location and now needs to determine contact information for this customer (address, phone, and so on). However, this information is not available locally and is instead maintained in real time by another system (owned or maintained by your company) running an SAP R/3 server for this purpose. The COBOL copy book used by ZCUSTGET looks like this Listing 1.

Listing 1. zcustcpy.cpy
      *                                                    
      * zcustcpy.cpy copy book                    
      *                                                    
       01  DFHCOMMAREA.                                    
           02  CustomerNumber PIC X(10).                   
           02  FirstName  PIC A(15).                       
           02  LastName   PIC A(25).                       
           02  Street     PIC X(20).                       
           02  City       PIC A(20).                       
           02  State      PIC A(10).                       
           02  Country    PIC A(10).                       
           02  Phone      PIC X(15).                       
           02  PostalCode PIC X(7).

In this step, you will create a WOLA-enabled stateless session bean that will be the target of an Invoke WOLA API call from your CICS program. In addition, the file containing this copy book will be imported into Rational Application Developer and made into a class containing helper getter/setter methods for accessing it. To do this:

  1. Copy the file zcustcpy.cpy (Listing 1) to your Rational Application Developer workstation, or paste it's contents into a file and use the J2C WOLA bean creation tooling and CICS/IMS Java Data Binding tools in Rational Application Developer to generate helper classes to provide access to the passed data, and copy the response back. Be aware that COBOL is column sensitive; the asterisks shown in Listing 1 should start in column 7, which is the comment column for COBOL.
  2. Open a new Rational Application Developer workspace (Figure 2).
    Figure 2. Rational Application Developer workspace
    Rational Application Developer workspace
  3. Create a new J2C bean by selecting File > New > Other > J2C > J2C Bean (Figure 3).
    Figure 3. New wizard
    New wizard
  4. Select Next then WOLA (Figure 4).
    Figure 4. Resource Adapter Selection
    Resource Adapter Selection
  5. Select Next (Figure 5), and a new Connector project will be setup.
    Figure 5. Connector Import
    Connector Import
  6. Select Inbound and then Next (Figure 6).
    Figure 6. Adapter Style
    Adapter Style
  7. Enter a JNDI name for the new stateless session bean; for this test enter SAPCustomerGetDetail (Figure 7).
    Figure 7. Connection Properties
    Connection Properties
  8. On the Java Bean Output Properties dialog, select New (Figure 8).
    Figure 8. J2C Java Bean Output Properties
    J2C Java Bean Output Properties
  9. On the EJB Project dialog, enter a new Project name; for this test enter SAPWOLATestProject and click Next (Figure 9).
    Figure 9. EJB Project
    EJB Project
  10. Accept the default folder of ejbModule (Figure 10).
    Figure 10. New EJB Project
    New EJB Project
  11. Click Finish (Figure 11).
    Figure 11. EJB Module
    EJB Module
  12. You will see the new project files display on the left side of the workspace. When the Java Bean Output Properties dialog displays (Figure 12), click New on the Package name. Give the new bean class a package name of com.ibm.rad.ola.test and a stateless session bean name of SAPCustomerGet.
    Figure 12. J2C Java Bean Output Properties
    J2C Java Bean Output Properties
  13. Click Next to see an Add Java Method dialog. Click Use the input type for output and then select New (Figure 13).
    Figure 13. EJB Method
    EJB Method
  14. On the Data Import dialog (Figure 14), enter zcustcpy.cpy for the COBOL file name and select COBOL to Java for the desired mapping. Click Next.
    Figure 14. Data Import
    Data Import
  15. On the Importer dialog (Figure 15), select z/OS as the Platform and IBM-1047 for the Code page. Select DFHCOMMAREA for the Data structures and click Next.
    Figure 15. Importer
    Importer
  16. On the Saving Properties dialog, set the Class Name from DFHCOMMAREA to CUSTOMER and click Finish (Figure 16).
    Figure 16. Saving Properties
    Saving Properties
  17. Click Finish on the next two dialogs to complete the wizard. Rational Application Developer will have created code that looks similar to that shown in Figure 17. A new project called SAPWOLATestProject is created, along with a part called SAPCustomerGetDetail.java, which is where you can put your implementation code (replacing the comment TODO - Need to implement business logic here). It also created a connector project called ola. You now have a new part CUSTOMER.java which contains the Java helper methods for handling data binding conversions from (and to) COBOL and Java objects. (Rational Application Developer might require you to perform Project > Clean at this point before all references will properly resolve.)
    Figure 17. EJB source listing
    EJB source listing

That's it for the WOLA target EJB for now. You can now use Rational Application Developer to export this into an EAR file and install into WebSphere Application Server and call this target EJB from your CICS ZCUSTGET program.

After installing the EAR, confirm that the Remote JNDI name is set properly in the WebSphere Application Server admin console by navigating to the application SAPWOLATestProjectEAR, where you should see the Remote Home JNDI name set to SAPCustomerGetDetail (Figure 18).

Figure 18. WebSphere Application Server admin console
WebSphere Application Server admin console

We'll wait to add the implementation code to the SAPCustomerGet bean's execute() method until you have completed the CICS COBOL calling program and set it up to call the SAP Server's BAPI_CUSTOMER_GETDETAIL business object.


2. Create the calling CICS COBOL program

You are now ready to get our COBOL program ready to call the EJB at JNDI name SAPCustomerGetDetail. Listing 2 shows sample JCL for the ZCUSTGET CICS COBOL program.

Listing 2. ZCUSTGET JCL
//ZCUSTGET JOB MSGCLASS=H,MSGLEVEL=(1,1),REGION=4M,NOTIFY=&SYSUID
//*                                                              
//*  Compile Cobol CICS test target program for OLA              
//*                                                              
//*  Test being invoked from WebSphere Application Server over WOLA Link Server and then  
//*  calling back to WAS for a Customer Get Details from an      
//*  SAP Server using BAPI-CUSTOMER-GETDETAIL.                   
//*                                                              
//MYPROCS JCLLIB ORDER=CICSTS42.CICS.SDFHPROC           
//CMP  EXEC DFHYITVL,INDEX='CICSTS42.CICS',             
//        PROGLIB='<MY_LOADLIB>',                 
//        DSCTLIB='<MY.INCLUDE_LIB>',                        
//        AD370HLQ='COBPFX',                            
//        LE370HLQ='CEEPFX',                                        
//        PARM.TRN='COBOL2 NOLINKAGE'                            
//TRN.SYSIN  DD  *                                               
       CBL CICS                                                  
       Identification Division.                                  
       Program-Id. ZCUSTGET.                                     
       Environment Division.                                     
       Data Division.                                            
       Working-Storage Section.                                  
       01 olaRegister          PIC X(8)      VALUE 'BBOA1REG'.   
       01 olaInvoke            PIC X(8)      VALUE 'BBOA1INV'.   
       01 olaUnRegister        PIC X(8)      VALUE 'BBOA1URG'.   
       01 reqType              PIC 9(8) COMP VALUE 0.            
       01 regDaemonName        PIC X(8)      VALUE LOW-VALUES.   
       01 reqArea              PIC X(100)    VALUE SPACES.       
       01 reqAreaAddr          USAGE POINTER.                    
       01 respArea             PIC X(2048)   VALUE SPACES.       
       01 respAreaAddr         USAGE POINTER.                    
       01 name                 PIC X(255)    VALUE SPACES.       
       01 daemonName           PIC X(8)      VALUE 'WAS00   '.   
       01 nodeName             PIC X(8)      VALUE 'NDN1    '. 
       01 serverName           PIC X(8)      VALUE 'BBOS001 '.                  
       01 registerName         PIC X(12)     VALUE 'ZCUSTGET'.                  
       01 serviceName          PIC X(255).                                      
       01 serviceNameLen       PIC 9(8) COMP VALUE 0.                           
       01 reqLen               PIC 9(8) COMP VALUE 100.                         
       01 respLen              PIC 9(8) COMP VALUE 100.                         
       01 minConn              PIC 9(8) COMP VALUE 1.                           
       01 maxConn              PIC 9(8) COMP VALUE 10.                          
       01 waitTime             PIC 9(8) COMP VALUE 0.                           
       01 regOpts              PIC 9(8) COMP VALUE 0.                           
       01 rc                   PIC 9(8) COMP VALUE 0.                           
       01 rsn                  PIC 9(8) COMP VALUE 0.                           
       01 rv                   PIC 9(8) COMP VALUE 0.                           
       01 verbose              PIC 9(8) COMP VALUE 0.                           
       01 result               PIC 9(8) COMP VALUE 0.                           
       01 reason               PIC 9(8) COMP VALUE 0.                           
       01 testcase             PIC X(8)      VALUE 'ZCUSTGET'.                  
       01 endMessage           PIC X(25).                                       
       Linkage Section.                                                         
       Copy DFHEIBLK.                                                           
       Copy ZCUSTCPY.                                                           
       Procedure Division Using EIBLK DFHCOMMAREA.                              
       Start-Para.                                                              
           MOVE 1 to verbose.                                                   
      *                                                                         
      * OLA REGISTER                                                            
      *                                                                         
           IF verbose = 1 THEN                                                  
             DISPLAY TESTCASE ": Calling Register for : " registerName          
             DISPLAY TESTCASE ": with Daemon name : " daemonName                
             DISPLAY TESTCASE ": with Node name : " nodeName                    
             DISPLAY TESTCASE ": and Server name : " serverName                 
           END-IF.                                                              
                                                                                
           Inspect daemonName converting ' ' to low-values. 

           CALL olaRegister Using daemonName, nodeName, serverName,      
                 registerName, minConn, maxConn,                         
                 regOpts, rc, rsn.                                       
                                                                         
           If rc > 0 Then                                                
             DISPLAY TESTCASE ": Bad RC/RSN from BBOA1REG: " rc "/" rsn  
             GO TO LEAVE-ZCUSTGET                                        
           End-IF.                                                       
                                                                         
      *    MOVE '0000000001' to CustomerNumber.                          
           MOVE SPACES to FirstName.                                     
           MOVE SPACES to LastName.                                      
           MOVE SPACES to Street.                                        
           MOVE SPACES to City.                                          
           MOVE SPACES to Country.                                       
           MOVE SPACES to Phone.                                         
           MOVE SPACES to PostalCode.                                    
           MOVE LENGTH OF DFHCOMMAREA to reqLen.                         
           MOVE reqLen to respLen.                                       
           MOVE LOW-VALUES TO serviceName.                               
           MOVE 'SAPCustomerGetDetail' to serviceName.                   
           MOVE 20 TO serviceNameLen.                                    
                                                                         
      * Null terminate service name.                                     
           Inspect serviceName converting ' ' to low-values.             
                                                                         
           SET reqAreaAddr TO ADDRESS OF DFHCOMMAREA.                    
           SET respAreaAddr TO ADDRESS OF DFHCOMMAREA.                   
                                                                         
       Invoke-WAS.                                                       
      *                                                                  
      * OLA INVOKE                                                       
      *                                                                  
           MOVE 1 TO reqType.     
      *                                                                     
      * Make the ejb call                                                   
      *                                                                     
           IF verbose = 1 THEN                                              
             DISPLAY TESTCASE ": Invoking EJB at ... " serviceName          
             DISPLAY TESTCASE ": Service name len: " serviceNameLen         
             DISPLAY TESTCASE ": CustomerNumber in " CustomerNumber         
             DISPLAY TESTCASE ": First Name In: " FirstName                 
             DISPLAY TESTCASE ": Last Name In: " LastName                   
             DISPLAY TESTCASE ": Street In: " Street                        
             DISPLAY TESTCASE ": City In: " City                            
             DISPLAY TESTCASE ": State In: " State                          
             DISPLAY TESTCASE ": Country In: " Country                      
             DISPLAY TESTCASE ": Phone In: " Phone                          
             DISPLAY TESTCASE ": Postal Code In: " PostalCode               
           END-IF.                                                          
                                                                            
           CALL olaInvoke Using registerName, reqType,                      
                 serviceName,                                               
                 serviceNameLen,                                            
                 reqAreaAddr, reqLen,                                       
                 respAreaAddr, respLen,                                     
                 waitTime, rc, rsn, rv.                                     
                                                                            
           If rc > 0 Then                                                   
             DISPLAY TESTCASE ": Bad RC/RSN from BBOA1INV: " rc "/" rsn     
             GO TO LEAVE-ZCUSTGET                                           
           End-IF.                                                          
                                                                            
           IF verbose = 1 THEN                                              
             DISPLAY TESTCASE ": Invoke back rc/rsn/rv: " rc " " rsn " " rv 
             DISPLAY TESTCASE ": Response length: " respLen                 
             DISPLAY TESTCASE ": CustomerNumber: " CustomerNumber           
             DISPLAY TESTCASE ": First Name Out: " FirstName                
             DISPLAY TESTCASE ": Last Name Out: " LastName  
             DISPLAY TESTCASE ": Street Out: " Street                          
             DISPLAY TESTCASE ": City Out: " City                              
             DISPLAY TESTCASE ": State Out: " State                            
             DISPLAY TESTCASE ": Country Out: " Country                        
             DISPLAY TESTCASE ": Phone Out: " Phone                            
             DISPLAY TESTCASE ": Postal Code Out: " PostalCode                 
             DISPLAY TESTCASE ": Returning."                                   
           END-IF.                                                             
                                                                               
      *                                                                        
      * OLA UNREGISTER                                                         
      *                                                                        
           IF verbose = 1 THEN                                                 
             DISPLAY TESTCASE ": Calling UnRegister for : " registerName       
           END-IF.                                                             
                                                                               
           CALL olaUnRegister Using registerName,                              
                 regOpts, rc, rsn.                                             
                                                                               
           If rc > 0 Then                                                      
             DISPLAY TESTCASE ": Bad RC/RSN from BBOA1URG: " rc "/" rsn        
             GO TO LEAVE-ZCUSTGET                                              
           End-IF.                                                             
                                                                               
       LEAVE-ZCUSTGET.                                                         
           MOVE rc TO RESULT.                                                  
           MOVE rsn TO REASON.                                                 
           EXEC CICS RETURN                                                    
           END-EXEC.                                                           
//LKED.SYSIN  DD  *                                                            
  NAME ZCUSTGET(R)

This program needs to be compiled, linkedited, and saved into a load dataset in the CICS region's DFHRPL DD concatenation. The needed CICS program definition might also be required.

The intention here is to call this program from a small sample JSP over WOLA and through the WOLA CICS Link Server. The Rational Application Developer generated JSP will pass a customer number and call this COBOL program using WOLA's outbound calling support. This program will then call back over WOLA's Invoke API to your newly created SAPCustomerGet EJB, which will then move the customer over and drive over the SAP resource adapter into the BAPI_CUSTOMER_GETDETAIL business object to pull the customer information. Finally, the response with the customer information will come back into WebSphere Application Server then into CICS, and back into your calling JSP, where you will display the details.


3. Create the business object calling code

You are now ready to locate the BAPI_CUSTOMER_GETDETAIL business object and generate the code to drive it from inside your SAPWOLATestProject workspace. To do that:

  1. Ensure the SAP resource adapter is installed in the WebSphere Application Server for z/OS server and the connection factory settings for the ApplicationServerHost, userName, and Password are specified. The resource adapter configuration should look like Figure 19.
    Figure 19. WebSphere Application Server admin console - Resource Adapters
    WebSphere Application Server admin console - Resource Adapters
    The resource adapter can be located in ${CONNECTOR_INSTALL_ROOT}/CWYAP_SAPAdapter.rar. Regarding the class path and native library path, you will need the z/OS-specific DLLs to be available, and with this path set to the location where you have them. Refer to the Rational Application Developer Information Center document on configuring the SAP resource adapter for z/OS.

    You are now ready to use Rational Application Developer to locate the remote function calls (RFC) or business object repositories (BOR) on your target SAP Server. Select File > New > Other > J2C > J2C Bean, and then Next.

  2. Select the IBM WebSphere Adapter for SAP Software and click Next (Figure 20).
    Figure 20. Resource Adapter Selection
    Resource Adapter Selection
  3. On the Connector Import dialog, accept the default and click Next (Figure 21).
    Figure 21. Connector Import
    Connector Import
  4. Refer to the Information Center to locate information on using the WebSphere Adapters SAP resource adapter in the Rational Application Developer V9.0.1 environment. You need to obtain these files from your SAP server administrator and indicate the path to these, as shown in Figure 22.:
    • sapidoc3.jar
    • sapjco3.dll
    • sapjco3.jar

    Since the example shown was run with Rational Application Developer on Windows 7, you will notice the DLL is the win64bitx86 version.

    Figure 22. Connector Settings
    Connector Settings
  5. You should now be ready to locate SAP RFCs and BORs and generate code in Rational Application Developer to work with them. On the Adapter Style dialog, select Outbound and click Next (Figure 23).
    Figure 23. Adapter Style - Outbound Processing
    Adapter Style - Outbound Processing
  6. On the Discovery Configuration dialog (Figure 24), you'll need to identify the important data related to connecting to the target SAP Server. Host name, Client, System number, User name, and Password are the key fields. Review this with your SAP system administrator to determine these values. Select the BAPI option. Click Next and Rational Application Developer will drive a request to the SAP Server and query it's resources.
    Figure 24. Discovery Configuration
    Discovery Configuration

    Click to see larger image

    Figure 24. Discovery Configuration

    Discovery Configuration
  7. If the SAP server was contacted successfully, a dialog such as that shown in Figure 25 will display.
    Figure 25. Object Discovery and Selection
    Object Discovery and Selection
  8. Select RFC, then click the Filter icon (showing three arrows) directly above (Figure 26).
    Figure 26. Object Selection
    Object Selection
  9. On the Filter Properties for ‘RFC’ dialog, change the value of Find objects with this pattern from "*" to BAPI_CUSTOMER_GETD* and click OK (Figure 27).
    Figure 27. Filter Properties for 'RFC'
    Filter Properties for 'RFC'
  10. You will get a set of responses back under RFC (Figure 28). Click in the > button to expand the results (Figure 28).
    Figure 28. Filtered Object Selection
    Filtered Object Selection
  11. You are now ready to tell Rational Application Developer what to import (or generate code to invoke or interact with). Select BAPI_CUSTOMER_GETDETAIL and click the > icon to select it for Import (Figure 28). You will see the dialog shown in Figure 29. Click Use SAP field names… value and click OK.
    Figure 29. Configuration Parameters
    Configuration Parameters
  12. The Object Discovery and Selection dialog should look Figure 30. Click Next.
    Figure 30. Selected object
    Selected object
  13. The Configure Composite Properties dialog should look like Figure 31. Enter ejbModule as the Folder to enable the code to end up in the same location you have been using so far.
    Figure 31. Configure Composite Properties
    Configure Composite Properties
  14. Complete the properties fields in the Bean Creation and Deployment Configuration dialog, as shown in Figure 32. Enter eis/sap_server as value for the JNDI Lookup Name and then Finish.
    Figure 32. J2C Bean Creation and Deployment Configuration
    J2C Bean Creation and Deployment Configuration
  15. You now have the code you need to interact with this business object. In the Rational Application Developer workspace, you should see something like that shown in Figure 33. You are ready now to code the implementation that pulls from the WOLA EJB and forwards the request to the SAP server's BAPI_CUSTOMER_GETDETAIL business object.
    Figure 33. Outbound bean source listing
    Outbound bean source listing

4. Add the implementation code in the WOLA target EJB

Up to this point, all the code created (with the exception of the COBOL WOLA calling code in CICS) has been generated by Rational Application Developer. You used Rational Application Developer to create a WOLA target EJB called SAPCustomerGet and a method called execute() within it that gets control for the WOLA invoke call from the CICS ZCUSTGET COBOL program. You used Rational Application Developer to import the COBOL copy book and generate a helper class that will handle getting at and setting object values that come from the COBOL side and return to the COBOL side. The part generated for this is called CUSTOMER.java. Finally, you used Rational Application Developer to generate the code that uses the SAP resource adapter to drive into the BAPI_CUSTOMER_GETDETAIL business object. The code in parts SAP_BAPI_Customer_GetDetail.java and SAP_BAPI_Customer_GetDetailImpl.java was generated for this purpose.

Now you are ready to put the code in place to tie these pieces together.

Let's go back and modify SAPCustomerGet.java. Figure 34 shows a modified version that accesses the input customer number and only prints it out. The execute method is modified to return the input byte array back as the output response.

Figure 34. Implementation listing
Implementation listing

It might be useful to build this into an EAR and test it before proceeding. To drive the initial request on the CICS side, define a transaction called ZGET and associated it with program ZCUSTGET. You can alter the program to place the copy book in the WORKING-STORAGE section and preset the customer number in to 0000000001 then run the transaction in CICS while logged on to a terminal session. This test step can be skipped, as later in this article is a description of how you can build code in Rational Application Developer to call the CICS ZCUSTGET program from WebSphere Application Server over WOLA and using the WOLA CICS Link server; this enables you to drive requests into CICS, replacing the need to logon to a 3270 terminal session and execute the ZGET/ZCUSTGET transaction/program.

The next step is to enhance this to add the code that will call the BAPI_CUSTOMER_GETDETAIL business object. Figure 35 shows code to print debug information to the WebSphere Application Server log. The code in the figure shows how to accept the request from CICS , retrieve the customer number, create a new instance of SapBapiCustomerGetdetail, fill in the customer number, and then drive the call over the SAP resource adapter to the SAP server.

Figure 35. Calling SAP outbound J2C bean
Calling SAP outbound J2C bean

The code in Figure 26 processes the response from the SAP customer inquiry and populates it back into a byte array for return to the COBOL CICS caller.

Figure 36. Mapping output data
Mapping output data

Executing a test to drive this from a CICS transaction will yield the following output messages in the WebSphere Application Server for z/OS SYSPRINT routine coming from the WOLA target EJB SAPCustomerGet (Figure 37)

Figure 37. WebSphere Application Server for z/OS servant region job output (SYSPRINT)
WebSphere Application Server for z/OS servant region job output (SYSPRINT)

The output messages in the CICS CEEMSG log from the running COBOL program should look like Figure 38. Again, in ZCUSTGET you ran with the ZCUSTCPY copy book located in the WORKING-STORAGE section and preset the customer number to be queried to 0000000001. When you use WOLA to call ZCUSTGET from WebSphere Application Server (shown in the next section) the ZCUSTCPY copy book must be moved to the LINKAGE-SECTION of the ZCUSTGET program and the hardcoded customer number removed; instead it is accepted as an input parameter from WebSphere Application Server and the test web page that you will build.

Figure 38. z/OS CICS job output display (CEEMSG)
z/OS CICS job output display (CEEMSG)

Step 5: Generate WOLA code to call to the CICS COBOL program

New support in Rational Application Developer provides the ability to build code that will call over to a CICS, IMS, or a batch program from WebSphere Application Server using WOLA. This step walks through the tasks for generating a simple web page that accepts the customer number, queried from the SAP server, and drives it over to the ZCUSTGET COBOL CICS program, which in turn will call back to WebSphere Application Server, over WOLA, to the SAPCustomerGet EJB, which will in turn call the SAP BAPI_CUSTOMER_GETDETAIL business object. The response will flow back from the SAP application to the SAPCustomerGet EJB, then back to ZCUSTGET and then the calling servlet/web application where the customer details will be displayed.

  1. Generate a WOLA J2C bean to be used for the outbound call from WebSphere Application Server to CICS. In Rational Application Developer select File > New > Other > J2C > J2C Bean (Figure 39).
    Figure 39. New J2C Bean wizard
    New J2C Bean wizard
  2. Under the WOLA directory, select the ola folder and click Next (Figure 40).
    Figure 40. Resource Adapter Selection
    Resource Adapter Selection
  3. Select Outbound and then Next (Figure 41).
    Figure 41. Adapter Style
    Adapter Style
  4. Set the JNDI name to eis/ola and click Next (Figure 42).
    Figure 42. Connection Properties
    Connection Properties
  5. Define the project, package, and EJB names as shown in Figure 43.
    Figure 43. J2C Java Bean Output Properties
    J2C Java Bean Output Properties
  6. On the Java Method panel, select New (Figure 44) to add a Java method type. Be sure to check Use the input type for output. Enter zCUSTCPY_Out for the Name field, click Browse, type in CUSTOMER and select it. Click Finish when done.
    Figure 44. Java Method
    Java Method
  7. This next dialog asks for the WOLA target service name to invoke; this would be the CICS target program ZCUSTGET (Figure 45).
    Figure 45. Java Methods
    Java Methods
  8. On the Deployment Information dialog, check Create a Web page, Web Services, or EJB from the J2C bean to indicate you want a new web page (Figure 46). Select Simple JSP and click Next.
    Figure 46. Deployment Information
    Deployment Information
  9. To create a new web project, enter SAPWOLATestWeb as the new project name and Finish (Figure 47).
    Figure 47. Web Project
    Web Project
  10. A new project will display on the left. Be sure the EAR Project name is set to SAPWOLATestProjectEAR (Figure 48). If it does not, your new project will not be integrated and included in the EAR.
    Figure 48. Deployment
    Deployment
  11. You are now ready to create the JSP associated with the servlet that was created for testing. In the Simple JSP Creation dialog, enter JSP as the folder and click Finish (Figure 49).
    Figure 49. Simple JSP Creation
    Simple JSP Creation

At this point, you should see a new part that looks like Figure 50. It was created as a helper and is used for handling interactions over the WOLA resource adapter and on to CICS.

Figure 50. Outbound J2C bean source listing
Outbound J2C bean source listing

At this time, you should be able to see a new set of JSPs that were created in the new SAPWOLATestWeb project (Figure 51):

  • TestClient.jsp is the top level JSP that includes the others.
  • Input.jsp accepts the input parms.
  • Method.jsp drives the call to the resource adapter interacting code.
  • Result.jsp holds the response.
Figure 51. Resource View
Resource View

Figure 52 shows what Input.jsp should look like.

Figure 52. Input JSP
Input JSP

6. Run the full end to end scenario

Make sure the EAR project SAPWOLATestProjectEAR has the new Web Project SAPWOLATestWeb included in it's deployment assembly setup (Figure 53).

Figure 53. Ear Module Assembly
Ear Module Assembly

In Rational Application Developer right click on the SAPWOLATestProjectEAR project and select Properties and Deployment Assembly. If you don't see SAPWOLATestWeb.war there, click Add and add it to this list now; otherwise the JSPs will not be bundled into your EAR file.

You now have the complete application built and ready to test. Issue a Project > Clean command and Run. Right-click select on SAPWOLATestProject and SAPWOLATestProjectEAR, then select Java EE > Prepare for Deployment to ensure everything is compiled and ready.

  1. Right-click on the SAPWOLATestProjectEAR file and select Export > EAR. Give it a name as shown in Figure 54.
    Figure 54. EAR Export
    EAR Export
  2. Logon to the WebSphere Application Server admin console and define a connection factory of type OptimizedLocalAdapter with the name eis/ola (Figure 55). You'll need to specify a Register Name on the CF custom properties panel that matches the name you plan to use for the WOLA CICS Link server (see step 5 below).
    Figure 55. WebSphere Application Server admin console - J2C Connection Factories
    WebSphere Application Server admin console - J2C Connection Factories
    Use the name OLASERVER as the Register name (Figure 56).
    Figure 56. Register Name Property
    Register Name Property
  3. Install the EAR file in your application server using the admin console.
  4. Make sure the ZCUSTGET COBOL program is ready to be invoked in your CICS region. It should have the ZCUSTCPY copy book in the LINKAGE-SECTION and DFHCOMMAREA specified on the PROCEDURE DIVISION. It should have been compiled and linked and be available in the CICS DFHRPL DD in the regions start JCL. If you are not using CICS program autoinstall, it also will require a CICS PPT definition for ZCUSTGET, indicating it's a COBOL program. The linkafe section and procedure division should look like that shown in Figure 57 (see the included ZCUSTGET and ZCUSTCPY examples).
    Figure 57. Linkage section
    Linkage section
  5. Logon to CICS and start the WOLA CICS Link Server specifying these parameters; issue this command from a CICS 3270 terminal session:

    bboc start_srvr rgn=olaserver svn=bbos001 dgn=was00 ndn=ndn1 trc=2 svc=*

    (TRC=2 is extended tracing and is only set this way for debugging.)

    This command starts up a CICS background transaction called BBO$ which will catch program invocation requests from WebSphere Application Server and issue START TRANSACTION for another transaction, BBO#, which is the WOLA invocation task. It's this task that issues EXEC CICS LINK to the selected target programs. In this case, the target program will be ZCUSTGET. But any other program that comes in for this connection factory can also be served by this Link Server since it is running with SVC=* (any service name under this matching register name is accepted).

    If the WOLA CICS Link Server started properly, you'll see messages like those in Figure 58 in the CICS joblog on z/OS; the BBOOUT DD.

    Figure 58. Console output
    Console output
  6. Once CICS and the WebSphere Application Server server have been restarted and are ready, go ahead and try to test the entire end to end flow. Open a browser and paste in a URL such as:

    http://<hostname>:<port>/SAPWOLATestWeb/JSP/TestClient.jsp

    You should see a page like Figure 59 if all is installed and working properly.

    Figure 59. Test client
    Test client
  7. To test, enter customerNumber 0000000002 and click Invoke. The response back should match the Result section in Figure 60.
    Figure 60. Test Client Results
    Test Client Results

    This means the request for customer number 0000000002 went over to CICS ZCUSTGET over WOLA, which in turn went back to WebSphere Application Server over WOLA to your SAPCustomerGet EJB, and then over to the SAP server for business object BAPI_CUSTOMER_GETDETAIL. The response came back in to WebSphere Application Server, to CICS, and then back into WebSphere Application Server again and up to the response page above.

    Figure 61 shows what you might see when checking the logs in the WebSphere Application Server SYSPRINT.

    Figure 61. Console log
    Console log

    When checking in the CICS WOLA Link Server BBOOUT log in the CICS job, when running with TRC=2 as you did here, you see the trace messages in Figure 62 shows ZCUSTGET ran.

    Figure 62. CICS Job output WOLA BBOQ trace messages (BBOOUT)
    CICS Job output WOLA BBOQ trace messages (BBOOUT)
  8. Finally, look in the ZCUSTGET COBOL program's message log (Figure 63).
    Figure 63. ZCUSTGET output in CICS job log (CEEMSG)
    ZCUSTGET output in CICS job log (CEEMSG)

This is the end of the sample end to end test using WebSphere Application Server for z/OS, WOLA, WebSphere Adapters, and the SAP resource adapter. As mentioned at the outset, there is very little manually created code needed to make this work. The total lines of code is less than 50 when implementing the WOLA EJB that calls over the SAP resource adapter. The COBOL code, to call the WOLA EJB, is required as well.


Conclusion

Rational Application Developer Version 9.0.1 provides some truly impressive capability in the area of application integration with minimal programming required between disparate environments, such as WebSphere Application Server, CICS, IMS, SAP, Oracle, Seibel, and other supported enterprise information systems. This pattern, once mastered, offers a way to match any of the WebSphere Adapters supported environments with applications on z/OS today running in CICS, IMS, as batch, and so on. The integration of the WebSphere Optimized Local Adapters bi-directional calling capability opens up many possibilities for real time interactions between applications that were simply too complex to deal with in the past.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Rational
ArticleID=957011
ArticleTitle=Rational Application Developer enhancements for WebSphere Optimized Local Adapters present new opportunities for end to end EIS integration
publish-date=12182013