Using WebSphere Developer for zSeries V6 to Connect to COBOL/CICS

An Example Using J2EE Connectors, CICS Transaction Gateway and CICS Transaction Server for WebSphere

This article shows you how to use WebSphere Developer for zSeries to create and test workstation code that accesses CICS without having to deploy to the mainframe.

Reginaldo Barosa (rbarosa@us.ibm.com), Senior Certified Application Development Specialist, EMC

Author photoReginaldo W. Barosa is an IBM Senior Certified Application Development Specialist. He provides sales support, helping customers with application transformation solutions and development tools such as WebSphere Studio Enterprise Developer. Before joining IBM US more than six 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 IBM developerWorks. He holds a degree in Electrical Engineering from Instituto Maua de Tecnologia, Sao Paulo, Brazil. You can reach Reginaldo at rbarosa@us.ibm.com



14 September 2005

Introduction

Integrating existing systems made up of COBOL/CICS®-based applications with systems running under Web application servers using Java™ is a common requirement. For those facing such a task, this article uses an extended example to show you how to code Java classes that connect to an existing COBOL/CICS program using the J2EE Connector (J2C) tools included in IBM® Rational® Application DeveloperVersion 6.0.0.1. The article then shows you how to test your solution using CICS Transaction Gateway (CTG) and CICS Transaction Server for Windows®, which are included in WebSphere® Developer for zSeries®Version 6.0.

The objective of this article is to create and test the code accessing CICS, using WebSphere Developer for zSeries on a workstation, without being required to deploy to the mainframe. You can also create the connectors using only Rational Application Developer, but you would not be able to test the completed connectors. Since WebSphere Developer for zSeries is installed on top of Rational Application Developer, you can use all of the capabilities of both products.

This article uses viewlets to present several brief animated examples. When you see the symbol , double-click on it, and an animation sequence will demonstrate a specific development task for you.

Connecting to an existing COBOL/CICS program

You can connect to COBOL/CICS using many different technologies. This tutorial uses the J2EE Connector Architecture (JCA), which is an open architecture and fully compliant with J2EE specifications.

The J2EE Connectors (J2C) tools, resource adapters, and file importers let you create J2EE Connector artifacts, which you can use to create enterprise applications. These tools also enable you to create J2EE applications running on WebSphere Application Server to access operations and data on an Enterprise Information System (EIS) such as CICS or IMS. Running on a J2EE application server provides several advantages:

  • Security credential management
  • Connection pooling
  • Transaction management

These advantages are provided by system-level contracts between a resource adapter provided by the connector (CICS Transaction Gateway or IMS Connect, for example), and the application server. You do not need to provide any extra program code, freeing you to concentrate on writing the business code without being concerned with providing quality of service. JCA defines a programming interface, called the Common Client Interface (CCI), and you can use it, with minor changes, to communicate with any EIS.

The following diagram illustrates the architecture of the J2C tools within the development environment:

Figure 1. J2C wizards and JEE Connector Architecture.
J2C Overview

Resource adapters

A resource adapter is a system-level software driver that is used by a Java application to connect to an enterprise information system (EIS). The resource adapters reside on the application server and provide connectivity between the EIS, the application server, and the enterprise application. Applications deployed on the application server communicate with the resource adapter using the CCI. The resource adapters (RAR files) contain all the information necessary for installing, configuring, and running a JCA Resource Adapter. These adapters can be provided by and used by any vendor, if they comply with the JCA specification.

In order for your application to communicate with an EIS like CICS or IMS, you need a resource adapter to create a communication link. J2C tools include a number of resource adapters that let you create and test J2C enterprise applications in a unit test environment. These RAR files can be imported into the workbench and used to create enterprise applications. Two CICS and two IMS resource adapters are shipped with Rational Application Developer V6.0.0.1 and with WebSphere Developer for zSeries:

  • CICS ECI Adapter 5.1. This version of the CICS ECI resource adapter is based on J2EE Connector Architecture 1.0 (JCA 1.0). Because CICS ECI resource adapter for Java V5.1 is a JCA 1.0 resource adapter, it will only run in a JCA 1.0 application server or WebSphere Application Server V5.0.2 (or later).
  • CICS ECI Adapter 6.0.0. This version of the CICS ECI resource adapter is based on J2EE Connector Architecture 1.5 (JCA 1.5). This version of CICS ECI resource adapter for Java runs with WebSphere Application Server V6.0 or later.
  • IMS resource adapter 9.1.0.1.1
  • IMS resource adapter 9.1.0.2

Importers

In order for your application to process source files from CICS or IMS, the data must be imported and mapped to Java data structures. Two importers are available in Rational Application Developer: the C Importer and the COBOL Importer. These tools let you import C or COBOL programs into your application through a process of data type transformation. The importers map the datatypes in the source file so that your application can access the source material. In other words, if you are coding Java applications to use J2C resource adapters to access transaction programs written in COBOL or C in CICS or IMS, the Java applications must:

  • Serialize values from Java to the COBOL or C byte buffer that the IMS or CICS program expects.
  • Deserialize the returned value from the COBOL or C buffer for processing in the Java application.

J2C wizard

The J2C wizard enables you to create J2C applications, either as standalone programs or as added functionality to existing applications. The wizard dynamically imports your selected resource adapter, lets you set the connection properties to connect to the EIS servers, guides you through the file importing and data mapping steps, and helps you create Java classes and methods to access the transformed source data.

The following diagram illustrates the flow of the J2C Java bean wizard through the creation of a J2C Java bean, a data bean, and an optional deployment artifact:

Figure 2. Creating J2C artifacts with Rational Application Developer.

The process of using the J2C wizard to build a Java application that runs an EIS transaction is summarized by these steps:

  1. The J2C wizard imports C or COBOL definitions of the EIS transaction input and output messages into the Java Data Binding wizard to map to Java data structures. This wizard creates Java data bindings for the input and output messages.
  2. The J2C wizard provides Java data bindings to the J2C Java bean wizard. This wizard creates a J2C Java bean with methods that can be used to run EIS transactions on the host.
  3. The J2C wizard creates a J2EE resource that you can associate with the J2C Java bean. This J2EE resource can be deployed to WebSphere Application Server and used to run your EIS transactions. The types of J2EE resources that can be created from a J2C Java bean are:
    • JSP
    • Web
    • EJB

The wizard exports the J2EE resource, packaged as an EAR file, so that it can be deployed to and run on a standalone WebSphere Application Server.

Sample application

This tutorial will show you how to create an application that connects to a COBOL/CICS program and returns some information. To keep the example and the testing of it simple, we will use an existing COBOL/CICS program that does not have any file or database I/O. Before you start using the wizards to create the adapters, you need to prepare your workstation so you can test the created connectors without having to go to CICS on the mainframe.


I. Preparing your workstation for this tutorial

To prepare your workstation for testing, you will need to complete these steps, each of which is detailed in the sections below.

  1. Install WebSphere Developer for zSeries V6.0.
  2. Install CICS Transaction Server (CICS TS) for WebSphere Developer.
  3. Install CICS Transaction Gateway (CTG).
  4. Configure CICS TS to support CTG.
  5. Configure CTG to communicate with CICS TS.
  6. Test if CTG is communicating with CICS TS.
  7. Verify that the workspace has the capability to use J2C.
  8. Load the sample COBOL program into WebSphere Developer for zSeries, compile it, and create the DLL.
  9. Install the generated DLL into CICS TS.

1. Install WebSphere Developer for zSeries V6.0

For detailed installation instructions, see the product documentation. Remember that Rational Application Developer V6 must be installed first. You can install WebSphere Developer for zSeries from Disk 1 by executing launchpad.exe. The first screen is shown below. You will need to install CICS TS later.

Figure 3. WebSphere Developer for zSeries install dialog.

2. Install CICS Transaction Server for WebSphere Developer (CICS TS)

CICS TS for WebSphere Developer is an advanced transaction processing solution for Windows It provides a development environment for CICS applications. It is your option to install it or not when installing WebSphere Developer for zSeries. We will need it for this tutorial.

You can use CTG and CICS Universal Clients with CICS TS for Windows. These clients allow access to CICS TS for Windows transactions and programs from separate machines running Windows or UNIX. However, you cannot install CICS TS for WebSphere Developer on a machine on which CICS Universal Clients is already installed.

Figure 3 above shows the install dialog. The default CICS install directory is C:\CICSWIN, and we will use this default in this tutorial.

3. Install CICS Transaction Gateway (CTG)

The key CICS component located outside the application is the CTG, which is used during application development, after deployment, and at run time. The gateway supports many programming paradigms, and includes a JCA interface that lets you develop applications to take advantage of the many facilities of compliant J2EE Servers. CTG provides both a local (direct to CICS) protocol as well as networked protocols such as TCP and SSL for communication to a CTG Server, which in turn directs calls to CICS Servers. For more information on the various aspects of CTG, such as setup, administration, and program development, see the product documentation.

CTG is delivered with WebSphere Developer for zSeries V6 for application testing. Before installing CTG, you will need to use the Windows Add/Remove Programs wizard to remove the CICS Client that is installed with CICS TS. Otherwise, you will receive an error message when trying to install CTG.

Use a simple windows path for the CTG installation, such as IBM/CTG. Otherwise it will have a long path name (C:\Program Files\IBM\IBM CICS Transaction Gateway\) that may cause problems due to Windows path length limits. Select CUSTOM installation and click Change to modify the path. Do not install CTG as a Windows Service unless you will use CTG frequently. For details, see the CTG documentation. CTG can be found with the CDs packaged and shipped with WebSphere Developer for zSeries. You can use the CTG Configuration Task guide during the installation, as shown below in Section 5. If CTG does not start, and you get the message CCL8807E Unable to find a JVM, consider installing a Java Runtime Environment (JRE) shipped with CTG. For CTG V5.1, the JRE is under the directory JRE 1.3.1).

4. Configure CICS TS to support CTG

After you have installed CTG and CICS TS, your next step is to set up the communication links between those two products. For communications, we will use TCP/IP, which should already be correctly configured on your local machine. To configure CICS TS:

4.1. Start CICS: Click Start => IBM CICS Transaction Server for WebSphere => Start CICS => OK. Tip: The Enter key for the CICS is the Ctrl key on the right side of your keyboard.

4.2. Log on to CICS using the default userid sysad and the default password sysad. You should get the message FAA2250I (CICSNT) Signon completed successfully.

4.3. Press Esc (Clear), type the transaction CEDA, and press Ctrl.

4.4. Place a / next to the SIT table and press Ctrl.

4.5. Place a / next to FAASYS and press Ctrl. When FAASYS group is shown, press F8 to advance and F10 to apply an action. F10 positions the cursor in the appropriate place in the window (by Update). Press Ctrl to enter update mode.

4.6. Change the TCP/IP support category. You can add a TCP/IP Local Host Port (2345 in our example), which is the port on which the CICS Server TCP/IP service listens. You also must change Maximum TCP/IP Systems to some value greater than 0, such as 5. Press Ctrl twice to save the update and exit update mode:

Figure 4. Changing the SIT FAASYS group.

5. Configure CTG to communicate with CICS TS

This tutorial uses TCP/IP and assumes that CICS TS and CTG are installed on the same machine. Here are the steps to configure CTG:

5.1. Start CTG: Click Programs => IBM CICS Transaction Gateway => Configuration Tool. If CTG does not start and you get the message CCL8807E Unable to find a JVM, consider installing a Java Runtime Environment (JRE) shipped with CTG. For CTG V5.1, the JRE is under the directory JRE 1.3.1).

5.2. Create a CICS Server definition. This task must be done for each CICS Server that you want to connect to. From the window IBM CICS Configuration Tool, select Tools => New Server.

5.3. When the dialog opens, type the server name DEMOTCP, the Server IP address localhost, and the server Port 2345, as shown below:

Figure 5. Configuring CTG Client.

5.4. Select the first icon on the left, TCP Select the Enable protocol handle option. Use the default port number 2006, which is the port that must be used in programs that will communicate with CTG, which in turn communicates with CICS TS. Here are the correct TCP settings:

Figure 6. Configuring TCP Java gateway.

5.5. Select File => Save, which saves the values into ctg.ini, which is located in the bin directory under the CTG installation directory (C:\IBM\CTG).

5.6. Close the configuration tool. At this point CTG is ready to communicate with CICS TS.

6. Test if CTG is communicating with CICS TS

6.1. Start CTG: Click Programs => IBM CICS Transaction Gateway => IBM CICS Transaction Gateway. The program will start and the window shown below will open. This window must remain open in order for CTG to function.

Figure 7. CTG windows after has started.

6.2. Be sure that CICS Transaction Server and CTG are started. Start the CICS Terminal: click Programs => IBM CICS Transaction Gateway => CICS Terminal. This command will start the 3270 terminal emulation. If your configuration is correct, you will see an emulation window that is connected to CICS TS via CTG.

6.3. Type xxx just to be sure that you are communicating with CICS. You should see a screen similar to Figure 8 below. If CTG is not correctly configured, you will receive a message when the emulator is opened saying that CICS TS is unavailable. You would also receive this message if CICS TS is not running, so verify that CICS TS is running.

Figure 8. Emulating 3270 terminal using CTG.

6.4. To stop CTG, enter Ctrl + C in the Gateway console session. If you try to close the CTG console window by using either the "X" close-window icon, or the Close menu item, a full thread dump is produced. Do not stop CICS TS, since we will need it later.

Show me an animation of the CTG talking to CICS TS and ready for the tests.

7. Verify that the workspace has capability to use J2C

You can now start WebSphere Developer for zSeries. It is a good idea to use a clean workspace, so it will be easy for you to find the generated code. In this example we will use a workspace located in C:\WDz\J2C_Tutorial.

7.1. Using WebSphere Developer for zSeries from any perspective, go to the menu bar and click Window => Preferences.

7.2. On the left side of the Preferences window, expand Workbench (first option in the list).

7.3. Click Capabilities. The Capabilities pane opens. If you would like to receive a prompt when you first use a feature that requires an enabled capability, select Prompt when enabling capabilities.

7.4. Expand Enterprise Java and make sure that Enterprise Java is selected, which is required when using J2C.

7.5. If you made any changes, click Apply, and then click OK to close the Preferences window. Enabling Enterprise Java capabilities will automatically enable any other capabilities that are required to develop and debug J2C applications.

8. Load the sample COBOL program into WebSphere Developer for zSeries, compile it, and create the DLL

WebSphere Developer for zSeries should already be running. At this point, you must load the sample COBOL program that is provided with this tutorial. DownloadCOBOL_JCA.zip and unzip it to a temporary directory. (For simplicity's sake, the steps below assume that you have unzipped the downloaded file in C:\temp.) The DLL is delivered with the sample code, and if you want, you can bypass the rest of Section 8 and jump to Section 9 to install the DLL in the CICS TS.

(A second download file, COBOL_JCA_SOLUTION.zip contains the complete solution for this tutorial. If you just want to see the results of the tutorial without following the steps, unzip this file and load it into your workspace: select File => Import Project Interchange and then select all of the projects.)

8.1. Create a Local COBOL project to hold our source and executable code and import the required properties. Using the z/OS Projects Perspective from the Workbench, select File => New => Other => Workstation COBOL or PL/I => Local project. Click Next and type Demo_JCA_COBOL_Source as the project name. We need to load the required project properties to build the code, so click Import Project definitions:

Figure 9. Creating a Local COBOL project.

You must import the properties in the file C:\temp\Demo_JCA_COBOL_Source_properties.xml, Click Next twice and be sure that the Link options are like those shown in Figure 10 below. These options are required to compile and link a COBOL/CICS program. Click Finish to create the project. If you get the Confirm Perspective Switch dialog, click Yes.

Figure 10. Local Link Options.

8.2. Import the COBOL source code.

There are many ways to import the supplied COBOL code into the project. One easy way is to use drag and drop:

  1. Using the z/OS Projects perspective, go to the Remote Systems view that by default is on the right side of the perspective.
  2. Expand the Local node.
  3. Drag and drop WBCSCUST.cbl to the folder Demo_JCA_Source:
Figure 11. Drag and drop the COBOL to the Local project.

8.3. Check the COBOL syntax and build the program to generate a DLL

  1. In the z/OS Projects view, expand Demo_JCA_COBOL_Source and right-click on WBCSCUST.CBL.
  2. Select Nominate as Entry Point. If you don't perform this step, you will have extra DLLs generated with the same name as the project.
  3. Before building the executables, you can use the Local Syntax Check capability of WebSphere Developer for zSeries. Using the Z/OS Projects view, right-click on WBCSCUST.CBL and select Local Syntax Check. The Problems view, in the lower part of the WebSphere Developer for zSeries window, must be empty. A folder named BuildOutput is created.
  4. To generate the DLL, right-click on the project Demo_JCA_COBOL and select Rebuild Project. Since you have no errors, one DLL is generated under the BuildOutput folder. See in Figure 12 below the contents of the BuildOutput folder after the Rebuild Project. You will need to export WBCSCUST.dll to be used by CICS TS.
Figure 12. COBOL Build output.

Select WBCSTDT.dll under the BuildOutput folder. From the WebSphere Developer for zSeries menus, select File => Export, select File system from the Export dialog, and then click Next. Be sure that you are exporting to the directory C:\CICSWIN\WSEntDev, which is the default location to deploy CICS TS applications. There are other ways to make this DLL visible to CICS using classpath CICS variables. For more information about installing DLLs see the CICSTS documentation.

9. Install the generated DLL into CICS TS

After the DLL is created and exported to the file system, install it into CICS TS:

9.1. If CICS was not shut down, skip to instruction 3. Otherwise, start CICS TS: select Programs => IBM CICS Transaction Server for Windows => Start CICS, and then click OK.

9.2. Log on to CICS using the default userid sysad and the default password sysad. You should get the message FAA2250I (CICSNT) Sign on completed successfully. The Enter key for CICS is the Ctrl key on the right side of your keyboard.

9.3. You will need to add an entry to the CICS table named PPT (Processing Program table). The transaction CEDA must be used to modify the PPT. In the CICS TS window, enter CEDA and press Ctrl. Select the PPT using /, then press Ctrl. Then move the cursor under the action Add, press Ctrl, and type WBCSCUST as Program Name, WDZ as Group Name, and press Ctrl again. You should see a window like this:

Figure 13 Adding a resource to the CICS PPT.

9.4. You can use the Install action to install this resource. Stop CICS: Select Programs => IBM CICS Transaction Server for WebSphere => Stop CICS.

Show me an animation of the CICS PPT configuration.


II. Building a J2C application to connect to a COBOL/CICS program

Before you can start section II, you must have first completed section I, which establishes the environment you will use in this part of the tutorial. This steps in this tutorial must be completed in sequence for it to work properly. Section II will show you how to use the J2C Java bean wizard to connect to a CICS ECI server. While completing the exercises, you will:

  • Use the J2C Java bean wizard to create a J2C application that interfaces with a CICS transaction using the External Call Interface (ECI) APIs of CICS.
  • Create a Java method, customerDetail, which accepts a customer number and then calls the COBOL program, which returns the customer detail.
  • Test the generated J2C application to connect to CICS using CTG.
  • Read about the various deploy options.

1. Start WebSphere Developer for zSeries

This example assumes that the workspace is located in C:\WDz\J2C_Tutorial.

2. Launch the J2C Java bean cheat sheet

To make this sequence of steps easier to follow and include explanations of each activity, we will use an Eclipse feature called cheat sheets. which guide you through required wizards to perform certain development tasks. Each cheat sheet lists the sequence of steps required to help you complete the task and explains the purpose of each step. As you progress from one step to the next, the cheat sheet automatically launches the required tools for you. If there is a manual step in the process, the step will tell you to perform the task and click a button in the cheat sheet to move on to the next step. To view relevant help information to guide you through a task, click on the icon to the right of each step in the cheat sheet. These icons eliminate lengthy documentation searches.

To launch a cheat sheet from the Workbench, select Help => Cheat Sheets => J2C Java Bean => Creating a Java bean using J2C Java Bean wizard for a CICS or IMS COBOL program and click OK. The cheat sheet window opens. You can resize it so you have more space and can read the instructions more easily, as shown in Figure 14:

Figure 14. J2C Java Bean cheat sheet.

You can expand the sign next to each step. Click on the icon shown in Figure 15 below to start the sequence. We will use our sample COBOL program instead of the product-provided COBOL code.

Figure 15. J2C Java Bean Wizard Introduction cheat sheet.

3. Review importer preferences

This is an optional task. You can change the preferences later if you never use C programs. For now, skip this step by clicking .

4. Open the J2EE perspective

Start by opening a J2EE perspective: click on . When the J2EE Perspective opens, the cheat sheet window is resized:

Figure 16. Cheat sheets: Open the J2EE Perspective.

5. Select the back-end system

This tutorial uses CICS as the back-end system (actually, the CICS TS product that is part of WebSphere Developer for zSeries). Click on , as shown in Figure 17. When the dialog asks for the back-end system, select CICS and click OK.

Figure 17. Cheat sheets: Select the back-end system.

6. Select a sample COBOL program

Skip this step, since we have our own COBOL source. Click on to skip, as shown below:

Figure 18. Cheat sheets: Open the J2EE perspective.

7. Your COBOL sample location

Our COBOL program is in the project folder Demo_JCA_COBOL_Source, which we created earlier. Under the J2EE perspective, this folder is in the Other Projects folder. Click on the icon:

Figure 19. Cheat sheets: Your COBOL sample program.

8. Create Java mapping with the standalone CICS/IMS Java Binding wizard

The J2C Java Data Binding wizard helps you create specialized Java classes representing the input and output messages of a CICS transaction. These messages correspond to the COBOL data structures of the CICS application program. The resulting specialized Java classes are called data binding classes, which are used as input or output types for invoking CICS functions. After you create the data binding classes, you can use the J2C wizard to create a Java bean containing a method that uses the binding classes. The cheat sheet will guide you through this sequence:

When you click on , it starts the wizard:

Figure 20. Cheat sheets: Create Java mapping

Since we are using an existing COBOL program, click COBOL to Java as the mapping type. The other COBOL option (COBOL MPO to Java) is for output data bindings only. Use Browse to locate the COBOL source code in the folder Demo_JCA_COBOL_Source inside your workspace. Click Open to close the Open dialog and then click Next in the Import dialog window:

Figure 21. Importing the COBOL code.

The platform we are using is Win32, but you could use other options such as AIX, z/OS. or Not Specified. Click Query and you will see the data structures of your COBOL Program. You must select the DFHCOMMAREA, since this is the COBOL area we will use for communication:

Figure 22. Choose the COBOL communication area.

The connector code may be used by a number of different projects. For this reason, we place the generated code in a separate project. In the Project Name field, type a name like Demo_JCA_Connectors and click New. Another dialog opens, where you select the type of project for this source. Select Java project, click Next, and then click Finish. Back in the Import dialog box, type demo.cobol.cics for Package name. The class name is DFHCOMMAREA (default). Click Finish to create the data bean. Sample Import dialog:

Figure 23. Creating the project, package, and Java class name.

9. Launching the J2C Java bean wizard

You can create a J2C Java bean using the J2C Java bean wizard. After you have created the Java bean and the wizard is closed, you can add additional data binding classes using the J2C Data Binding wizard, and then add methods to the Java bean through the Snippets view. Alternatively, you can use the wizard to create the data bean and add methods to use the data bean. In both cases, you can use the wizard to create a J2EE artifact (JSP, EJB, or Web service) to use to deploy your J2C Java bean. Click to continue:

Figure 24. Cheat sheets: Launching the J2C Java Bean wizard.

In the Resource Adapters Selection page, select the type of resource adapter you want to use. We will use CICS ECI resource adapter V5.1. After you have selected the appropriate resource adapter, click Next:

Figure 25. Selecting the ECI Resource adapter.

In the Connection Properties page, select Non-managed Connection and uncheck Managed Connection. For this tutorial, you will use the non-managed connection to directly access the CICS server, so you do not need to provide the JNDI name. In a "real world" application, a managed connection is recommended. Accept the default Connection class name of com.ibm.connector2.cics.ECIManagedConnectionFactory. We will provide additional information in order to connect to the CICS server. The Connection URL field is required; the others are optional.

  • Connection URL -- Server address of the CICS ECI server. Since we are on the same workstation as CICS, use localhost.
  • Server name -- Name of the CTG server. Use DEMOTCP, defined above in Section I, Step 5.3.
  • Port number -- Number of the port used to communicate with the CTG. The default port is 2006.
  • User name -- User name for the connection. Type SYSAD (uppercase).
  • Password -- Password for the connection. Type SYSAD (uppercase).

When you have provided the required connection information, click Next. See the values in Figure 26 below:

Figure 26. Defining the Connection Properties.

As the project name, type in the one that we created above: Demo_JCA_Connectors. Alternatively, you can click Browse and select the project name. For the package name, type demo.cobol.cics. As interface name type CallCICSCOBOL, as shown in Figure 27 below. Click Next to define the Java methods:

Figure 27. Defining the J2C Java Bean Output properties.

You will now create a Java method that will use the COBOL importer to map the data types between the COBOL source and the data in your Java method:

  • In the Java Method page, click Add.
  • In the Java method name field, type customerDetail for the name of the operation. Click Next.
  • When the Add Java Method page opens, click the first Browsebutton, select DFHCOMMAREA, and click OK.
  • Also in this Add Java Method dialog, check Use the input type for output and click Finish:
Figure 28. Adding a Java Method.

You are not quite finished -- you still need to specify the function name (equates to the CICS program name) that will be called inside of CICS. In an earlier step, we used WBCSCUST when adding the DLL to the PPT. Optionally, if you click Show Advanced, you can specify other CICS parameters, such as transaction name. Click Finish:

Figure 29. Cheat sheets: Your COBOL sample program.

The Java connector code is now generated. Using the J2EE Perspective, you will see that code under Other Projects in the Demo_JCA_Connectors folder:

Figure 30. Java code generated.

10. Editing generated code with the Java snippet editor

No updates are required to user this generated Java code (CallCICSCOBOL and CallCICSCOBOLImpl), though updates may be needed for more complex applications. Figure 31 shows this step. Click on to skip this step, since we are not making changes.

Figure 31. Cheat sheets: Editing generated code.

11. Import the sample test program into your project

At this point, you can test the generated connectors using a simple Java program named TestClient.java that has been provided in the download file.

Figure 32. Cheat sheets: Import the test program.

Using the same technique that you used before to import the COBOL source code, import this Java program: Using the z/OS Projects perspective, go to the Remote Systems view that by default is located at the right, expand the Local node, and find the directory where you unzipped the download code. Then just drag and drop TestClient.java, the test program, to the folder Demo_JCA_Source:

Figure 33. TestClient.java imported and ready to run.

This test class instantiates the class CallCICSCOBOLImpl and uses the Java bean DFHCOMMAREA. For test purposes, this class requests that customer detail be returned for customer number 2 by invoking the CallCICSCOBOLImpl class. The results will be printed to the WebSphere Developer for zSeries console view. Source code for this class:

package  demo.cobol.cics  ;
    public class  TestClient   {
        public static void main(String[]  args  ) {
            try {
                CallCICSCOBOLImpl   proxy = new  CallCICSCOBOLImpl  ();
                DFHCOMMAREA record = new DFHCOMMAREA();
                int   cust_num = 2;
                record.setCustNo  (cust_num);
                System.out.println  ("Invoking CICS Service for customer number " +  cust_num);
                record =  proxy.customerDetail  (record);
                System.out.println  ("CICS Results");

                System.out.println  ("First " +  record.getFirstName  ());
                System.out.println  ("Last " +  record.getLastName  ());
                System.out.println  ("Address " + record.getAddress1());
                System.out.println  ("City " +  record.getCity  ());
                System.out.println  ("State " +  record.getState  ());
                System.out.println  ("Country " +  record.getCountry  ());
            }
                catch (Exception  exc  )
                {
                System.out.println   ( exc  );
                exc.printStackTrace  ();
                }
        }
}

Figure 34. Java class TestClient

12. Test your application using the test program

Before you test your code, start CICS TS and CTG if they are not already started. For details, see the instructions in Section I.

Figure 35. Cheat sheets: Test your application.

Using the J2EE perspective, expand the folder Other projects and the package demo.cobol.cics. Right-click on TestClient.java and select Run => Java Application. The Java class will call the COBOL/CICS program. You can see the results in the Java Console view at the bottom of the WebSphere Developer for zSeries workbench:

Figure 36. Test results.

13. Launching the standalone J2EE Resource from J2C Java Bean wizard

Using the J2EE Perspective and Project Explorer view, right-click on CallCICSCOBOLImpl, select New => Other => J2C => Web Page, Web Service, or EJB from J2C Java Bean, and click Next.

As you see in Figure 37 below, from here you can use the J2C Java bean in your implementation. The wizard provided by WebSphere Developer for zSeries can create a JSP, EJB, or Web service:

Figure 37. Deployment capabilities.

In this article we will not do any of those implementations since it is all documented. Just press the icon in the cheat sheet to find out more about creating these resources. You can skip this task, so select to continue:

Figure 38. Cheat sheets: Launching the standalone J2EE Resource.

14. Deploying J2C application

Application deployment depends on your implementation and is well documented, so it will not be covered here. WebSphere Developer for zSeries can help you to deploy the J2C application, and gives you three main choices:

  • Deploy the J2C application to an EJB. Once you have created your J2C application, you can create an EJB to wrap it. For more information on creating EJBs, see the EJB documentation in the help.
  • Deploy the J2C application as a Web service. Once you have created your J2C application, you can create a Web Service for it.
  • Create a Web page, EJB, or Web Service to deploy your J2C Java bean. The wizard lets you create a JSP or Faces JSP, an EJB, or a Web service that wraps the functionality provided by a J2C Java bean.
Figure 39. Cheat sheets: deploying the J2C application.

Remember that we used the cheat sheet dialogs to illustrate the sequence of operations. As you saw, some operations are optional, but cheat sheets are a good way to learn when you have no idea how to start the process of creating the Java connectors. After you become familiar with the tools, you will not need to use these dialogs anymore, and you can just call the wizards directly.

All 14 steps above can be replaced by the sequence File => New => Other => J2C and the options listed under J2C under any perspective.

Show me an animation of the J2C Application Build using J2C wizards (no cheat sheets).


Conclusion

WebSphere Developer for zSeries can help developers who want to test J2C applications and do not want to use the mainframe for the development tasks. All of the wizards shown here are part of Rational Application Developer (except for the capability to generate a DLL from COBOL code and test the code using CICSTS and CTG). So with WebSphere Developer for zSeries, you can work with this type of application end-to-end on your workstation.

Acknowledgements

The author wishes to thank Brian S. Colbert, Veronique Quiblier, and Wilbert Kho of IBM for reviewing this article.


Downloads

DescriptionNameSize
Code samples in zip formatCOBOL_JCA.zip  ( HTTP | FTP )3 KB
Code samples in zip formatCOBOL_JCA_SOLUTION.zip  ( HTTP | FTP )998 KB

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. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. 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=94091
ArticleTitle=Using WebSphere Developer for zSeries V6 to Connect to COBOL/CICS
publish-date=09142005