Develop TXSeries CICS apps with Rational Developer for Power Systems Software: Part 3. Test your CICS application from a Java client

Part 3 shows you how to configure the IBM® CICS® Transaction Gateway (CTG) to communicate with IBM® TXSeries® for Multiplatforms software, and then how to create a client project in IBM® Rational® Developer for Power Systems Software™ and test your application using the CTG.

Share:

Balaji S. Kumar (balajiku@in.ibm.com), Software Engineer, IBM

author photoBalaji S. Kumar has worked with both IBM TXSeries for Multiplatforms and IBM WebSphere eXtended Transaction Runtime and has made significant contributions towards Functional Verification Test for WXTR. He has won the best implementation award in HackDay, an IBM internal technical forum. He has also actively participated in other IBM forums.



Hariharan N. Venkitachalam (vharihar@in.ibm.com), Senior Software Engineer, IBM

author photoHariharan N. Venkitachalam holds a Diploma in Computer Science & Engineering from M.E.I Polytechnic, Bangalore, India. He is employed with IBM India Software Development Laboratory in India and has over ten years of experience in IT. His areas of expertise include distributed CICS systems and Structured Query Language (SQL) internals. He has co-authored a Redbook on "Revealed! The Next Generation of Distributed CICS". In his current role he leads the development team for WebSphere eXtended Transaction Runtime product and assists in technical pre-sales, and customer engagement services for the distributed CICS products. He has been working for the CICS organization since he joined IBM in 2001.



Janaki Sundar (janakisundar@in.ibm.com), Staff Software Engineer, IBM  

Janaki SundarJanaki Sundar has a B.Tech degree from the National Institute of Technology, Tiruchirappalli, India. She has been with the TXSeries for Multiplatforms and WebSphere eXtended Transaction Runtime teams at the IBM India Software Lab for five years. Her interests include CICS application development and modernization of testing using Rational tools. She has written for IBM developerWorks previously.



Nageswararao V. Gokavarapu (nagesh.gokavarapu@in.ibm.com), Staff Software Engineer, IBM  

author photoNageswararao V. Gokavarapu holds an M.E. in Electronic Instrumentation from Andhra University, India, and has been with IBM for the last five years. He has worked on distributed CICS transaction processors, including the WebSphere eXtended Transaction Runtime and TXSeries for Multiplatforms software. Nageswararao has written several IBM developerWorks articles, some of which were selected as featured articles. His areas of interest are virtualization, transaction processing management, and UNIX systems.



25 October 2011

Overview of this series

Part 1 of this series introduced IBM® TXSeries® for Multiplatforms and IBM® Rational® Developer for Power Systems™, followed by instructions on installation and configuration of these products. Configuration of the TXSeries included creating a region for deploying IBM® CICS® applications. Configuration of Rational Developer for Power Systems Software included installation of the Remote System Explorer component on an IBM® AIX® server and establishing a connection to that server.

Part 2 described how to use the configurations from Part 1 to create IBM® CICS® applications for TXSeries, using Rational Developer for Power Systems Software. Steps explained creating a new AIX COBOL project and an AIX COBOL program file. Code for sample CICS application and sample Makefile file were provided in the article.

Part 3 explains how to create a client Java project in Rational Developer for Power Systems Software. Java samples provided by CICS Transaction Gateway are used to call CICS COBOL application deployed onto TXSeries.


Introduction to CICS Transaction Gateway

The CICS Transaction Gateway (CTG) is a secure and scalable connector that enables client applications in different runtime environments to access CICS servers. Integrating TXSeries with IBM® WebSphere® Application Server, using the CICS Transaction Gateway, enables composite applications with sophisticated feature-rich user interfaces to become the front end of TXSeries applications.

There are two interfaces provided by CTG to access TXSeries regions, and CTG provides sample applications for both of these interfaces:

  • External Call Interface (ECI) is used to call a program in a CICS server, optionally passing data through COMMAREA or channels.
  • External Presentation Interface (EPI) allows a user application program to access 3270–based transactions on one or more CICS servers.

This article focuses on using the sample ECI Java client application provided by CTG to pass data through COMMAREA to the TXSeries region. The client application project can be created and managed through Rational Developer for Power Systems Software.

Install the CTG on the Microsoft Windows machine where Rational Developer for Power Systems Software is installed. Make sure that you select the version of CTG supported by the TXSeries version on the AIX server. The default installationlocation is C:\Program Files\IBM\CICS Transaction Gateway.

The steps that follow explain the procedure required to configure TXSeries region and CTG for communication, to create a client project in Rational Developer for Power Systems Software, and to invoke the CICS application from the client.

Configure communication between TXSeries region and CTG

  1. On AIX server, add a Listener Definition (LD) entry to the TXSeries region (created in Part 1) as Listing 1 shows.
Listing 1. Listener Definition entry
# cicsadd –c ld -r region_name listener_name Protocol=TCP TCPAddress=
host_name TCPService=TCP Service name

In Listing 1:

  • region_name refers to TXSeries region
  • listener_name refers to the name of the LD entry
  • host_name refers to the host name or IP address of the AIX server where TXSeries region exists
  • TCP Service name refers to the TCP service name to be used in the /etc/services file on AIX server corresponding to the TXSeries region

Following is an example:

 cicsadd –c ld –r TXREG LSNR Protocol=TCP TCPAddress=myhost TCPService=TXREG
  1. Add a TCP port entry in the /etc/services file on the AIX server where TXSeries region resides, using the chservices command. Following example adds the TCP Service name TXREG and the corresponding port number 10214 to the /etc/services file.
 chservices -a -v TXREG -p tcp -n 10214

Note:
The TCP service name added to the /etc/services file should match the value mentioned for the attribute TCPService in the LD entry created in step 1. Ensure that the port number is unique on the AIX server.

  1. CTG.INI is an initialization file located in the bin directory of CTG installation location on Windows machine. Add an entry in the CTG.INI file under the Server section, as the example in Listing 2 shows.
Listing 2. Addition to the CTG initialization file
SECTION Server = TXREG # CTG Server name; matching with TXSeries region name for
consistency
Description = TCP/IP Server 
Protocol = TCPIP 
NetName = myhost # host name / IP address of the AIX server where TXSeries region exists
Port = 10214 #port number added to /etc/services file on AIX, corresponding to TXSeries
region
ENDSECTION

Create a client project in Rational Developer for Power Systems

  1. In Rational Developer for Power Systems Software, open the Java perspective by clicking Window > Open Perspective > Other, selecting Java, and clicking OK.

Figures 1 and 2 show how to open Java perspective in Rational Developer for Power Systems.

Figure 1. Opening a perspective in Rational Developer for Power Systems
Shows menu selections described
Figure 2. Open Perspective window with Java selected
Selecting Java perspective
  1. Create a new Java Project by clicking File > New > Java Project as Figure 3 shows.
Figure 3. Creating new Java project
Shows selections, as described
  1. In the New Java Project window (Figure 4), provide a Project name (for example, SampleJavaClient).
  2. Retain the other default options and click Finish.
Figure 4. New Java Project window
Create a Java Project dialog window

You can see the Java project created and listed in Package Explorer in the left pane.

  1. Right-click the Java project (SampleJavaClient), and select New > File.
  2. In the New File window (Figure 5), select the parent folder under your Java project where you want to save your Java program (for example, SampleJavaClient/src).
  3. Provide a name for your Java program in the File name text box (SampleClient.java).
Figure 5. New File window
Shows entries described

To write SampleClient.java, use any of the Java sample programs provided by the CTG. You can find them at samples\java\com\ibm\ctg\samples\eci under the CTG install location on the Windows machine. The example in this article is based on the EciB1.java program. Listing 3 provides a few code snippets for reference.

Listing 3. Code snippets for the SampleClient Java program
ECIRequest eciRequestObject = null;
String strProgram = "HELLOPRG"; /* this is the CICS COBOL program to be invoked */
String strChosenServer = "TXREG"; /* this points to the CTG server name, as in 
Listing 2 */
String strUrl = "local:"; /* this mentions the URL on which CTG gateway daemon is 
running */
int iPort = 2007; /* this is the port on which CTG gateway daemon is listening to */
int iCommareaSize = 18; /* size of the COMMAREA data to be sent */
byte[] abytCommarea = new byte[iCommareaSize];
String commarea=”SAMPLE DATA!”; /* COMMAREA data sent by the client to CICS program */
abytCommarea=commarea.getBytes(); /* Converting COMMAREA to a byte array */

In the code in Listing 3:

  • HELLOPRG refers to the CICS COBOL program created using Rational Developer for Power Systems Software. This COBOL program resides on the AIX server, where TXSeries region exists.
  • The local: value for the URL means that the CTG daemon on the local machine will be used.
  • The value for Port refers to the port on which CTG daemon will be started on the Windows machine.
  • strChosenServer refers to the entry that must be added in CTG.INI file.
  • The data to be passed is referred to by the variables commarea and abytCommarea.

Listing 4 shows the ECI request call to the CICS COBOL program on the TXSeries region with the specified COMMAREA.

Listing 4. ECI request call
eciRequestObject =
    new ECIRequest(ECIRequest.ECI_SYNC, //ECI call type
        strChosenServer, //CTG server entry
        "CICSUSER", //CICS userid
        "             ", //CICS password
        strProgram, //CICS program to be run
        null, //CICS transid to be run
        abytCommarea, //Byte array containing the COMMAREA 
        iCommareaSize, //COMMAREA length 
        ECIRequest.ECI_NO_EXTEND,//ECI extend mode 
        0); //ECI LUW token
  1. If your Java program has this statement, ensure that it resides in the com.ibm.ctg.samples.eci package under the src folder of your Java project.
     package com.ibm.ctg.samples.eci;
  2. Right-click the Java project and select Properties.
  3. In the left pane of Properties window, select Java Build Path.
  4. In the right pane, choose Libraries tab.
    1. Click Add External JARs. Browse to select the JAR file called ctgclient.jar, which is in the classes directory under the CTG install location on the Windows machine. Click Open. You can see that the selected JAR file appears in the right pane.
    2. Repeat the step to select the ctgserver.jar file in the same location as that of ctgclient.jar. Click OK after adding these two jar files.

Figure 6 guides you to add the JAR files as mentioned in this step.

Figure 6. Adding external JAR files to the Java build path
Java Build Path pane > JAR Selection window

Now the Java application is ready for execution.


Test the sample application

The previous sections explained how to configure TXSeries region and the CTG for communication and how to create a client project using Rational Developer for Power Systems Software. This section shows how to run the sample application using Rational Developer for Power Systems Software and connecting to a TXSeries region.

  1. On AIX server, cold-start the TXSeries region by using this command:
    cicscp –v start region region_name StartType=cold
    Example:
     cicscp –v start region TXREG StartType=cold
  2. Issue the following command on the Windows machine to start CTG gateway daemon on a particular port:
     ctgstart –port=port number

    Here, port numberrefers to the same port referred to by the iPort variable in Listing 3.
    Example:
     ctgstart –port=2007
  3. Open the Java perspective in Rational Developer for Power Systems Software, and select your Java program in the Package Explorer pane.
  4. Right-click on your Java program, and select Run as > Java application.

Figure 7 shows these actions.

Figure 7. Steps to run the Java application
Menu and drop-down menu show selections

Tip:
Alternatively, you can click on the green arrow Run icon on the tool bar.

You can see the output of your Java application in the Console view of Rational Developer for Power Systems Software. You can also check the output of your COBOL program by opening the console.msg file on the AIX machine where TXSeries region resides, at this location:

/var/cics_regions/region_name

Figure 8 is a screen capture of the output of the Java application in the Console view of Rational Developer for Power Systems Software Java perspective.

Figure 8. Output of Java application
Console tab active, screen output

Figure 9 shows the contents of /var/cics_regions/TXREG/console.msg on the AIX machine.

Figure 9. Output of the TXSeries application in console.msg
HELLOPRG PROGRAM: YOU HAVE SENT COMMAREA…
  1. To provide runtime arguments to your Java client application:
    1. Click the Java client project and select Run > Run configurations from the menu.
    2. Select the Arguments tab in the right panel and type the required arguments into the "Program arguments" section.

Figure 10 highlights the section where arguments can be mentioned for the Java application.

Figure 10 Providing runtime arguments to the Java application
Create, manage, and run configurations window

You have now completed this tutorial. See the Resources section below for where to find related information.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

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

 


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

All information submitted is secure.

Choose your display name



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

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

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

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

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, DevOps
ArticleID=767566
ArticleTitle=Develop TXSeries CICS apps with Rational Developer for Power Systems Software: Part 3. Test your CICS application from a Java client
publish-date=10252011