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
- 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
- Add a TCP port entry in the /etc/services file on the AIX server where TXSeries region resides, using the
chservicescommand. 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
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.
- 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
- 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
Figure 2. Open Perspective window with Java selected
- Create a new Java Project by clicking File > New > Java Project as Figure 3 shows.
Figure 3. Creating new Java project
- In the New Java Project window (Figure 4), provide a Project name (for example,
- Retain the other default options and click Finish.
Figure 4. New Java Project window
You can see the Java project created and listed in Package Explorer in the left pane.
- Right-click the Java project (SampleJavaClient), and select New > File.
- 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).
- Provide a name for your Java program in the File name text box (
Figure 5. New File window
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
- 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.
- Right-click the Java project and select Properties.
- In the left pane of Properties window, select Java Build Path.
- In the right pane, choose Libraries tab.
- 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.
- 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
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.
- On AIX server, cold-start the TXSeries region by using this command:
cicscp –v start region region_name StartType=cold
cicscp –v start region TXREG StartType=cold
- 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.
- Open the Java perspective in Rational Developer for Power Systems Software, and select your Java program in the Package Explorer pane.
- 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
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:
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
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
- To provide runtime arguments to your Java client application:
- Click the Java client project and select Run > Run configurations from the menu.
- 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
You have now completed this tutorial. See the Resources section below for where to find related information.
- 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:
- 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.
- 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.