Exposing an existing program

Now that you have configured your CICS region, and you have a working development environment and you have created the project structure you can fully focus on Java development. This section will guide you through the main points to develop your JAX-WS application.

Select an existing program to expose

In a real environment you will have a business need that will lead you to the choice of a CICS program to expose. For this article the program has been developed using these criteria:

  1. Invocation method (COMMAREA or Channel/Container) — COMMAREA will be used because it is the most common invocation method
  2. Data structure complexity — The data structure will be described by a COBOL copy book file. It is extensive enough to show most common data types treated by CICS programs. Here the point is that your Java application will need to marshall the COBOL data before generating the web service code.
  3. Functionality — The focus of this article is on web services processing. So, the CICS program you link to can be as simple as you want. For example a computational program

Program communication area description

The COMMAREA used by our program is as follows:

*—————————————————————*
* EDUCPY.cpy                                                    *
*                                                                     *
* AUTHOR  : Giovanni Creato/Italy/IBM                                 *
* DATE    : 19 / 12 / 2014                                            *
* VERSION : 1.0                                                       *
*                                                                     *
* MISSION : Sample COPY book to demonstrate J2C conversion            *
* HISTORY :                                                           *
*———————————————————————*
* Description                                                         *
*                                                                     *
* This COPY will be used by a Java program to communicate with        *
* a COBOL CICS program. Data types used in this COPY should be        *
* exaustive enough to demonstrate common cases of data                *
* conversion from Java to COBOL                                       *
*                                                                     *
*———————————————————————*
03 DATA-PAYLOAD.
05 BINARY-DIGIT                      PIC 9(4) COMP.
05 CHARACTER-STRING                  PIC X(30).
05 NUMERIC-STRING                    PIC 9(18).
05 PACKED-DIGIT                      PIC 9(15) COMP-3.
05 PACKED-DIGIT-WITH-COMMA           PIC 9(12)V9(3) COMP-3.
05 SIGNED-PACKED                     PIC S9(12) COMP-3.
05 BOOL                              PIC X.
88 BOOL-FALSE                      value X'00'.
88 BOOL-TRUE                       value X'01' through X'FF'.
05 RESULT.
09 RESULT-CODE                     PIC S9(5) VALUE +0.
09 RESULT-TEXT                     PIC X(25).
*—————————————————————-*

Develop Java web application to run in Liberty JVM

In the following sections you will develop the actual Java code that will expose a web service on you CICS region. This web service will interact with an existing CICS program using the JCICS API. For more details please refer to Developing Java web applications to run in Liberty JVM.

Develop JAX-WS web applications that invoke an existing CICS program

This section present the application logic you need to develop to expose an existing CICS program using JAX-WS. If you are interested in JAX-WS development you may find more resources on DeveloperWorks web site.

In this next section you will use JAX-WS annotations to expose a POJO as a web service.

Create input and output messages

You will use JAX-WS annotations on a POJO to expose a Java class as a web service. In order to expose only the input and output messages you are interested in you may find it convenient to use a class for the web service response and list the parameters for the web service request.

For example you could use a class like this for the message response:

package com.ibm.it.bean;
public class ResponseWrapper {
   int resultCode;
   String resultText;
   //getters and setters associated with the fields and default constructor
}

Create the actual web service

In this section you will develop a POJO and annotate it with JAX-WS annotations. At run time this will be available as a web service. See the snippet below:

@WebService(name="MyCICSService")

public class MyCICSService {

   @WebMethod
   public ResponseWrapper invokeCICSProgram( int binaryDigit, String characterString, long numericString,
              BigDecimal packedDecimal, long signedDecimal, String bool  ){
      …
   }
}

The snippet provided will resolve at run time in a web service having an operation named InvokeCICSProgram that has a message with the six listed parameters as input and a message of the type ResponseWrapper as output.

Develop the business logic

This section focuses on the Java business logic of your web service. In this section you will:

  1. Use the Java wrapper to map input parameters to the binary structure that will be used to LINK to a CICS program
  2. Invoke an existing program using JCICS API
  3. Map the response received from the CICS program to the web service response

Map input parameters to the binary structure

Programs invoked using the JCICS LINK API generally require a binary COMMAREA structure for input and output. If you have generated a Java wrapper of your binary structure you will simply need to instantiate a new wrapper and set its fields with the parameters. See the snippet below:

 CommareaWrapper commareaWrapper = new CommareaWrapper();

 commareaWrapper.setBinaryDigit(binaryDigit);

 commareaWrapper.setCharacterString(characterString);

 commareaWrapper.setNumericString(numericString);

 commareaWrapper.setPackedDigit(packedDecimal);

 commareaWrapper.setSignedPacked(signedDecimal); 

 commareaWrapper.setBool(bool);

Invoke an existing program

Now that you have a binary structure to invoke the CICS program you will LINK to it using JCICS API. For more details on JCICS API please refer to Java development using JCICS.

Task t = Task.getTask();
if ( t == null ){
   System.err.println("LinkProgram : Can't get Task");
}
else
{
   Program programToLink = new Program();
   programToLink.setName(cicsProgram);

   try {
      programToLink.link(commareaWrapper.getByteBuffer()); //JZOS
      programToLink.link(commareaWrapper.getBytes()); //J2C
      result = "OK";
   } catch (CicsConditionException e) {
      System.err.println("An error occurred");
      System.err.println("Message " + e.getMessage());
   }
}
 

Now map the response received from the CICS program to the web service response. Then once returned from the CICS program you can simply map the received results to the ResponseWrapper.

 
ResponseWrapper response = new ResponseWrapper(
   commareaWrapper.getResultCode(),
   commareaWrapper.getResultText()

);

Congratulations you have now finished developing your CICS Liberty JAX-WS web service that invokes an existing CICS program.

Join The Discussion

Your email address will not be published. Required fields are marked *