Debug mixed-language CICS applications deployed on TXSeries with Rational Developer tools

Learn how to debug the mixed-language IBM® CICS® applications deployed in IBM® TXSeries™ for Multiplatforms regions using the IBM® Rational® Developer for AIX® and Linux® software. Along with an overview of each of these systems, this article includes configurations for debugging and a detailed debugging procedure.

Share:

Nageswararao V. Gokavarapu (nagesh.gokavarapu@in.ibm.com), TXSeries Level 3 Support, IBM  

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



Suvadeep Das (suvadeep.das@gmail.com), TXSeries Level 3 Support, IBM

Suvadeep Das has a M.C.A. degree from the West Bengal University of Technology, India. He has been with the IBM TXSeries for Multiplatforms team at the IBM India Software Lab for five years. His interests include debugging on different platforms.



Hariharan N. Venkitachalam (vharihar@in.ibm.com), Product Architect, TXSeries for Multiplatforms, IBM

author photoHariharan N. Venkitachalam holds a diploma in Computer Science and 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 IBM CICS systems and Structured Query Language (SQL) internals. He has co-authored an IBM Redbooks book Revealed! The Next Generation of Distributed CICS. In his current role he leads the development team for IBM 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.



17 December 2013

Also available in Chinese

Introduction

This article explains how to use IBM® Rational® Developer for AIX and Linux software to debug mixed-language IBM CICS applications deployed in IBM® TXSeries™ for Multiplatforms regions.

Rational Developer for AIX and Linux software provides an integrated set of application development tools. It extends the rich base of Eclipse functionality, especially the Remote System Explorer.

IBM TXSeries for Multiplatforms (TXSeries) is general-purpose online transaction-processing software that handles security, data integrity, and resource scheduling. The TXSeries for Multiplatforms architecture of integrated software components can be used to create a Customer Information Control System (CICS) environment.

CICS integrates the basic business software services that online transaction processing applications require. This tutorial is to provide a step-by-step procedure to debug the mixed language CICS applications deployed in TXSeries regions.

In this article you will learn more about each of these systems.


Rational Developer for AIX and Linux software

IBM® Rational® Developer for AIX and Linux software works seamlessly with other Eclipse-based tools, such as IBM® Rational Team Concert™ for collaborative change and project management and IBM® Rational® Application Developer for WebSphere® Software integrated development environment (IDE). The source editing support helps the developer edit source code with the Remote Systems LPEX Editor, using features such as automatic indenting for language parsing and text effects to emphasize different parts of your source program.

The source code can be stored in Eclipse projects. These projects offer the option of working while connected from the IBM® AIX® server, and then synchronizing your source code when reconnecting. They also enable team sharing with any source control provider that works with the Eclipse platform. The source code within the project is built, and any error feedback is integrated with the standard Eclipse mechanisms. This quickly brings the developer to the problematic line of code.

You can use the Remote System Explorer to see files and processes on an IBM AIX system. Shells can be launched in integrated windows to interact with the AIX server.

Note:
Although this article mentions the usage of IBM Rational Developer for AIX and Linux client, the procedure is applicable for other clients, including: IBM® Rational® Developer® for System z® and IBM Rational Developer for the Enterprise clients.


IBM TXSeries for Multiplatforms

IBM TXSeries for Multiplatforms is a distributed CICS online transaction processor for mixed-language applications. It is widely used for integrating data and applications between distributed solutions and enterprise systems. It is also used for deployment of IBM CICS applications written in COBOL, C / C++, PL/I, and Java programming languages. Uniquely, the TXSeries enables you to scale up to CICS Transaction Server on the mainframe as the needs of your business grow.

The TXSeries for Multiplatforms software controls the processing of transactions in a business system, even when the transactions are working concurrently on different computers and accessing the same data. User application programs do not have to perform the specialized task scheduling, control, data routing, and locking that are required by transaction processing. Transaction processing services enable application programs to concentrate on business logic rather than on how the logic is implemented. These services are implemented by TXSeries CICS regions to provide you and your team with a separate view of the transaction processing system, without sacrificing data integrity and optimum performance for many concurrent users.


Overview of the software environment used in this article

Table 1 shows the software stack used in this article to demonstrate how to remotely debug mixed language applications (C- and IBM COBOL-based) deployed in TXSeries regions.

Table 1. Software stack used for demonstrations
SoftwarePlatformVersion
TXSeries for MultiplatformsAIX7.1.0.4
IBM COBOLAIX4.1
XLC/C++AIX11.1
Rational Developer for AIX and Linux SoftwareWindows9.0
IBM Debugger Engine (This gets shipped with Rational Developer for AIX and Linux software or with the IBM compiler products.)AIX12.1.0.3

A typical remote debugging environment using Rational Developer for AIX and Linux software for debugging mixed languages applications deployed on TXSeries region running on AIX server is shown in Figure 1.

Rational Developer for AIX and Linux software is based on a client-server model. The debug engine acts as a client and the user interface of Rational Developer for AIX and Linux software acts as the server. This type of client-server model provides the flexibility to have the user interface on a local Windows or Linux desktop machine, even though you debug a program that resides on a remote AIX machine.

Figure 1. Client-server configuration using both local and remote machines
Debug process distributed between local and remote

Prepare TXSeries CICS regions to be debugged

Follow these steps to use Rational Developer for AIX and Linux to debug TXSeries CICS regions:

  1. Issue the following command to enable a TXSeries region to allow programs to be debugged:
    # cicsupdate -r region_name -c rd AllowDebugging=yes
  2. Reset the resource-level security setting for the check point management interface (CPMI) transaction, or for other transactions under which the CICS programs need to be debugged:
    # cicsupdate -c td -r region_name CPMI Permanent=no
    # cicsupdate –c td -r region_name CPMI RSLCheck=none
    # cicsupdate -c td -r region_name CPMI Permanent=yes
  3. Issue the following command to set the path in the CICS region's environment file. The <source_directory_path> refers to the absolute directory path where all the program source files that are required during debugging, can be found.
     DER_DBG_PATH="<source_directory_path>"
  4. Issue the following command to set the path to the debug libraries. The <library_path_idebug> refers to the absolute directory path where the IBM IDEBUG libraries are located. These files are usually located under the /usr/idebug/engine/lib directory.
    CICS_IDEBUG_LIBPATH="<library_ path_idebug>"

Note:
In the above commands replace region_name with the CICS region name appropriately. Regions need to be cold-started (StartType=cold) to reflect the above changes.


Prepare the environment to debug CICS applications

IBM Rational Developer for AIX and Linux Version 9.0 is used for this article, as shown in Figure 2.

Note:
Although this article uses the IBM Rational Developer for AIX and Linux client, the procedure is applicable for other clients, such as IBM® Rational® Developer for System z and IBM Rational Developer for the Enterprise clients.

Figure 2. Rational Developer for AIX and Linux software version
About window shows Version 9.0

Click to see larger image

Figure 2. Rational Developer for AIX and Linux software version

About window shows Version 9.0

To launch IBM Rational Developer for AIX and Linux, go to Start Menu > Programs, select IBM Software Delivery Platform and then choose IBM Rational Developer for AIX and Linux. Once Rational Developer for AIX and Linux software is launched, select a workspace and then the IBM Rational Developer for AIX and Linux view is displayed. Then choose the Debug Perspective from Window > Open Perspective, and the Debug window is active, as shown in Figure 3.

Figure 3. Debug perspective of Rational Developer for AIX and Linux
Launch window opens debug perspective

Click to see larger image

Figure 3. Debug perspective of Rational Developer for AIX and Linux

Launch window opens debug perspective

In Figure 3, the debug button is circled in red. By default, the debugger will listen to port 8001. As shown in Figure 4, click the debug button to change the port where you want the IBM Rational Developer for AIX and Linux debugger to listen.

Figure 4. Set the port with the debug button
Click the debug button to set the port

Click to see larger image

Figure 4. Set the port with the debug button

Click the debug button to set the port

You can change the port as shown in Figure 4 by clicking the drop-down arrow next to the debug button, and then you click the debug button. The button turns green to indicate that IBM Rational Developer for AIX and Linux is now listening for debug requests on the port that was just set.

Prepare the mixed-language CICS applications to be debugged

A sample COBOL program (COBOLPRG.ccp) which uses EXEC CICS LINK to call a C program (CPROGRAM.ccs) is used in the code listings. The data is passed to the C program using COMMAREA facility with LINK API.

Listing 1. Sample CICS/COBOL program snippet (COBOLPRG.ccp)
IDENTIFICATION DIVISION.
PROGRAM-ID.   COBOLPRG.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.

01 TEXT-OUT.
   05  MSG PIC X(24)  VALUE 'HELLO TXSERIES PRODUCT'.
   05  TERMCHAR PIC X.
01 OUT-MSG            PIC X(80)  VALUE SPACES.
01 W-RESP             PIC S9(8)  BINARY.
01 W-RESP2            PIC S9(8)  BINARY.

LINKAGE SECTION.

PROCEDURE DIVISION.


    EXEC CICS LINK PROGRAM('CPROGRAM')
                   COMMAREA(TEXT-OUT)
                   LENGTH(LENGTH OF TEXT-OUT)
                   RESP(W-RESP)
                   RESP2(W-RESP2)
    END-EXEC.

    IF W-RESP = DFHRESP(NORMAL)

    STRING 'MODIFIED MESSAGE FROM C PROGRAM :'
           DELIMITED BY SIZE
           TEXT-OUT DELIMITED BY SIZE
           INTO OUT-MSG
    END-STRING

    EXEC CICS WRITE OPERATOR TEXT(OUT-MSG)
              TEXTLENGTH(LENGTH OF OUT-MSG)
    END-EXEC

    END-IF.

    EXEC CICS RETURN
    END-EXEC.
Listing 2. Sample CICS/C Program snippet (CPROGRAM.ccs)
#include <cicstype.h>
#include <stdio.h>
#include <memory.h>

DFHEIBLK  *eibptr;

int main(void)
{
     cics_char_t* commarea;
     cics_char_t outmsg[128];
     cics_ushort_t msglen;
     cics_ushort_t rcode;


     EXEC CICS ADDRESS EIB(eibptr);

     EXEC CICS ADDRESS COMMAREA(commarea);

     memset(outmsg,'\0',sizeof(outmsg));

     commarea[eibptr->eibcalen-1]='\0';

     if(eibptr->eibcalen == 0){
          sprintf(outmsg,"INPUT MESSAGE FOR C PROGRAM IS NULL\n");
          msglen=strlen(outmsg);
          EXEC CICS WRITE OPERATOR
                          TEXT(outmsg)
                          TEXTLENGTH(msglen)
                          RESP(rcode);
     }else{
          sprintf(outmsg,"INPUT MESSAGE FOR C PROGRAM IS :%s\n",commarea);
          msglen=eibptr->eibcalen + strlen(outmsg);
          EXEC CICS WRITE OPERATOR
                          TEXT(outmsg)
                          TEXTLENGTH(msglen)
                          RESP(rcode);
          memcpy(commarea,"TRIED",5);
          sprintf(outmsg,"MODIFIED MESSAGE IN C PROGRAM IS :%s\n",commarea);
          EXEC CICS WRITE OPERATOR
                          TEXT(outmsg)
                          TEXTLENGTH(msglen)
                          RESP(rcode);
     }
     EXEC CICS RETURN;
}

Compile the programs

CICS-based mixed-language applications are compiled using the cicstcl utility supplied with TXSeries. The utility would preprocess the CICS statements (translate) and invoke appropriate language compilers to generate (compile-link-edit) the load modules. The programs must to be compiled with the -a flag to enable them for debugging using IBM Rational Developer for AIX and Linux.

The compilation steps are:

  • To compile the IBM COBOL program named COBOLPRG.ccp, issue the command:
    	# cicstcl -alIBMCOB COBOLPRG.ccp
  • To compile the C program named CPROGRAM.ccs, issue the command:
    	# cicstcl -alC CPROGRAM.ccs

Add the program resources to the TXSeries region

To deploy the programs in the TXSeries region, define the transaction name and program names to the region as follows:

  • To add the transaction DPRG, which uses the program COBOLPRG, issue the command:
    	# cicsadd -c td -r region_name DPRG ProgName="COBOLPRG"
  • To add the IBM COBOL program COBOLPRG resource entry, issue the command:
    	# cicsadd -c pd -r region_name COBOLPRG PathName="COBOLPRG.ibmcob"
  • To add the C program CPROGRAM resource entry, issue the command:
    	# cicsadd -c pd -r region_name CPROGRAM PathName="CPROGRAM"

After you issue these commands, the applications deploy to the TXSeries region and are ready to be debuggged with Rational Developer for AIX and Linux software.

Note:
Any transaction that starts with "C" cannot be debugged on TXSeries.


Enable CICS applications to be debugged in a TXSeries region

To enable and disable the debugging of CICS transactions, they need to be managed by the CICS CDCN transaction. The resource could be a terminal, a transaction, a program or a SYSID.

For demonstration purposes enable the programs COBOLPRG and CPROGRAM for debugging. The following steps show how resources can be enabled for debugging using CDCN transaction:

Run the transaction CDCN from a 3270-based terminal. Provide the DISPLAY parameter in the following format, using the IP address and the port of the machine where Rational Developer for AIX and Linux is listening:

IP address: port

As shown in Figure 5, if the desktop machine where Rational Developer for AIX and Linux software is listening on the IP address 1.1.1.1 and it is listening to port 1234 the DISPLAY parameter is:

1.1.1.1:1234
Figure 5. CDCN screen showing DISPLAY parameter for COBOLPRG
CDCN screen shows DISPLAY and PROGRAM fields.

As shown in Figure 5, add COBOLPRG as the PROGRAM and then press Enter. The following message is displayed on the terminal.

ERZ104056I: Successfully configured debugging on for program 
COBOLPRG ERZ104072I: The display to be used for the debugging information is
 '1.1.1.1:1234'

You can repeat that same procedure to enable the CPROGRAM for debugging.

All resources, the TXSeries region, and Rational Developer for AIX and Linux software are ready to start debugging.


Start debugging

To start to debug, launch the transaction DPRG, which invokes the COBOL program (COBOLPRG). The transaction DPRG can be launched from a 3270 terminal. Once the transaction (DPRG) is run, the programs running in the TXSeries are attached automatically to the Rational Developer for AIX and Linux user interface as shown in Figure 6.

Figure 6. Initial debug view after the program gets attached
4 panes showing: Debug, Mod COBOLPRG, and Console

Click to see larger image

Figure 6. Initial debug view after the program gets attached

4 panes showing: Debug, Mod COBOLPRG, and Console

As shown in Figure 6 the transaction stops in the COBOL module COBOLPRG in PROCEDURE DIVISION. You can set the breakpoints on the program. Use the function key F5 to step into each line and debug further.

Figure 7 shows the COMMAREA contents HELLO TXSERIES PRODUCT passed from the COBOL program. When the mouse pointer is pointed to any variable, the variable contents are displayed. The variable contents can also be seen from the Variables window. In Rational Developer for AIX and Linux, you can change the values for different variables used in the application programs at the same time you are debugging the programs.

Figure 7. Initial COMMAREA view inside COBOLPRG
TEXT-OUT box is highlighted to show the comment

Click to see larger image

Figure 7. Initial COMMAREA view inside COBOLPRG

TEXT-OUT box is highlighted to show the comment

Press the F5 (Resume) function key to go to the C module, which is called from the COBOL program. Figure 8 depicts the COMMAREA text in the C program, which it gets from the COBOL module.

Figure 8. COMMAREA view inside the C program CPROGRAM
COMMAREA HELLO TXSERIES PRODUCT in CPROGRAM

Click to see larger image

Figure 8. COMMAREA view inside the C program CPROGRAM

COMMAREA HELLO TXSERIES PRODUCT in CPROGRAM

If you want to continue to debug this program use the F5 (Resume) key. Other options are to use the debugging directives defined in Rational Developer for AIX and Linux software, such as the F7 (Step-In) key and the F8 (Step-Out) key. The modify the COMMAREA text in this program and Figure 9 shows how it gets modified.

Figure 9. Modified COMMAREA inside CPROGRAM
Modified message in the CPROGRAM window

Click to see larger image

Figure 9. Modified COMMAREA inside CPROGRAM

Modified message in the CPROGRAM window

You can continue to debug. At this point, control is returned to the parent COBOL module, which is also visible in the module section. The modified COMMAREA contents are shown in Figure 10.

Figure 10. Debug view of modified COMMAREA inside COBOLPRG
Modified COMMAREA after returning to COBOLPRG

Click to see larger image

Figure 10. Debug view of modified COMMAREA inside COBOLPRG

Modified COMMAREA after returning to COBOLPRG

This process demonstrates how to debug a mixed-language TXSeries application using IBM Rational Developer for AIX and Linux. You can also debug an IBM PLI, C++, or Java application using a similar procedure.


Troubleshoot common problems

Some of the common problems seen while debugging the CICS applications using Rational Developer for AIX and Linux software are illustrated below:

  • The debug listen port is not enabled or is listening on a wrong port in Rational Developer for AIX and Linux software. In this case, the console.msg or console.<nnnnnn> logs of TXSeries indicates a problem connecting with the IDEBUG Rational Developer for AIX and Linux software client as shown below:
    SERVICE_MESSAGE 09/23/13 13:44:14.709092505 
    NEWREG 15532258/000     : Unable to attach to debugger. error: -3
    SERVICE_MESSAGE 09/23/13 13:44:16.775111648 NEWREG 15532258/000     : 
    Unable to attach to debugger. error: -3
  • If AllowDebugging is not set to yes, the warning message shown in Figure 11 is displayed when the CDCN transaction is run.
Figure 11. Warning message when debugging is not enabled
Error message: Debugging not allowed
  • CICS programs not compiled with the –a flag. The debugger shows the assembly instructions, see Figure 12.
Figure 12. Assembly instructions shown with Rational Developer for AIX and Linux software
Result of leaving out the –a flag

Click to see larger image

Figure 12. Assembly instructions shown with Rational Developer for AIX and Linux software

Result of leaving out the –a flag
  • If the CICS_IDEBUG_LIBPATH environment variable is not set properly, or has an incorrect path reference, CDCN throws an error message,shown in Figure 13.
Figure 13. Environment is not set properly
Debugger uninstalled or installed incorrectly

Summary

This tutorial showed you step-by-step how to configure and debug mixed- language CICS applications deployed on TXSeries regions from IBM Rational Developer for AIX and Linux.

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
ArticleID=957415
ArticleTitle=Debug mixed-language CICS applications deployed on TXSeries with Rational Developer tools
publish-date=12172013