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.

Back to top

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.

# 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 

2. 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.

3. 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.

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

Back to top

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.

2. Create a new Java Project by clicking File > New > Java Project as Figure 3 shows.

3. In the New Java Project window (Figure 4), provide a Project name (for example, SampleJavaClient).
4. Retain the other default options and click Finish.

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

5. Right-click the Java project (SampleJavaClient), and select New > File.
6. 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).
7. Provide a name for your Java program in the File name text box (SampleClient.java).

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.

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.

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

8. 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;

   
   
9. Right-click the Java project and select Properties.
10. In the left pane of Properties window, select Java Build Path.
11. 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.

Now the Java application is ready for execution.

Back to top

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.

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 9 shows the contents of /var/cics_regions/TXREG/console.msg on the AIX machine.

5. 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.

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

Resources

Learn

• Browse the TXSeries 7.1 information center and review the TXSeries product information.
  
  
• Review the Rational Developer for Power Systems Software overview page.
  
  
• Browse Rational Developer for Power Systems software information center for documentation, where you will find these instructions:
  • Getting Started with the Remote System Explorer
  • Configuring a connection to a remote server
  
  
• Find out more about the Rational solution for Collaborative Lifecycle Management, a ready-to-run integrated ALM solution comprising Rational Team Concert, IBM Rational Quality Manager, and IBM Rational Requirements Composer.
  
  
• Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
  • Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
  • Attend a free developerWorks Live! briefing to get up-to-speed quickly on IBM products and tools, as well as IT industry trends.
  • Watch developerWorks on-demand demos, ranging from product installation and setup demos for beginners to advanced functionality for experienced developers.
  • Improve your skills. Check the Rational training and certification catalog, which includes many types of courses on a wide range of topics. You can take some of them anywhere, any time, and many of the “Getting Started” ones are free.
  
  

Get products and technologies

• Download and evaluate a free trial version IBM TXSeries for Multiplatforms.
  
  
• Explore the Enterprise Modernization Sandbox for Power Systems.
  
  
• Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.
  
  

Discuss

• Participate in the TXSeries forum, join the CICS User Group to get updates on TXSeries, and follow IBM TXSeries on Twitter (@txseries) to get the latest updates.
  
  
• Follow Rational software on Facebook and Twitter (@ibmrational) to and add your comments and requests.
  
  
• Rate or review Rational software. It’s quick and easy. Really.
  
  
• Share your knowledge and help others who use Rational software by writing a developerWorks article. You’ll get worldwide exposure, RSS syndication, a byline and a bio, and the benefit of professional editing and production on the developerWorks Rational website. Find out what makes a good developerWorks article and how to proceed.
  
  
• Ask and answer questions and increase your expertise when you get involved in the Rational forums, cafés, and wikis.
  
  
• Get involved in the developerWorks community and connect with others who share your interests while exploring the developer-driven blogs and by following devWorks on Facebook and Twitter.
  
  

About the authors

Balaji 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 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 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 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.

Rate this article

Comments

Back to top

Table of contents

• Overview of this series
• Introduction to CICS Transaction Gateway
• Create a client project in Rational Developer for Power Systems
• Test the sample application
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: PL/I for AIX
• Demo: Video: See what compilers can do for you
• Community: PL/I Cafe
• Buy: PL/I for AIX

Dig deeper into Rational on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers