CICS-Run Java applications-(5) Use JCICSX

Introduction

CICS Transaction Server provides a class library called JCICS for using CICS functions from Java. This is the Java version of the so-called EXEC CICS API, which allows you to call other CICS programs with LINK and access CICS management resources such as TSQ / TDQ. By using this, you can write a CICS application in Java. Shipping on June 12, 2020, CICS TS V5.6 now offers a new CICS API for Java called JCICSX, which is an extension of JCICS. Here, I will describe a series of flow when I tried to move the JCI CSX.

Related article

CICS-Run Java application-(1) Run simple sample application CICS-Run Java application-(2) Build management by Maven CICS-Run Java application-(3) Build management with Gradle CICS-Run Java application-(4) Spring Boot application CICS-Run Java application-(5) Use JCICSX

Environmental information

Development environment Windows10

** Execution environment ** z/OS V2.4 CICS Transaction Server for z/OS V5.6

Overview of JCICSX

The position of "class library for using CICS functions from Java ≒ Java version of EXEC CICS API" is the same for both JCICS and JCICSX. What's different is that JCICSX is an API that has been extended to make it easier to test on your local PC (development environment). In addition, JCICS supports a wide range of functions equivalent to EXEC CICS, but JCICSX is still limited and provides only Channel & Container and Link-related functions. reference: JCICS Javadoc JCICSX Javadoc

"Easy to test on a local PC (development environment)" has the following two points.

(1) Unit testing is possible using the testing framework image.png

Of course, there is no CICS runtime on the local PC, so the CICS-dependent code (JCICSX part) cannot be executed as it is. When unit testing a module containing environment-dependent code such as DB access, there is a framework (Mockito etc.) that handles the external resource access part as a Mock, but it is said that it will also be applied to the CICS access part. .. (I think this is mainly due to the features provided by frameworks such as Mockito.)

(2) Operation can be confirmed on the Liberty server on the PC This is the main extension function of CICS, but we provide a mechanism to check the operation of JCICSX with Liberty on the local PC (in the development environment). The image is as follows. image.png

This mechanism is called "remote development". Prepare Liberty on the PC and CICS-Liberty for the development environment, and configure the features for JCICSX remote development respectively. With this configuration, Liberty on the local PC behaves as if it were running on CICS. Therefore, it is not necessary to deploy the application on the host side and check the operation every time when trying & error or testing, and you can run a detailed cycle of operation check and correction on the local PC. Once the code is finally solidified, it can be deployed and run in the real CICS-Liberty environment for test / production rings.

In other words, it is convenient to use JCICSX when creating a Liberty application that passes data with Channel & Container and calls an existing application with Link (LINK passed with COMMAREA is not possible).

The following describes the configuration procedure for testing JCICSX on the Liberty server on your PC.

CICS-Liberty Remote Development Environment Configuration

Reference: Configuring the environment for JCICSX

CICS-Liberty side (server side) configuration

JVM profile

Prepare the JVM profile on USS. (Properties for the JVMServer are effectively specified in a file on this USS. The JVMSERVER resource definition points to the filename of this JVM profile.) A sample is provided, so copy it and use it.

Create a directory called /var/cicsts/cicsts56/CT56B4A1/JVMProfiles and put /usr/lpp/cicsts/cicsts56/JVMProfiles/DFHWLP.jvmprofile (sample definition for Liberty located under the CICS installation directory) in it. Copy it with the name DFHWLPX.jvmprofile. Customize as appropriate for your environment.

DFHWLPX.jvmprofile excerpt


JAVA_HOME=/usr/lpp/java/J8.0_64/
WORK_DIR=/var/cicsts/cicsts56/CT56B4A1/work
WLP_INSTALL_DIR=/usr/lpp/cicsts/cicsts56/wlp
-Dcom.ibm.cics.jvmserver.wlp.autoconfigure=true
-Dcom.ibm.cics.jvmserver.wlp.server.host=*
-Dcom.ibm.cics.jvmserver.wlp.server.http.port=56461
-Dcom.ibm.cics.jvmserver.wlp.server.https.port=56471
-Xms128M
-Xmx256M
-Xmso1M
-Xgcpolicy:gencon
-Xscmx256M
-Xshareclasses:name=cicsts%g,groupAccess,nonfatal
-Xtune:virtualized
-Dcom.ibm.tools.attach.enable=no
-Dfile.encoding=ISO-8859-1
_BPXK_DISABLE_SHLIB=YES

SIT

Specify the directory where the above properties file is located in the SIT parameter "JVMPROFILEDIR".

JVMPROFILEDIR=/var/cicsts/cicsts56/CT56B4A1/JVMProfiles 

Restart the region for the changes to take effect.

JVM Server definition

Prepare the JVMSERVER resource definition. Customize the JVMSERVER definition "DFHWLP" in the product-provided DFH $ WLP group by copying it to the appropriate group with the name "DFHWLPX".

OBJECT CHARACTERISTICS                                    CICS RELEASE = 0730 
 CEDA  View JVmserver( DFHWLPX  )                                             
  JVmserver      : DFHWLPX                                                    
  Group          : TAGGRP                                                     
  DEScription    : CICS JVM server to run WLP samples                         
  Status         : Enabled            Enabled | Disabled                      
  Jvmprofile     : DFHWLPX                                        (Mixed Case)
  Lerunopts      : DFHAXRO                                                    
  Threadlimit    : 015                1-256                                   
 DEFINITION SIGNATURE                                                         
  DEFinetime     : 08/07/20 17:01:19                                          
  CHANGETime     : 08/07/20 17:01:36                                          
  CHANGEUsrid    : CICSUSER                                                   
  CHANGEAGEnt    : CSDApi             CSDApi | CSDBatch                       
  CHANGEAGRel    : 0730                                                                                                                    

Install this JVMSERVER once.

It is OK if it is enabled by looking at CEMT I JVMSERVER.

I JVMS                                                
STATUS:  RESULTS - OVERTYPE TO MODIFY                 
 Jvm(DFHWLPX ) Ena     Prf(DFHWLPX ) Ler(DFHAXRO )    
    Threadc(012) Threadl( 015 ) Cur(65873224)              

JCICSX feature / server side configuration

Since "com.ibm.cics.jvmserver.wlp.autoconfigure = true" is specified in the JVM Profile, Liberty is automatically configured when the JVM Server is installed.

\ <WORK_DIR > /CT56B4A1/DFHWLPX/wlp/usr/servers/defaultServer/server.xml has been created, so edit it. Add a feature called cicsts: jcicsxServer-1.0 as follows:

server.xml


...
    <featureManager>
        <feature>cicsts:core-1.0</feature>
        <feature>cicsts:defaultApp-1.0</feature>
        <feature>jsp-2.3</feature>
        <feature>wab-1.0</feature>
        <feature>transportSecurity-1.0</feature>
        <feature>cicsts:jcicsxServer-1.0</feature>
    </featureManager>
...

When you restart the JVM Server, you can see the following log as the Liberty startup message. (<WORK_DIR>/CT56B4A1/DFHWLPX/wlp/usr/servers/defaultServer/logs/messages.log)

messages.log


...
[8/7/20 8:13:40:387 GMT] 00000050 com.ibm.ws.webcontainer.osgi.webapp.WebGroup                 I SRVE0169I: Loading Web Module: com.ibm.cics.wlp.jcicsxserver.
[8/7/20 8:13:40:387 GMT] 00000050 com.ibm.ws.webcontainer                                      I SRVE0250I: Web Module com.ibm.cics.wlp.jcicsxserver has been bound to default_host.
[8/7/20 8:13:40:387 GMT] 00000050 com.ibm.ws.http.internal.VirtualHostImpl                     A CWWKT0016I: Web application available (default_host): http://xx.xx.xx:56461/jcicsxServer/
...

The URL shown here is used in the Liberty configuration on the PC side.

Liberty (client side) configuration on the local PC

Eclipse / Liberty introduced

Set up the Eclipse environment on Windows 10 and install Liberty. For the procedure, use the one in the following article as it is. [WebSphere Application Server Liberty Base --JCA connection environment construction memo --Development environment setup (Windows)](https://qiita.com/tomotagwork/items/73d84923cc1a1ee6f6b0#%E9%96%8B%E7%99%BA%E7% 92% B0% E5% A2% 83% E3% 82% BB% E3% 83% 83% E3% 83% 88% E3% 82% A2% E3% 83% 83% E3% 83% 97 windows)

Added JCIC SX related features

Double-click the target Liberty feature manager in Eclipse server view to open server.xml and click Add to the right of the feature list image.png

Click Install additional features image.png

If you specify "JCICS" for the filter, the JCICSX development feature for Java will be listed. Click Install to Next. image.png

Confirm license and complete image.png

image.png

Now that the feature is installed, select user: jcicsxClient-1.0, which is filtered by jcicsx and displayed. image.png

Added as a feature. image.png

Looking at the source of server.xml, it looks like this.

server.xml


    <featureManager>
        <feature>jsp-2.3</feature>
        <feature>localConnector-1.0</feature>
    	<feature>servlet-3.1</feature>
		<feature>jca-1.7</feature>
		<feature>jndi-1.0</feature>
		<feature>ejb-3.2</feature>
		<feature>usr:jcicsxClient-1.0</feature>
	</featureManager>
...

JCICSX feature / client side configuration

Edit server.xml and add the following settings.

server.xml


...
    <!-- JCICSX Client Config -->
    <usr_jcicsxClient serverUri="http://etp1:56461"/>
...

The serverUri address and port are CICS-Liberty endpoints configured for the JCICSX server. If you look at server.xml in Design view, it will look like this: image.png

This completes the "remote development" configuration.

Application development on a local PC using JCICSX

JCICSX development environment maintenance

There are several ways to provide the JCICSX class library, but it is also included in the CICS SDK for Java in CICS Explorer. If you incorporate the CICS Explorer function into Eclipse, it will be easier to manage, so I decided to include CICS Explorer in the Eclipse environment.

Reference: Downloading and starting CICS Explorer (https://www.ibm.com/support/knowledgecenter/SSSQ3W_5.5.0/com.ibm.cics.core.help/topics/concepts/install_planning_client.html)

Select Help-Install New Software from the Eclipse menu image.png

Press Add to add the following repositories. 「https://public.dhe.ibm.com/ibmdl/export/pub/software/htp/zos/tools/aqua3.2/」 image.png

Select CICS Explorer and Next image.png

next image.png

Confirm license and complete image.png

It takes a long time to install. This kind of confirmation may appear on the way, so take appropriate action. image.png

When completed, the following pop-up will appear, so restart Eclipse image.png

The CICS Explorer feature is now built into Eclipse.

Import sample app

Here, I will try running the sample provided on GitHub. GitHub: cics-java-jcicsx-samples Clone locally.

c:\y\workspace\cicsts56>git clone https://github.com/cicsdev/cics-java-jcicsx-samples.git
Cloning into 'cics-java-jcicsx-samples'...
remote: Enumerating objects: 361, done.
remote: Counting objects: 100% (361/361), done.
remote: Compressing objects: 100% (157/157), done.
Receiving objects:  76% (275/361)   ed 350 (delta 137), pack-reused 0
Receiving objects: 100% (361/361), 97.91 KiB | 331.00 KiB/s, done.
Resolving deltas: 100% (145/145), done.

Of the several samples, import "char-link-program-sample" into Eclipse.

Right-click on Enterprise Explorer view in JavaEE perspective-Import Maven-Select an existing Maven project image.png

Select "char-link-program-sample" under the cloned directory image.png

The project has been created. image.png

Check the contents

Let's take a look at pom.xml.

pom.xml


<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.ibm.cics</groupId>
  <artifactId>char-link-program-sample</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <packaging>war</packaging>

  <dependencies>
    <dependency>
      <groupId>javax.servlet</groupId>
      <artifactId>javax.servlet-api</artifactId>
      <version>3.1.0</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>javax.annotation</groupId>
      <artifactId>jsr250-api</artifactId>
      <version>1.0</version>
      <scope>provided</scope>
    </dependency>

    <!-- JCICSX dependency, used in CharLinkServlet.java -->
    <dependency>
      <groupId>com.ibm.cics</groupId>
      <artifactId>com.ibm.cics.jcicsx</artifactId>
      <version>1.000.0-5.6</version>
      <scope>provided</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.8.1</version>
        <configuration>
          <source>1.8</source>
          <target>1.8</target>
        </configuration>
      </plugin>

      <!-- The below bundles the application as a WAR in a CICS bundle and deploys this to CICS using the CICS bundle deployment API.
           This is optional and can be removed if you don't wish to deploy the application this way -->
      <plugin>
        <groupId>com.ibm.cics</groupId>
        <artifactId>cics-bundle-maven-plugin</artifactId>
        <version>1.0.0</version>
        <executions>
          <execution>

            <!-- These goals will firstly run the war packaging on the project, and then will run the deploy goal, which will happen during the verify phase of the lifecycle by default-->
            <goals>
              <goal>bundle-war</goal>
              <goal>deploy</goal>
            </goals>

            <configuration>
              <!-- The bundle classifier indicates that the war should be packaged into a CICS bundle -->
              <classifier>cics-bundle</classifier>

              <!-- Update the default JVM server that the application will be installed into by default, This is used when creating the bundle, and goes into the CICS bundle's manifest -->
              <jvmserver>DFHWLP</jvmserver>
              
              <!-- Set the URL of the deploy target -->
              <url>http://yourcicsurl.com:9080</url>

              <!-- We'd recommend that you use Maven's password encryption, or supply your credentials using environment variables or properties, as shown here. -->
              <username>${cics-user-id}</username>
              <password>${cics-password}</password>

              <!-- Identify which bundle definition you're going to use from the CSD and which region and CICSPlex you want to deploy to -->
              <bunddef>DEMOBUNDLE</bunddef>
              <csdgroup>BAR</csdgroup>
              <cicsplex>CICSEX56</cicsplex>
              <region>IYCWEMW2</region>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

A JCICSX dependency has been specified. The settings for the BUNDLE definition are also included, but for now, leave them as they are.

Next, let's take a look at the Servlet source.

CharLinkServlet.java


package sample;

/* Licensed Materials - Property of IBM                                   */
/*                                                                        */
/* SAMPLE                                                                 */
/*                                                                        */
/* (c) Copyright IBM Corp. 2020 All Rights Reserved                       */
/*                                                                        */
/* US Government Users Restricted Rights - Use, duplication or disclosure */
/* restricted by GSA ADP Schedule Contract with IBM Corp                  */
/*                                                                        */

import java.io.IOException;

import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.ibm.cics.jcicsx.CICSConditionException;
import com.ibm.cics.jcicsx.CICSContext;

/**
 * A sample servlet to demonstrate how to use JCICSX to LINK to a CICS Program
 * with CHAR data
 */
@WebServlet("/SampleServlet")
public class CharLinkServlet extends HttpServlet {

	private static final long serialVersionUID = 1L;

	/**
	 * Name of the program to invoke.
	 */
	private static final String PROG_NAME = "EDUCHAN";

	/**
	 * Name of the channel to use.
	 */
	private static final String CHANNEL = "MYCHANNEL";

	/**
	 * Name of the container used to send data to the target program.
	 */
	private static final String INPUT_CONTAINER = "INPUTDATA";

	/**
	 * Name of the container which will contain the response from the target
	 * program.
	 */
	private static final String OUTPUT_CONTAINER = "OUTPUTDATA";

	/**
	 * Data to place in the container to be sent to the target program.
	 */
	private static final String INPUTSTRING = "Hello from Java";

	/**
	 * @see HttpServlet#doGet(HttpServletRequest request, HttpServletResponse
	 *      response)
	 */
	@Override
	protected void doGet(HttpServletRequest request, HttpServletResponse response)
			throws ServletException, IOException {
		response.setContentType("text/html");

		response.getWriter().print("Hello world! ");

		// Message to emit as the response
		String resultStr = null;

		// Gets the current CICS Context for the environment we're running in
		CICSContext task = CICSContext.getCICSContext();

		try {
			// Create a reference to the Program we will invoke and specify the channel
			// Don't syncpoint between remote links, this is the default
			// Link to the program with an input container, containing the input string of
			// "Hello from Java"
			task.createProgramLinkerWithChannel(PROG_NAME, CHANNEL).setSyncOnReturn(false)
					.setStringInput(INPUT_CONTAINER, INPUTSTRING).link();

			// Get the data from the output container as a string
			// You could remove task.getChannel(CHANNEL) and do this as one chained command
			// above, but this demonstrates how you could call this part later on in your
			// program
			resultStr = task.getChannel(CHANNEL).getCHARContainer(OUTPUT_CONTAINER).get();

			if (resultStr == null) {
				// Missing response container
				resultStr = "<missing>";
			}

			// Format the final message and print it
			String msg = "Returned from link to \'" + PROG_NAME + "\' with a text response of \'" + resultStr + "\'";
			response.getWriter().println(msg);

		} catch (CICSConditionException e) {
			response.getWriter().println("An exception has occured" + "\nRESP: " + e.getRespCode() + "\nRESP2: "
					+ e.getResp2() + "\nMessage: " + e.getMessage());
		}
	}

}

Here, the JCICSX class is used to perform operations on Channel & Container and LINK the program. Specifically, the following operations are performed.

--Create a container called "INPUT DATA" in the channel "MY CHANNEL" and enter the string "Hello from Java" --Call the COBOL program "EDUCHAN" with "MYCHANNEL" --Obtain data from the container "OUTPUT DATA" of "MY CHANNEL" and display the result on the screen.

The COBOL source is also provided, so check that as well.

EDUCHAN


      *----------------------------------------------------------------*
      *  Licensed Materials - Property of IBM                          *
      *  SAMPLE                                                        *
      *  (c) Copyright IBM Corp. 2016 All Rights Reserved              *
      *  US Government Users Restricted Rights - Use, duplication or   *
      *  disclosure restricted by GSA ADP Schedule Contract with       *
      *  IBM Corp                                                      *
      *----------------------------------------------------------------*

      ******************************************************************
      *                                                                *
      * Module Name        EDUCHAN.CBL                                 *
      * Version            1.0                                         *
      * Date               22/10/2016                                  *
      *                                                                *
      * CICS back-end channel/container sample                         *
      *                                                                *
      * This program expects to be invoked with a CHAR container named *
      * INPUTDATA and returns the following containers:                *
      * A CHAR container containing the reversed input string          *
      * A CHAR container containing the time                           *
      * A BIT container containing the CICS return code from reading   *
      * the input container                                            *
      ******************************************************************

       IDENTIFICATION DIVISION.
       PROGRAM-ID. EDUCHAN.

       ENVIRONMENT DIVISION.
       CONFIGURATION SECTION.
       DATA DIVISION.
       WORKING-STORAGE SECTION.

      *  Container name declarations
      *  Channel and container names are case sensitive
       01 DATE-CONT          PIC X(16) VALUE 'CICSTIME'.
       01 INPUT-CONT         PIC X(16) VALUE 'INPUTDATA'.
       01 OUTPUT-CONT        PIC X(16) VALUE 'OUTPUTDATA'.
       01 LENGTH-CONT        PIC X(16) VALUE 'INPUTDATALENGTH'.
       01 ERROR-CONT         PIC X(16) VALUE 'ERRORDATA'.
       01 RESP-CONT          PIC X(16) VALUE 'CICSRC'.


      *  Data fields used by the program
       01 INPUTLENGTH        PIC S9(8) COMP-4.
       01 DATALENGTH         PIC S9(8) COMP-4.
       01 CURRENTTIME        PIC S9(15) COMP-3.
       01 ABENDCODE          PIC X(4) VALUE SPACES.
       01 CHANNELNAME        PIC X(16) VALUE SPACES.
       01 INPUTSTRING        PIC X(72) VALUE SPACES.
       01 OUTPUTSTRING       PIC X(72) VALUE SPACES.
       01 RESPCODE           PIC S9(8) COMP-4 VALUE 0.
       01 RESPCODE2          PIC S9(8) COMP-4 VALUE 0.
       01 DATE-TIME.
         03 DATESTRING         PIC X(10) VALUE SPACES.
         03 TIME-SEP           PIC X(1) VALUE SPACES.
         03 TIMESTRING         PIC X(8) VALUE SPACES.
       01 RC-RECORD          PIC S9(8) COMP-4 VALUE 0.
       01 ERR-RECORD.
         03 ERRORCMD           PIC X(16) VALUE SPACES.
         03 ERRORSTRING        PIC X(32) VALUE SPACES.


       PROCEDURE DIVISION.
      *  -----------------------------------------------------------
       MAIN-PROCESSING SECTION.
      *  -----------------------------------------------------------

      *  Get name of channel
           EXEC CICS ASSIGN CHANNEL(CHANNELNAME)
                            END-EXEC.

      *  If no channel passed in, terminate with abend code NOCH
           IF CHANNELNAME = SPACES THEN
               MOVE 'NOCH' TO ABENDCODE
               PERFORM ABEND-ROUTINE
           END-IF.


      *  Read content and length of input container
           MOVE LENGTH OF INPUTSTRING TO INPUTLENGTH.
           EXEC CICS GET CONTAINER(INPUT-CONT)
                            CHANNEL(CHANNELNAME)
                            FLENGTH(INPUTLENGTH)
                            INTO(INPUTSTRING)
                            RESP(RESPCODE)
                            RESP2(RESPCODE2)
                            END-EXEC.

      *  Place RC in binary container for return to caller
           MOVE RESPCODE TO RC-RECORD.
           EXEC CICS PUT CONTAINER(RESP-CONT)
                            FROM(RC-RECORD)
                            FLENGTH(LENGTH OF RC-RECORD)
                            BIT
                            RESP(RESPCODE)
                            END-EXEC.

           IF RESPCODE NOT = DFHRESP(NORMAL)
             PERFORM RESP-ERROR
           END-IF.

      *  Place reversed string in output container
           MOVE FUNCTION REVERSE(INPUTSTRING) TO OUTPUTSTRING.

           EXEC CICS PUT CONTAINER(OUTPUT-CONT)
                            FROM(OUTPUTSTRING)
                            FLENGTH(LENGTH OF OUTPUTSTRING)
                            CHAR
                            RESP(RESPCODE)
                            END-EXEC.

           IF RESPCODE NOT = DFHRESP(NORMAL)
             PERFORM RESP-ERROR
           END-IF.

      *  Get the current time
           EXEC CICS ASKTIME ABSTIME(CURRENTTIME)
                            END-EXEC.

      *  Format date and time
           EXEC CICS FORMATTIME
                     ABSTIME(CURRENTTIME)
                     DDMMYYYY(DATESTRING)
                     DATESEP('/')
                     TIME(TIMESTRING)
                     TIMESEP(':')
                     RESP(RESPCODE)
                     END-EXEC.

      *  Check return code
           IF RESPCODE NOT = DFHRESP(NORMAL)
               STRING 'Failed' DELIMITED BY SIZE
                            INTO DATESTRING END-STRING
           END-IF.

      *  Place current date in container CICSTIME
           EXEC CICS PUT CONTAINER(DATE-CONT)
                            FROM(DATE-TIME)
                            FLENGTH(LENGTH OF DATE-TIME)
                            CHAR
                            RESP(RESPCODE)
                            END-EXEC.
      *  Check return code
           IF RESPCODE NOT = DFHRESP(NORMAL)
             PERFORM RESP-ERROR
           END-IF.



      *  Return back to caller
           PERFORM END-PGM.

      *  -----------------------------------------------------------
       RESP-ERROR.
             MOVE 'EDUC' TO ABENDCODE
             PERFORM ABEND-ROUTINE.

           PERFORM END-PGM.

      *  -----------------------------------------------------------
      *  Abnormal end
      *  -----------------------------------------------------------
       ABEND-ROUTINE.
           EXEC CICS ABEND ABCODE(ABENDCODE) END-EXEC.

      *  -----------------------------------------------------------
      *  Finish
      *  -----------------------------------------------------------
       END-PGM.
           EXEC CICS RETURN END-EXEC.


In the COBOL program, the character strings received in the INPUTDATA container are set in the OUTPUTDATA container in the reverse order and returned. In addition, we are adding a container to store the date and time and RESP Code.

The source is used as it is without any modification.

COBOL application preparation

Since this sample is a scenario of creating a Java program that calls an existing COBOL program, the COBOL application must be prepared in the development environment. Transfer the COBOL source (EDUCHAN) to z / OS, compile / link it, and register the program definition in the CICS region where the CICS-Liberty configuration for remote development is performed. This is the same as the procedure for a traditional CICS-COBOL application, so I will omit it here.

Build / deploy / test Java application

Right click on the project --Maven --Select Update Project Select a project and OK image.png

Right click on CharLinkServlet.java --Run --Run on server Select Liberty Server with jcicsx configuration and Next image.png

Done image.png

After the specified Liberty is launched and the app is deployed, the browser will open and the Servlet will be executed. image.png

It ran successfully! The string "Hello from Java" is returned in reverse order. In other words, you can see that the COBOL program on CICS was called even though it was run on the local Liberty. In other words, it was confirmed that if you configure JCICSX for remote development in advance, you can even test on Liberty just by operating the PC side! As a normal development process, you can complete the modification, deployment, and testing on your PC.

Deploy / test to real CICS-Liberty environment

CICS side preparation

In order to actually run the CICS-Liberty application, you need to configure the JVMSERVER for Liberty. You don't need the JCICSX remote development feature here, so you can just configure the JVMSERVER as you normally would. Also, since it is assumed that Deployment is automated as a Maven project here, the target CICS belongs to CICSplex, and it is necessary to configure the Deployment API in WUI. The following "preparation of execution environment" corresponds to that area as it is. Reference: [Run CICS-Java application-(2) Build management by Maven](https://qiita.com/tomotagwork/items/a487484835d4e8dd2d6f#%E5%AE%9F%E8%A1%8C%E7%92% B0% E5% A2% 83zos-cics)

Edit pom.xml

pom.xml also contains the configuration for the CICS Bundle project. When deploying the application to the actual CICS environment, the configuration around it is required, so edit it according to the execution environment set above.

pom.xml


<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.ibm.cics</groupId>
  <artifactId>cics004-char-link-program-sample</artifactId>
  <version>1.0.0</version>
  <packaging>war</packaging>

  <dependencies>
    <dependency>
      <groupId>javax.servlet</groupId>
      <artifactId>javax.servlet-api</artifactId>
      <version>3.1.0</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>javax.annotation</groupId>
      <artifactId>jsr250-api</artifactId>
      <version>1.0</version>
      <scope>provided</scope>
    </dependency>

    <!-- JCICSX dependency, used in CharLinkServlet.java -->
    <dependency>
      <groupId>com.ibm.cics</groupId>
      <artifactId>com.ibm.cics.jcicsx</artifactId>
      <version>1.000.0-5.6</version>
      <scope>provided</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.8.1</version>
        <configuration>
          <source>1.8</source>
          <target>1.8</target>
        </configuration>
      </plugin>

      <!-- The below bundles the application as a WAR in a CICS bundle and deploys this to CICS using the CICS bundle deployment API.
           This is optional and can be removed if you don't wish to deploy the application this way -->
      <plugin>
        <groupId>com.ibm.cics</groupId>
        <artifactId>cics-bundle-maven-plugin</artifactId>
        <version>1.0.0</version>
        <executions>
          <execution>

            <!-- These goals will firstly run the war packaging on the project, and then will run the deploy goal, which will happen during the verify phase of the lifecycle by default-->
            <goals>
              <goal>bundle-war</goal>
              <goal>deploy</goal>
            </goals>

            <configuration>
              <!-- The bundle classifier indicates that the war should be packaged into a CICS bundle -->
              <classifier>cics-bundle</classifier>

              <!-- Update the default JVM server that the application will be installed into by default, This is used when creating the bundle, and goes into the CICS bundle's manifest -->
              <jvmserver>DFHWLP</jvmserver>

              <!-- Set the URL of the deploy target -->
              <url>http://etp1:56002</url>

              <!-- We'd recommend that you use Maven's password encryption, or supply your credentials using environment variables or properties, as shown here. -->
              <username>TAG</username>
              <password>********</password>

              <!-- Identify which bundle definition you're going to use from the CSD and which region and CICSPlex you want to deploy to -->
              <bunddef>CHARLINK</bunddef>
              <csdgroup>TAGGRP</csdgroup>
              <cicsplex>C73PLX</cicsplex>
              <region>CT56B4A1</region>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

Modify the first artifactId and version so that they are unique in the same CICSplex environment.

BUNDLE definition preparation

Create a BUNDLE definition on CICS that matches the definition in pom.xml above.

OBJECT CHARACTERISTICS                                    CICS RELEASE = 0730 
 CEDA  View Bundle( CHARLINK )                                                
  Bundle         : CHARLINK                                                   
  Group          : TAGGRP                                                     
  DEScription    : CICS-BUNDLE-DEMO                                           
  Status         : Enabled            Enabled | Disabled                      
  BUndledir      : /var/cicsts/cicsts56/bundles/cics004-char-link-program-sam 
  (Mixed Case)   : ple_1.0.0                                                  
                 :                                                            
                 :                                                            
                 :                                                            
  BAsescope      :                                                            
  (Mixed Case)   :                                                            
                 :                                                            
                 :                                                            
                 :                                                            
 DEFINITION SIGNATURE                                                         
  DEFinetime     : 08/11/20 16:05:22                                          
  CHANGETime     : 08/11/20 16:07:52                                          

No installation is done here.

Preparing the JVMSERVER

This time, the same region is used for the development environment and the production environment, but the JVM Server is separated. I used a JVMSERVER definition called DFHWLPX for the development environment, but this should be Discarded and only the JVMServer: DFHWLP (not configured for JCICSX) for the production environment should be enabled.

COBOL application preparation

Since a COBOL program called EDUCHAN is linked from a Java application, it is necessary to be able to call that program. Since the same region is used for the development environment and the production environment this time, it is assumed that the COBOL program has already been set up. Of course, if the regions are separated, it is necessary to add the program definition to the actual environment.

Build / deploy Java application

Right click pom.xml in Eclipse --Run --Maven install select image.png

You can check the execution result of mvn install in the console view. image.png

It is OK if BUILD SUCCESS is output.

To be on the safe side, make sure that the bundle and bundle parts are installed in CICS Explorer. image.png

Run

Access the CICS-Liberty app at the following URL http://etp1:56441/cics004-char-link-program-sample-1.0.0/SampleServlet image.png

I was able to confirm the operation with the same code even in the actual CICS-Liberty environment!

Recommended Posts

CICS-Run Java applications-(5) Use JCICSX
CICS-Run Java applications-(3) Build management with Gradle
CICS-Run Java applications-(2) Build management with Maven
[Java] Use Collectors.collectingAndThen
Use OpenCV in Java
Use PreparedStatement in Java
Use Lambda Layers with Java
[Java] How to use Map
[Java] How to use Map
How to use java Optional
How to use java class
[Java] How to use Optional ②
[Java] How to use removeAll ()
[Java] How to use string.format
How to use Java Map
[Java] Use Big Decimal properly ~ 2018 ~
CICS-Run Java application-(4) Spring Boot application
[java] Reasons to use static
How to use Java variables
Use SpatiaLite with Java / JDBC
[Java] How to use Optional ①
Run Java EE applications on CICS
How to use Java HttpClient (Get)
Use Microsoft Graph with standard Java
Easily Docker Java applications with Jib
How to use Java HttpClient (Post)
[Java] How to use join method
Let's use Twilio in Java! (Introduction)
Use Azure Bing SpellCheck with Java
Use JDBC with Java and Scala.
[Java] Do not use "+" in append!
Use composite keys in Java Map.
[Processing × Java] How to use variables
Use Java 11 with Google Cloud Functions
java (use class type for field)
[JavaFX] [Java8] How to use GridPane
How to use class methods [Java]
[Java] How to use List [ArrayList]
How to use classes in Java?
[Processing × Java] How to use arrays
How to use Java lambda expressions
Do you use Stream in Java?
[Java] How to use Math class
How to use Java enum type