IBM WebSphere Developer Technical Journal: Using WebSphere Studio V5 to Connect to COBOL./CICS

Document options Document options requiring JavaScript are not displayed Sample code Rate this page Help us improve this content

Level: Intermediate

Reginaldo Barosa (rbarosa@us.ibm.com), Application Development Specialist, IBM

10 Sep 2003

This tutorial illustrates an end-to-end example of how to code a simple Web application, connect it to an existing COBOL/CICS program, and test it using WebSphere Studio Application Developer Integration Edition, Version 5, for deployment on WebSphere Application Server V5.

Introduction

Integrating legacy systems, made up of COBOL/CICS-based applications, with newer systems running under Web application servers is an extremely common requirement, especially for larger companies. For those facing such a task, this article will illustrate a complete example, showing how to code a simple Web application, connect it to an existing COBOL/CICS program, and test it using WebSphere® Studio Application Developer Integration Edition, Version 5, for deployment on WebSphere Application Server V5.

Back to top

Connecting to CICS

It's possible to connect to CICS using many different technologies; in any solution, the infrastructure for accomplishing this is usually required. In our example, we will use the J2EE Connector Architecture, which is an open architecture and fully compliant with J2EE specifications.

J2EE Connector Architecture, also known as JCA or J2C, defines a standard architecture for connecting the J2EE platform to heterogeneous Enterprise Information Systems (EIS), mainframe transaction processing applications, database systems, and legacy applications not written in the Java programming language. In our example, the Enterprise Information System is CICS.

By defining a set of scalable, secure, and transactional mechanisms, JCA enables the integration of EISs with application servers and enterprise applications. JCA enables an EIS vendor to provide a standard resource adapter for its particular system. The resource adapter plugs into an application server, providing connectivity between the EIS, the application server, and the enterprise application.

The following resource adapters are shipped with WebSphere Studio Application Developer Integration Edition, Version 5 (hereafter called Application Developer):

• CICS ECI (CICS External Call Interface)
• CICS EPI (CICS External Presentation Interface)
• HOD 3270 (Host On-Demand for 3270 terminals)
• IMS^TM.

In our example, we will use the CICS ECI resource adapter.

Back to top

Our sample application

In our application, we have a legacy COBOL/CICS program that accesses a DB2® table. Using the J2C connectors and running under WebSphere Application Server V5, we want to write an application that connects to this existing COBOL/CICS program and returns some information. Figure 1 shows the architecture of our sample application: the Web application passes a customer number to the COBOL/CICS program, which then reads a DB2 customer table and returns detailed information.

For practical reasons, we will have the enterprise server and the WebSphere Application Server on the same machine running Windows© 2000. However, the steps necessary to implement this sample would be the same if the enterprise server was a z/OS® machine.

To simplify the development process, we will divide the process into three main activities:

A. Install the software and prepare the environment

If your environment does not already have the prerequisite software installed, this activity will need to be performed (once). The main tasks are:

1. Install the required software
2. Configure the DB2, TXSeries and CICS Transaction Gateway
3. Import the CICS ECI resource adapter into Application Developer

B. Create an EJB to call the CICS program

Perform these tasks to create the Enterprise JavaBean (EJB) session bean that will use the J2C connector:

4. Create a service project and import the COBOL program to be wrapped
5. Generate the enterprise service for the CICS program
6. Generate the deploy code for the enterprise service
7. Add a server and server configuration
8. Add JAAS authentication to the server configuration
9. Add a connection factory to the server configuration
10. Bind the connection factory
11. Test the session bean

C. Create a Struts application that uses the EJB

Perform these tasks to implement our sample application using Struts:

12. Add the required code in the EJB to access customer information
13. Create an access bean
14. Create a Web project that supports Struts
15. Create a Web diagram
16. Create the components (JSPs, action and form bean)
17. Create the action
18. Test the Web application
19. Customize the code using Struts properties and error messages

In the sections that follow we describe each of these activities in detail.

Back to top

1. Install the required software

Our solution requires the following software:

• Windows 2000 with FP3 or greater
  • TCP/IP configured and operational
  • MS Loopback driver is configured and operational. CICS will not start if there is no network
• IBM DB2 UDB Version 8.1 (Enterprise Server Edition). Previous versions of DB2 (DB2 V7.2 FP7) would be fine also.
• IBM TXSeries© Version 5.0 for Windows (CICS Server)
• WebSphere Studio Application Developer Integration Edition, Version 5.0

Install the required software, as necessary, before continuing. Note that CICS Transaction Gateway is silently installed as part of the WebSphere Studio Application Developer Integration Edition installation.

Back to top

2. Configure DB2, TXSeries and CICS Transaction Gateway

This activity is dependent upon on your specific environment. Refer to the Read_me_first.doc file located in the download file.

Back to top

3. Import the CICS ECI resource adapter into Application Developer

The CICS ECI resource adapter is shipped with Application Developer, but is not automatically loaded into the user's workspace. Before you can generate enterprise services for a resource adapter, you must first import it into the workspace. However, you will only need to do this once after installing Application Developer. (If you have multiple workspaces, you will need to import the resource adapter separately into each workspace.)

To import the resource adapter:

1. Start Application Developer.
2. Launch the "Connector Import" wizard as follows:
   1. Open the Business Integration perspective.
   2. From the menu bar, select File => Import.... The "Import" wizard opens.
   3. In the Import wizard, select RAR file. The "Connector Import" wizard opens (Figure 2).
3. Click Browse to locate the resource adapter file, ciceci.rar. The J2C resource adapters shipped with the WebSphere Studio product can be found in WS_installdir\resource adapters, where WS_installdir is the directory where WebSphere Studio is installed.
4. Check the Standalone connector project check box, and select the New radio button for Connector project.
5. Enter a value for New project name, such as Resource Adapters Project.
6. Select Use default for the location of the new connector project.
7. Click Finish to complete the import.
   Figure 2. Importing CICS ECI resource adapter to the workspace
   
   

Go to the J2EE Hierarchy view and expand Connector Modules to see the new connector project that contains the imported resource adapter.

Back to top

4. Create a service project and import the COBOL program to be wrapped

Service projects manage the development of services and processes, and are also the containers for the files (WSDL, Java, process files, etc.) that make up each service or process. Service project files are packaged and deployed in Enterprise Archive (EAR) files.

To create a Service project and import the COBOL program:

1. Using the Business Integration perspective, select File => New => Service Project from the menu bar.
2. On the "New Service Project" dialog, specify CICSStrutsDemo as the Project name, and click Finish.
3. Select CICSStrutsDemo, then select File => New => Package on the Workbench menu bar.
4. On the "Java Package" dialog, specify cics.custdetail as Package Name, and click Finish.
5. Open Windows Explorer and navigate to where you downloaded the sample COBOL, like c:\temp. Using drag and drop, import the COBOL program WBCSTDT2.cpp to the CICSStrutsDemo\cics.custdetail package.
6. Double-click the WBCSTDT2.cpp to open it in the text editor and examine it (Figure 3). Look for the DFHCOMMAREA, which is the communication area that is passed between the CICS server and the application. We will be referring back to this shortly.
   Figure 3. COBOL CICS program imported to the Integration Edition
   
   

Back to top

5. Generate the enterprise service for the CICS program

In this step, you will use the Create CICS ECI Service wizard to generate the service definitions to access the CICS program on your CICS server. The service definitions will be in three Web Services Description Language (WSDL) files, as shown in Figure 4.

To generate the enterprise service:

1. From the Services view, select the CICSStrutsDemo service project and click the Service built from... icon from the toolbar. The "Create Service" wizard opens.
2. In the "Create Service" dialog, select CICS ECI for the resource adapter and click Next (Figure 5).
   Figure 5. Creating a CICS ECI Service dialog
   
   
3. In the "New CICS ECI Service" dialog, enter the following connection properties (Figure 6):
   • Gateway address: target URL of your CICS transaction gateway
   • CICS server name: name of your CICS server
   • User name: valid user ID to access the CICS system
   • Password: valid password for the User name.
   Accept the defaults for the other connection properties.
   Figure 6. CICS ECI service -- Connection properties
   
   
4. Click Next.
5. In the "Service Binding" dialog (Figure 7) enter the following values:
   1. Source folder: click Browse to select /CICSStrutsDemo
   2. Package: click Browse to select cics.custdetail
   3. Interface file name: CustomerInfo
      
      Default values for the other fields, such as Port type name, binding name, and so forth, are generated based on the Interface file name, but can be overridden if desired. Typically, the defaults are accepted, which is what we will do here.
      Figure 7. CICS ECI service -- Service binding
      
      
   4. Click Finish.
   When the "Create Service" wizard completes, a dialog box displays a message to proceed to create the binding operations in the Binding WSDL file, CustomerInfoCICSECIBinding.wsdl, which is opened in the editor. (You can suppress this message by selecting the check box in the dialog.) You will see that the service-binding file is opened for editing.
   
   At the end of the above steps, three WSDL files are generated:
   • CustomerInfo.wsdl - Interface WSDL file: contains a port type with no operations and messages.
   • CustomerInfoCICSECIBinding.wsdl - Binding WSDL file: does not contain any binding definition for any operation.
   • CustomerInfoCICSECIService.wsdl - Service WSDL file: contains the required service and port definition.
   At this point, the WSDL does not yet contain any operations or binding information. The next instructions will add these for the service.
6. You are now in the "Bindings" page of the CustomerInfoCICSECIBinding.wsdl file, which is open in the WSDL editor. You have to add an operation before you can add its binding definition. Therefore, click the New button (to the right of Available Operations) in the "Port Type and Binding Operations" section to add an operation.
7. In the "Operation Binding" dialog, enter the value getCustomerInfo in the Operation name field. Leave the type of operation as REQUEST_RESPONSE because there will be two messages, one for the request and one for the reply. See Figure 8.
   Figure 8. Adding a message in the WSDL service
   
   Click Next, then proceed with the following:.
   1. In the "Bind Properties" dialog, type the name of the CICS program that will be invoked for the service, which will be WBCSTDT2, in the functionName field. Click Next.
   2. In the "Operation Binding" dialog, select Use input message for output. You may recall that the DFHCOMMAREA in a COBOL/CICS program stores the input and output results. Click Import (not Browse...), which is next to the input message.
   3. In the "File selection" dialog, browse to the CICSStrutsDemo project and expand the cics and custdetail folders, then select WBCSTDT2.cpp.
   4. Click Next.
   5. On the "COBOL Import Properties" dialog, click the Next button. (This panel would be used to specify properties on how data would be transformed on the target platform and would vary depending on the execution platform of the CICS server (Intel, 390, etc.). Since the CICS server in our example is Win32, there is nothing to change. However, if your CICS Server runs on another platform, like z/OS, you would have to change this page.)
   6. On the "COBOL Importer" dialog (Figure 9), scroll down the communication data structures and select DFHCOMMAREA. Click Finish.
      Figure 9. Importing the COBOL
      
      
8. Back on the "Operation Binding" dialog, note that the Input message has been filled in as a result of importing the COBOL. Click the Next button.
9. On the "Operation Binding-Summary" dialog, briefly examine the Summary. Note that the customerInfo operation is being added, as well as the customerInfoRequest message. Click Finish.

At the end of this step, you should see the three generated WSDL files in the cics.custdetail package, as shown in Figure 10.

You can now test the generated WSDL files to verify that you are able to connect to the CICS server and access the service. (Follow the instructions in Application Developer under "Testing the service definitions" in the online help.) You do not have to create the server to run this test.

Remember that if you decide to test the WSDL files now, you must return to this point and continue with Step 6, below, since you have not yet generated the code to deploy the CICS ECI service that you are building.

Back to top

6. Generate the deploy code for the enterprise service

Before you can create an application, you need to generate deploy code for the enterprise service, which can be done using the "Generate Deploy Code" wizard. Although you can generally accept the default values in the wizard and click Finish as soon as the wizard opens, you should navigate through the pages in the wizard to familiarize yourself with the default attributes and values that are specified for the deploy code.

If you do need to change any value in the "Generate Deploy Code" wizard, it will most likely be the inbound binding type. In the Inbound binding type drop-down list, you can select one of the following three values to determine how your deployed service will be executed:

• SOAP: (default) a stateless session bean is generated to execute the service, and SOAP deployment code is generated to execute the stateless session bean.
• EJB: a stateless session bean is generated to execute the service.
• JMS: a message-driven bean (MDB) is generated that will execute the service.

Depending on which of these values you choose on the initial "Deployment" dialog of the "Generate Deploy Code" wizard, the subsequent pages in the wizard will vary.

Since we want to invoke CICS without having to use SOAP, and because we want the best performance, we will use the EJB inbound binding type.

The "Generate Deploy Code" wizard generates a stateless session bean to pass the client request to the service and handle the returned response from the service. It also generates deployed classes that allow your session bean to operate on an EJB server, such as WebSphere Application Server. The "Generate Deploy Code" wizard also generates an EAR file for the service, and that EAR file is what you will deploy to the run time or to the WebSphere Studio test environment for testing.

To generate the deploy code for the CICS ECI service:

1. Expand the CICSStrutsDemo service project and cics.custdetail package, then select the service-binding file named CustomerInfoCICSECIService.wsdl.
2. From the toolbar, click the Generate deploy code for a service icon . The "Generate Deploy Code" wizard opens.
3. In the "Deployment" dialog, the WSDL file, service name, and port name default to values based on the service binding file you selected earlier. Since you are creating a service that will use EJB, you have to select EJB from the Inbound Binding type drop-down list. Default values for Enterprise application project and EJB project are specified for you. Select the Generate helper classes check box, then click Next.
4. The "Inbound Service Files" dialog lets you specify the names, file names and location of the EJB service binding and service files. You can accept the generated defaults, since they are based on the interface file name and your selected inbound binding type. Click Next.
5. The "EJB Inbound Service Files" dialog lets you specify the names, file names, and location of the EJB service binding and service files. You can accept the generated defaults, which are based on the interface file name and the EJB binding type. Click Next.
6. In the "EJB Port dialog", leave the default for the JNDI name. This JNDI name is for the EJB binding. You can accept the default. Click Finish. (Tip: To get additional help, press the Tab key to get to the entry field or button in the wizard's page and press the F1 key.)

See the generated files in Figure 11.

The CICSStrutsDemoEJB project contains all the resources for EJB applications, including:

• stateless session bean (CustomerInfoService)
• deployment descriptor
• remote interface
• EJB home
• service definition file (CustomerInfoEJBService.wsdl) that describes the generated session bean
• service project (CICSStrutsDemo) that contains a service definition; this project is zipped as a JAR file and placed in the EAR project (CICSStrutsDemoEAR), together with the CICSStrutsDemoEJB project's JAR file.

At this point, we have an EJB Session bean that is able to access the CICS Server and use the DFHCOMMAREA as input/output parameter. To test this EJB using the J2C connectors, we now have to create and configure the WebSphere Application Server.

Back to top

7. Add a server and server configuration

This step adds a server and server configuration to run the generated session bean. A server identifies the run time environment that you want to use for testing. A server configuration contains information that is required to set up and publish a server. (Skip this step if you want to use an existing server and server configuration to run the session bean.)

The server can be created automatically when testing components, but we will create a server and configuration manually:

1. In the Services view, right-click the server project and select New => Other.
2. Select Server in the left pane and Server and Server Configuration in the right pane. Click Next.
3. The "Create a New Server and Server Configuration" wizard opens. This wizard creates a new server and configuration at the same time.
4. Type WASV5 as the server name and follow the instructions in the wizard to specify the details of the server and server configuration that you want to create.
5. On the "Create a new server and server configuration" dialog, select Test Environment from the Server type list. Note that an EE (Enterprise Edition) server is not required for a simple J2C connector. See Figure 12.
   Figure 12. Creating a server and server configuration
   
   
6. Click Finish.

Open the Server perspective and see:

• The new server and configuration folder appears under the Servers project folder in the Navigator view.
• The server also appears in the Servers view and the Server Configuration view.
• The server configuration also appears in the Server Configuration view.

Back to top

8. Add JAAS authentication to the server configuration

This activity is dependent on your specific environment.

WebSphere Application Server V5 fully supports the Java Authentication and Authorization Service (JAAS) architecture and extends the access control architecture to support role-based authorization for J2EE resources, including servlet, JSP and EJB components. To use JAAS authentication, you have to add JAAS authentication entries to the server configuration, as follows (Figure 13):

1. Using the Server perspective and the Server Configuration view, select the server WASV5 and double-click to open the server configuration properties.
2. Click the Security tab.
3. For JAAS Authentication Entries, select Add.... The Add JAAS Authentication Entry dialog opens.
4. Enter the value cicsentry for Alias, User ID and Password.
   
   For J2C, the alias name is used as the user ID to obtain a connection to the back end system. When you add the J2C connection factory, you have to select this alias name for the component-managed and container-managed authentication aliases. For more information on JAAS support, refer to the Java Authentication and Authorization Service subject using the Help feature.
   Figure 13. Adding a JAAS authentication entry
   
   
5. Click OK.

Back to top

9. Add a connection factory to the server configuration

This step is required step because we will implement our CICS connection using the J2C adapter.

A connection factory for the J2C resource adapter in the server configuration provides the connections to CICS. When defining the connection factory, you specify all the information needed by the resource adapter to connect to the particular instance of CICS, and also specify the Java Naming and Directory Interface (JNDI) lookup name under which the new connection factory instance would be available to components. With this lookup name, the components can quickly make a connection to CICS. At run time, a factory object can generate a connection, locate the CICS server, and invoke the CICS program at the server.

To add a connection factory:

1. Using the Server perspective, expand Servers in the Server Configuration view.
2. Double-click on the server WASV5 to open it in an editor.
3. Select the J2C tab. With WebSphere Application Server, depending on what you are administering, you can configure at the cell, node, or server level; cells contain nodes which contain servers. Values specified at a higher level apply at the lower levels, unless they are overridden at the lower level. In the J2C page, you can define a connection factory at the node level and it will apply to all servers that it contains, or you can define the connection factory at the server level. Click Add, which is next to the J2C Resource Adapters table. The "Create Resource Adapter" wizard opens.
4. Select the name of the resource adapter from the Resource Adapter Name drop-down list. In our example, select Resource Adapters Project, then click OK.
5. In the server configuration editor, select the new ECIResourceAdapter in the J2C Resource Adapters table, then click Add, which is next to the J2C Connection Factories table. The vEdit Connection Factory" wizard opens.
6. In the "Edit Connection Factory" wizard, enter the following values (Figure 14):
   • Name: CICSECI_CF
   • JNDI name: eis/cicseci
   • Container-managed authentication alias and Component-managed authentication alias: cicsentry (the same alias that was specified in the Security page).
   Optionally specify other values, then select OK. You will later bind this J2C connection factory's JNDI name to the generated deploy code's session bean.
   Figure 14. Connection factory
   
   
7. In the server configuration editor, enter the connection properties in the Resource Properties table. For instance, you may enter the following values (Figure 15):
   • ServerName: DEMOTCP (name of the CICS server)
   • ConnectionURL: localhost (URL of the CICS Transaction Gateway to access the server)
   • PortrNumber: 2006 (leave default).
   
   Figure 15. Connection factory specifications
   
   
8. Close the editor and click Yes to save the changes.

Note that the CICS Transaction Gateway (CTG) configuration must match the specifications in the J2C Connection Factory. Figure 16 shows the definitions that were made in the CTG for our example.

Back to top

10. Bind the connection factory

Now we need to bind the J2C connection factory to the generated (deploy code's) stateless session bean. To bind the JNDI name:

1. Using the Business Integration perspective and the Services view, expand Deployable Services.
2. Right-click on CICSStrutsEJB project, then select Open with => Deployment Descriptor editor. When open, select the Reference tab (Figure 17).
3. In the EJB container, expand the EJB project and the session bean until you can see and select ResourceRef.
4. Under "WebSphere Bindings", enter the value eis/cicseci as JNDI name of the J2C connection factory that you have added to the server configuration.
5. Press Ctrl+S to save the changes.
   Figure 17. Binding the EJB to the J2C Connector
   
   

Back to top

11. Test the session bean

We are now ready to test the EJB session bean that calls the CICS Server. Before testing our code, you have to start the TXSeries and the CICS Transaction Gateway.

To start TXSeries:

• Select Start => Programs => IBM TXSeries => CICS => IBM TXSeries Administration Tool.
• When the Administration window is open, select DEMO and apply the action Start.
• When prompted for auto or cold, specify auto. After a few minutes a signal sound and a message indicate that the CICS is started: Region 'DEMO' started successfully.

Figure 18 shows a window that indicates that TXSeries is ready to be used.

To start CICS Transaction Gateway:

• Select Start => Programs => IBM CICS Transaction Gateway => IBM CICS Transaction Gateway.
• This program is started immediately. A window will open and a message will be display, like CCL6524I: Successfully started handler for the tcp: protocol.

At this point, the server is ready. (Remember, however, that DB2 must also be started.)

To test the EJB, use Application Developer and the Universal Test Client tool to make sure that the generated session bean is functional. The Universal Test Client enables you to view and invoke methods, objects, and classes to test the session bean.

To invoke and use the Universal Test Client:

1. In the Services view, under Deployable Services, select the EJB project that contains the session bean. Expand the project until you find the session bean CustomerInforService, right-click and select Run on Server.
2. In the "Server Selection" wizard, select the server you created, WASV5, then click Finish.
3. In the "Referencesv pane, under EJB References, expand the session bean, then the home bean. Select the create method for the home bean.
4. In the "Parameters" pane, click Invoke. This creates the home object for your session bean and displays a Work with Object button.
5. Click Work with Object. This creates a new bean in the "References" pane.
6. Expand this new bean to display a list of methods that can be executed in the bean. Select a method you want to execute.
7. In the "Parameters" pane, the input field for the selected method is displayed. Enter a value and click Invoke to run the method. A result is returned to the Results field.
8. You may select other methods and continue similar testing. When testing is complete, close the test client. (Refer to the online help for more details.) Figures 19 and 20 show an example of the EJB test where we entered 1 for the customer number and received Daniel as the first name.
   Figure 19. Testing the EJB to access CICS (1 of 2)
   
   
   Figure 20. Testing the EJB to access CICS (1 of 2)
   
   

At this point, we have an EJB session bean named CustomerInfoService that returns the data accessed by the COBOL/CICS program. Figure 21 shows what we have done so far. What we are missing is the Web portion that invokes the EJB.

Back to top

12. Add the required code in the EJB to access customer information

Before coding the Struts application, we need to add code to the generated session bean to set the customer number before the CICS call, and to retrieve the customer information (name, address, city, state, country) after the CICS call. This could be done in many ways. In our example, we provide simple access to the DFHCOMMAREA by defining individual fields for the customer information and extracting the data from the DFHCOMMAREA into these fields. Basically, you will need to edit the Java class CustomerInfoServiceBean and:

1. Create variables for each of the customer data items you will need to pass to the EJB when invoking the getCustomerInfo method, like customerNumber, name, lastName, adress1, city, etc.
2. Create the getters and setters for those variables of the Java class being edited: using the context editor, select Source => Generate Getter and Setter.
3. Add the necessary code to initialize the DFHCOMMAREA with the customerNumber before calling CICS, and then retrieve the data after the invocation of the method that calls CICS. This must be done in the method getCustomerInfo. The code to be added in the CustomerDetailsServiceBean class appears in bold type below:

   // added int customerNumber; String name; String lastName; String adress1; String city; String state; int accountNum; String country; DFHCOMMAREA record = new DFHCOMMAREA(); // added until here public cics.custdetail.DFHCOMMAREA getCustomerInfo( cics.custdetail.DFHCOMMAREA argDFHCOMMAREA) { try {initialize(); // added --> user code begin {pre_execution} setRecord(argDFHCOMMAREA); record.setCustNo(getCustomerNumber()); // user code end WSIFDefaultMessage aMessage = new WSIFDefaultMessage(); aMessage.setObjectPart("dFHCOMMAREA", argDFHCOMMAREA); WSIFMessage outputMessage = execute("getCustomerInfo", "getCustomerInfoRequest", "getCustomerInfoResponse",aMessage, REQUEST_RESPONSE); // added --> user code begin {post_execution} this.record = (cics.custdetail.DFHCOMMAREA) outputMessage.getObjectPart("dFHCOMMAREA"); setName(record.getFirstName()); setAccountNum(record.getAcctNumList(1)); setAdress1(record.getAddress1()); setCountry(record.getCountry()); setLastName(record.getLastName()); setState(record.getState()); setCity(record.getCity()); // user code end return (cics.custdetail.DFHCOMMAREA) outputMessage.getObjectPart("dFHCOMMAREA"); } catch (Exception e) {

   
   
4. Promote the generated getter and setter methods to Remote Interface. To do this, select the method, then using the context editor, select Enterprise Bean => Promote to remote Interface. See the result of the promote in Figure 22.
   Figure 22. Methods promoted to the remote interface
   
   
5. Deploy the EJB again; using the J2EE view, select the bean CustomerInfoService, then Generated Deploy Code.

If you want to run the EJB at this point (you'll need to stop and start the server) and retrieve the customer data, you will need to execute the methods in this sequence:

1. create
2. setCustomerNumber
3. getCustomerInfo (call to CICS)
4. getName, getLastname, etc.

Back to top

13. Create an access bean

EJB access beans can greatly simplify client access to enterprise beans, and they can also alleviate many of the performance problems associated with remote calls for multiple enterprise bean attributes. Access beans are Java bean representations of enterprise beans, and are typically used in client programs that employ JavaServer Pages (JSP) files, servlets, or enterprise beans that interface with other enterprise beans. Access beans shield you from the complexities of managing enterprise bean lifecycles. This means that you can program to enterprise beans as easily as you can program to Java beans, which greatly simplifies your enterprise bean client programs and helps reduce your overall development time.

To create an access bean for the CustomerInfoService:

1. Switch to the J2EE Hierarchy view.
2. Select the EJB CustomerInfoService. Fom the context menu, select New => Access Bean. The "Access Bean Creation" wizard opens.
3. Select the Java bean wrapper radio button, then Next.
4. Be sure that the correct EJB project name appears in the EJB Project field. The correct project is the one that contains the enterprise bean for which you want to create an access bean.
5. In the Enterprise Bean field, ensure that CustomerInfoService is selected, then click Finish. A class named CustomerInfoServiceAccessBean is generated. This class will be used in the Web project to call the session bean that invokes CICS.

Back to top

14. Create a Web project that supports Struts

The sequence here can be performed using the Cheat Sheet selection:

1. In the action bar, select Help => Cheat Sheets => Other... => Struts => Create a Struts-based Web application. This operation will guide you through the wizards required. Figure 23 shows the "Cheat Sheets" dialog that we will execute in these steps.
   Figure 23. Cheat Sheets for Struts
   
   
2. In the "Create a Web Project" dialog, enter CICSStrutsDemoWeb for the Context root, and use the existing project CICSStrutsDemoEAR (Figure 24). Click Next.
   Figure 24. Creating a Web project
   
   
3. In the "Module dependencies" dialog, select CICSStrutsDemo.jar and CICSStrutsDemoEJB.jar.
4. In the "Struts Settings" dialog, enter or select the following values, as shown in Figure 25:
   • Check Override default settings
   • Struts version: 1.1 (Struts 1.1 has more tag options, but level 1.0.2 would work as well.)
   • Default Java package prefix: cics.struts.demo.web.
5. Click Finish, then OK for the dialog that will repair the server configuration.
   Figure 25. Creating a Web Struts project
   
   

Back to top

15. Create a Web diagram

A Web diagram is a file that helps you visualize and better understand the flow structure of a Struts-based Web application. We will use the diagram editor to show our Struts application:

1. Using the Cheat Sheets, click the Perform icon to create the Web diagram.
2. We can create our Web diagram under the CICSStrutsDemoWeb folder. Type CICSStrutsDiagram as the file name, then click Finish. A blank area will be available for the diagram creation.
3. Use the Struts icons to place new objects into the Web diagram: select an icon, then click in the blank Web diagram space where you want a new object created. In this way:
   • Create two JSPs, named input.jsp and output.jsp.
   • Create one action, named callCobolAction.
   • Create one form bean, named formCICSStrutsBean.
   • Connect the objects using the connector icon (click on source and target objects).
   • When making the connection from the action to the output.jsp, you are prompted for a forward name; use the name OK.
   The final result is shown in Figure 26.
   Figure 26. Empty diagram
   
   

Back to top

16. Create the components (JSPs, action and form bean)

Using the Cheat Sheets, click the perform icon to create the components. The dialog shown in Figure 27 opens.

A form bean is an instance of an ActionForm subclass that stores data. We must define in the form all the variables that we want to access in our application. When a browser submits a Struts form, the ActionServlet:

1. looks at the field names from the HTML form
2. matches them to the property names in the form bean
3. calls the setter methods of these variables to put the values retrieved in the HTML form.

In addition, if you implement a validate method and set the validate flag in the corresponding action mapping entry in the Struts configuration file, the ActionServlet invokes the validate method of the form bean.

To create the form bean:

1. Double click the formCICSStrutsBean. (Minimize the Cheat Sheets; we will use them again later.)
2. Accept the defaults in the first dialog and click Next.
3. In the Choose new accessors dialog, also click Next.
4. In the Create new accessors dialog, we create all the variables that we want to use. Figure 28 shows the contents of this page with all the variables defined.
   Figure 28. Creating the accessors for the form bean
   
   
5. Click Finish to create the Form bean.
6. Since we want to validate the input data typed, we will now add a method, called validate, as shown in figure 29.
   Figure 29. Validate method in the form bean
   
   
7. Now, let's create the input.jsp. Double-click on input.jsp to open the wizard.
8. Accept all the defaults and click Next until you reach the Form Field Selection dialog.
9. Select the formCICSStrutsBean form and the customerNumber field, as shown in Figure 30.
   Figure 30. Creating the input.jsp
   
   
10. Click Finish. A JSP model will be generated, as shown in Figure 31.
    Figure 31. Input.jsp generated
    
    
11. Using the Cheat Sheet or the diagram, double-click the output.jsp. This JSP page should display the results returned by the COBOL/CICS call. We also can use the wizard to generate the JSP automatically.
12. As before, when the "New JSP File dialog" opens, accept all the defaults and click Next until you reach the "Form Field Selection" dialog.
13. Select the formCICSStrutsBean form and all the fields that we want to show (Figure 32):
    • city
    • country
    • accountNumber
    • state
    • firstName
    • lastName
    • adress1.
14. In the "Design the Form" dialog, use the up and down arrows to rearrange the order of the fields.
15. Select the Fields button at the bottom, and in the Field Type field, change from the value from text to static text. See this selection in Figure 32.
    Figure 32. Design the output.jsp
    
    
16. Click Finish. Note that some buttons will be generated in the JSP. Since we don't need buttons, we can select and delete them.
17. Select the Source tab and also delete this tag pair in the source: <html:form action="">and </html:form>. The result is shown in Figure 33.
    Figure 33. Output.jsp with the Struts tags
    
    
18. Note that a <bean:write> is generated automatically, with the property names set. Select the Source tab to see the generated code:

    <bean:write name='formCICSStrutsBean' property='firstName' /> <bean:write name='formCICSStrutsBean' property='lastName' /> <bean:write name='formCICSStrutsBean' property='adress1' /> <bean:write name='formCICSStrutsBean' property='city' /> <bean:write name='formCICSStrutsBean' property='state' /> <bean:write name='formCICSStrutsBean' property='country' /> <bean:write name='formCICSStrutsBean' property='accountNumber' />

    
    

Be careful that the form bean name is formCICSStrutsBean (first letter is lowercase), even though the Java class will be FormCICSStrutsBean. This is a common mistake.

Back to top

17. Create the action

A Struts action is an instance of an Action class that implements a portion of a Web application and returns an object. An action mapping is a configuration file entry that associates an action name with an action, a form bean, and a local forward. In this step, we will implement the action associated with the Web diagram, and in this action, we will execute the COBOL/CICS call.

Using the Cheat Sheets:

1. Click the Perform icon .
2. In the "Select Action" dialog, double-click on /callCobolAction .
3. The "New Action Mapping" wizard opens. For Form Bean Name, select formCICSStrutsBean, then click Next.
4. In the "Create an Action class for your mapping" dialog, change the generated name of Action class name to CallCobolAction, then click Finish. See Figure 34.
   Figure 34. Creating an action class
   
   
5. In the CallCobolAction class, add the necessary Java code to call the access bean that will use the EJB session bean to call COBOL/CICS. The code below in bold type was introduced in the execute method:

   import cics.custdetail.CustomerInfoServiceAccessBean; .... public ActionForward execute( ActionMapping mapping, ActionForm form, HttpServletRequest request, HttpServletResponse response) throws Exception { ActionErrors errors = new ActionErrors(); ActionForward forward = new ActionForward(); // return value FormCICSStrutsBean formCICSStrutsBean = (FormCICSStrutsBean) form; try { // do something here cics.custdetail.DFHCOMMAREA record = new cics.custdetail.DFHCOMMAREA(); CustomerInfoServiceAccessBean acess = new CustomerInfoServiceAccessBean(); acess.setCustomerNumber(formCICSStrutsBean.getCustomerNumber()); acess.getCustomerInfo(record); // perform the CICS call formCICSStrutsBean.setFirstName(acess.getName()); formCICSStrutsBean.setAccountNumber(acess.getAccountNum()); formCICSStrutsBean.setAdress1(acess.getAdress1()); formCICSStrutsBean.setCity(acess.getCity()); formCICSStrutsBean.setCountry(acess.getCountry()); formCICSStrutsBean.setLastName(acess.getLastName()) // ============ } catch (Exception e) {

   
   
6. When you save this class, errors are displayed in the task list because some required JAR files are missing in the Java build path. Figure 35 shows these error messages.
   Figure 35. Errors when in the class CallCobolAction
   
   To correct these errors, select the project CICSStrutsDemoWeb, and use the "Propertitesv dialogs to add the external JAR files: wsadie_install_path\runtimes\base_v5\lib\wsatlib.jar
   wsadie_install_path\runtimes\base_v5\lib\wsif.jar The warning message is acceptable. See Figure 36 for our example.
   Figure 36. Library JAR files required for using CICS ECI
   
   

Note that it is preferable to use variables to give you more flexibility, rather than using an "external" JAR file, which was used in our example for the sake of simplicity.

Back to top

18. Test the Web application

Before testing the application, start a program called cicstail to monitor the CICS call so you can be sure that the COBOL program gets invoked. To run this program, open a command window and execute:

cicstail.exe -r DEMO

A window opens for monitoring. Keep this window open when testing your code so you will be able to monitor during execution.

To test your application:

1. Use the Web perspective and the J2EE Navigator view. Select input.jsp located in the project CICSStrutsDemoWeb/Web Content and select Run on Server.... See Figure 37. The application is published to the application server (WASV5), and execution starts by displaying the input.jsp.
   Figure 37. Testing the Struts application.
   
   
2. For data, enter a value of 1, and click Submit. The cicstail program informs you that a program called WBCSTDT2 has been called. (See Figure 38.)
   Figure 38. Calling COBOL/CICS program
   
   
3. The result of the execution is shown in Figure 39.
   Figure 39. Execution results
   
   The results indicate that the CICS COBOL program read the DB2 data, retrieved customer information associated with Customer Number 1, and then passed the data back to the Java client.
   
   If you forgot to remove the <html:form action="">and </html:form> tags from the output.jsp source, you will get the error: E SRVE0026E: [Servlet Error]-[Cannot retrieve mapping for action / This html code was associated with the buttons that we deleted.

Back to top

19. Customize the code using Struts properties and error messages

Our application is already accessing the server and performing most of the important tasks, but we still want to make some improvements, like validating the input data, displaying error messages, changing the appearance and using the Struts properties for possible translation to other languages.

For example, with the code that has been completed so far, if you enter a value of 0 in the first JSP page during execution, an error message will be generated on the application server console:

We coded some validation in the form bean, as seen in Figure 29. Therefore, it is necessary to add some modifications to the generated files:

1. Define Struts application resources:

   The ApplicationResources.properties file (under Java Source and cics.struts.demo.web.resources) contains the text constants that we require in the JSPs, and the error messages from the business logic. Open the file and add the code in bold face, shown below. Save and close when done.

   # Optional header and footer for <errors/> tag. #errors.header=<ul> #errors.footer=</ul> # input.title=Calling COBOL/CICS Example input.customerNumber=Enter the customer number input.submit=EXECUTE error.customer.required=Customer Number cannot be zero error.customer.number=Customer Number must be smaller than 11 result.title=Result from COBOL/CICS call

   
   
2. Modify the input JSP:

   The JSPs must be modified to enable them to use the Application Resources and Struts capabilities:

   1. Edit the input.jsp and be sure that the option JSP => Show Visual Custom Tags is selected; otherwise, you will only see icons when designing the JSPs.
   2. Open the Properties view by selecting Window => Show View => Properties.
   3. Using the "Design" page, and with the cursor on the left border, add a heading by selecting JSP => Insert Custom. In the dialog, select the bean tag library (left) and message (right), then select Insert and Close. Select the new entry, Missing message for key. In the Properties view, enter a value of input.title for Key value. This is a reference to the resources file.
   4. Select the new heading (must display black when selected), then either select Format => Paragraph => Heading 1, or add <h1> and </h1> tags around the heading in the source page
   5. In the same way, we will replace the literal "customerNumber" with custom tags of type bean => message with a key value. To do this, remove the literal "customerNumber", and in its place select JSP => Insert Custom, bean (left), message (right), then Insert and Close. In the Properties view, enter input.customerNumber as the Key value.
   6. Delete the Submit button and add a custom tag by selecting html => submit. In the Source view, you can then insert a custom bean => message into the submit button, using the key input.submit. The result is: <TD><html:submit>
      <bean:message key="input.submit"></bean:message>
      </html:submit></TD>
      
   7. Using the Design page again, add a custom tag html => errors, between the heading and the form, to display error messages.
   8. Drag an image from the Gallery view and drop it in the top of the JSP page; in our example, we'll use cut018.gif from the Illustration folder. The final layout is shown in Figure 40.
      Figure 40. Input JSP page, customized
      
      
3. Modify the output JSP:
   
   Performing a similar sequence as in step 2, above, change the output page by adding the message key result.title to the header, using Format => Paragraph => Heading 1 to format the header. See the results in Figure 42.
   Figure 41. Output JSP, customized
   
   
4. Modify the Struts configuration:
   
   Using the J2EE Navigator view, open the struts-config.xml file, located under the CICSStrutsDemoWeb/Web Content/WEB-INF folder. On the Actions page, select the callCobolAction and set the Input field to /input.jsp (move the cursor out of the field to be sure it was entered). Save and close. The Input field sets the JSP that is redisplayed in case of validation errors.

You now have a better application than before, since the application can now use some of the Struts resources. Stop the server and test the applications again, as described above. Use the values 0 and 11 (invalid Customer Number) to see the error messages. Figure 42 shows the output when the value 11 is used.

Back to top

Conclusion

Congratulations! You have now implemented an application that uses Struts where the connection to CICS is accomplished using the J2C Connector. Although this is a relatively simple example, it's easy to see how the application created here can be extended to become as sophisticated as necessary. Also in our example, we used CICS running under Windows. If your CICS Server is running in z/OS, you will need to apply some updates in the WSDL Port Type and Binding Operations (see Step 5), regenerate some Java code, and update the J2C configuration.

Regardless of the complexity of the application and the backend platform being accessed, you will find that the steps for coding, testing and debugging the application would, in either case, be very similar to what has been outlined here.

Back to top

Download instructions

• To import the EAR file to your workspace (after downloading it):
  • Go to the Navigator view in Application Developer, and select Import... from the context menu.
  • Select EAR file => Next => CICSStruts.ear, specify CICSStrutsEAR as the Project name, then click Finish.
  You will need to create a WebSphere Application Server to test the application. Even if this is done automatically, you will need to define the data source and the J2C connector information as specified in this article. For instructions how to install the base required software and database for the tutorial, see the Read_me_first.doc file that is part of the file that ZIP file, below.

Back to top

Download

Name	Size	Download method
WSADIE_CICS_STRUTS_files.zip	1.6 MB	FTP|HTTP

	Information about download methods

Resources

• Java 2 Platform, Enterprise Edition (J2EE)
  
  
• Redbook: Java Connectors for CICS, Phil Wakelin, Martin Keen, Richard Johnson and Daniel Cerecedo Diaz
  
  
• Redbook: CICS Transaction Gateway V5 - The WebSphere Connector for CICS, Phil Wakelin, John Joro, Kevin Kinney and David Seager
  
  
• Redbook: WebSphere Studio Application Developer Version 5 Programming Guide, Ueli Wahli, Ian Brown, Fabio Ferraz, Maik Schumacher and Henrik Sjostrand
  
  
• Redbook: Exploring WebSphere Studio Application Developer Integration Edition 5.0, Osamu Takagiwa, Rama Krishna V. Guddati, Martin Keen and Soeren Kristiansen
  

About the author

		Reginaldo Barosa is an IBM Certified Application Development Specialist. He provides sales support, helping customers with WebSphere application development tools such as VisualAge Generator and WebSphere Studio. Before joining IBM US three years ago, Reginaldo worked for 27 years in IBM Brazil. He has co-authored IBM Redbooks and has written two books, as well as other articles for the developerWorks WebSphere Web site. He has a degree in Electrical Engineering from Instituto Mau de Tecnologia in San Paulo, Brazil. You can contact Reginaldo at rbarosa@us.ibm.com.

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Share this.... Digg this story del.icio.us Slashdot it!

Back to top