Why use the IRAD J2C tooling?

The IBM® Rational® Application Developer (IRAD) tooling greatly simplifies the process of accessing a CICS® program as a Web service. This article will demonstrate how a CICS program can be exposed as a Web service without writing a single line of code, and how the use of a few simple wizards can greatly speed up development time when integrating your legacy programs in a Service-Oriented Architecture.

Back to top

Prerequisites

This example uses the following levels of software:

• IBM® Rational® Software Architect v6.0.0.1 (IRSA). IRAD v6.0.0.1 is also supported
• IBM® WebSphere® Application Server v6 (test environment shipped with IRSA)
• CICS Transaction Gateway v6
• CICS Transaction Server v3.1

In addition, the following runtime combinations are supported:

This article assumes that the CICS Transaction Gateway has already been installed and configured to connect to the target CICS Transaction Server. For more information on this task refer to the CICS Transaction Gateway v6 documentation. You will also need to have a copy of the ec01.ccp sample that comes supplied with the CICS Transaction Gateway on your workstation. This is a very simple program that receives a commarea, populates it with the current date and time on the CICS server, and returns it.

Back to top

Overview

This article will show you how to create a J2C Bean, and a Java™ Data Binding that will be used to call the CICS Transaction Gateway, which in turn will access the CICS Transaction Server. You will also expose the J2C Bean as a Web Service Endpoint, which will receive Simple Object Access Protocol (SOAP) requests. All the artifacts you create will run on WebSphere Application Server. Figure 1 illustrates all the pieces and how they fit together.

Back to top

Create the projects

The first step is to create projects in to which you can put your Web application. You will create an enterprise archive (EAR) project, which you can deploy into WebSphere, and within that a Dynamic Web Project to hold the Web service and Java components that will be created.

1. From the Java™ 2 Platform, Enterprise Edition (J2EE™) perspective, create a new EAR project called EC01EAR, with J2EE version 1.4 and Target server WebSphere Application Server v6.
2. Create a new Dynamic Web Project (EC01Web) in EC01EAR, and fill in as shown in Figure 2.

3. Click Finish, and do not switch to the Web perspective when asked.

Back to top

Create Java Data Binding

You will use wizards to create a mapping from a COBOL structure to a Java object, and vice-versa. This is necessary because the COBOL executing on CICS is expecting a COBOL record structure, in EBCDIC, whereas our Web application will manipulate Java objects in ASCII.

1. Under Dynamic Web Projects, right-click EC01Web and select New -> Other. In the select a Wizard dialog, under J2C select CICS/IMS Java Data Binding and click Next.
2. On the Data Import screen, in the Choose mapping field select COBOL to Java. Next to COBOL file select the location of your ec01.ccp file. (C:\Program Files\IBM\IBM CICS Transaction Gateway\samples\server\ec01.ccp). Click Next.
3. The Importer field is where you select the code page conversion that will be done. Select Platform: z/OS.
4. Under Data Structures, click Query. When the list has been populated, select DFHCOMMAREA and click Next. See Figure 3 following for examples.

5. On the next page, leave generation style as Default. The Project name should be EC01Web. Enter a package name (for this example, use ec01test.data). You can leave the class name as DFHCOMMAREA.
6. Click Finish. This should have created a DFHCOMMAREA.java file in the Web project. You will use this class later to pass and receive data from CICS.

Back to top

Create J2C Java Bean

Now you will use the wizard to create a bean, which means you do not have to write any code yourself to use the CCI interface to the CICS Transaction Gateway to call the program on CICS. This wizard will use the Java Data Binding you created in the previous section.

1. Under Dynamic Web Projects, right click EC01Web and select New -> Other. In the select a Wizard dialog under J2C, select J2C Bean and click Next.
2. The Resource Adapter selection window is where you select the Resource Adapter you are going to use. Select the J2C 1.5 ECI Resource Adapter and click Next. See Figure 4 following for an example.

3. On the Connection Properties page you will use a managed connection.
4. Next to JNDI lookup name click New. This will take you through a wizard that will create a Connection Factory on your WebSphere Application Server v6 Test Environment.
5. On the Server Selection page select WebSphere Application Server v6 and click Next.
6. On the New J2C Connection Factory page, you enter the values for the Connection Factory that will be created in WebSphere. These values will depend on your installation. The Server name should match the server you created using the Configuration tool, and a Connection URL of local: means it will use the Gateway in local mode on the local machine. For more information on these parameters consult the CICS Transaction Gateway documentation. An example is shown in Figure 5 following.

7. When you have filled it in, click Finish. This step will take some time, as it will start the test server, and then create a new Connection Factory on it. When this has finished it should have filled in the JNDI lookup name on the Connection Properties window. Click Next.
8. The J2C Bean Output Properties window lets us select names for the generated classes. The Project name should be EC01Web, the Package Name ec01test.bean, the Interface Name EC01J2CBean, and it should automatically fill in the Implementation Name as EC01J2CBeanImpl. Click Next.
9. In the Java Methods page you can add a method for each Program you want to access in CICS. Click Add.
10. The Method Name should be callEC01. Click Next.
11. On the next page, select the inputs and outputs for the method. These should be the data type(s) you created earlier. Next to Input type, click Browse.
12. In the window that appears next, select the DFHCOMMAREA class you created earlier. EC01 uses the same structure for input and output, so select the Use the input type for output checkbox. Click Finish.
13. For Function name enter EC01. This is the name of the program that will be called on CICS. Commarea length should be 20, as should Reply length under the advanced properties. The Interaction verb should be SYNC_SEND_RECIEVE because you want a synchronous call. Click Finish.
14. This should open up the implementation class that has been created (EC01J2CBeanImpl.java).

In the wizard you selected SYNC_SEND_RECIEVE for the Interaction verb. This has resulted in the following line being added to the code: ((com.ibm.connector2.cics.ECIInteractionSpec) is).setInteractionVerb(2); This is a bug in IRAD, as an Interaction verb of 2 is actually a SYNC_RECIEVE. This will result in an error at runtime unless you change this to 1. Change this in the code, and in the comments above the method. So the callEC01 method should look like this:

/**
 * @j2c.interactionSpec class="com.ibm.connector2.cics.ECIInteractionSpec"
 * @j2c.interactionSpec-property name="functionName" value="EC01"
 * @j2c.interactionSpec-property name="commareaLength" value="20"
 * @j2c.interactionSpec-property name="replyLength" value="20"
 * @j2c.interactionSpec-property name="interactionVerb" value="1"
 * @generated
 */
public ec01test.data.DFHCOMMAREA callEC01(ec01test.data.DFHCOMMAREA arg) throws 
                                                    javax.resource.ResourceException {
    ConnectionSpec cs = getConnectionSpec();
    InteractionSpec is = interactionSpec;
	if (is == null) {
		is = new com.ibm.connector2.cics.ECIInteractionSpec();
        ((com.ibm.connector2.cics.ECIInteractionSpec) is).setFunctionName("EC01");
        ((com.ibm.connector2.cics.ECIInteractionSpec) is).setCommareaLength(20);
        ((com.ibm.connector2.cics.ECIInteractionSpec) is).setReplyLength(20);
        ((com.ibm.connector2.cics.ECIInteractionSpec) is).setInteractionVerb(1);
}
...

This Java class can now be used to call the program on CICS by invoking the callEC01 method, and using the DFHCOMMAREA Java Data Binding you created.

Back to top

Create a Web service to use the J2C bean

The previous step created a bean that contains the code to call the CICS program. Now you can use the wizards to expose this as an Enterprise JavaBean™ (EJB™), a JavaServer™ Page (JSP), or as a Web service. In this example you will expose it directly as a Web Service, but the other wizards can be used in a similar way to create an EJB or JSP.

1. Right click the EC01J2CBeanImpl.java file in the project explorer (Under EC01Web/JavaResources/JavaSource/eco01test.bean), and select New -> Other.
2. In the select a Wizard dialog, under J2C select Web Service, Web Page, or EJB from J2C bean, and click Next.
3. J2C Bean Implementation should be filled in with /EC01Web/JavaSource/ec01test/bean/EC01J2CBeanImpl.java. Click Next.
4. Under J2EE Resource type, click Web Service. Click Next.
5. On the Web Service creation page the Web Project should be EC01Web, and the EAR project should be EC01EAR. Under the Advanced properties enter a Resource Reference of CICS1Ref, and the JNDI lookup name should be CICS1. (This should match the JNDI Name you entered when creating the Connection Factory, as shown in Figure 5). Click Finish and it will generate the Web service.

Back to top

Testing the Web service

Now that your Web service has been created, you want to run it, and test it to make sure that it works from end to end. IRAD provides a number of features that enables us to do this. The first is the WebSphere Application Server v6 Test Environment. This is a version of WebSphere Application Server that comes as part of IRAD, and lets you install and run your Application (EAR file). The second is the Web Services Explorer. This feature is supplied with a WSDL file, and it uses this to create a Web Services client. The client enables you to fill in the parameters, send these in a SOAP message to the endpoint, and receive in return the response from the Web service.

1. Ensure that the CICS Transaction Server and CICS Transaction Gateway are started.
2. Right-click the EC01EAR, and select Run -> Run on Server. This will deploy the application on the test server.
3. Under EC01Web, expand Web Content, and wsdl and right-click EC01J2CBeanImpl.wsdl and select Web Services -> Test with Web Services Explorer, as shown in Figure 6 following.

4. This should bring up the Web Services explorer in a Web browser. In the Explorer, expand the tree in the navigator, and then click callEC01.
5. The action page is where you fill in the parameters for a call. You do not need to fill any in for this request, so click Go to invoke your Web service, as shown in Figure 7.

6. When the invoke completes, Figure 8 illustrates how you should be able to see the Date and Time returned from CICS in the status window.

Resources

Learn

• CICS TG v6 Information center: For more information on the CICS Transaction Gateway v6.
  
  
• IBM Rational Application Developer V6 Programming Guide: For more information on using IRAD.
  
  
• developerWorks WebSphere zone: You'll find technical documentation, how-to articles, education, downloads, product information, and more.
  
  
• developerWorks SOA and Web Services zone: For more information about Web services and SOA.
  
  
• IBM Rational Application Developer product page: Find technical documentation, how-to articles, education, downloads, and product information about IRAD.
  
  
• J2EE Connector Architecture: For more information on the J2EE Connector Architecture.
  
  

Get products and technologies

• IBM trial products for download: Build your next development project using IBM trial software, available for download directly from developerWorks.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Rational Software Architect, Software Modeler, Application Developer and Web Developer forum: Ask questions about Rational Application Developer.
  
  
• developerWorks blogs: Participate in the developerWorks community.
  
  

About the author

Dan McGinnes is an IT specialist working in the Pan-EMEA WebSphere services group, with previous experience in the CICS TS and CICS TG development teams.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Why use the IRAD J2C tooling?
• Prerequisites
• Overview
• Create the projects
• Create Java Data Binding
• Create J2C Java Bean
• Create a Web service to use the J2C bean
• Testing the Web service
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Rational Application Developer for WebSphere Software
• Demo: Build, test and deploy JAX-WS Web services
• Webcast: Webcast: Develop innovative applications efficiently using the right application foundation in today's economy
• Briefing: Software development conference
• Buy: Rational Application Developer for WebSphere Software

My developerWorks community

Dig deeper into Rational on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers