Configuring WebSphere Message Broker with CICS Transaction Server using the CICSRequest node

A new feature in Websphere Message Broker V7, the CICSRequest node, enables it to act as a client for IBM CICS Transaction Server (TS), invoking CICS transactions and receiving responses back from CICS TS. This article gives you the details.

Saurabh Dixit (saudixit@in.ibm.com), Software Engineer, IBM

Photo of Saurabh DixitSaurabh Dixit has five years of experience on the WebSphere TXSeries and WebSphere Message Broker Test Teams. He has expertise in database testing, and has an MS in Computer Science with a specialization in Software Engineering. You can contact Saurabh at saudixit@in.ibm.com.



Avinash Jhawar (avjhawar@in.ibm.com), Staff Software Engineer, IBM

Photo of Avinash JhawarAvinash Jhawar has nine years of experience in software testing and development. He currently works on WebSphere Message Broker and IBM Integration Bus. You can contact Avinash at avjhawar@in.ibm.com.



Pabitra Mukhopadhyay (pabmukho@in.ibm.com), Software Engineer, IBM

Photo of Pabitra MukhopadhyayPabitra Mukhopadhyay has seven years of experience with IBM mainframes (System z) application development, testing, and systems programming. He is currently working with the IBM India Software Labs System z Competency team as a z/OS and middleware systems programmer. He has co-authored developerWorks articles involving messaging products and z/OS. You can contact Pabitra at pabmukho@in.ibm.com.



31 August 2011

Also available in Chinese

Introduction

This article shows you how IBM® Websphere® Message Broker (hereafter referred as Message Broker) communicates with Customer Information Control System Transaction Server (hereafter referred to as CICS® TS) running on z/OS®. A new feature in Websphere Message Broker V7, the CICSRequest node, enables Message Broker to act as a CICS TS client., sending Internet Protocol InterCommunications (IPIC) requests over TCP/IP to CICS TS and receiving responses back from CICS TS. This article shows you how to set up a communication link between Message Broker and CICS TS, which involves the following steps:

  1. Creating a VSAM Key-Sequenced Dataset (KSDS)
  2. Writing a sample COBOL CICS program on z/OS
  3. Setting up a CICS TS region on z/OS
  4. Developing a sample message flow using the CICSRequest node
  5. Executing the message flow

CICS TS on z/OS supports several programming languages. Because of its simplicity and easy-to-understand syntax, COBOL is used as the programming language for the sample program in this article. Depending on your skills and preferences, you can create an equivalent program in any other supported language and use it in place of the sample COBOL program.

Message Broker is a middleware product for transforming and routing messages between business-critical applications. CICS TS is a widely used application server in distributed transaction processing environments as well as in IBM System z® (mainframe) environments. CICS TS for z/OS provides general-purpose transaction processing, meeting the needs of both large and small enterprises.

Prerequisites for this article

To benefit from this article, you should have basic knowledge of:

  • CICS TS and z/OS
  • CICS and COBOL programming and compilation
  • WebSphere Message Broker
  • WebSphere MQ

To execute the message flow provided in this article, you will need:

  • A z/OS LPAR with:
    • COBOL and CICS TS V3.2 or later
    • A user ID with authority to compile COBOL and CICS programs, and execute CICS administrative commands
  • A Microsoft® Windows® machine with:
    • WebSphere Message Broker runtime V7.0 or later
    • WebSphere Message Broker Toolkit V7.0 or later
    • The rfhutil utility (available for free from IBM)

Setup required to run a message flow

  1. Create a queue manager QM_CICSTestFlow and a Message Broker BRK_CICSTestFlow on the Windows machine and start these components.
  2. Create an execution group CICSTestFlowEG.
  3. Create the following queues: CICSINPUT, CICSOUTPUT, and CICSOUTPUTXML.
  4. Start a CICS region on z/OS with TCPIP=YES.

1. Creating a VSAM Key-Sequenced Dataset (KSDS)

  1. Use the IDCAMS utility to create a VSAM KSDS cluster, data, and index datasets. In the example below, the record length is 80, the key length is 5, and the key position is 1 through 5. Check your system's standard job card and dataset high level qualifiers (HLQs) and modify all jobs given below accordingly:
    JCL to create VSAM KSDS
      File  Edit  Edit_Settings  Menu  Utilities  Compilers  Test  Help            
    -------------------------------------------------------------------------------
    VIEW       PABMUKH.CNTL(IDCKSDS1) - 01.05                  Columns 00001 00072 
    Command ===>                                                  Scroll ===> CSR
    ****** ***************************** Top of Data ******************************
    000001 //IDCKSDS1 JOB (934801),'IDCAMS - KSDS',CLASS=A,                        
    000002 //     NOTIFY=&SYSUID,REGION=0M,MSGCLASS=H,MSGLEVEL=(1,1)           
    000003 //*                                                                     
    000004 //*  DELETE CLUSTER, SET RC=0 AND THEN CREATE KSDS DATASET              
    000005 //*                                                                     
    000006 //ALLOKSDS EXEC PGM=IDCAMS                                              
    000007 //SYSPRINT DD SYSOUT=*                                                  
    000008 //SYSIN DD *                                                            
    000009  DELETE (PABMUKH.WMBCICS.KSDS.FILE1) CLUSTER PURGE                      
    000010  IF MAXCC ¬= 0 THEN SET MAXCC=0                                         
    000011  DEFINE CLUSTER (                                     -                 
    000012           NAME(PABMUKH.WMBCICS.KSDS.FILE1)            -                 
    000013           VOLUMES(LETSMS)                             -                 
    000014           CISZ(4096)                                  -                 
    000015           FREESPACE(10 10)                            -                 
    000016           RECORDSIZE(80 80)                           -                 
    000017           KEYS(5 0)                                   -                 
    000018           TRACKS(100 100)                             -                 
    000019           INDEXED                                     -                 
    000020           )                                           -                 
    000021         DATA (                                        -                 
    000022           NAME(PABMUKH.WMBCICS.KSDS.FILE1.DATA)       -                 
    000023           )                                           -                 
    000024         INDEX (                                       -                 
    000025           NAME(PABMUKH.WMBCICS.KSDS.FILE1.INDEX)      -                 
    000026           )                                                             
    000027  IF LASTCC = 0 THEN LISTCAT ALL LEVEL(PABMUKH.WMBCICS.KSDS.FILE1)       
    000028 /*
  2. Insert a few records into the VSAM dataset created in Step 1 in this section. In this example, the following data layout has been used:
    • Position 01 to 05: Employee ID
    • Position 06: Filler (Space)
    • Position 07 to 31: Employee Name
    • Position 32: Filler (Space)
    • Position 33 to 35: Department Code
    • Position 36: Filler(Space)
    • Position 37 to 44: Lotus Notes ID
    • Position 45 to 80: Filler (Space)

    Use the JCL below to insert data into the VSAM dataset:

    JCL to insert data into VSAM KSDS
       File  Edit  Edit_Settings  Menu  Utilities  Compilers  Test  Help            
    ------------------------------------------------------------------------------- 
     VIEW       PABMUKH.CNTL(REPRO02) - 01.01                   Columns 00001 00072 
     Command ===>                                                  Scroll ===> CSR
     =COLS> ----+----1----+----2----+----3----+----4----+----5----+----6----+----7-- 
     ****** ***************************** Top of Data ******************************
     000001 //REPRO02 JOB (934801),'LOAD VSAM',CLASS=A,                             
     000002 //     NOTIFY=&SYSUID,REGION=0M,MSGCLASS=H,MSGLEVEL=(1,1)           
     000003 //*                                                                     
     000004 //STEP1 EXEC PGM=IDCAMS                                                 
     000005 //SYSPRINT DD SYSOUT=*                                                  
     000006 //FILEOUT DD DSN=PABMUKH.WMBCICS.KSDS.FILE1,DISP=SHR                    
     000007 //DATAIN DD *                                                           
     000008 00001 PABITRA MUKHOPADHYAY      AB1 PABMUKHO                            
     000009 00002 AVINASH JHAWAR            AB1 AVJHAWAR                            
     000010 00004 SAURABH DIXIT             CD2 SAUDIXIT                            
     000011 /*                                                                      
     000012 //SYSIN DD *                                                            
     000013   REPRO INFILE(DATAIN) OUTFILE(FILEOUT)                                 
     000014 /*
     ****** **************************** Bottom of Data ****************************
  3. Use the JCL below to view the records that were inserted into the VSAM dataset in Step 2 in this section:
    JCL to view data present in VSAM KSDS
       File  Edit  Edit_Settings  Menu  Utilities  Compilers  Test  Help            
    -------------------------------------------------------------------------------
     VIEW       PABMUKH.CNTL(REPRO03) - 01.00                   Columns 00001 00072 
     Command ===>                                                  Scroll ===> CSR
     ****** ***************************** Top of Data ******************************
     000001 //REPRO03 JOB (934801),'DISPLAY VSAM',CLASS=A,                          
     000002 //     NOTIFY=&SYSUID,REGION=0M,MSGCLASS=H,MSGLEVEL=(1,1)           
     000003 //*                                                                     
     000004 //STEP1 EXEC PGM=IDCAMS                                                 
     000005 //SYSPRINT DD SYSOUT=*                                                  
     000006 //INDD DD DSN=PABMUKH.WMBCICS.KSDS.FILE1,DISP=SHR                       
     000007 //OUTDD  DD SYSOUT=*                                                    
     000008 //SYSIN DD *                                                            
     000009   REPRO INFILE(INDD) OUTFILE(OUTDD)                                     
     000010 /*
     ****** **************************** Bottom of Data ****************************

    After the job has completed successfully, go to the Systems Display and Search Facility (SDSF) panel and check the OUTDD DDNAME of the job. It will show all records read from the VSAM dataset:

    Job output as viewed in spool
       Display  Filter  View  Print  Options  Help                                  
     -------------------------------------------------------------------------------
     SDSF OUTPUT DISPLAY REPRO03  JOB11978  DSID   103 LINE 0       COLUMNS 02- 81  
     COMMAND INPUT ===>                                            SCROLL ===> CSR
    ********************************* TOP OF DATA **********************************
    00001 PABITRA MUKHOPADHYAY      AB1 PABMUKHO                       
    00002 AVINASH JHAWAR            AB1 AVJHAWAR                       
    00004 SAURABH DIXIT             CD2 SAUDIXIT                       
    ******************************** BOTTOM OF DATA ********************************

2. Writing a sample COBOL CICS program on z/OS

  1. The next step is to write a sample COBOL CICS program to read a record from VSAM dataset based on a record key. A sample program named RDVSAM1 is given below as an example. This program accepts an operation code and a record key as inputs, then reads the VSAM dataset and returns the record back to CICS. DFHCOMMAREA has been used for data transfer between the client and CICS TS. The VSAM dataset created in Section 1 is referred to as EMPKSDS1 in this CICS region.

    The copybook RDVSAMC1, which contains the VSAM dataset layout, is shown below. The RDVSAM1 program uses this copybook in its WORKING-STORAGE SECTION.

    Copybook RDVSAMC1
      File  Edit  Edit_Settings  Menu  Utilities  Compilers  Test  Help            
    -------------------------------------------------------------------------------
    VIEW       PABMUKH.COBCOPY(RDVSAMC1) - 01.00               Columns 00001 00072 
    Command ===>                                                  Scroll ===> CSR
    ****** ***************************** Top of Data ******************************
    000100        01 FD-COMM-VARIABLES.                                            
    000200           05 FD-REQUEST.                                                
    000300              10 FD-Q-OPERATION                  PIC X(01).              
    000500              10 FD-Q-KSDS-KEY                   PIC X(05) VALUE SPACES. 
    000600       *                                                                 
    000700           05 FD-RESPONSE.                                               
    000800              10 FD-R-KSDS-FILEREC.                                      
    000900                 15 FD-R-KSDS-FILEREC-EMPID      PIC X(05) VALUE SPACES. 
    001000                 15 FILLER                       PIC X.                  
    001100                 15 FD-R-KSDS-FILEREC-EMPNAME    PIC X(25) VALUE SPACES. 
    001200                 15 FILLER                       PIC X.                  
    001300                 15 FD-R-KSDS-FILEREC-DEPTCD     PIC X(03) VALUE SPACES. 
    001400                 15 FILLER                       PIC X.                  
    001500                 15 FD-R-KSDS-FILEREC-LNID       PIC X(08) VALUE SPACES. 
    001600                 15 FILLER                       PIC X(36).              
    001700              10 FD-R-STATUS-MESSAGE             PIC X(40) VALUE SPACES. 
    ****** **************************** Bottom of Data ****************************
  2. The COBOL CICS program is shown below:
    COBOL CICS program RDVSAM1
      File  Edit  Edit_Settings  Menu  Utilities  Compilers  Test  Help            
    -------------------------------------------------------------------------------
    VIEW       PABMUKH.COBOL(RDVSAM1) - 01.00                  Columns 00001 00072 
    Command ===>                                                  Scroll ===> CSR
    ****** ***************************** Top of Data ******************************
    000001        IDENTIFICATION DIVISION.                                         
    000002        PROGRAM-ID.  RDVSAM1                                             
    000003        AUTHOR. P.MUKHOPADHYAY, A.JHAWAR, S.DIXIT                        
    000004       ******************************************************************
    000005       *                        DESCRIPTION                             *
    000006       *                        -----------                             *
    000007       *    THIS PROGRAM ACCEPTS A RECORD KEY, READS THE RECORD FROM    *
    000008       *    VSAM KSDS BASED ON THE KEY PROVIDED, AND RETURNS THE RECORD *
    000009       *    BACK THROUGH DFHCOMMAREA.                                   *
    000010       *    FILE USED: EMPKSDS1 (VSAM KSDS)                             *
    000011       *                                                                *
    000012       ******************************************************************
    000013        ENVIRONMENT DIVISION.                                            
    000014       *=====================*                                           
    000015        DATA DIVISION.                                                   
    000016       *==============*                                                  
    000017        WORKING-STORAGE SECTION.                                         
    000018       *                                                                 
    000019       * INCLUDE THE COPYBOOK FOR REQUEST AND RESPONSE DATA STRUCTURE.   
    000020       * THIS INCLUDES THE VSAM FILE LAYOUT FOR EMPKSDS1.                
    000021       *                                                                 
    000022        COPY RDVSAMC1.                                                   
    000023       *                                                                 
    000024       * DECLARE WORKING STORAGE VARIABLES USED IN THIS PROGRAM.         
    000025       *                                                                 
    000026        01 WS-VARIABLES.                                                 
    000027           05 WS-CICS-RESP-CODE                  PIC S9(08) COMP.        
    000028           05 WS-CICS-RESP-CODE-NUM              PIC 9(08) VALUE ZEROS.  
    000029           05 WS-FILE-NAME                       PIC X(08) VALUE SPACES. 
    000030       *                                                                 
    000031        LINKAGE SECTION.                                                 
    000032       *================*                                                
    000033       * THIS PROGRAM USES DFHCOMMAREA TO RECEIVE REQUEST AND SEND       
    000034       * THE RESPONSE BACK. HENCE, CODE DFHCOMMAREA IN THE LINKAGE       
    000035       * SECTION OF THIS PROGRAM. THE LENGTH OF DFHCOMMAREA FOR THIS     
    000036       * PROGRAM IS EQUAL TO THE VARIABLE STRING LENGTH OF RDVSAMC1      
    000037       * COPYBOOK (THIS INCLUDES REQUEST AND RESPONSE DATA STRUCTURE).   
    000038       *                                                                 
    000039        01 DFHCOMMAREA                        PIC X(126).                
    000040       *                                                                 
    000041        PROCEDURE DIVISION.                                              
    000042       *===================*                                             
    000043        A000-MAIN-CONTROL SECTION.                                       
    000044       *==========================*                                      
    000045       * CHECK THE EIBCALEN VARIABLE TO DETERMINE IF DFHCOMMAREA         
    000046       * CONTAINS REQUEST DATA OR NOT. EIBCALEN VARIABLE CONTAINS        
    000047       * THE LENGTH OF THE CICS COMMUNICATION AREA.                      
    000048       *                                                                 
    000049            IF EIBCALEN = ZERO                                           
    000050               INITIALIZE FD-RESPONSE                                    
    000051               MOVE 'ERR: REQUEST DATA NOT RECEIVED BY CICS'             
    000052                                        TO FD-R-STATUS-MESSAGE           
    000053            ELSE                                                         
    000054       *                                                                 
    000055       *       COPY THE REQUEST DATA FROM DFHCOMMAREA TO LOCAL VARIABLES.
    000056       *                                                                 
    000057               MOVE DFHCOMMAREA(1:6) TO FD-REQUEST                       
    000058               PERFORM B100-INITIALIZATION                               
    000059       *                                                                 
    000060       *       VALIDATE THE REQUEST DATA RECEIVED FROM DFHCOMMAREA.      
    000061       *                                                                 
    000062               EVALUATE FD-Q-OPERATION                                   
    000063                 WHEN 'R'                                                
    000064                      PERFORM B200-READ-FILE                             
    000065                 WHEN OTHER                                              
    000066                      MOVE 'ERR: UNKNOWN FILE OPERATION IN REQUEST'      
    000067                                               TO FD-R-STATUS-MESSAGE    
    000068               END-EVALUATE                                              
    000069            END-IF                                                       
    000070            PERFORM B300-TERMINATE                                       
    000071            EXIT.                                                        
    000072       ******************************************************************
    000073       /                                                                 
    000074        B100-INITIALIZATION SECTION.                                     
    000075       *============================*                                    
    000076       * INITIALIZE THE LOCAL VARIABLES USED IN THIS PROGRAM.            
    000077       *                                                                 
    000078            INITIALIZE FD-RESPONSE                                       
    000079                       WS-CICS-RESP-CODE                                 
    000080                       WS-CICS-RESP-CODE-NUM                             
    000081                       WS-FILE-NAME                                      
    000082            EXIT.                                                        
    000083       /                                                                 
    000084        B200-READ-FILE SECTION.                                          
    000085       *=======================*                                         
    000086       * READ THE EMPKSDS1 FILE WHICH IS ALREADY OPENED BY CICS.         
    000087       *                                                                 
    000088            MOVE 'EMPKSDS1' TO WS-FILE-NAME                              
    000089            EXEC CICS                                                    
    000090                READ FILE(WS-FILE-NAME)                                  
    000091                     INTO(FD-R-KSDS-FILEREC)                             
    000092                     RIDFLD(FD-Q-KSDS-KEY)                               
    000093                     RESP(WS-CICS-RESP-CODE)                             
    000094            END-EXEC.                                                    
    000095       *                                                                 
    000096       * CHECK THE CICS RESPONSE CODE RETURNED FOR READ FILE COMMAND.    
    000097       *                                                                 
    000098            EVALUATE WS-CICS-RESP-CODE                                   
    000099                 WHEN DFHRESP(NOTFND)                                    
    000100                     MOVE 'ERR: EMPLOYEE ID DOES NOT EXIST'              
    000101                               TO FD-R-STATUS-MESSAGE                    
    000102                 WHEN DFHRESP(NORMAL)                                    
    000103                     MOVE 'MSG: EMPLOYEE DETAILS FOUND'                  
    000104                               TO FD-R-STATUS-MESSAGE                    
    000105                 WHEN OTHER                                              
    000106                     MOVE WS-CICS-RESP-CODE TO WS-CICS-RESP-CODE-NUM     
    000107                     STRING 'ERR: CICS RESPONSE CODE: '                  
    000108                         WS-CICS-RESP-CODE-NUM DELIMITED BY SIZE         
    000109                                          INTO FD-R-STATUS-MESSAGE       
    000110            END-EVALUATE                                                 
    000111            EXIT.                                                        
    000112       /                                                                 
    000113        B300-TERMINATE SECTION.                                          
    000114       *=======================*                                         
    000115       * COPY THE LOCAL VARIABLES FOR REQUEST AND RESPONSE DATA BACK     
    000116       * TO DFHCOMMAREA. CICS WILL RETURN THE DATA FROM DFHCOMMAREA TO   
    000117       * TO THE CLIENT THAT INVOKED THIS TRANSACTION.                    
    000118       *                                                                 
    000119            MOVE FD-COMM-VARIABLES TO DFHCOMMAREA                        
    000120       *                                                                 
    000121       * RETURN THE CONTROL BACK TO CICS.                                
    000122       *                                                                 
    000123            EXEC CICS RETURN END-EXEC.                                   
    000124            EXIT.                                                        
    ****** **************************** Bottom of Data ****************************
  3. Compile the COBOL CICS program that you have written in the previous step. Place the load module generated at the end of compilation in an appropriate load library, and ensure that that load library is present in the CICS library concatenation.

3. Setting up a CICS TS region on z/OS

The next step is to set up your CICS region to communicate with Message Broker. Log on to your CICS region using a 3270 emulator and follow these steps:

  1. Define a VSAM KSDS:

    Execute the command CEDA DEF F. Specify the logical file name EMPKSDS1, the CICS group name for your system setup, and the DSName as the dataset name that you created in Section 1. Specify the record length as 80 and the key length as 5. By default, this dataset is enabled for READ operation. Default values for other parameters are good enough to run this message flow. After the dataset is defined, you can view the entries by providing the group name after executing the command CEDA V F(EMPKSDS1).

  2. Define a TCPIPService:

    Execute the command CEDA DEF TC. Specify a TCPIPService name, a, CICS group name, and a port number through which CICS TCPIPService will communicate with the Message Broker (before you assign a port for this setup, consult your CICS administrator).

    Also, specify DFHISAIP as the Urm, IPic as the PROtocol, CISS as the TRansaction (default transaction for this setup), and the IP address of the z/OS LPAR in the Ipaddress field. Default values for the other parameters will satisfy the requirements for running this message flow. After the TCPIPService has been defined, you can view the entries after executing the command CEDA V TC(<TCPIPService_Name>) and providing the group name.

  3. Define a program:

    Execute the command CEDA DEF PROG. Specify the program name RDVSAM1 in the PROGram field, the CICS group name for your system setup, and CObol as the Language. Default values for other parameters are good enough to run this message flow. After the TCPIPService has been defined, you can view the entries after executing the command CEDA V PROG(RDVSAM1) and providing the group name.

  4. Install CICS components:

    Install one by one all of the components that you created in Steps 1, 2, and 3 in this section. Execute the following command and provide the component name along with the CICS group to which the component is associated.

  5. Check file status:

    For your program to be able to read a record from the VSAM KSDS, the dataset must be in opened state in the CICS region. Execute the command CEMT I FI(EMPKSDS1), then check the file status. If it is Clo (closed), overtype it with Ope and press the Enter key. Ensure that you get a NORMAL response to changing the file status. The file will open in the CICS region and the status will be updated accordingly on your screen.

4. Developing a sample message flow using the CICSRequest node

A sample message flow involving the CICSRequest node is shown in Figure 1 below. The nodes used in this message flow are:

  • MQInput node (CICS INPUT)
  • Compute node (Format Request and Format Response)
  • CICSRequest node (Read KSDS Record)
  • MQOutput node (CICS OUTPUT [EBCDIC] and CICS OUTPUT [XML])
    Figure 1. Message flow using CICSRequest node
    Message flow using CICSRequest node

Create this message flow using the WebSphere Message Broker Toolkit and the connections shown in Figure I. The settings and configuration of the different nodes are described below:

  1. CICS INPUT -- MQInput node:
    1. Specify queue name as CICSINPUT.
    2. Click on Input Message Parsing tab and select XMLNSC in the Message Domain field to set the MQInput node to accept input in XML format.
    3. Accept the defaults for the other settings.
  2. Format Request and Format Response -- Compute nodes:
    1. The Format Request node converts XML input into a CICS request string and then changes the encoding from ASCII to EBCDIC.
    2. Here is the ESQL for the Format Request node:
      ESQL for Format Request Compute node
      CREATE COMPUTE MODULE CICSTestFlow_FormatRequest
         CREATE FUNCTION Main() RETURNS BOOLEAN
         BEGIN
            DECLARE MsgIn      CHARACTER;
            DECLARE CICSReqMsg BLOB;
      
      -- Concatenate Operation and EmpID fields in the xml to 
      -- prepare the CICS Request String in ASCII
            SET MsgIn = InputRoot.XMLNSC.Message.operation || 
               InputRoot.XMLNSC.Message.empid;
      -- Convert the CICS Request string from ASCII to EBCDIC
            SET CICSReqMsg = CAST(MsgIn as BLOB CCSID 500);
      
            SET OutputRoot.BLOB.BLOB = CICSReqMsg;
            RETURN TRUE;
         END;
      END MODULE;
    3. The Format Response node converts the CICS response string encoding from EBCDIC to ASCII and then transforms the response into XML.
    4. Here is the ESQL for the Format Response node:
      ESQL for Format Response Compute node
      CREATE COMPUTE MODULE CICSTestFlow_FormatResponse
         CREATE FUNCTION Main() RETURNS BOOLEAN
         BEGIN
            DECLARE CICSRespMsg  BLOB;
            DECLARE CICSRespChar CHARACTER;
            DECLARE MsgOut       BLOB;
            DECLARE MsgOutChar   CHARACTER; 
      
         -- Receive CICS Response into CICSRespMsg variable and convert the 
         -- response string from EBCDIC to ASCII
            SET CICSRespMsg  = InputRoot.BLOB.BLOB;
            SET CICSRespChar = CAST(CICSRespMsg AS CHARACTER CCSID 500);
            SET MsgOut       = CAST(CICSRespChar AS BLOB CCSID 850);
            SET MsgOutChar   = CAST(MsgOut AS CHARACTER CCSID 850);
      
         -- Prepare Output xml from the CICS Response string in ASCII encoding
            SET OutputRoot.XMLNSC.Message.Status = 
               TRIM(SUBSTRING(MsgOutChar FROM 87 FOR 40)) ;
            SET OutputRoot.XMLNSC.Message.EmpDetails.EmpID = 
               TRIM(SUBSTRING(MsgOutChar FROM 7 FOR 5)) ;
         SET OutputRoot.XMLNSC.Message.EmpDetails.EmpName = 
               TRIM(SUBSTRING(MsgOutChar FROM 13 FOR 25)) ; 
            SET OutputRoot.XMLNSC.Message.EmpDetails.DeptCode = 
               TRIM(SUBSTRING(MsgOutChar FROM 39 FOR 3)) ;
            SET OutputRoot.XMLNSC.Message.EmpDetails.LNID = 
               TRIM(SUBSTRING(MsgOutChar FROM 43 FOR 8)) ;
            RETURN TRUE;
         END;
      END MODULE;
    5. Select the Format Request node:
      1. Click on the Basic tab and choose the appropriate ESQL module using the Browse button.
      2. Choose Local Environment and Message in the Compute mode dropdown.
    6. Select the Format Response node:
      1. Click on the Basic tab. Choose the appropriate ESQL module using the Browse button.
      2. Choose Message in the Compute mode dropdown.
    7. Accept the default values for the other settings.
  3. Read KSDS Record -- CICSRequest node:
    1. Execute the following command to create a configurable service:
      Command to create a configurable service
      mqsicreateconfigurableservice BRK_CICSTestFlow 
      -c CICSConnection 
      -o CICSTestFlowConfServ 
      -n cicsServer,clientApplid,clientQualifier 
      -v tcp://<IPaddress_or_hostname>:<CICS_TCPIPService_port_number>,BRKApp,BRKQual

      The port number in this command is the port on which CICS TCPIPService is listening, and the same port that you set up in Section 3. After the configurable service has been created successfully, restart the broker using the mqsistop and mqsistart commands.

    2. Next, click on the CICSRequest node and select the Basic tab:
      1. Provide the CICS configurable service object name CICSTestFlowConfServ in the CICS Server field.
      2. Provide your CICS program name, in this case - RDVSAM1, in the Program name field.
      3. Select Commarea Data structure radio button, as the RDVSAM1 program uses CICS Commarea.
      4. Provide the Commarea Length, which is 126 for the RDVSAM1 program.
      5. Enter the Request timeout as 120 sec.
    3. Select the Request tab:
      1. Set Data location as $Body
      2. Set Program name override location as $LocalEnvironment/Destination/CICS/CICSProgramName
    4. Select the Result tab:
      1. Set Result data location as $ResultRoot
      2. Set Output data location as $OutputRoot
    5. Select the Response Message Parsing tab:
      1. Set Message Domain as BLOB
      2. Set Message coded character set ID as EBCDIC (500)
      3. Set Message Encoding as Big Endian, with S390 Floating Point (785)
    6. Accept the default values for the other settings.
  4. CICS OUTOUT XML and CICS OUTPUT (EBCDIC) -- MQOutput nodes:
    1. Click on CICS OUTPUT XML node and select Basic tab. Provide the queue name as CICSOUTPUTXML.
    2. Click on CICS OUTPUT (EBCDIC) node and select Basic tab. Provide the queue name as CICSOUTPUT.
    3. Accept the default values for the other settings.
  5. Deploy the message flow to the message broker execution group.

5. Executing the message flow

  1. Download CICSTestFlow.zip file at the bottom of the article and unzip the downloaded file. The zipped file contains the project interchange (PI) file for this message flow (CICSTestFlow_PI.zip), the input message XML (MsgIn.xml), the COBOL CICS program (RDVSAM1.cbl), and the program copybook (RDVSAMC1.cpy).
  2. Put the input message from MsgIn.xml file in the CICSINPUT queue.
  3. Get the output messages from the CICSOUTPOUT and CICSOUTPUTXML queues.
  4. Execute this message flow with different combinations of input data in the XML, and then check the responses.

There are different ways to send and receive messages from WebSphere MQ for testing purposes. One way is to use the free utility rfhutil: Download rfhutil as a WebSphere MQ Support Pack from the IBM Support site.

Figures 2 and 3 are snapshots of the output message data using rfhutil:

Figure 2. Output message (in EBCDIC format), read from CICSOUTPUT queue, using COBOL copybook RDVSAMC1
Output message (in EBCDIC format), read from CICSOUTPUT queue, using COBOL copybook RDVSAMC1
Figure 3. Output XML message (in ASCII format), read from CICSOUTPUTXML queue
Output XML message (in ASCII format), read from CICSOUTPUTXML queue

Download

DescriptionNameSize
PI file, Input Message, COBOL program and copybookCICSTestFlow.zip8KB

Resources

  • CICS resources
  • WebSphere Message Broker resources
    • WebSphere Message Broker V7 information center
      A single Web portal to all WebSphere Message Broker V7 documentation, with conceptual, task, and reference information on installing, configuring, and using your WebSphere Message Broker environment.
    • WebSphere Message Broker developer resources page
      Technical resources to help you use WebSphere Message Broker for connectivity, universal data transformation, and enterprise-level integration of disparate services, applications, and platforms to power your SOA.
    • WebSphere Message Broker product page
      Product descriptions, product news, training information, support information, and more.
    • What's new in WebSphere Message Broker V7
      WebSphere Message Broker V7 provides universal connectivity with its ability to route and transform messages from anywhere to anywhere. Through its simple programming model and a powerful operational management interface, it makes complex application integration solutions much easier to develop, deploy, and maintain. This article describes the major enhancements in V7.
    • Download free trial version of WebSphere Message Broker V7
      WebSphere Message Broker V7 is an ESB built for universal connectivity and transformation in heterogeneous IT environments. It distributes information and data generated by business events in real time to people, applications, and devices throughout your extended enterprise and beyond.
    • WebSphere Message Broker documentation library
      WebSphere Message Broker specifications and manuals.
    • WebSphere Message Broker forum
      Get answers to your technical questions and share your expertise with other Message Broker users.
    • WebSphere Message Broker support page
      A searchable database of support problems and their solutions, plus downloads, fixes, and problem tracking.
  • WebSphere resources
    • developerWorks WebSphere developer resources
      Technical information and resources for developers who use WebSphere products. developerWorks WebSphere provides product downloads, how-to information, support resources, and a free technical library of more than 2000 technical articles, tutorials, best practices, IBM Redbooks, and online product manuals.
    • developerWorks WebSphere application connectivity developer resources
      How-to articles, downloads, tutorials, education, product info, and other resources to help you build WebSphere application connectivity and business integration solutions.
    • developerWorks WebSphere SOA and Web services developer resources
      How-to articles, downloads, tutorials, education, product info, and other resources to help you design and build WebSphere SOA and Web services solutions.
    • Most popular WebSphere trial downloads
      No-charge trial downloads for key WebSphere products.
    • WebSphere forums
      Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users.
    • WebSphere on-demand demos
      Download and watch these self-running demos, and learn how WebSphere products and technologies can help your company respond to the rapidly changing and increasingly complex business environment.
    • developerWorks WebSphere weekly newsletter
      The developerWorks newsletter gives you the latest articles and information only on those topics that interest you. In addition to WebSphere, you can select from Java, Linux, Open source, Rational, SOA, Web services, and other topics. Subscribe now and design your custom mailing.
    • WebSphere-related books from IBM Press
      Convenient online ordering through Barnes & Noble.
    • WebSphere-related events
      Conferences, trade shows, Webcasts, and other events around the world of interest to WebSphere developers.
  • developerWorks resources
    • Trial downloads for IBM software products
      No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
    • developerWorks blogs
      Join a conversation with developerWorks users and authors, and IBM editors and developers.
    • developerWorks tech briefings
      Free technical sessions by IBM experts to accelerate your learning curve and help you succeed in your most challenging software projects. Sessions range from one-hour virtual briefings to half-day and full-day live sessions in cities worldwide.
    • developerWorks podcasts
      Listen to interesting and offbeat interviews and discussions with software innovators.
    • developerWorks on Twitter
      Check out recent Twitter messages and URLs.
    • IBM Education Assistant
      A collection of multimedia educational modules that will help you better understand IBM software products and use them more effectively to meet your business requirements.

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 WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=754690
ArticleTitle=Configuring WebSphere Message Broker with CICS Transaction Server using the CICSRequest node
publish-date=08312011